{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Check, then fine-tune, a foundation potential\n",
    "\n",
    "Compare model predictions with reference labels in a parity plot (the demo compares two foundation models), then follow the LoRA fine-tuning recipe used for MoS₂ with N₂.\n",
    "\n",
    "Paper: Fine-tuning a Foundation Interatomic Potential to Investigate Nitrogen-Dependent Structural Evolution in MoS₂\n",
    "\n",
    "Website tutorial: reproduce/mos2-n2-finetune/ · Status: Example run locally · Runtime: < 1 min (GPU). In Colab choose *Runtime → Change runtime type → GPU*."
   ],
   "id": "cell-1"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "!pip install mace-torch ase matplotlib numpy scipy"
   ],
   "id": "cell-2"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "%%writefile models.py\n",
    "\"\"\"One place to pick an ML interatomic potential for every tutorial.\n",
    "\n",
    "    from models import get_calc\n",
    "    calc = get_calc(\"mace-small\")      # default, no account needed\n",
    "    calc = get_calc(\"uma-s-1p1\")       # Meta UMA via fairchem (needs a Hugging Face token)\n",
    "\n",
    "MACE-MP-0 downloads its weights on first use (about 20-90 MB).\n",
    "UMA is gated: accept the license at https://huggingface.co/facebook/UMA and run\n",
    "`huggingface-cli login` (or set HF_TOKEN) before using it.\n",
    "\"\"\"\n",
    "import os\n",
    "\n",
    "\n",
    "def device():\n",
    "    try:\n",
    "        import torch\n",
    "        return \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
    "    except ImportError:\n",
    "        return \"cpu\"\n",
    "\n",
    "\n",
    "def get_calc(name: str = \"mace-small\", task: str = \"omat\", dtype: str = \"float64\"):\n",
    "    \"\"\"dtype: float64 for geometry optimisation, float32 (about 2x faster) for molecular dynamics.\"\"\"\n",
    "    if os.path.exists(name):  # a fine-tuned MACE model file\n",
    "        from mace.calculators import MACECalculator\n",
    "        return MACECalculator(model_paths=name, device=device(), default_dtype=dtype)\n",
    "    name = name.lower()\n",
    "    if name.startswith(\"mace\"):\n",
    "        from mace.calculators import mace_mp\n",
    "        size = name.split(\"-\", 1)[1] if \"-\" in name else \"small\"\n",
    "        return mace_mp(model=size, device=device(), default_dtype=dtype)\n",
    "    if name.startswith(\"uma\"):\n",
    "        from fairchem.core import pretrained_mlip, FAIRChemCalculator\n",
    "        predictor = pretrained_mlip.get_predict_unit(name, device=device())\n",
    "        return FAIRChemCalculator(predictor, task_name=task)\n",
    "    raise ValueError(f\"unknown model {name!r}; use mace-small, mace-medium or uma-s-1p1\")\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    print(\"device:\", device(), \"| HF_TOKEN set:\", bool(os.environ.get(\"HF_TOKEN\")))\n"
   ],
   "id": "cell-3"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "%%writefile parity_check.py\n",
    "\"\"\"Tutorial — Measure a foundation model's error before you trust it (and after you fine-tune it).\n",
    "\n",
    "In the MoS2–N2 project, the foundation MACE model had an energy RMSE of 76.0 meV/atom against\n",
    "r2SCAN DFT. After LoRA fine-tuning on automatically generated DFT data, the error fell to\n",
    "9.2 meV/atom. The first step of that work is this script:\n",
    "a parity check of model predictions against reference labels.\n",
    "\n",
    "Use it two ways:\n",
    "  python parity_check.py my_dft_data.extxyz                 # your labeled data (energy + forces in the file)\n",
    "  python parity_check.py --demo                             # no DFT needed: medium model labels, small model is tested\n",
    "\n",
    "Output: out/parity.png and printed RMSE / MAE for energy (meV/atom) and forces (meV/Å).\n",
    "\"\"\"\n",
    "import argparse\n",
    "import sys\n",
    "from pathlib import Path\n",
    "\n",
    "import numpy as np\n",
    "from ase import Atoms\n",
    "from ase.build import molecule, mx2\n",
    "from ase.io import read\n",
    "\n",
    "from models import get_calc  # noqa: E402\n",
    "\n",
    "OUT = Path(__file__).parent / \"out\"\n",
    "OUT.mkdir(exist_ok=True)\n",
    "\n",
    "\n",
    "def demo_set(n=24, seed=0):\n",
    "    \"\"\"Distorted MoS2 bilayers with N2 in the gap: small, diverse configurations.\"\"\"\n",
    "    rng = np.random.default_rng(seed)\n",
    "    out = []\n",
    "    for k in range(n):\n",
    "        layer = mx2(\"MoS2\", kind=\"2H\", a=3.18 * (1 + rng.normal(0, 0.01)), thickness=3.19, size=(3, 3, 1), vacuum=0)\n",
    "        top = layer.copy()\n",
    "        top.translate([0, 0, 6.6])\n",
    "        s = layer + top\n",
    "        n2 = molecule(\"N2\")\n",
    "        n2.rotate(rng.random() * 180, \"x\")\n",
    "        n2.translate(0.5 * s.cell[0] + 0.3 * s.cell[1] + [0, 0, 3.3 + 1.6])\n",
    "        s += n2\n",
    "        s.cell[2] = [0, 0, 16.0]\n",
    "        s.pbc = True\n",
    "        s.rattle(0.03 + 0.07 * rng.random(), seed=k)\n",
    "        out.append(s)\n",
    "    return out\n",
    "\n",
    "\n",
    "def main():\n",
    "    ap = argparse.ArgumentParser()\n",
    "    ap.add_argument(\"data\", nargs=\"?\")\n",
    "    ap.add_argument(\"--model\", default=\"mace-small\")\n",
    "    ap.add_argument(\"--demo\", action=\"store_true\")\n",
    "    a = ap.parse_args()\n",
    "\n",
    "    if a.demo or not a.data:\n",
    "        frames = demo_set()\n",
    "        ref_calc = get_calc(\"mace-medium\")\n",
    "        E_ref, F_ref = [], []\n",
    "        for f in frames:\n",
    "            f.calc = ref_calc\n",
    "            E_ref.append(f.get_potential_energy() / len(f))\n",
    "            F_ref.append(f.get_forces().ravel())\n",
    "        label = \"reference = MACE-MP-0 medium (demo)\"\n",
    "    else:\n",
    "        frames = read(a.data, \":\")\n",
    "        E_ref = [f.get_potential_energy() / len(f) for f in frames]\n",
    "        F_ref = [f.get_forces().ravel() for f in frames]\n",
    "        label = f\"reference = {a.data}\"\n",
    "\n",
    "    calc = get_calc(a.model)\n",
    "    E_pred, F_pred = [], []\n",
    "    for f in frames:\n",
    "        f = f.copy()\n",
    "        f.calc = calc\n",
    "        E_pred.append(f.get_potential_energy() / len(f))\n",
    "        F_pred.append(f.get_forces().ravel())\n",
    "    E_ref, E_pred = np.array(E_ref), np.array(E_pred)\n",
    "    F_ref, F_pred = np.concatenate(F_ref), np.concatenate(F_pred)\n",
    "    # constant energy shifts between codes are common; report RMSE after removing the mean offset too\n",
    "    dE = E_pred - E_ref\n",
    "    rmse_E, rmse_E_shift = np.sqrt(np.mean(dE ** 2)) * 1e3, np.std(dE) * 1e3\n",
    "    rmse_F = np.sqrt(np.mean((F_pred - F_ref) ** 2)) * 1e3\n",
    "    print(f\"{a.model} vs {label}\")\n",
    "    print(f\"energy RMSE {rmse_E:.1f} meV/atom (after removing mean offset: {rmse_E_shift:.1f})\")\n",
    "    print(f\"force  RMSE {rmse_F:.1f} meV/Å   over {len(F_ref)} components\")\n",
    "\n",
    "    import matplotlib\n",
    "    matplotlib.use(\"Agg\")\n",
    "    import matplotlib.pyplot as plt\n",
    "    fig, axs = plt.subplots(1, 2, figsize=(9, 4))\n",
    "    axs[0].plot(E_ref, E_pred, \"o\", color=\"#1f6fa8\", ms=5)\n",
    "    axs[1].plot(F_ref, F_pred, \".\", color=\"#c2414f\", ms=2, alpha=0.4)\n",
    "    for ax, (x, y), t in ((axs[0], (E_ref, E_pred), f\"Energy  RMSE {rmse_E:.1f} meV/atom\"),\n",
    "                          (axs[1], (F_ref, F_pred), f\"Forces  RMSE {rmse_F:.0f} meV/Å\")):\n",
    "        lo, hi = min(x.min(), y.min()), max(x.max(), y.max())\n",
    "        ax.plot([lo, hi], [lo, hi], \"k:\", lw=1)\n",
    "        ax.set_title(t, fontsize=10)\n",
    "    axs[0].set_xlabel(\"reference (eV/atom)\"); axs[0].set_ylabel(f\"{a.model} (eV/atom)\")\n",
    "    axs[1].set_xlabel(\"reference (eV/Å)\"); axs[1].set_ylabel(f\"{a.model} (eV/Å)\")\n",
    "    fig.tight_layout()\n",
    "    fig.savefig(OUT / \"parity.png\", dpi=160)\n",
    "    print(\"wrote\", OUT / \"parity.png\")\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()\n"
   ],
   "id": "cell-4"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "!python parity_check.py --demo"
   ],
   "id": "cell-5"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Optional: Supply your own DFT-labeled extended XYZ file and replace my_dft.extxyz with its filename.\n",
    "# !python parity_check.py my_dft.extxyz --model mace-small"
   ],
   "id": "cell-6"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "from IPython.display import Image, display\n",
    "import glob\n",
    "for f in sorted(glob.glob('out/*.png') + glob.glob('*.png')):\n",
    "    print(f); display(Image(f))"
   ],
   "id": "cell-7"
  }
 ],
 "metadata": {
  "kernelspec": {
   "name": "python3",
   "display_name": "Python 3"
  },
  "language_info": {
   "name": "python"
  },
  "accelerator": "GPU",
  "colab": {
   "provenance": []
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}