README.md

---
license: cc-by-nc-nd-4.0
language:
- en
tags:
- chemistry
- materials-science
- machine-learning
- interatomic-potentials
- batteries
- sodium-ion
- cathode
- painn
- cpainn
- dft
library_name: cpainn
---

# Polyanion Pretrained MLIPs (PaiNN / cPaiNN / CHGNet / MACE)

Twenty-three machine-learning interatomic potentials trained on the [polyanion sodium cathode DFT dataset](https://huggingface.co/datasets/Mahpe/polyanion-sodium-cathode-dft) (298,144 structures): system-specific PaiNN/cPaiNN models plus fine-tuned universal foundation models (CHGNet, MACE-MP-0).

**Paper:** [*Limitations of Foundation Models in Energy Materials Simulations: A Case Study in Polyanion Sodium Cathode Materials*](https://doi.org/10.1002/aidi.202500065) — Advanced Intelligent Discovery (2026).

**Dataset:** [Scientific Data (2025)](https://doi.org/10.1038/s41597-025-05799-8) · [Hugging Face](https://huggingface.co/datasets/Mahpe/polyanion-sodium-cathode-dft) · [DTU archive](https://doi.org/10.11583/DTU.27411681.v4)

**Code:** [dtu-energy/cPaiNN](https://github.com/dtu-energy/cPaiNN)

## Model inventory

| Folder | Architecture | Models | Targets |
|--------|--------------|--------|---------|
| `Pretrained_models_PaiNN/` | PaiNN | 8 | energy, forces, stress |
| `Pretrained_models_cPaiNN/` | cPaiNN | 8 | energy, forces, stress, magmom, Bader charge |
| `Pretrained_models_ensemble_cPaiNN/` | cPaiNN ensemble | 3 | energy, forces, stress, magmom, Bader charge |
| `Pretrained_universal_models/CHGNet/` | CHGNet | 2 | energy, forces, stress, magmom, charge |
| `Pretrained_universal_models/Mace_MP_0_large/` | MACE-MP-0 | 2 | energy, forces |

Each PaiNN/cPaiNN model directory contains:

- `best_model.pth` — validation-best checkpoint
- `arguments.json` — hyperparameters
- `datasplits.json` — train/validation split indices
- `commandline_args.txt` — launch command

Hidden dimensions (`node_size`) and interaction depth (`num_interactions`) are encoded in the folder name, e.g. `Polyanion_ionicsteps_magmom_bader_512_3` → 512 nodes, 3 interaction layers, with magmom + Bader charge heads.

Universal foundation models (`Pretrained_universal_models/`) include CHGNet and MACE-MP-0 (large) checkpoints, each trained **from scratch** and **fine-tuned** on the polyanion dataset for comparison in [AIDi (2026)](https://doi.org/10.1002/aidi.202500065).

## Quick start

```bash
git lfs install
git clone https://huggingface.co/Mahpe/polyanion-pretrained-mlips
pip install git+https://github.com/dtu-energy/cPaiNN.git
```

```python
import torch
from cpainn import CPaiNN  # see cPaiNN repo for exact API

checkpoint = torch.load(
    "Pretrained_models_cPaiNN/Polyanion_ionicsteps_magmom_bader_512_3/best_model.pth",
    map_location="cpu",
)
# Load into CPaiNN using arguments.json hyperparameters — see cPaiNN train.py / inference examples
```

## Training & benchmark figures

Validation MAE curves below are extracted from the original `printlog.txt` training logs bundled with each checkpoint.

<p align="center">
  <img src="figures/training-energy-mae.svg" width="700" alt="Training energy MAE"/>
</p>

<p align="center">
  <img src="figures/training-forces-mae.svg" width="700" alt="Training forces MAE"/>
</p>

Benchmark figures from the related AIDi / electronic-entropy study on NaFePO₄ charge ordering ([arXiv:2603.26471](https://arxiv.org/abs/2603.26471)):

<p align="center">
  <img src="figures/paper-fig3-structure-benchmark.png" width="620" alt="Structure benchmark (Fig. 3)"/>
</p>
<p align="center"><em>Figure 3.</em> GA structures and relative energies — cPaiNN vs MACE vs CHGNet vs DFT.</p>

<p align="center">
  <img src="figures/paper-fig6-convex-hull-mae.png" width="620" alt="Convex hull MAE comparison (Fig. 6)"/>
</p>
<p align="center"><em>Figure 6.</em> Na<sub>x</sub>FePO<sub>4</sub> convex hulls before/after electronic-entropy embedding (MAE vs DFT).</p>

## Citation

If you use these models, please cite the dataset and cPaiNN papers:

```bibtex
@article{petersen2026foundation,
  title={Limitations of Foundation Models in Energy Materials Simulations: A Case Study in Polyanion Sodium Cathode Materials},
  author={Hoffmann Petersen, Martin and others},
  journal={Advanced Intelligent Discovery},
  year={2026},
  doi={10.1002/aidi.202500065}
}

@article{petersen2025polyanion,
  title={Dataset exploring the atomic scale structure and ionic dynamics of polyanion sodium cathode materials},
  author={Hoffmann Petersen, Martin and others},
  journal={Scientific Data},
  year={2025},
  doi={10.1038/s41597-025-05799-8}
}
```