| name | mace |
| description | Use when running machine-learning potential calculations with MACE. Load pretrained MACE-MP models, compute energies and forces, and run geometry optimizations on atomistic structures. |
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
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.
