# Fine-tuning a MACE foundation model on your own DFT data

This is the recipe behind the MoS₂–N₂ result (energy RMSE 76.0 → 9.2 meV/atom).
It needs a GPU and a labeled dataset. The project's dataset holds r²SCAN DFT frames of MoS₂ flakes, slabs and layered structures with H₂O, O₂ and N₂. It will be released with the paper.

## 1. Collect and label data
- Generate diverse frames (MD snapshots, rattled structures, molecules near edges and defects).
- Label them with DFT (energy, forces, stress) using the same functional as your target, here r²SCAN.
- Save as extended XYZ with keys `REF_energy`, `REF_forces`, `REF_stress`.

## 2. Check the starting point
```bash
python parity_check.py train.extxyz --model mace-small
```
Fine-tuning is worth it when the error is much larger than the energy differences you care about.

## 3. Fine-tune
MACE (≥ 0.3.10) fine-tunes a foundation model and replays part of its original training data ("multi-head" fine-tuning). The replay keeps the model from forgetting chemistry outside your dataset.

```bash
mace_run_train \
  --name="mos2_n2_ft" \
  --foundation_model="small" \
  --multiheads_finetuning=True \
  --train_file="train.extxyz" --valid_fraction=0.1 \
  --energy_key="REF_energy" --forces_key="REF_forces" --stress_key="REF_stress" \
  --E0s="foundation" \
  --lr=0.005 --batch_size=4 --max_num_epochs=50 \
  --device=cuda --default_dtype="float64"
```
Low-rank adaptation (LoRA) freezes the foundation weights and trains small added matrices instead. Fewer trainable weights means less overfitting on a small dataset. In mace-torch 0.3.17, add:
```bash
  --lora=True --lora_rank=4 --lora_alpha=1.0
```

## 4. Validate on held-out data and on physics
- Parity on frames the model never saw: `python parity_check.py test.extxyz --model path/to/mos2_n2_ft.model` (the `models.py` loader accepts MACE file paths through `mace.calculators.MACECalculator`).
- Physics checks: N₂ bond length, S–N reaction energies, MoS₂ lattice constant.
- Run MD and watch for unphysical events (atoms collapsing, explosions).
