OneScience-Group/MatterSim

MatterSim

Model Introduction

MatterSim is a deep-learning interatomic potential developed by Microsoft Research for a broad range of elements, temperatures, and pressures. It predicts energies and forces for inorganic materials, molecules, and periodic systems.

Paper: MatterSim: A deep-learning atomistic model across elements, temperatures, and pressures
Reference implementation: https://github.com/microsoft/mattersim

Model Description

MatterSim uses a deep-learning architecture trained on multiple materials and molecular datasets. It supports energy and force prediction, structure relaxation, molecular dynamics, and fine-tuning on custom datasets for inorganic materials, molecules, and periodic systems.

Use Cases

Use case	Description
Single-point energy/force prediction	Quickly predict the energy and atomic forces of a given atomic structure
Batch structure inference	Predict energies and forces for multiple structures in a batch
Structure relaxation	Optimize atomic positions and cell shape with FIRE/BFGS
Molecular dynamics	Run short MD sampling in the NVT ensemble
Fine-tuning on custom data	Fine-tune a pretrained MatterSim model on your own dataset
Environment connectivity check	Use the single-point and relaxation scripts to verify the OneScience MatChem environment, model loading, and CUDA/DCU availability

Usage

1. Using OneCode

Try intelligent, one-click AI4S programming in the OneCode online environment:

Try intelligent, one-click AI4S programming

2. Manual Installation and Usage

Hardware requirements

• A GPU or DCU is recommended.
• A CPU can be used for import checks and small-configuration connectivity tests, but full training and inference will be slow.
• DCU users must install DTK in advance. DTK 25.04.2 or later, or the OneScience-recommended version matching the current cluster, is recommended.

Download the Model Package

hf download --model OneScience-Group/Mattersim --local-dir ./mattersim
cd mattersim

Install the Runtime Environment

DCU environment

# Activate DTK and conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
# uv installation is also supported
pip install onescience[matchem-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai

GPU environment

# Activate conda first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
# uv installation is also supported
pip install onescience[matchem-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai

Training Data

By default, this repository only includes the high_level_water.xyz sample data for quickly validating model loading, single-point inference, structure relaxation, molecular dynamics, and fine-tuning workflows. Download any additional training data separately and place it in data/.

Trained Weights

The repository includes weight/mattersim-v1.0.0-1M.pth. All scripts also accept a custom model weight through --checkpoint.

Inference

cd scripts
python single_point.py --checkpoint ../weight/mattersim-v1.0.0-1M.pth

cd scripts
python batch_inference.py --checkpoint ../weight/mattersim-v1.0.0-1M.pth

Structure relaxation

cd scripts
python relax.py --checkpoint ../weight/mattersim-v1.0.0-1M.pth --device cuda

The default checkpoint is ../weight/mattersim-v1.0.0-1M.pth.

Molecular dynamics

cd scripts
python md.py --checkpoint ../weight/mattersim-v1.0.0-1M.pth --device cuda

This script also uses ../weight/mattersim-v1.0.0-1M.pth by default.

Fine-Tuning

Edit the paths and parameters in scripts/finetune_config.yaml, including train_data_path and checkpoint:

cd scripts
# Edit train_data_path, checkpoint, and other fields in finetune_config.yaml

Single GPU:

python finetune.py --config finetune_config.yaml

Multi-GPU DDP:

torchrun --nproc_per_node=4 finetune.py --config finetune_config.yaml

Official OneScience Resources

Platform	OneScience Main Repository	Skills Repository
Gitee	https://gitee.com/onescience-ai/onescience	https://gitee.com/onescience-ai/oneskills
GitHub	https://github.com/onescience-ai/OneScience	https://github.com/onescience-ai/oneskills

---

Citation and License

• The MatterSim-related code comes from the MatChem examples in the OneScience project and refers to the upstream MatterSim project (https://github.com/microsoft/mattersim). The upstream MatterSim code is released under the MIT License.
• If you use MatterSim training or inference results in research, please cite the original MatterSim paper, the relevant OneScience projects, and the datasets used.