Model Introduction

MACE is a machine-learning interatomic potential (MLIP) model for molecular and materials systems, built on E(3)-equivariant graph neural networks. It predicts energy and forces for atomic structures.

Paper: MACE: Higher order equivariant message passing neural networks for fast and accurate force fields
Reference implementation: https://github.com/ACEsuit/mace

Model Description

MACE is based on an E(3)-equivariant graph neural network architecture and is trained on HDF5/XYZ format data. It performs energy and force prediction and structure optimization for molecular and materials systems.

Applicable Scenarios

Scenario	Description
Interatomic potential training	Train a MACE model using standard configurations that read HDF5/XYZ data
Distributed training pre-check	Check multi-GPU/multi-node training configuration, data paths, and statistics consistency
Validation-set evaluation	Output energy- and force-related error metrics on the validation set during training
Custom data migration	Replace the existing HDF5/XYZ data and statistics files with your own data
Environment connectivity check	Use the pre-check script to verify the OneScience matchem environment, pyyaml, h5py, and data readability

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 for training.
CPU can be used for import and small-configuration connectivity checks; full training 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/MACE --local_dir ./mace
cd mace

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

This repository does not include built-in training data. Taking the DMC starter dataset as an example, download it from ModelScope and place it under data/ in the repository root:

modelscope download --dataset OneScience/DMC --local_dir ./data

After downloading, the data path will be data/data/DMC/. scripts/demo/run.sh automatically uses the repository root as ONESCIENCE_DATASETS_DIR, so there is no need to manually set this variable to match the paths in the configuration file.

For other configurations (e.g., ani1x_8dcu.yaml, water_*.yaml, etc.), download the corresponding datasets and adjust the data paths in the YAML file.

Training

Single-GPU:

bash scripts/demo/run.sh --config scripts/demo/configs/DMC.yaml

Multi-GPU:

# Taking 8 GPUs as an example; launch.launcher in the config should be torchrun
bash scripts/demo/run.sh --config scripts/demo/configs/ani1x_8dcu.yaml

SLURM submission:

bash scripts/demo/run.sh --config scripts/demo/configs/ani1x_8dcu.yaml --submit

Training Weights

This repository currently does not include built-in trained weights. Weights can be obtained through the training steps above.

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 MACE-related code comes from the matchem example implementation in the OneScience project and references the upstream MACE project (https://github.com/ACEsuit/mace). The upstream MACE code is released under the MIT License.
If you use MACE training results in scientific research, we recommend citing the original MACE paper, the relevant OneScience project information, and the sources of the datasets actually used.