Key Features

• Run single-point calculations and structure relaxations across 20+ ML interatomic potentials through one shared BaseCalculator interface, or swap in the licensed VASPCalculator without changing calling code
• Accept ase.Atoms, pymatgen.Structure, and pymatgen.Molecule interchangeably as calculator input
• Run molecular dynamics with NVE and a broad set of NVT/NPT thermostats and barostats on calculators that support it
• Compute formation energy, elastic constants, phonons, stacking faults, surface/binding energies, and reaction barriers with 14 property analyzers, each paired with a transformation that generates the structures it needs
• Generate special quasirandom structures, cluster expansion models, phase-field simulations, and stability maps with the built-in tools
• Look up calculators, analyzers, transformations, and tools by name, without importing every MLIP backend at once

Supported MLIPs

Non-MLIP calculators: RandomCalculator (dependency-free testing stub) and VASPCalculator (external licensed VASP backend).

Property Analyzers

Tools

Installation

We recommend uv for dependency management, though a plain pip install also works. Use the Extra column in the Supported MLIPs table above to pick which MLIP extras to add. Some backends require additional installation steps documented in the full installation guide.

uv

uv add materialsframework

Add one or more compatible MLIP extras:

# Single MLIP
uv add "materialsframework[chgnet]"

# Compatible multi-MLIP stack
uv add "materialsframework[chgnet,matgl,sevennet]"

pip

pip install materialsframework

Add an MLIP extra the same way:

pip install "materialsframework[chgnet]"

See the installation guide for full setup instructions and MLIP Conflicts for conflict and optional-dependency details.

Quickstart

Calculators

Every calculator except MEGNetCalculator accepts ase.Atoms or pymatgen.Structure and exposes the same relax()/calculate() interface, regardless of which MLIP backs it.

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

structure = bulk("Cu", crystalstructure="fcc", a=3.6, cubic=True)
calc = MACECalculator()

result = calc.relax(structure)
print(result["final_structure"])
print(result["energy"])

calculate() evaluates the same properties on the structure exactly as given, with no relaxation step:

result = calc.calculate(structure)
print(result["energy"])
print(result["forces"])

Molecular Dynamics

Calculators that subclass BaseMDCalculator add a run() method for NVE and multiple NVT/NPT thermostats and barostats.

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

structure = bulk("Fe", crystalstructure="bcc", a=2.87, cubic=True)
calc = CHGNetCalculator(ensemble="nvt_nose_hoover", temperature=300)

result = calc.run(structure, steps=1000)
print(result["final_structure"])

Property Analyzers

Analyzers pair with a transformation of the same name: the transformation generates the structures a calculation needs, and the analyzer orchestrates the calculator calls and combines the results.

from ase.build import bulk
from materialsframework.analysis import FormationEnergyAnalyzer
from materialsframework.calculators import CHGNetCalculator

structure = bulk("NaCl", crystalstructure="rocksalt", a=5.64)
analyzer = FormationEnergyAnalyzer(calculator=CHGNetCalculator())

result = analyzer.calculate(structure, is_relaxed=True)
print(result["formation_energy"])

Tools

Standalone utilities such as special quasirandom structure generation, cluster expansion, and phase-field modeling live in materialsframework.tools.

from materialsframework.tools import SqsGenerator

generator = SqsGenerator(iterations=1000)
result = generator.generate("Fe0.5Co0.5", crystal_structure="bcc", supercell_size=(2, 2, 2))
print(result["structure"])
print(result["objective"])

Registries

Look up calculators, analyzers, transformations, and tools by name to swap in a new backend without importing every MLIP dependency up front.

from materialsframework.calculators import get_calculator

calc = get_calculator("chgnet")

License

Distributed under the GPL-3.0-or-later License. See GPL-3.0 for details.

Citation

If you use MaterialsFramework in your research, please cite:

Sarıtürk, D., & Arroyave, R. (2025). MaterialsFramework. Zenodo. https://doi.org/10.5281/zenodo.15731044

@software{sariturk_2025_15731044,
  author    = {Sarıtürk, Doğuhan and Arroyave, Raymundo},
  title     = {MaterialsFramework},
  month     = jun,
  year      = 2025,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.15731044},
  url       = {https://doi.org/10.5281/zenodo.15731044},
}