What you will learn
- How to compute energy and force RMSE against reference data
- Why to look at the mean offset separately
- How to fine-tune MACE with multi-head replay and LoRA
Set up
pip install mace-torch ase matplotlib numpy scipyFiles for this tutorial:
parity_check.py— Parity plot + RMSE for any labeled extxyzfinetune.md— Fine-tuning recipe (mace_run_train flags)../common/models.py— Shared MACE and UMA model loader
Put the shared files in common/, next to the mos2-n2-finetune/ directory. Run the commands from mos2-n2-finetune/.
How it works
Get labeled data
Use your own DFT frames, or run --demo, in which MACE-MP-0 medium labels small MoS₂–N₂ configurations so no DFT is needed.
Parity check
Predict energies and forces, then report RMSE. In the real project the foundation model’s energy RMSE against r²SCAN DFT was 76.0 meV/atom, too large for reaction energetics.
Fine-tune
finetune.md gives the mace_run_train command with --foundation_model, --multiheads_finetuning and --lora. After fine-tuning, the project’s energy RMSE fell to 9.2 meV/atom.
Run it
The local run used MACE-MP-0 with mace-torch 0.3.17 on an NVIDIA GeForce RTX 5080.
python parity_check.py --demoOptional
Supply your own DFT-labeled extended XYZ file and replace my_dft.extxyz with its filename.
python parity_check.py my_dft.extxyz --model mace-smallWhat you should see

How this differs from the paper
The demo compares two foundation models, not a model against DFT. The project’s r²SCAN dataset and fine-tuned model will be released with the paper.
Full source
parity_check.py (109 lines)
"""Tutorial — Measure a foundation model's error before you trust it (and after you fine-tune it).
In the MoS2–N2 project, the foundation MACE model had an energy RMSE of 76.0 meV/atom against
r2SCAN DFT. After LoRA fine-tuning on automatically generated DFT data, the error fell to
9.2 meV/atom. The first step of that work is this script:
a parity check of model predictions against reference labels.
Use it two ways:
python parity_check.py my_dft_data.extxyz # your labeled data (energy + forces in the file)
python parity_check.py --demo # no DFT needed: medium model labels, small model is tested
Output: out/parity.png and printed RMSE / MAE for energy (meV/atom) and forces (meV/Å).
"""
import argparse
import sys
from pathlib import Path
import numpy as np
from ase import Atoms
from ase.build import molecule, mx2
from ase.io import read
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "common"))
from models import get_calc # noqa: E402
OUT = Path(__file__).parent / "out"
OUT.mkdir(exist_ok=True)
def demo_set(n=24, seed=0):
"""Distorted MoS2 bilayers with N2 in the gap: small, diverse configurations."""
rng = np.random.default_rng(seed)
out = []
for k in range(n):
layer = mx2("MoS2", kind="2H", a=3.18 * (1 + rng.normal(0, 0.01)), thickness=3.19, size=(3, 3, 1), vacuum=0)
top = layer.copy()
top.translate([0, 0, 6.6])
s = layer + top
n2 = molecule("N2")
n2.rotate(rng.random() * 180, "x")
n2.translate(0.5 * s.cell[0] + 0.3 * s.cell[1] + [0, 0, 3.3 + 1.6])
s += n2
s.cell[2] = [0, 0, 16.0]
s.pbc = True
s.rattle(0.03 + 0.07 * rng.random(), seed=k)
out.append(s)
return out
def main():
ap = argparse.ArgumentParser()
ap.add_argument("data", nargs="?")
ap.add_argument("--model", default="mace-small")
ap.add_argument("--demo", action="store_true")
a = ap.parse_args()
if a.demo or not a.data:
frames = demo_set()
ref_calc = get_calc("mace-medium")
E_ref, F_ref = [], []
for f in frames:
f.calc = ref_calc
E_ref.append(f.get_potential_energy() / len(f))
F_ref.append(f.get_forces().ravel())
label = "reference = MACE-MP-0 medium (demo)"
else:
frames = read(a.data, ":")
E_ref = [f.get_potential_energy() / len(f) for f in frames]
F_ref = [f.get_forces().ravel() for f in frames]
label = f"reference = {a.data}"
calc = get_calc(a.model)
E_pred, F_pred = [], []
for f in frames:
f = f.copy()
f.calc = calc
E_pred.append(f.get_potential_energy() / len(f))
F_pred.append(f.get_forces().ravel())
E_ref, E_pred = np.array(E_ref), np.array(E_pred)
F_ref, F_pred = np.concatenate(F_ref), np.concatenate(F_pred)
# constant energy shifts between codes are common; report RMSE after removing the mean offset too
dE = E_pred - E_ref
rmse_E, rmse_E_shift = np.sqrt(np.mean(dE ** 2)) * 1e3, np.std(dE) * 1e3
rmse_F = np.sqrt(np.mean((F_pred - F_ref) ** 2)) * 1e3
print(f"{a.model} vs {label}")
print(f"energy RMSE {rmse_E:.1f} meV/atom (after removing mean offset: {rmse_E_shift:.1f})")
print(f"force RMSE {rmse_F:.1f} meV/Å over {len(F_ref)} components")
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
fig, axs = plt.subplots(1, 2, figsize=(9, 4))
axs[0].plot(E_ref, E_pred, "o", color="#1f6fa8", ms=5)
axs[1].plot(F_ref, F_pred, ".", color="#c2414f", ms=2, alpha=0.4)
for ax, (x, y), t in ((axs[0], (E_ref, E_pred), f"Energy RMSE {rmse_E:.1f} meV/atom"),
(axs[1], (F_ref, F_pred), f"Forces RMSE {rmse_F:.0f} meV/Å")):
lo, hi = min(x.min(), y.min()), max(x.max(), y.max())
ax.plot([lo, hi], [lo, hi], "k:", lw=1)
ax.set_title(t, fontsize=10)
axs[0].set_xlabel("reference (eV/atom)"); axs[0].set_ylabel(f"{a.model} (eV/atom)")
axs[1].set_xlabel("reference (eV/Å)"); axs[1].set_ylabel(f"{a.model} (eV/Å)")
fig.tight_layout()
fig.savefig(OUT / "parity.png", dpi=160)
print("wrote", OUT / "parity.png")
if __name__ == "__main__":
main()