MatterSim: A Pretrained M3GNet Potential That Ships Two Checkpoints and a Finetune Script

What MatterSim replaces, and for whom

The project is a machine-learning force field, or MLFF, distributed as an ASE calculator. The problem it addresses is the cost of atomistic simulation: instead of running density functional theory for every ionic step, you load a pretrained neural network and get energies, forces and stresses at a fraction of the cost. MatterSim-v1 is built on the M3GNet architecture and trained on data generated through the workflows described in the associated arXiv preprint, 2405.04967. The intended user is a computational materials scientist who already works with ASE and wants a potential that covers many elements without training a model from scratch. The README is explicit that MatterSim-v1 targets bulk materials. Anyone simulating slabs, grain boundaries, or anything where long-range interactions dominate is outside the design envelope, and the project says so rather than leaving you to discover it.

Two checkpoints, one architecture, an explicit accuracy and speed trade

The repository ships two pretrained files, MatterSim-v1.0.0-1M.pth and MatterSim-v1.0.0-5M.pth. The README describes the 1M version as a mini model that is faster to run and the 5M version as larger and more accurate. The 1M checkpoint is loaded by default, so a user who never reads the model section will silently get the smaller model. Switching is done through the load_path argument of the calculator, for example MatterSimCalculator(load_path="MatterSim-v1.0.0-5M.pth", device=device). That default matters for reproducibility. If two people run the same script and only one of them set load_path, they are comparing different models. The README also asks users to name the exact checkpoint in publications rather than writing MatterSim generically, and gives the phrasing "This study was conducted using MatterSim-v1.0.0-1M" as an acceptable form. Treat that as a hard requirement on your methods section, not a courtesy.

How the calculator plugs into ASE

The integration point is MatterSimCalculator, which you assign to the calc attribute of an ASE Atoms object. From there the standard ASE accessors work: get_potential_energy(), get_forces() and get_stress(voigt=False). The README's minimal test builds a diamond silicon cell with bulk("Si", "diamond", a=5.43) and prints energy, energy per atom, the forces on the first atom, and the stress tensor in both eV/A^3 and GPa, converting with the ase.units.GPa constant. Device selection is left to the caller: the example uses device = "cuda" if torch.cuda.is_available() else "cpu". There is no separate CLI for inference and no server component. The data flow is ordinary ASE, so any script, optimizer or molecular dynamics driver that already speaks ASE can drive this potential without modification. That is the main reason to prefer it over a standalone simulation package: the surrounding tooling is already written.

Installation, and the conda resolution warning worth heeding

The prerequisite is Python 3.12 or newer. The shortest path is pip install mattersim, with pip install git+https://github.com/microsoft/mattersim.git if you want the latest unreleased state. The README suggests creating a clean conda environment first to avoid package conflicts, which is reasonable given the PyTorch dependency chain. For source installs the project is more opinionated: the README carries a warning that users should install with mamba or micromamba because conda can be significantly slower when resolving the dependencies in environment.yaml. The source path is git clone, cd mattersim, then mamba env create -f environment.yaml, mamba activate mattersim, and uv pip install -e . Note that the editable install goes through uv rather than pip, so uv needs to be available. There is one platform caveat stated plainly for macOS on Apple Silicon: the MPS backend may be numerically unstable, and the README recommends using the CPU device there instead. That is a real constraint, not a footnote, because it removes GPU acceleration for a whole class of laptops.

Finetuning is a torchrun script, not a Python API

The finetune path is exposed as a script rather than a documented library call. The README's minimal example is a single command: 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. Two things stand out. First, the training data is an extended XYZ file, so your custom dataset has to be prepared in that format with the energies and forces the trainer expects. Second, the README defers the details to the documentation site and gives no description of hyperparameters, loss weighting, train/validation splitting or convergence criteria. That is the thinnest part of the supplied material. If your plan depends on finetuning to escape the bulk-materials limitation, budget time for reading the full documentation and the training source under src/mattersim/training, because the README alone does not tell you how to judge whether a finetune succeeded.

The documented limitation is the whole decision

MatterSim-v1 is scoped to bulk materials, and the README states that simulations involving surfaces, interfaces, or properties influenced by long-range interactions may be qualitatively accurate but are not suitable for quantitative analysis. It then recommends finetuning for those cases. Read that carefully: the escape hatch is not a flag, it is retraining on data that covers your regime. A surface energy calculated with the stock 5M checkpoint is not a number you should put in a paper. The same caution applies to any property where electrostatics beyond the model's cutoff dominate. There is also a versioning trap. The README distinguishes MatterSim-v1 from what it calls more advanced and fully-supported pretrained versions available in Azure Quantum Elements, which means the open repository is not the full product line and the checkpoints here may lag the commercial offering. If your project needs those additional capabilities, the open weights are not the answer.

Where a classical potential still wins

The obvious alternative for the same job is a classical interatomic potential such as an embedded-atom method or Tersoff-style parameterization, run through the same ASE interface. The difference is in where the accuracy comes from. A classical potential encodes physics in a hand-fitted functional form with a small number of parameters, so it extrapolates predictably and runs extremely fast, but it is typically parameterized for a narrow set of elements and phases and transfers poorly outside them. MatterSim instead learns the energy surface from a broad training set spanning elements, temperatures and pressures, which is what lets one checkpoint handle many compositions. The trade is transparency and cost: you cannot inspect why the network produced a given force, and inference is far heavier than evaluating a pair potential. For a large-scale screening run over millions of configurations where only relative ordering matters, a classical potential may still be the better tool. For a system with no existing parameterization, the learned model is the more practical starting point.

Licence, maintenance and what to pin

The code is MIT licensed, which permits commercial and academic use with the usual requirement to retain the copyright and permission notice. The pretrained weights are distributed in the same repository, but the README does not state a separate licence for the checkpoints, and the trademark section notes that use of Microsoft marks in modified versions carries additional conditions. If you plan to redistribute a finetuned checkpoint, that distinction is worth confirming with the project before you ship. On maintenance, the release cadence in the supplied material is roughly one patch every two to three weeks through the 1.2.x line, with v1.2.5 dated 2026-05-28 and the repository's last push in August 2026. Nothing in the material indicates a deprecation or a migration guide, so the practical cost is checkpoint discipline: record which .pth file produced which numbers, and re-run your reference system after any version bump. The README's own request to cite the exact checkpoint is the cheapest version of that discipline you can adopt.

Editorial conclusion

Adopt MatterSim if you need a quick ASE-compatible potential for bulk crystalline or amorphous systems and you are willing to pin and cite an exact checkpoint such as MatterSim-v1.0.0-5M. Do not adopt it as a drop-in replacement for surface, interface or long-range electrostatics work, since the README states those results are not suitable for quantitative analysis. Before committing, verify that your Python is at least 3.12, confirm the checkpoint file you intend to use, and reproduce the silicon bulk example end to end on your own hardware so you know which device backend is actually being exercised.

Official sources

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