mace

MACE - Machine Learning Force Fields

Overview

MACE provides fast, accurate universal machine-learning potentials for atomistic simulations.

When to Use MACE vs. Other Tools

Scenario	Recommended Tool	Why
Fast energy/force evaluation on materials, molecules, or interfaces	MACE	Near-DFT accuracy at a fraction of the cost
Benchmark-quality energies or electronic properties (DOS, band gaps)	DFT (PySCF/ASE-DFT)	MLIPs do not predict electronic structure
Very large systems with well-established chemistry	Classical force fields (GROMACS/LAMMPS)	Lower overhead and longer time scales

Key rule: Use MACE when you need quantum-like accuracy for geometries and energies but do not need electronic properties.

Installation

uv pip install mace-torch

Core Capabilities

1. Energy and Forces

python scripts/run_mace.py water.xyz --task energy --model small --device cpu

2. Geometry Optimization

python scripts/run_mace.py water.xyz --task opt --model small --fmax 0.01 --device cpu

Output

Results are printed as JSON to stdout.

Anti-Patterns (Do Not Do These)

• Do not use MACE to predict electronic properties. MACE models energies and forces, not densities of states, band gaps, or charges.
• Do not assume MACE works for elements outside its training set. Always check that the model was trained on the elements in your system.
• Do not ignore device mismatch. Running large systems on cuda with insufficient GPU memory will crash; use cpu if unsure.
• Do not accept an optimization with loose fmax for production geometries. Tight convergence (fmax <= 0.01) is standard for reliable structures.

Best Practices

• Use device=cpu unless a compatible GPU with sufficient memory is available.
• The first run downloads the model automatically; ensure internet access or set the cache path via the MACE environment variables.
• Validate MACE predictions against a small DFT or reference dataset for your specific system class before scaling up.
• Start with medium model size for production work; small is good for quick screening and large for maximum accuracy.
• For questions about the latest MACE models, newly supported options, or version-specific syntax changes, use WebFetch on https://mace-docs.readthedocs.io/en/latest/ before answering.

Common Errors and Fixes

Error / Symptom	Likely Cause	Fix
CUDA out of memory	System too large for GPU	Switch to device=cpu or reduce cell size
Model download fails	No internet or cache path issue	Check connectivity or set MACE_CACHE environment variable
"Element X not found in model"	Element outside training set	Use a different model or switch to DFT/classical FF
Optimization does not converge	Poor initial structure or fmax too tight	Visualize structure, fix clashes, or relax fmax slightly
Energy seems unphysical	Wrong model or mixed units	Verify model tag and input structure units (Å)

References

• Documentation: https://mace-docs.readthedocs.io/en/latest/
• GitHub: https://github.com/ACESuit/mace
• Paper (arXiv): https://arxiv.org/abs/2206.07697

Getting Live Information

If the user asks about recently added features, new model releases, or version-specific syntax changes, use WebFetch on the official documentation at https://mace-docs.readthedocs.io/en/latest/ before answering.