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.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.