MatterSim

Common errors

• ImportError: cannot import name 'Filter' from 'ase.optimize.precon'

  cause The `Filter` class was moved or removed in `ase` version 3.27+. Older MatterSim versions are not compatible with this change.
  fix Upgrade `mattersim` to version `1.2.1` or newer: `pip install --upgrade mattersim`.

• ModuleNotFoundError: No module named 'mattersim.utils.stress'

  cause Incorrect or broken import path for internal stress calculation utilities in MatterSim versions prior to 1.2.2.
  fix Upgrade `mattersim` to version `1.2.2` or newer: `pip install --upgrade mattersim`.

• ERROR: Package 'mattersim' requires 'torch<X.Y.Z', but you have 'torch A.B.C'.

  cause Your installed `torch` version conflicts with the strict version requirement of an older `mattersim` release.
  fix Upgrade `mattersim` to `1.1.2` or newer: `pip install --upgrade mattersim`. Alternatively, downgrade your `torch` version to satisfy the `mattersim` requirement if upgrading `mattersim` is not an option.

Warnings

• breaking Upgrading Atomic Simulation Environment (ASE) to version 3.27 or newer may cause import errors related to `Filter` or API changes in optimizers when using older MatterSim versions.
  Fix: Upgrade MatterSim to version 1.2.1 or newer to ensure compatibility with ASE 3.27+.
• gotcha Older MatterSim versions (prior to 1.2.1) had compatibility issues with `setuptools` version 82 or higher, leading to import failures.
  Fix: Ensure MatterSim is updated to version 1.2.1 or newer. If you must use an older MatterSim version, you might need to downgrade `setuptools`.
• gotcha MatterSim versions prior to 1.2.2 had an incorrect import path for stress calculation utilities, which could lead to `ImportError` when attempting to compute stress.
  Fix: Upgrade MatterSim to version 1.2.2 or newer to resolve the `stress` calculation import issue.
• deprecated Older MatterSim versions (prior to 1.1.2) had strict `torch` version pinning (`torch<2.5.0`), which could conflict with other libraries or newer hardware/software setups.
  Fix: Upgrade MatterSim to version 1.1.2 or newer to benefit from unpinned `torch` dependency, allowing greater flexibility in your environment. If staying on an older version, ensure your `torch` version matches the strict requirement.

Install

• pip install mattersim Install stable version

Imports

• MatterSimModel

  from mattersim.models import MatterSimModel

• MatterSimCalculator

  from mattersim.calc import MatterSimCalculator

Quickstart

This quickstart demonstrates how to load a pre-trained MatterSim model, initialize a calculator, attach it to an ASE Atoms object, and perform a basic energy minimization. It relies on `torch.hub.load` for convenient model retrieval.

import torch
from ase import Atoms
from ase.optimize import LBFGS
from mattersim.models import MatterSimModel
from mattersim.calc import MatterSimCalculator

# 1. Load a pre-trained MatterSim model
# Using torch.hub.load handles model downloading automatically
model = torch.hub.load("microsoft/mattersim", "mattersim_model_v1_0")

# 2. Initialize MatterSimCalculator
# Use 'cuda' if a GPU is available, otherwise 'cpu'
calculator = MatterSimCalculator(model=model, device="cpu")

# 3. Create an ASE Atoms object and set the calculator
atoms = Atoms("H2O", positions=[[0, 0, 0], [0, 1, 0], [0.5, -0.5, 0]], cell=[10,10,10], pbc=False)
atoms.set_calculator(calculator)

# 4. Perform an energy minimization using an ASE optimizer
print(f"Initial energy: {atoms.get_potential_energy():.4f} eV")

optimizer = LBFGS(atoms)
optimizer.run(fmax=0.01) # Relax until forces are below 0.01 eV/Å

print(f"Final energy: {atoms.get_potential_energy():.4f} eV")
print(f"Relaxed positions:\n{atoms.get_positions()}")