Skip to content

MaterialsFramework

License: GPL-3.0-or-later Python Platforms

Tests Lint

DOI

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

  • Installation

    Set up uv or pip and install the MLIP extras you need.

    Installation

  • Quick Start

    Relax a crystal structure in a few lines of code.

    Quick Start

  • Usage

    Task-oriented walkthroughs for calculators, analyzers, and tools.

    Usage

  • Theory

    The physics and derivations behind each analyzer and tool.

    Theory

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

Citing

If you use MaterialsFramework in your research, please cite:

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

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