mace-training

MACE Training

Description

This skill covers the full workflow for training MACE (Message-passing Atomic Cluster Expansion) machine-learned interatomic potentials: DFT dataset preparation in extxyz format, isolated atom energy handling, train/validation/test splitting, model architecture selection, loss weighting, training execution, validation error analysis, and deployment to ASE and LAMMPS. Invoke this skill when building a new MACE model from DFT reference data, when diagnosing training failures, or when deciding whether MACE or another MLP architecture is appropriate for a given application.

Domain Context

MACE is an equivariant graph neural network potential that combines two theoretical frameworks: the Atomic Cluster Expansion (ACE) body-ordered basis and E(3)-equivariant message passing. The key physical insight is that the potential energy surface must be invariant to rotations, reflections, and translations of the entire system, while forces — being vectors — must transform equivariantly under rotations. MACE enforces this by representing atomic features as geometric tensors (irreducible representations of SO(3)) and contracting them via Clebsch-Gordan tensor products.

Practical consequences of this architecture:

• Higher body order per layer: A single MACE interaction block effectively encodes higher-body-order interactions than a standard message-passing layer, because the tensor product at each node combines information from multiple neighbors simultaneously. This allows MACE to reach DFT accuracy with fewer layers than SchNet or DimeNet.
• Data efficiency: Equivariance acts as a physical inductive bias. A model that does not need to learn rotational symmetry from data requires fewer training structures to reach a given accuracy. MACE typically achieves force MAE < 50 meV/Å on well-sampled datasets with 1,000–10,000 structures.
• The dataset defines the model's validity domain: MACE is a local potential with a fixed cutoff radius. It cannot extrapolate to compositions, coordination environments, or bond lengths absent from the training set. A low test error on held-out data does not guarantee stability in MD if the MD trajectory visits configurations outside the training distribution.
• Reference energy convention: DFT total energies are extensive and include core-electron contributions that are not physically meaningful on their own. MACE subtracts isolated atom reference energies (E0) from all structure energies before training. The E0 values must be computed at the same level of DFT theory (functional, pseudopotential, cutoff) as the training data. Errors in E0 shift the predicted formation energy of every structure by a constant and destabilize model training.
• Stress tensor convention: MACE uses ASE's stress convention: Voigt-ordered Cauchy stress in eV/ų, with tensile stress positive (opposite to engineering convention). VASP outputs stress in kBar with compression positive. The conversion factor and sign flip are a common source of silent dataset errors.