SEAMM xnn Plug-in

A SEAMM plug-in providing machine-learned force fields (MLFFs) trained with xnn as model chemistries, run as MDI engines.

• Free software: BSD-3-Clause

• Documentation: https://molssi-seamm.github.io/xnn_step/index.html

• Code: https://github.com/molssi-seamm/xnn_step

History

2026.10.17.1 – xnn’s fast paths on NVIDIA GPUs

• For a CUDA build of torch the installer now adds xnn’s fast paths to the environment: the vesin-torch neighbour lists and the cuEquivariance tensor products, with the operations matching torch’s CUDA. xnn uses them by itself; without them a large system ran up to twice as slowly on the GPU, with the same results. torch is kept as it is, and an environment SEAMM did not create is left alone, with a note of what it lacks.

• Steps that drive the engine on a GPU, such as LAMMPS from 2026.10.17.3, say in their output whether it has the fast paths, and warn when it does not.

2026.10.17 – Bugfix: committees in a standard installation, and the GPU by default

• The seamm-xnn environment now includes ASE. A committee’s engine runs in that environment and needs ASE for its spreads, so in a standard installation a committee’s molecular dynamics stopped at the first spreads it wrote. Updating the plug-in adds ASE to an existing seamm-xnn.

• When the installer creates xnn.ini and the environment’s PyTorch can use an NVIDIA GPU, it sets device = cuda, so that the Energy step and others run the model on the GPU rather than the CPU. An existing xnn.ini is never changed; the installer says when its device = cpu could be cuda.

2026.10.16 – Bugfix: readable names for committees in a job

• A committee given by path in a directory with a generic name, such as the committee that the Active Learning step’s Train Committee writes, was called after its parent directory, which in a job is just the step’s number: Job_012130/2/1/committee became xnn:MLFF@1-committee-5c20d7. It is now called after the nearest directory above it that is neither an index nor generic, here xnn:MLFF@Job_012130-committee-5c20d7.

2026.10.14 – Committees of models as one model chemistry

• A committee – a directory of members m0/best.pt, m1/best.pt, … as the Active Learning step trains them – is offered as one model, xnn:MLFF@<name>, found in the model directories or given by path. It runs as the committee-mean engine of the active-learning-step package, serving the members’ mean and writing their spreads to committee_spreads.csv, for molecular dynamics that shows where the model is uncertain.

• A model chemistry now lists the files its engine writes (engine_files), so that the step driving it keeps them, e.g. a committee’s spreads in LAMMPS.

2026.10.13 – Distinct names for checkpoints called best.pt, last.pt, …

• A checkpoint with a generic name – best, last, model, checkpoint or final, as training writes them – is now called after its directory (and the one above when its own is only an index such as m1) plus a short hash of the file, e.g. xnn:MLFF@x013_m1-3f9a2c rather than xnn:MLFF@best, so results from different models are labelled differently. Other checkpoints keep their names.

2026.10.12 – The engine as an MPI pair with LAMMPS; checkpoints by path

• The engine’s command can be for an MPI pair (-method MPI), in the driver’s environment, as LAMMPS runs a machine-learned forcefield from the Model Chemistry step; with the checkpoint, device and the run’s engine options.

• A checkpoint given by its path (or a variable) in the Model Chemistry step is offered as xnn:MLFF@<file stem>, checked as the models found are.

2026.10.5 – PyTorch installed for the machine’s NVIDIA driver, and checked

• xnn-step-installer no longer takes whatever torch PyPI serves, which on a machine whose driver is older than the wheel’s bundled CUDA runtime imports and silently runs on the CPU. It reads the driver with nvidia-smi, installs torch from the matching PyTorch index (PyPI’s wheel on macOS, for mps), applies the rest of the environment on that index, leaves a torch that works alone, and checks afterwards that torch sees the GPU and that xnn and mdi import. torch-build in xnn.ini or --torch-tag forces a build, which a cluster login node without a GPU needs; a torch that cannot use the GPU is replaced only when asked that way. torch is no longer in seamm-xnn.yml. (seamm_manager#31)

• Requires seamm-manager 2026.10.5.1, and so Python 3.12 or later.

2026.10.2 – Show what each model is, and pass the charge for D4 models

• The Model Chemistry step now describes each xnn model: its family (e.g. MACE), the elements it was trained on, and how dispersion enters it, e.g. “D4, 12 Å + tail added by the engine”. The plug-in reads this from the training configuration stored in the checkpoint, without PyTorch and without executing anything in the file.

• Models trained on dispersion-subtracted labels, which record the subtracted term as subtracted_dispersion in their training configuration, are recognized; the xnn mdi engine adds the term back by itself. A model that records the term and also carries a dispersion wrapper would count the dispersion twice. It is no longer offered, and asking for it by name is an error.

• For a charged configuration the total charge is now passed to the engine as --total-charge. D4 dispersion needs it for its EEQ partial charges.

2026.9.28 – Require xnns 0.4.0, which loads the existing checkpoints

• The environment now requires xnns>=0.4.0 instead of xnns<0.2. xnns 0.4.0 loads the checkpoints that 0.2.1 and 0.3.0 could not, and its engine supports --eeq-reuse. Updating the plug-in moves an existing environment to it, including one rolled back to 0.1.0 by hand; a torch built for the machine’s CUDA driver is kept, since xnns needs only torch 2.0 or later.

2026.9.27.1 – Local models can belong to the installation

• local: model directories in xnn.ini meant ~/SEAMM/data/Forcefields. They now mean the data/Forcefields directory of the SEAMM installation in use, then ~/SEAMM/data/Forcefields; a model in the installation’s own directory takes precedence. A second installation such as ~/SEAMM_DEV therefore sees the default installation’s models and can add its own.

• The SEAMM root now comes from seamm_util.current_root(), so an installation’s xnn.ini is found without --root. Requires seamm-util 2026.9.27.1.

2026.9.27 – Bugfix: pin xnns below 0.2 so existing checkpoints load

• The environment now requires xnns<0.2. The 0.2.1 and 0.3.0 releases on PyPI added scale_shift buffers to the MACE model with no defaults for older state dicts, so every existing checkpoint failed to load in the MDI engine (“Missing key(s) in state_dict: model.model.scale_shift.scale/shift”) and a LAMMPS run then hung waiting for it. A fresh installation was getting 0.3.0.

• Updating does not downgrade an environment that already has a newer xnns; run pip install xnns==0.1.0 in it by hand. The pin will move forward once an xnns release loads the older checkpoints.

2026.9.26 – Internal: depend on seamm-manager rather than seamm-installer

• The plug-in’s installer now builds on seamm-manager, which replaces seamm-installer for managing SEAMM installations. Nothing changes for users; this only lets the two packages stop being installed side by side.