Library / SDK
microsoft/mattersim avatar
microsoft/mattersim

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

MatterSim: A deep learning atomistic model across elements, temperatures and pressures.

610 stars102 forksPythonMIT

At a glance

What is it?
MatterSim is Microsoft's MIT-licensed machine-learning force field for bulk materials, distributed as an ASE calculator with 1M and 5M parameter checkpoints. It is easy to run and honest about its scope, but the README itself warns that surfaces, interfaces and long-range effects are outside what the pretrained model should be trusted for quantitatively.
Who is it for?
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.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 12 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • microsoft/mattersim610 ★ · +16
Star history
Repository2026-09-112026-11-15
microsoft/mattersim594610

16 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

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. 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 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. 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.

Frequently asked questions

Which MatterSim checkpoint should I use?

Two are shipped, a mini version and a larger one, both based on the M3GNet architecture. The 1M version is the default and runs faster; the 5M version is more accurate. You switch by passing the load path to the calculator, and the project asks you to name the exact checkpoint in anything you publish.

Can MatterSim run on a Mac with Apple Silicon?

Yes, with a caveat. The documentation warns about potential numerical instability with the MPS backend on Apple Silicon and recommends using the CPU device on a Mac instead. Everything else in the usage path is the standard calculator interface attached to an atoms object.

What does MatterSim not work well for?

It is designed for atomistic simulations of bulk materials. For surfaces, interfaces, or properties influenced by long-range interactions, the results may be qualitatively accurate but are not suitable for quantitative analysis, and the recommendation is to fine-tune for the specific application.

How do I install MatterSim from source?

Clone the repository and create the environment with mamba or micromamba rather than conda, which the documentation warns can be much slower at resolving the environment file. Then create the environment, activate it, and do an editable install with uv pip from the repository root.

How do I finetune a MatterSim model?

With the shipped script launched through torchrun, passing the path of the model to start from and the path of your training data. The README example launches on a single process and points at a water fixture from the repository's own test data, so it is a smoke test rather than a real training run.

Official sources

  1. License: MIT
  2. microsoft/mattersim on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/microsoft-mattersim.svg)](https://hysenlabs.com/projects/microsoft-mattersim)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/microsoft-mattersim.svg)](https://hysenlabs.com/projects/microsoft-mattersim)

Was this useful?