Quick Start¶

This guide shows the minimal code needed to evaluate and relax a crystal structure using MaterialsFramework.

Single-Point Calculation¶

from ase.build import bulk
from materialsframework.calculators import MACECalculator

# Build an FCC copper structure
struct = bulk(name="Cu", crystalstructure="fcc", a=3.6, cubic=True)

# Instantiate the calculator (model weights are downloaded on first use)
calc = MACECalculator()

# Evaluate energy, forces, and stress with no optimization
res = calc.calculate(struct)

# Inspect results
print(res["energy"])    # eV
print(res["forces"])    # numpy array, eV/Å
print(res["stress"])    # numpy array, eV/Å³

The calculate() method returns a dict with at minimum:

Key	Description
`final_structure`	Input structure as a pymatgen `Structure`, unchanged
`energy`	Total energy (eV)
`forces`	Forces on each atom (eV/Å)
`stress`	Stress tensor (eV/Å³)

Geometry Optimization¶

from ase.build import bulk
from materialsframework.calculators import MACECalculator

# Build an FCC copper structure
struct = bulk(name="Cu", crystalstructure="fcc", a=3.6, cubic=True)

# Instantiate the calculator
calc = MACECalculator()

# Run geometry optimization (cell shape + atomic positions)
res = calc.relax(struct)

# Inspect results
print(res["final_structure"])   # pymatgen Structure
print(res["forces"])            # numpy array, eV/Å
print(res["stress"])            # numpy array, eV/Å³

The relax() method returns a dict with at minimum:

Key	Description
`final_structure`	Relaxed structure as a pymatgen `Structure`
`trajectory`	`TrajectoryObserver` containing intermediate states
`energy`	Final total energy (eV)
`forces`	Forces on each atom (eV/Å)
`stress`	Stress tensor (eV/Å³)

Swapping Calculators¶

Most MLIP calculators implement the same BaseCalculator interface and can be swapped without changing the workflow. MEGNetCalculator is the exception: it predicts formation energy only and does not implement relax().

from materialsframework.calculators import CHGNetCalculator

calc = CHGNetCalculator()
res = calc.relax(struct)

See the Calculators API reference for all available calculators and their parameters.