OneScience-Group/MACE

MACE

Model Introduction

MACE is a machine-learning interatomic potential (MLIP) for molecular and materials systems. Built on an E(3)-equivariant graph neural network, it predicts the energies and forces of 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 uses an E(3)-equivariant graph neural network architecture and is trained with HDF5/XYZ data. It supports energy and force prediction and structure optimization for molecular and materials systems.

Use Cases

Use case	Description
Interatomic-potential training	Read HDF5/XYZ data with a standard configuration and train a MACE model
Distributed-training preflight	Check multi-GPU/multi-node settings and ensure that data paths and statistics are consistent
Validation-set evaluation	Report energy- and force-related error metrics on the validation set during training
Custom data migration	Adapt an existing configuration to your own HDF5/XYZ data and statistics file
Environment connectivity check	Use the preflight script to verify the OneScience MatChem environment, PyYAML, h5py, and data readability

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 for training.
• A CPU can be used for import checks and small-configuration connectivity tests, but full training 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 OneScience-Group/MACE 
cd mace

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

Training data is not bundled with this repository. Using the introductory DMC dataset as an example, download it from Hugging Face to data/ in the repository root:

hf download OneScience-Group/DMC --repo-type dataset

After downloading, the data is located at data/data/DMC/. scripts/demo/run.sh automatically sets the repository root as ONESCIENCE_DATASETS_DIR, so you do not need to set this variable manually for the paths in the configuration file to resolve.

Other configurations, such as ani1x_8dcu.yaml and water_*.yaml, require the corresponding datasets and adjusted data paths in the YAML files.

Training

Single GPU:

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

Multiple GPUs:

# Eight-GPU example; launch.launcher must be set to torchrun in the configuration
bash scripts/demo/run.sh --config scripts/demo/configs/ani1x_8dcu.yaml

SLURM:

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

Trained Weights

This repository does not currently include trained weights. You can obtain them by following the training procedure above.

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 MACE-related code comes from the MatChem examples in the OneScience project and refers to 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 research, please cite the original MACE paper, the relevant OneScience projects, and the datasets used.