Model Introduction

MatterSim is a deep-learning interatomic potential model across elements, temperatures, and pressures proposed by Microsoft Research. It predicts energy 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 is based on a deep-learning architecture and is trained on multiple materials and molecular datasets. It performs energy and force prediction, structure relaxation, molecular dynamics, and custom-dataset fine-tuning for inorganic materials, molecules, and periodic systems.

Applicable Scenarios

Scenario	Description
Single-point energy/force prediction	Quickly predict energy and atomic forces for a given atomic structure
Batch structure inference	Perform batch energy/force prediction for multiple structures
Structure relaxation	Optimize atomic positions and unit-cell shape using FIRE/BFGS
Molecular dynamics	Run short-range MD sampling under the NVT ensemble
Custom data fine-tuning	Fine-tune a pre-trained MatterSim model on your own dataset
Environment connectivity check	Use the single-point/relaxation scripts to check the OneScience matchem environment, model loading, and CUDA/DCU availability

Usage Instructions

1. Using OneCode

You can try out intelligent one-click AI4S programming in the OneCode online environment:

Try intelligent one-click AI4S programming

2. Manual Installation and Usage

Hardware Requirements

GPU or DCU is recommended.
CPU can be used for import and small-configuration connectivity checks; full training and inference will be slow.
DCU users need to install DTK in advance. DTK 25.04.2 or above, or the OneScience-recommended version matching the current cluster, is suggested.

Download the Model Package

modelscope download --model OneScience/Mattersim --local_dir ./mattersim
cd mattersim

Install the Runtime Environment

DCU Environment

# Please 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

# Please 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 Description

By default, this repository only includes the example data file high_level_water.xyz, used for quickly verifying model loading, single-point inference, structure relaxation, molecular dynamics, and fine-tuning workflows. For other training data, please download it yourself and place it in the data/ directory.

Training Weights

The repository includes weight/mattersim-v1.0.0-1M.pth. All scripts also support specifying model weights via --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 weight 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

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

Fine-tuning

Edit the paths and parameters in scripts/finetune_config.yaml directly (e.g., train_data_path, checkpoint, etc.):

cd scripts
# Edit fields such as train_data_path and checkpoint 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

OneScience Official Information

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 example implementation in the OneScience project and references 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 scientific research, we recommend citing the original MatterSim paper, the relevant OneScience project information, and the sources of the datasets actually used.