IANN: A Unified Framework for Equivariant InterAtomic Neural Networks with User-Friendly Implementation

Changzhi Ai, Xueping Qin, Dimosthenis Sokaras, Frank Abild-Pedersen, Johannes VossarXiv 2026 · arXiv

TL;DR

IANN (InterAtomic Neural Network) is a unified PyTorch framework that brings seven state-of-the-art equivariant neural network architectures under one roof. By standardizing data handling, training, and deployment, IANN allows researchers to swap complex model architectures with a single line of configuration, while providing high-performance paths to production molecular dynamics in LAMMPS.

What Problem Does This Paper Address?

In the world of computational materials science, Density Functional Theory (DFT) is the gold standard for accuracy but is notoriously slow. Machine-learning interatomic potentials (MLIPs) have emerged as a solution, offering near-DFT accuracy at a fraction of the cost. However, the field suffers from extreme software fragmentation.

Currently, every time a research group publishes a new state-of-the-art architecture (like MACE, NequIP, or Allegro), they release it as a standalone codebase with its own unique data formats, training loops, and deployment hurdles. This makes "apples-to-apples" comparisons nearly impossible and creates a massive engineering burden for researchers who just want to run a simulation. IANN tackles this by providing a unified "intermediate layer" that standardizes the entire MLIP workflow.

Methods

IANN doesn't propose a new neural network architecture; instead, it provides a robust infrastructure for the best existing ones. Key technical pillars include:

  • Unified Data Representation (AtomsData): A single, TorchScript-compatible data object used by all models. This ensures that neighbor-list construction and batching are handled identically across architectures.
  • The Unified Trainer: A configuration-driven system where changing the model is as simple as changing a string in a dictionary (e.g., from "painn" to "mace"). It automatically handles distributed training across SLURM, PBS, or MPI environments.
  • Uniform Analytic Derivatives: Forces, stresses, and virials are calculated using a single, unified implementation of automatic differentiation with respect to graph edge vectors. This approach is mathematically exact under periodic boundary conditions and works for all supported models.
  • Production Deployment: IANN includes a generic TorchScript wrapper and C++ pair styles for LAMMPS, allowing any model trained in the framework to be used in large-scale production simulations with single- or multi-GPU support.
  • Agent Interface: Uniquely, IANN includes a Model Context Protocol (MCP) server, enabling Large Language Model (LLM) agents to programmatically train, inspect, and deploy models.

Datasets

The authors curated and standardized a massive collection of 41.9 million DFT structures, organized into three databases based on their exchange-correlation functionals:

  1. PBE (31.9M structures): Includes data from MPtrj, Alexandria, OMat24, MatPES, and OC22.
  2. RPBE (9.37M structures): Focused on catalysis, including OC20 and OC25.
  3. r²SCAN (0.63M structures): High-accuracy meta-GGA data from Materials Project and MatPES.

These datasets were cleaned of geometric outliers and unreliable labels to serve as a high-quality foundation for training.

Key Insights and Ideas

  • Architecture as a Controllable Variable: By fixing the training split, optimizer, and loss function, IANN reveals that while accuracy varies slightly between SOTA models (0.029 to 0.054 eV/atom for energy), the computational efficiency varies wildly.
  • The "Latency Floor": For small systems (like the few-hundred-atom slabs common in catalysis), the time per evaluation is dominated by GPU kernel launch overhead rather than model scaling. In this regime, simpler models like PaiNN often outperform "heavier" architectures in practical wall-clock time.
  • Foundation Models for Data-Scarce Regimes: The paper demonstrates that fine-tuning a "foundation model" (pre-trained on millions of structures) on a tiny, task-specific dataset (a few hundred structures) leads to significantly better accuracy than training a model from scratch.
  • Consistency Across Theory: Elemental error trends are dictated more by the underlying level of theory (PBE vs. RPBE) than by the specific source of the dataset, justifying the authors' decision to organize models by functional.

Key Results

  • Accuracy Benchmarking: In a head-to-head comparison on the MPtrj dataset, UMA achieved the lowest energy error (0.029 eV/atom), while EquiformerV3 and PaiNN showed excellent balances of accuracy and speed.
  • Speedups: IANN models provide 3 to 6 orders of magnitude speedup over plane-wave DFT (VASP).
  • Scalability: Training throughput scales near-linearly up to 16 GPUs. For inference, the parallel LAMMPS interface can handle systems of up to 200,000 atoms on 8 GPUs.
  • Fine-tuning: On the AdsTraj catalysis dataset, fine-tuning a foundation model reduced the adsorption energy MAE from 0.483 eV (from scratch) to 0.217 eV.

Limitations and Future Work

  • Locality Constraint: The framework currently relies on a strictly local decomposition of energy. It does not yet support long-range electrostatics, charge transfer, or magnetic degrees of freedom.
  • Functional Transferability: Because models inherit the specific DFT parameters of their training data, absolute energies are not transferable between different functionals (e.g., you cannot mix PBE and RPBE results).
  • Third-Party Checkpoints: Because IANN uses native reimplementations, you cannot directly load a checkpoint file generated by the original "official" repositories of models like MACE or NequIP; models must be trained or fine-tuned within the IANN ecosystem.

Summary updated

Abstract

Machine-learning interatomic potentials (MLIPs) now approach density functional theory (DFT) accuracy at a fraction of its cost, but the practical benefit is limited by software fragmentation: each state-of-the-art architecture is released as a separate codebase, with its own data format, configuration system, training loop and molecular-dynamics interface. Comparing two architectures on the same dataset, or moving a trained model into a production simulation, therefore requires substantial re-engineering. We introduce IANN (InterAtomic Neural Network), an open-source PyTorch framework that reimplements equivariant graph neural networks - PaiNN, NequIP, MACE, Allegro, EquiformerV2, EquiformerV3 and UMA - behind a unified data object, a unified trainer and a single deployment route, so that the architecture is a one-word change in a configuration dictionary. Forces, stresses and virials are obtained for every architecture from one analytic differentiation of the energy with respect to the edge vectors of the atomic graph, exact under periodic boundary conditions. Distributed training is configured automatically from the SLURM, PBS or MPI environment, so the same script runs unchanged from a workstation to a multi-node GPU allocation. Self-describing checkpoints serve directly as ASE calculators, as ensembles reporting uncertainties, or as TorchScript models run inside LAMMPS through bundled C++ pair styles with single- and multi-GPU inference. Trained on a common dataset of millions of structures, the architectures can be compared under identical conditions. We further release PaiNN foundation models trained on 41.9 million curated DFT structures from MPtrj, Alexandria, OMat24, MatPES, OC20, OC22, OC25, MPr2SCAN and MatPESr2SCAN, spanning the PBE, RPBE and r2SCAN functionals. Additionally, IANN provides an agent interface to facilitate integration with autonomous agents.
BibTeX
@misc{ai2026iann,
  author = {Changzhi Ai and Xueping Qin and Dimosthenis Sokaras and Frank Abild-Pedersen and Johannes Voss},
  title = {{IANN: A Unified Framework for Equivariant InterAtomic Neural Networks with User-Friendly Implementation}},
  year = {2026},
  eprint = {2611.19793},
  archivePrefix = {arXiv},
  url = {https://arxiv.org/abs/2611.19793},
}
Figure