The Command Line#
Installing xnn provides the xnn command (entry point
xnn.common.cli:main) with three subcommands. Reading structure files
requires the ase extra.
xnn train#
Train a model from a config file:
xnn train --config configs/train.yaml
xnn train --config configs/train.yaml --set optim.epochs=50 model.cutoff=6.0
--config: a YAML config (see Configuration)--set KEY=VALUE: dotted-key overrides, repeatable
Structures are read from data.train_path / data.val_path /
data.test_path with ase.io.read (any ASE-readable format: extxyz,
VASP, …); when no val_path (test_path) is given,
data.val_fraction (data.test_fraction) of the training set is held
out instead. The optional test set is evaluated once after training.
Checkpoints (best.pt, last.pt) go to output_dir.
The same command runs data-parallel on several GPUs or nodes when started
through a distributed launcher (torchrun --nproc-per-node 2 -m xnn train
--config configs/train.yaml) with no config changes; see
Training.
xnn benchmark#
Score several pre-trained models on one dataset and write a results table:
xnn benchmark --config configs/benchmark.yaml
xnn benchmark --config configs/benchmark.yaml --set "metrics={'energy': ['mae']}"
--config: a YAML benchmark config (see Benchmark Several Models)--set KEY=VALUE: dotted-key overrides applied to the config, repeatable
Each model listed in models is built from its architecture, loaded from its
checkpoint (benchmarking does not train; produce checkpoints with
xnn train first), and scored with the configured metrics – a mapping
from each target (energy / forces / stress) to the error metrics (MAE / MSE /
RMSE or custom) reported for it. The comparison table is printed and written to
output.dir in every configured format (CSV / JSON / Markdown). See
Benchmark Several Models for the full config.
xnn export#
Export a trained checkpoint for deployment:
xnn export --config configs/train.yaml --ckpt runs/exp/best.pt --to lammps
xnn export --config configs/train.yaml --ckpt runs/exp/best.pt --to torchscript
--ckpt: a checkpoint written byxnn train--to:lammps(TorchScript wrapped in the LAMMPS tensor ABI) ortorchscript(plain scripted model)
See Deployment for what to do with the exported file.