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 --model OneScience-Sugon/MACE --local-dir ./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 --dataset OneScience-Sugon/DMC --local-dir ./data
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.