xnn

Machine-Learning Interatomic Potentials in PyTorch

xnn is a library of machine-learning interatomic potentials (MLIPs) for molecular and periodic systems, implemented in PyTorch behind a single coherent nn.Module interface. It provides faithful and self-contained implementations of state-of-the-art equivariant open-source models such as NequIP, MACE, Allegro, and CACE, alongside SchNet, HDNNP, ANI, PhysNet, the BAMBOO graph equivariant transformer, and the learnable classical force fields ReaxFF / ReaxFF-nn (reactive), OPLS / L-OPLS (fixed topology) and DREIDING (rule-generated). The key strengths of xnn are

• all models share one data object, module interface, training loop, and deployment path to popular molecular dynamics packages such as ASE and LAMMPS

• distributed training and evaluation on multiple GPUs is supported out of the box

• the library is designed to be easily extensible with new models and featurizers

• a single configuration file and command-line interface enable benchmarking of a wide range of models on a variety of datasets

• upstream benchmark datasets download and preprocess in one line with a HuggingFace-style load_dataset(), ready to train

• the library is accompanied by extensive documentation, tutorials, examples and a complete hands-on course focusing on developing and training equivariant graph neural network MLIPs (see the Equivariant Graph Neural Networks with e3nn repository)

Getting Started

Installing xnn and a first training run

To the Getting Started Guide

How-To Guides

Recipes for accomplishing common tasks

To the How-To Guides

Examples

Executed example notebooks, rendered with their outputs

To the Examples

User Guide

Reference information for using xnn

To the User Guide

Developer Guide

Extending xnn with new models and featurizers

To the Developer Guide

Background Information

The design of xnn and the models it implements

To the Background Information

API Reference

Documentation of the xnn Python API

To the API Reference

Equivariant GNNs with e3nn

A hands-on course for developing equivariant GNN interatomic potentials

To the Equivariant GNN Course

Models at a glance

Model	Family	Featurizer	State
SchNet	cnn	Gaussian RBF	Complete: training, evaluation, deployment (TorchScript, LAMMPS, ASE); matches the NIPS 2017 manuscript.
PhysNet	dnn	exp-Gaussian RBF + attention masks	Complete: training, evaluation, deployment (ASE only); matches MMunibas/PhysNet
HDNNP	dnn	radial symmetry functions (G2)	Under development
ANI	dnn	AEV (radial + angular symmetry functions)	Complete: training, evaluation, deployment (ASE only); matches aiqm/torchani
NequIP	gnn	spherical-harmonic edges	Complete: training, evaluation, deployment (TorchScript, LAMMPS, ASE); matches mir-group/nequip
MACE	gnn	spherical-harmonic edges	Complete: training, evaluation, deployment (TorchScript, LAMMPS, ASE); matches ACEsuit/mace, and loads the pretrained MACE-MP / MACE-OFF foundation models (MACE.from_foundation(), verified to float64 round-off)
CACE	gnn	Cartesian monomial edges	Complete: training, evaluation, deployment (ASE only); matches BingqingCheng/cace
Allegro	gnn	spherical-harmonic edges	Complete: training, evaluation, deployment (TorchScript, LAMMPS, ASE); matches mir-group/allegro
BAMBOO	hybrid	exp-normal RBF + edge attention	Complete: training, evaluation, deployment (ASE only); matches bytedance/bamboo
ReaxFF / ReaxFF-nn	ffnn	bond orders from distances (reactive)	Complete: training, evaluation, deployment (ASE only); implements the published equations, cross-checked against LAMMPS pair_style reaxff (see the fidelity notes)
OPLS / L-OPLS	ffnn	fixed valence topology	Complete: training, evaluation, deployment (ASE only); matches OpenMM to ~1e-7 kJ/mol and Table 1 of Jorgensen et al. (1996)
DREIDING / X6	ffnn	rule-generated valence terms	Complete: training, evaluation, deployment (ASE only); matches LAMMPS DREIDING styles to ~1e-10 kcal/mol and Tables XI-XII of Mayo et al. (1990)

xnn is developed by The Molecular Sciences Software Institute (MolSSI). Visit the GitHub repository for the latest updates.