MatterSim: A Deep Learning Force Field for Materials Simulation Across Elements, Temperatures and Pressures

What MatterSim Is and the Problem It Addresses

First-principles methods such as density functional theory can predict material properties from quantum mechanics alone, but each single-point energy calculation on a moderately sized unit cell takes minutes to hours on a compute cluster. Atomistic simulations that require millions of force evaluations (molecular dynamics, phonon calculations, structural relaxations) are therefore prohibitively expensive for large-scale screening. Machine learning force fields aim to match the accuracy of DFT at a fraction of the computational cost by learning the potential energy surface from DFT-generated training data. MatterSim is one such model, trained across a wide range of chemical compositions, temperatures and pressures so that it generalizes beyond the narrow material families that most specialized force fields cover. It implements the ASE Calculator interface, which means any simulation workflow already using ASE can substitute MatterSim without code changes beyond setting the calculator object.

Model Architecture and Pretrained Checkpoints

MatterSim v1 uses the M3GNet graph neural network architecture. Two pretrained checkpoints are shipped in the pretrained_models/ directory. MatterSim-v1.0.0-1M is the smaller variant, with approximately one million parameters, designed for faster inference. MatterSim-v1.0.0-5M is the larger variant, with approximately five million parameters, offering higher accuracy at greater computational cost. The 1M checkpoint loads by default. To switch to the 5M checkpoint, pass the load_path argument explicitly when creating the calculator. Both checkpoints were trained on data generated through the workflow described in the MatterSim manuscript (arXiv 2405.04967). More advanced pretrained versions with additional capabilities are available through Azure Quantum Elements, the Microsoft commercial materials platform, separate from this open-source release.

Installing MatterSim

MatterSim requires Python 3.12 or later. The recommended install path uses a clean conda environment:

conda create -n mattersim python=3.12
conda activate mattersim

Then install from PyPI:

pip install mattersim

For installation from source:

git clone [email protected]:microsoft/mattersim.git
cd mattersim
mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .

The README recommends mamba or micromamba over conda for resolving the environment.yaml dependencies, noting that conda can be significantly slower with this dependency set. The package depends on PyTorch 2.2.0 or later, torch_geometric, e3nn and pymatgen, among other scientific Python libraries.

Running a Minimal Calculation

MatterSim integrates with ASE (Atomic Simulation Environment) through a calculator class. The following example creates a silicon bulk structure, attaches the MatterSim calculator and queries energy, forces and stress:

import torch
from loguru import logger
from ase.build import bulk
from mattersim.forcefield import MatterSimCalculator

device = "cuda" if torch.cuda.is_available() else "cpu"
si = bulk("Si", "diamond", a=5.43)
si.calc = MatterSimCalculator(device=device)
logger.info(f"Energy (eV)                 = {si.get_potential_energy()}")
logger.info(f"Forces of first atom (eV/A) = {si.get_forces()[0]}")

To use the 5M checkpoint instead of the default 1M:

MatterSimCalculator(load_path="MatterSim-v1.0.0-5M.pth", device=device)

The README warns macOS users with Apple Silicon that numerical instability can occur with the MPS backend and recommends using the CPU device on Mac.

Fine-Tuning on Custom Datasets

MatterSim ships a fine-tuning script that accepts a custom dataset in the XYZ file format. The script uses torchrun for distributed training. A minimal fine-tune run on a single GPU:

torchrun --nproc_per_node=1 src/mattersim/training/finetune_mattersim.py --load_model_path mattersim-v1.0.0-1m --train_data_path tests/data/high_level_water.xyz

Fine-tuning is the recommended path for applications involving surfaces, interfaces or materials families underrepresented in the training data. The model card in MODEL_CARD.md documents the responsible AI transparency information for the model, and CONTRIBUTING.md describes how to report issues or engage with the team at [email protected].

Available Notebooks, Dockerfiles and the Training Data Format

The repository ships a notebooks/ directory with Jupyter notebooks demonstrating property calculations, phonon computations and molecular dynamics runs. These are practical starting points for researchers who want to understand how to integrate MatterSim into a simulation pipeline before writing their own scripts. A dockerfiles/ directory provides container definitions for running MatterSim without managing the Python environment manually, which is useful on shared compute clusters where Python environment management is constrained. The data/ directory holds training data samples in the XYZ format used by the fine-tuning script: researchers can use these as a template for formatting their own custom datasets before running fine-tuning. For phonon calculations MatterSim depends on phonopy and phono3py, which are included in the default dependencies but require additional post-processing to interpret results correctly. The CITATION.cff file in the repository root provides the structured citation metadata for use with reference management tools, supplementing the BibTeX entry in the README for the arXiv preprint. The documentation site at microsoft.github.io/mattersim provides reference material beyond what the README covers.

Limitations and What MatterSim Is Not Suitable For

MatterSim-v1 is trained and validated for bulk materials. The README explicitly states that applications involving surfaces, interfaces or properties influenced by long-range interactions may produce qualitatively plausible but quantitatively unreliable results without fine-tuning on system-specific data. Molecular dynamics of liquids, defect formation energies and surface adsorption energies all fall into this category. MatterSim is not a general molecular force field for organic chemistry or biochemistry. The pyproject.toml lists Cython as a build requirement (for a three-body indices extension), which means a C compiler must be present for source installation. The package version is managed dynamically through setuptools_scm, so users installing from source must have the git history available for version detection to work correctly. A note for macOS users: the README warns that the MPS backend on Apple Silicon can produce numerical instability, and recommends using the CPU device on Mac instead. This limits practical performance on Apple hardware compared to Linux with a CUDA-capable GPU.

Editorial conclusion

Computational materials scientists who need faster energy and force evaluations than density functional theory provides, and who work primarily with bulk crystalline materials, are the primary audience. MatterSim-v1 is not validated for surfaces, interfaces or systems where long-range interactions dominate: the README states that quantitative results in those cases are unreliable without fine-tuning. Teams doing production research should cite the exact checkpoint name (MatterSim-v1.0.0-1M or MatterSim-v1.0.0-5M) in any paper, not the generic model name, as the README requires for reproducibility.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/mattersim on GitHub
3. Project website
4. README
5. Releases