{"id":8305,"library":"mattersim","title":"MatterSim","description":"MatterSim is a deep learning atomistic model developed by Microsoft, designed for simulating materials across various elements, temperatures, and pressures. It provides a flexible framework for energy, force, and stress calculations, and integrates with the Atomic Simulation Environment (ASE). The library is actively maintained with frequent patch releases addressing compatibility and bug fixes, typically on major versions like 1.x.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/microsoft/mattersim","tags":["physics","materials science","deep learning","simulation","DFT","ASE","atomistics"],"install":[{"cmd":"pip install mattersim","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core integration for atomistic simulations and optimization.","package":"ase","optional":false},{"reason":"Underlying deep learning framework for model execution.","package":"torch","optional":false},{"reason":"Fundamental package for numerical computing.","package":"numpy","optional":false},{"reason":"Scientific computing library, often used for optimizers and utilities.","package":"scipy","optional":false}],"imports":[{"symbol":"MatterSimModel","correct":"from mattersim.models import MatterSimModel"},{"symbol":"MatterSimCalculator","correct":"from mattersim.calc import MatterSimCalculator"}],"quickstart":{"code":"import torch\nfrom ase import Atoms\nfrom ase.optimize import LBFGS\nfrom mattersim.models import MatterSimModel\nfrom mattersim.calc import MatterSimCalculator\n\n# 1. Load a pre-trained MatterSim model\n# Using torch.hub.load handles model downloading automatically\nmodel = torch.hub.load(\"microsoft/mattersim\", \"mattersim_model_v1_0\")\n\n# 2. Initialize MatterSimCalculator\n# Use 'cuda' if a GPU is available, otherwise 'cpu'\ncalculator = MatterSimCalculator(model=model, device=\"cpu\")\n\n# 3. Create an ASE Atoms object and set the calculator\natoms = Atoms(\"H2O\", positions=[[0, 0, 0], [0, 1, 0], [0.5, -0.5, 0]], cell=[10,10,10], pbc=False)\natoms.set_calculator(calculator)\n\n# 4. Perform an energy minimization using an ASE optimizer\nprint(f\"Initial energy: {atoms.get_potential_energy():.4f} eV\")\n\noptimizer = LBFGS(atoms)\noptimizer.run(fmax=0.01) # Relax until forces are below 0.01 eV/Å\n\nprint(f\"Final energy: {atoms.get_potential_energy():.4f} eV\")\nprint(f\"Relaxed positions:\\n{atoms.get_positions()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade MatterSim to version 1.2.1 or newer to ensure compatibility with ASE 3.27+.","message":"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.","severity":"breaking","affected_versions":"<1.2.1"},{"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`.","message":"Older MatterSim versions (prior to 1.2.1) had compatibility issues with `setuptools` version 82 or higher, leading to import failures.","severity":"gotcha","affected_versions":"<1.2.1"},{"fix":"Upgrade MatterSim to version 1.2.2 or newer to resolve the `stress` calculation import issue.","message":"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.","severity":"gotcha","affected_versions":"<1.2.2"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.1.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade `mattersim` to version `1.2.1` or newer: `pip install --upgrade mattersim`.","cause":"The `Filter` class was moved or removed in `ase` version 3.27+. Older MatterSim versions are not compatible with this change.","error":"ImportError: cannot import name 'Filter' from 'ase.optimize.precon'"},{"fix":"Upgrade `mattersim` to version `1.2.2` or newer: `pip install --upgrade mattersim`.","cause":"Incorrect or broken import path for internal stress calculation utilities in MatterSim versions prior to 1.2.2.","error":"ModuleNotFoundError: No module named 'mattersim.utils.stress'"},{"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.","cause":"Your installed `torch` version conflicts with the strict version requirement of an older `mattersim` release.","error":"ERROR: Package 'mattersim' requires 'torch<X.Y.Z', but you have 'torch A.B.C'."}]}