| --- |
| license: mit |
| tasks: |
| - materials-simulation |
| - molecular-dynamics |
| - energy-prediction |
| - force-prediction |
| frameworks: |
| - pytorch |
| language: |
| - en |
| tags: |
| - OneScience |
| - MACE |
| - machine-learning-potential |
| - molecular-simulation |
| - materials-computing |
| - graph-neural-network |
| - equivariant-neural-network |
| - training |
| - inference |
| datasets: |
| - OneScience-Group/DMC |
| - OneScience-Group/ANI1x |
| - OneScience-Group/water |
| - OneScience-Group/nanotube |
| --- |
| |
| <p align="center"> |
| <strong> |
| <span style="font-size: 30px;">MACE</span> |
| </strong> |
| </p> |
| |
| # 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](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home) |
|
|
| ## 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 |
|
|
| ```bash |
| hf download OneScience-Group/MACE |
| cd mace |
| ``` |
|
|
| ### 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 |
|
|
| 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: |
|
|
| ```bash |
| 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 |
| bash scripts/demo/run.sh --config scripts/demo/configs/DMC.yaml |
| ``` |
|
|
| Multiple GPUs: |
|
|
| ```bash |
| # 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 |
| 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](https://github.com/ACEsuit/mace/blob/main/LICENSE). |
| - If you use MACE training results in research, please cite the original MACE paper, the relevant OneScience projects, and the datasets used. |
|
|
