Installation¶
Install MaterialsFramework¶
MaterialsFramework is published on PyPI. We recommend uv for dependency management, though a plain pip install also works.
This installs the framework core (pymatgen, ASE, numpy, scipy) plus RandomCalculator and VASPCalculator, which have no heavy ML dependencies.
Install MLIP Extras¶
Each MLIP has its own extra (for example mace, chgnet, eqv2, petmad). Install either one MLIP extra or a compatibility-safe group.
Before combining MLIPs, check MLIP Conflicts. Published package metadata cannot express the project-level exclusions or manually installed optional dependencies, so downstream uv and pip installs may not reject an unsupported combination.
Supported Platforms¶
MaterialsFramework's core dependencies (pymatgen, ASE, numpy, scipy) install broadly, but several MLIP extras (most torch-based backends) only resolve cleanly on:
- Linux
x86_64 - Linux
aarch64 - macOS
arm64(Apple Silicon)
If you are on a different platform, installation may still be possible with manual dependency management, but it is not a supported target.
Calculator-specific native dependencies can narrow this support. In particular, PyG does not publish the EqV2 extension wheels for Linux aarch64; see its install note below.
MLIP Extras Overview¶
| Calculator | Extra | Dependency spec |
|---|---|---|
| ALIGNN | alignn |
alignn>=2025.4.1 (extra step needed; see note below) |
| Allegro | allegro |
nequip-allegro>=0.8.3 |
| AlphaNet | alphanet |
msc-alphanet>=0.1.3 (extra step needed; see note below) |
| CHGNet | chgnet |
chgnet>=0.4.2 |
| DeePMD | deepmd |
deepmd-kit[torch]>=3.1.2 |
| EqNorm | eqnorm |
eqnorm>=0.1.1 (extra step needed; see note below) |
| EquFlash | N/A | GGNN (git-only, no pip extra; see note below) |
| EquiformerV2 | eqv2 |
fairchem-core>=1.10.0,<2.0 (extra step needed; see below) |
| eSEN | esen |
fairchem-core>=2.0.0 |
| GPTFF | N/A | gptff (git-only, no pip extra; see note below) |
| GRACE | grace |
tensorpotential>=0.5.7 |
| HIENet | hienet |
hienet>=1.0.1 (extra step needed; see note below) |
| M3GNet / MEGNet | matgl |
matgl>=2.0.0 |
| MACE | mace |
mace-torch>=0.3.15 |
| MatRIS | matris |
matris>=0.0.1 |
| MatterSim | mattersim |
mattersim>=1.2.1 |
| NequIP | nequip |
nequip>=0.17.0 |
| Nequix | nequix |
nequix>=0.4.3 |
| NewtonNet | newtonnet |
newtonnet>=2.0.0 (extra step needed; see note below) |
| ORB | orb |
orb-models>=0.5.5 |
| PET-MAD | petmad |
upet>=0.2.1 |
| PosEGNN | N/A | No installable package on any public index; see note below |
| SevenNet | sevennet |
sevenn>=0.12.0 |
| TACE | tace |
TACE>=0.1.0 |
| UMA | uma |
fairchem-core>=2.0.0 |
Extras Needing an Additional Install Step¶
EqNorm, HIENet, NewtonNet, and AlphaNet need torch-scatter (NewtonNet also needs torch-cluster), installed manually from PyG's wheel index before installing the extra. EqV2 also needs PyG extensions installed manually from that wheel index.
ALIGNN needs dgl instead, an undeclared dependency with no PyPI wheel for Python 3.12. Install it from DGL's own wheel indexes.
Run the install commands for each calculator in the order shown:
torch-scatter has no prebuilt wheel on PyPI, so it must be installed before materialsframework[eqnorm] — otherwise resolving eqnorm's dependency on it triggers a from-source build that fails outright (its setup.py imports torch before an isolated build environment has it available).
Linux x86_64 and macOS arm64 only
This combination doesn't resolve on Linux aarch64 because PyG doesn't publish wheels for these PyTorch 2.4 extensions. On that platform you need to build them from source yourself, following PyG's installation-from-source guide.
Non-Extra Calculators¶
EquFlashCalculator has no materialsframework extra. Its upstream GGNN package does not install the calculator's runtime dependencies, so add them explicitly.
The CPU commands below produce a fully importable EquFlashCalculator on Linux x86_64 and macOS arm64. Linux aarch64 requires source builds because PyG does not publish the matching torch_scatter and torch_sparse wheels.
uv pip install "GGNN @ git+https://github.com/SamsungDS/GGNN.git"
uv pip install fairchem-core==1.10.0
uv pip install torch-geometric e3nn cuequivariance==0.6.0 cuequivariance-torch==0.6.0
uv pip install torch_scatter==2.1.2 torch_sparse==0.6.18 \
--find-links https://data.pyg.org/whl/torch-2.4.1+cpu.html
uv pip install "scipy<1.17.0"
pip install "GGNN @ git+https://github.com/SamsungDS/GGNN.git"
pip install fairchem-core==1.10.0
pip install torch-geometric e3nn cuequivariance==0.6.0 cuequivariance-torch==0.6.0
pip install torch_scatter==2.1.2 torch_sparse==0.6.18 \
--find-links https://data.pyg.org/whl/torch-2.4.1+cpu.html
pip install "scipy<1.17.0"
GPTFFCalculator is only installable from its upstream git repository. That revision declares ase>=3.26,<3.29, while MaterialsFramework requires ase>=3.29. Installing GPTFF normally would therefore downgrade ASE and break MaterialsFramework's MD imports. The sequence below bypasses only GPTFF's dependency metadata, then installs its non-core runtime dependencies explicitly.
PosEGNNCalculator is not available on any public package index. Clone the repository, add its module directory to PYTHONPATH, and install the runtime dependencies that the module does not declare:
git clone --depth 1 https://github.com/IBM/materials.git
export PYTHONPATH="$PWD/materials/models/pos_egnn:$PYTHONPATH"
uv pip install torch==2.9.1 --index-url https://download.pytorch.org/whl/cpu
uv pip install torch_geometric torch_nl==0.3
uv pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.9.1+cpu.html --reinstall
git clone --depth 1 https://github.com/IBM/materials.git
export PYTHONPATH="$PWD/materials/models/pos_egnn:$PYTHONPATH"
pip install torch==2.9.1 --index-url https://download.pytorch.org/whl/cpu
pip install torch_geometric torch_nl==0.3
pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.9.1+cpu.html --force-reinstall
VASPCalculator is external and requires a separately installed licensed VASP binary. It wraps ASE's own Vasp calculator, so configuration (the command argument or the ASE_VASP_COMMAND/VASP_COMMAND/VASP_SCRIPT env vars, plus VASP_PP_PATH for pseudopotentials) follows ASE's conventions rather than anything MaterialsFramework-specific. See ASE's VASP calculator documentation for the full configuration reference.
Development Setup¶
To contribute to MaterialsFramework itself, rather than use it as a dependency, clone the repository and use uv sync directly. MaterialsFramework uses uv for dependency and environment management. Install it once:
Then clone the repository:
# Core (no ML extras)
uv sync
# Core + dev tools (ruff, ty, pytest, pre-commit)
uv sync --group dev
# Core + dev tools + selected MLIP extras
uv sync --group dev --extra chgnet --extra matgl --extra sevennet
If you synced alignn or eqv2, run the corresponding uv pip install commands from Extras Needing an Additional Install Step afterward.
For eqnorm, hienet, newtonnet, or alphanet, add --no-install-package torch-scatter (and, for newtonnet, --no-install-package torch-cluster) to the uv sync command itself, for example:
Then run the corresponding uv pip install torch/uv pip install torch-scatter commands from Extras Needing an Additional Install Step. Re-run those commands after a later uv sync if it removes or replaces those manually installed packages.
Running Tests¶
# Unit tests
uv run pytest -m "not integration and not slow" -v
# Integration tests
uv run pytest -m integration -v
Integration tests (@pytest.mark.integration) instantiate real ML calculators, download model weights on first run, and execute short relaxations on small structures. They are slow on first run but fast on subsequent runs once weights are cached.
Documentation¶
Then open http://localhost:8000.