MaterialsFramework

MaterialsFramework provides a single, uniform API for 20+ machine learning interatomic potentials (MLIPs), covering single-point calculations, structure relaxation, and molecular dynamics, plus the property analyzers and structure-generation tools that build on them. Swapping one MLIP for another, or for the licensed VASPCalculator, means changing one line of code.

Report a Bug | Request a Feature | Documentation

---

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

MLIP	Extra	Package	API	Repository	Paper
ALIGNN	alignn	alignn	API	Repo	Paper
Allegro	allegro	nequip-allegro	API	Repo	Paper
AlphaNet	alphanet	msc-alphanet	API	Repo	Paper
CHGNet	chgnet	chgnet	API	Repo	Paper
DeePMD	deepmd	deepmd-kit	API	Repo	Paper
EqNorm	eqnorm	eqnorm	API	Repo	N/A
EquFlash	N/A	GGNN (git-only)	API	Repo	Paper
EqV2	eqv2	fairchem-core	API	Repo	Paper
eSEN	esen	fairchem-core	API	Repo	Paper
GPTFF	N/A	gptff (git-only)	API	Repo	Paper
GRACE	grace	tensorpotential	API	Repo	Paper
HIENet	hienet	hienet	API	Repo	Paper
M3GNet	matgl	matgl	API	Repo	Paper
MACE	mace	mace-torch	API	Repo	Paper
MatRIS	matris	matris	API	Repo	Paper
MatterSim	mattersim	mattersim	API	Repo	Paper
MEGNet	matgl	matgl	API	Repo	Paper
NequIP	nequip	nequip	API	Repo	Paper
Nequix	nequix	nequix	API	Repo	Paper
NewtonNet	newtonnet	newtonnet	API	Repo	Paper
ORB	orb	orb-models	API	Repo	Paper
PetMad	petmad	upet	API	Repo	Paper
PosEGNN	N/A	N/A	API	Repo	N/A
SevenNet	sevennet	sevenn	API	Repo	Paper
TACE	tace	TACE	API	Repo	Paper
UMA	uma	fairchem-core	API	Repo	Paper

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

---

Property Analyzers

Analyzer	Description
ANNNIStackingFaultAnalyzer	ANNNI-based intrinsic and extrinsic stacking fault energies
BainPathAnalyzer	Energy along the FCC-to-BCC Bain transformation path
CTEAnalyzer	Coefficient of thermal expansion from NPT-MD volume trends
CubicElasticConstantsAnalyzer	Cubic elastic constants and derived moduli (B, G, E, ν)
ElasticConstantsAnalyzer	Full elastic tensor and Voigt-Reuss-Hill averages
EOSAnalyzer	Equation-of-state curve fitting from E-V data
FormationEnergyAnalyzer	Formation energy per atom
HSolubilityAnalyzer	Hydrogen insertion and solution energies
NEBAnalyzer	Nudged elastic band minimum energy path and reaction barrier
PhonopyAnalyzer	Total/projected phonon DOS and thermal properties
Phono3pyAnalyzer	Anharmonic force constants and lattice thermal conductivity
SBEAnalyzer	Surface binding energies, a first-principles proxy for sputtering resistance
SurfaceAnalyzer	Slab surface energies for a given Miller index
USFEAnalyzer	Generalized stacking fault energy curves and unstable SFE

---

Tools

Tool	Description
BondLatticeParameter	Lattice parameter estimation from bond lengths for FCC/BCC/HCP alloys
ClusterExpansion	Cluster expansion model construction and fitting
CoherentStabilityMap	Stability map generation with a coherent-elastic correction to the Gibbs energy Hessian
PhaseFieldModel	Cahn-Hilliard phase-field simulations
Sqs2tdb	Converts SQS output files to TDB format for CALPHAD workflows (PhaseForge)
SqsGenerator	Special quasirandom structure generation
StabilityMap	Composition-temperature stability map generation
TrajectoryObserver	Records energies, forces, stresses, and trajectory frames during relaxation or MD

---

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},
}