Add MLIPX PaiNN-style MLIP project: data pipeline, model, training, inference, and tests

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.zip

README.md

@@ -0,0 +1,129 @@
+# MLIPX: PaiNN-style 机器学习原子势工程项目
+
+MLIPX 是一个可训练、可评估、可推理、可扩展的原子势项目，面向 ASE/extxyz 数据，支持能量+力联合训练，默认采用 **PaiNN-style message passing**（标量+向量通道，支持从能量自动微分得到力）。
+
+## 1. 项目结构
+
+```text
+.
+├── configs/
+│   ├── minimal.yaml
+│   └── standard.yaml
+├── data/
+├── scripts/
+│   ├── make_demo_dataset.py
+│   ├── train.sh
+│   ├── evaluate.sh
+│   └── infer.sh
+├── src/mlipx/
+│   ├── config.py
+│   ├── train.py
+│   ├── evaluate.py
+│   ├── infer.py
+│   ├── data/
+│   │   ├── dataset.py
+│   │   ├── datamodule.py
+│   │   ├── graph.py
+│   │   └── types.py
+│   ├── models/
+│   │   ├── layers.py
+│   │   ├── painn.py
+│   │   └── model.py
+│   ├── training/engine.py
+│   ├── ase_ext/calculator.py
+│   └── utils/
+└── tests/
+```
+
+## 2. 安装
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+```
+
+## 3. 数据格式（ASE/extxyz）
+
+每个结构需要至少包含：
+- 原子序数（ASE 自动包含）
+- positions
+- `info['energy']`（总能）
+- `arrays['forces']`
+- cell / pbc（若有）
+
+可先生成可跑通数据：
+
+```bash
+python scripts/make_demo_dataset.py --out data/demo.extxyz --n-samples 80
+```
+
+## 4. 训练
+
+最小实验：
+
+```bash
+python -m mlipx.train --config configs/minimal.yaml
+# 或 bash scripts/train.sh configs/minimal.yaml
+```
+
+正式实验建议：
+
+```bash
+python -m mlipx.train --config configs/standard.yaml
+```
+
+可命令行覆盖超参数：
+
+```bash
+python -m mlipx.train --config configs/minimal.yaml --epochs 10 --batch-size 8 --lr 3e-4
+```
+
+训练输出：
+- `artifacts/.../best.pt`
+- `artifacts/.../last.pt`
+- `artifacts/.../history.json`
+
+## 5. 评估
+
+```bash
+python -m mlipx.evaluate \
+  --config configs/minimal.yaml \
+  --checkpoint artifacts/minimal/best.pt \
+  --split test \
+  --out artifacts/test_predictions.csv
+```
+
+输出指标：Energy/Force 的 MAE 与 RMSE。
+
+## 6. 推理
+
+```bash
+python -m mlipx.infer \
+  --config configs/minimal.yaml \
+  --checkpoint artifacts/minimal/best.pt \
+  --input data/demo.extxyz \
+  --output artifacts/infer.txt
+```
+
+## 7. ASE Calculator 接入
+
+```python
+from mlipx.config import load_config
+from mlipx.ase_ext.calculator import build_calculator
+from ase.io import read
+
+cfg = load_config("configs/minimal.yaml")
+calc = build_calculator(cfg, "artifacts/minimal/best.pt")
+atoms = read("data/demo.extxyz", index=0)
+atoms.calc = calc
+print(atoms.get_potential_energy())
+print(atoms.get_forces())
+```
+
+## 8. 当前实现说明
+
+- 使用 cutoff 邻域图，处理不同原子数 batch。
+- 使用 energy normalization（可选 per-atom）。
+- 支持 AdamW、CosineLR、gradient clipping、AMP（CUDA时）、early stopping、checkpoint resume。
+- stress/virial 目前未启用（可在后续版本加入基于应变导数的实现）。

configs/minimal.yaml

@@ -0,0 +1,34 @@
+name: mlipx_minimal
+data:
+  path: data/demo.extxyz
+  format: extxyz
+  energy_key: energy
+  force_key: forces
+  cutoff: 5.0
+  max_neighbors: 32
+  train_ratio: 0.8
+  val_ratio: 0.1
+  test_ratio: 0.1
+  batch_size: 4
+  num_workers: 0
+  normalize_energy_per_atom: true
+model:
+  hidden_dim: 64
+  n_interactions: 3
+  n_rbf: 24
+  cutoff: 5.0
+train:
+  seed: 42
+  device: auto
+  epochs: 3
+  lr: 0.0005
+  weight_decay: 1.0e-6
+  energy_weight: 1.0
+  force_weight: 20.0
+  grad_clip: 5.0
+  amp: false
+  scheduler: cosine
+  scheduler_tmax: 3
+  early_stopping_patience: 10
+  output_dir: artifacts/minimal
+  resume_checkpoint: null

configs/standard.yaml

@@ -0,0 +1,34 @@
+name: mlipx_standard
+data:
+  path: data/demo.extxyz
+  format: extxyz
+  energy_key: energy
+  force_key: forces
+  cutoff: 5.0
+  max_neighbors: 64
+  train_ratio: 0.8
+  val_ratio: 0.1
+  test_ratio: 0.1
+  batch_size: 16
+  num_workers: 2
+  normalize_energy_per_atom: true
+model:
+  hidden_dim: 128
+  n_interactions: 4
+  n_rbf: 32
+  cutoff: 5.0
+train:
+  seed: 42
+  device: auto
+  epochs: 50
+  lr: 0.0002
+  weight_decay: 1.0e-6
+  energy_weight: 1.0
+  force_weight: 50.0
+  grad_clip: 5.0
+  amp: true
+  scheduler: cosine
+  scheduler_tmax: 50
+  early_stopping_patience: 12
+  output_dir: artifacts/standard
+  resume_checkpoint: null