Skip to content

MACE

MACE checkpoints are loaded through mace-torch. A MACE profile is a checkpoint plus a precision, and mliport treats the two precisions as different models: float64 is the primary, accuracy-first profile, while float32 is a separate identity and its results are never mixed with float64 ones.

What the model is

  • Architecture. MACE is an equivariant message-passing network that builds higher-order many-body features in each layer (atomic cluster expansion inside message passing), so two layers are enough for accurate potentials (Batatia et al., NeurIPS 2022).
  • Training data of the example checkpoint. mace-omat-0 is trained on OMat24, Meta's set of about 110 million VASP calculations on bulk inorganic structures, many deliberately far from equilibrium (rattled and high-temperature frames). Its reference level is PBE / PBE+U (VASP 5.4), Materials-Project-style: +U is applied to some transition metals in oxides and fluorides only. The older MACE-MP-0 family is trained on MPtrj, also PBE / PBE+U (Batatia et al., 2024); the list of checkpoints and their licenses is in mace-foundations.
  • Forces are the gradient of the energy (conservative), so MACE is accepted by the NEB and configuration-search gradient pre-flight.
  • What this means for you. Energies and forces approximate PBE(+U) on bulk inorganic matter. The model has no dispersion term (see --d3), and surfaces, molecules and interfaces are outside its training distribution: check a few structures against your own DFT before trusting it there. Check the checkpoint's license before commercial use.

Install

Environment Python Runtime stack
.venv-mace 3.10, 3.11, 3.12, 3.13 mace-torch==0.3.16 (torch 2.8.0)
./scripts/install_mliport.sh --engines mace --device auto

Pinned profiles

Profile Identity dtype task head model SHA-256
mace_omat MACE-OMAT-0 medium, float64 inference float64 bulk None d4b14be9afa2...
mace_omat_float32 MACE-OMAT-0 medium, float32 inference float32 bulk None d4b14be9afa2...

The mace_omat profiles use mace-omat-0-medium.model from the upstream MACE releases, referenced by SHA-256 in validation/science/model_manifest.json. See Models for the download link.

Run it

.venv-mace/bin/mliport sp structure.cif \
  --model /path/to/mace-omat-0-medium.model --model-type mace

--task is the explicit periodic-boundary semantic (bulk or molecule). --dtype float32 is faster and less precise; use it deliberately and say so when you compare numbers.

Things to know

  • Heads. If a checkpoint offers several heads you must name one with --head; mliport will not pick for you. Single-head checkpoints need nothing. MACE-MH-1 is an ordinary multi-head energy model and loads normally.
  • Only energy models. A checkpoint without a potential-energy head is refused before it runs, because an energy from it would be fabricated: dipole/polarizability-only models (the MACE-MDP family), MACE-POLAR polarizable electrostatics (upstream loads those through mace_polar, not the energy calculator), and models with charge/spin joint embeddings (the MACE-OMOL family, which reads the charge and spin from atoms.info). The error names the reason and the upstream loader.
  • Precision is part of the identity. The recorded dtype always comes from the backend, never from an assumption. Don't compare float32 energies with float64 ones without saying so.
  • Stress is reported only if the loaded checkpoint provides it (implemented_properties), and that differs between checkpoints, so check the stress_supported field of the validation record or run mliport doctor rather than assuming.
  • NEB works with MACE because its forces are derived from the energy; the run-time consistency check is described in NEB.

mliport is MIT-licensed. The upstream software and model must be cited separately; see Citations.