MACE

Overview

MACE is a reference implementation of machine-learning interatomic potentials based on higher-order equivariant message passing. It supports both building potentials from atomistic reference data and using pretrained foundation models for inference or fine-tuning. The repository combines predictive models with training, evaluation and calculator interfaces rather than providing a single fixed potential for every chemical system.

The documented training workflow accepts XYZ datasets, with options for separate validation and test sets, atomic reference energies, and configuration-specific label weights. It can accommodate datasets containing both bulk structures with stress labels and molecular configurations. For larger datasets, preprocessing produces HDF5 files for on-line loading. Training produces model checkpoints and diagnostic plots; the evaluation interface takes an XYZ configuration file and a saved model and writes an output XYZ file. ASE calculator examples demonstrate obtaining potential energies from pretrained models.

Model choice matters: MACE-MP targets materials, while MACE-OFF supports organic molecules, crystals and molecular liquids. Other listed families address additional domains, including electrostatics. The README cautions that MACE-MP raw DFT energies are not directly comparable with Materials Project energies that include compatibility corrections. Code and checkpoint licences must also be considered separately.

The project README identifies v0.3.x as the supported line during a v1.0 rewrite, with future code incompatibility and explicit checkpoint conversion planned. Documentation is described as partial, and the installation section lists specific PyTorch exclusions; these are source-stated constraints, not independently tested compatibility results.

Key Features

• Higher-order equivariant message-passing interatomic potentials, with configurable channel counts and angular feature orders.
• Training from XYZ reference datasets, including heterogeneous labels and configuration-specific stress weighting.
• XYZ-based model evaluation through `mace_eval_configs`, with a saved checkpoint and output configuration file.
• Pretrained foundation-model inference and fine-tuning, including materials-focused MACE-MP and organic-chemistry MACE-OFF families.
• ASE calculator interfaces for pretrained models, illustrated with potential-energy calculations.
• HDF5 preprocessing and on-line data loading for large datasets, plus distributed multi-GPU training support.

Use Cases

• Suggested evaluation: train a system-specific potential on reference configurations and assess energy and force errors on held-out structures.
• Suggested evaluation: assess a materials foundation model on representative bulk configurations, accounting for differences between raw DFT energies and corrected Materials Project energies.
• Suggested evaluation: explore MACE-OFF for organic molecule, crystal or liquid simulations after checking checkpoint scope and terms.
• Suggested evaluation: fine-tune a foundation model on a targeted dataset and compare held-out predictions with those of the starting checkpoint.

How to Use

1. Start with the repository README and documentation. Check the supported release line, migration notices and documented Python/PyTorch requirements before selecting an environment.
2. Follow the README installation section and PyTorch installation guidance. The documented package is mace-torch; the similarly named MACE package is unrelated.
3. Choose training from reference data or pretrained inference. Consult the materials releases or organic-model releases, checking domain coverage, reference theory and checkpoint-specific licensing.
4. Prepare XYZ training, validation and test configurations. Follow the README guidance on atomic reference energies and label weighting; use its HDF5 preprocessing workflow when on-line loading is needed.
5. Use the documented training, fine-tuning or ASE calculator examples. The training and evaluation tutorial provides a guided entry point.
6. Evaluate saved models with the documented mace_eval_configs interface. As an intended evaluation step, compare held-out predictions against reference labels before relying on the potential in simulations.