File size: 5,567 Bytes
c25df3c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | ---
license: mit
tasks:
- materials-simulation
- molecular-dynamics
- energy-prediction
- force-prediction
- structure-relaxation
- fine-tuning
frameworks:
- pytorch
language:
- en
tags:
- OneScience
- MatterSim
- materials-science
- molecular-simulation
- machine-learning-potential
- graph-neural-network
- equivariant-neural-network
- inference
- fine-tuning
---
<p align="center">
<strong>
<span style="font-size: 30px;">MatterSim</span>
</strong>
</p>
# 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](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)
## 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
```bash
hf download --model OneScience-Sugon/Mattersim --local-dir ./mattersim
cd mattersim
```
### Install the Runtime Environment
**DCU environment**
```bash
# 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**
```bash
# 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
```bash
cd scripts
python single_point.py --checkpoint ../weight/mattersim-v1.0.0-1M.pth
```
```bash
cd scripts
python batch_inference.py --checkpoint ../weight/mattersim-v1.0.0-1M.pth
```
**Structure relaxation**
```bash
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**
```bash
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`:
```bash
cd scripts
# Edit train_data_path, checkpoint, and other fields in finetune_config.yaml
```
Single GPU:
```bash
python finetune.py --config finetune_config.yaml
```
Multi-GPU DDP:
```bash
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](https://github.com/microsoft/mattersim/blob/main/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.
|