DOCSEARCHbyAlgolia
Submit Docs

MatterSim

repository·main·Indexed 20 days ago

https://github.com/microsoft/mattersim

A deep learning atomistic model based on the M3GNet architecture for simulations across various elements, temperatures, and pressures. It provides pre-trained models (MatterSim-v1.0.0-1M and MatterSim-v1.0.0-5M) that function as forcefields in atomistic simulations. MatterSim integrates with the Atomic Simulation Environment (ASE) via MatterSimCalculator and includes specialized tools for batch structure relaxation (BatchRelaxer), phonon dispersion computation (PhononWorkflow), and model finetuning on custom datasets.

Tokens
25.5K
Snippets
75
Records
95
Agent score
70%

What's inside MatterSim

  1. Overview of MatterSim

    main
    MatterSim is a deep learning model designed for atomistic simulations. It simulates material properties across a wide range of elements, temperatures, and pressures. It is built using state-of-the-art deep learning techniques to provide high accuracy and efficiency in materials science research.

  2. What is MatterSim?

    main

    MatterSim is a large-scale pretrained deep learning model designed for efficient materials emulation and property prediction. It functions as a machine learning force field capable of simulating atomistic behavior across the periodic table, spanning temperatures from 0 to 5000 K and pressures up to 1000 GPa.

    Key capabilities include:

    • Predicting ground-state material structures and energetics.
    • Simulating behavior under realistic temperatures and pressures.
    • Serving as a platform for continuous learning via fine-tuning for specific levels of theory or direct structure-to-property predictions.

  3. Direct uses of MatterSim

    main

    MatterSim is intended for materials simulation and property prediction tasks. It provides an interface to the Atomic Simulation Environment (ASE). Common use cases include:

    • Direct prediction of energy, forces, and stress for given materials.
    • Phonon prediction using finite difference methods.
    • Molecular dynamics simulations.

  4. Available MatterSim-v1 Pre-trained Models

    main

    MatterSim currently offers two pre-trained models based on the M3GNet architecture:

    1. MatterSim-v1.0.0-1M: A mini version optimized for speed.
    2. MatterSim-v1.0.0-5M: A larger version optimized for higher accuracy.

    Note: More advanced, fully-supported versions and additional capabilities are available through Azure Quantum Elements.

  5. Install MatterSim from source code

    main

    To install from source, you must create a Conda environment from the provided environment.yaml and build the extensions. For faster installation, it is recommended to use mamba or micromamba along with the uv package manager.

    Note: The installation process may take a significant amount of time due to heavy dependencies.

    # Standard installation
conda env create -f environment.yaml
conda activate mattersim
pip install -e .
python setup.py build_ext --inplace

# Recommended faster installation using mamba and uv
mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .
python setup.py build_ext --inplace

  6. Install MatterSim from source

    main

    To install from source, clone the repository and use mamba (or micromamba) to create the environment, as conda may be slow with the provided environment.yaml. After activating the environment, use uv pip to install the package in editable mode.

    git clone git@github.com:microsoft/mattersim.git
cd mattersim
mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .

  7. Export MatterSim model for LAMMPS use

    main

    Before running simulations in LAMMPS, you must export the MatterSim checkpoint to a .pt file using the MatterSimMLIAP wrapper. You can choose between the mattersim-v1.0.0-1M or mattersim-v1.0.0-5M models. The checkpoint is automatically downloaded on the first use.

    from mattersim.lammps.mliap_wrapper import MatterSimMLIAP

# Choose your model: "mattersim-v1.0.0-1M" or "mattersim-v1.0.0-5M"
mliap = MatterSimMLIAP.from_checkpoint("mattersim-v1.0.0-1M", device="cpu")
mliap.save("mattersim-v1.0.0-1M-mliap.pt")

  8. Install prerequisites for compiling MatterSim documentation

    main

    To build the MatterSim documentation locally, you must install several Python packages and the pandoc system dependency. This includes sphinx with specific extensions for autodoc type hints, the Sphinx book theme, and copy buttons, as well as support for Markdown (recommonmark) and Jupyter Notebooks (nbsphinx, nbconvert).

    # sphinx
pip install sphinx sphinx-autodoc-typehints sphinx_book_theme sphinx-copybutton

# enable Markdown documentation in sphinx
pip install recommonmark

# enable python jupyter notebook in sphinx
pip install nbsphinx nbconvert

# install pandoc
conda install -c conda-forge pandoc

  9. Run LAMMPS simulations with MatterSim

    main

    To use the exported model in a LAMMPS input file, use the pair_style mliap unified command followed by the path to your .pt file.

    LAMMPS Input Example

    pair_style      mliap unified mattersim-v1.0.0-1M-mliap.pt
pair_coeff      * * Cu

    Execution Command (Single GPU)

    Run LAMMPS using the Kokkos package (-sf kk) and specifying the GPU count (-k on g 1):

    lmp -in input.in -k on g 1 -sf kk -pk kokkos newton on neigh half

  10. Build and use the MatterSim-LAMMPS Docker image

    main

    The easiest way to get started is using the provided Dockerfile, which includes LAMMPS with Kokkos GPU support, CUDA-aware MPI (UCX + OpenMPI), and MatterSim pre-installed.

    1. Build the image

    Set KOKKOS_ARCH to match your GPU architecture:

    • VOLTA70 (V100)
    • AMPERE80 (A100)
    • AMPERE86 (RTX A6000, A5000, A4000)
    • HOPPER90 (H100, H200)
    docker build -t mattersim-lammps \
    --build-arg KOKKOS_ARCH=AMPERE80 \
    -f dockerfiles/lammps.Dockerfile .

    2. Run simulations

    To use your own input files, mount your current directory to /work inside the container:

    Single GPU:

    docker run --gpus all -it -v $(pwd):/work -w /work mattersim-lammps \
    lmp -in input.in -k on g 1 -sf kk \
        -pk kokkos newton on neigh half \
        -var MODEL_PATH /path/to/mattersim-v1.0.0-5M-mliap.pt

    Multi-GPU (4 GPUs):

    mpirun -np 4 --mca pml ucx --mca osc ucx \
    lmp -in input.in \
    -k on g 4 -sf kk \
    -pk kokkos newton on neigh half gpu/aware on \
    comm/pair/forward device comm/pair/reverse device \
    -var MODEL_PATH /path/to/mattersim-v1.0.0-5M-mliap.pt

  11. Run Molecular Dynamics simulations with TorchSim

    main

    TorchSim supports various integrators for molecular dynamics. Use ts.integrate to run simulations.

    Available integrators in ts.Integrator:

    • NVE: ts.Integrator.nve (microcanonical ensemble)
    • NVT Langevin: ts.Integrator.nvt_langevin (Langevin thermostat)
    • NVT Nosé–Hoover: ts.Integrator.nvt_nose_hoover (Nosé–Hoover thermostat)
    • NPT Langevin: ts.Integrator.npt_langevin_isotropic (Langevin barostat, isotropic)
    • NPT Nosé–Hoover: ts.Integrator.npt_nose_hoover_isotropic (Nosé–Hoover barostat, isotropic)
    import torch
import torch_sim as ts
from ase.build import bulk
from mattersim.torchsim import get_torchsim_wrapper

device = "cuda" if torch.cuda.is_available() else "cpu"

# Create the wrapper
wrapper = get_torchsim_wrapper(potential="mattersim-v1.0.0-1M", device=device)

# Set up the structure
si = bulk("Si", "diamond", a=5.43)
state = ts.initialize_state([si], device=device)

# Run NVT MD at 300 K for 1000 steps
final_state = ts.integrate(
    system=state,
    model=wrapper,
    integrator=ts.Integrator.nvt_langevin,
    n_steps=1000,
    temperature=300.0,
    timestep=1e-3,
    pbar=True,
)

# Convert back to ASE Atoms
final_atoms = final_state.to_atoms()[0]

  12. Install MatterSim via PyPI

    main

    You can install MatterSim using pip. It is recommended to use a clean conda environment with Python 3.12 to avoid conflicts.

    Setup Environment

    conda create -n mattersim python=3.12
conda activate mattersim

    Install Package

    pip install mattersim

    To install the latest development version from GitHub:

    pip install git+https://github.com/microsoft/mattersim.git