Metadata-Version: 2.4
Name: xnn_step
Version: 2026.10.17.1
Summary: A SEAMM plug-in for xnn
Home-page: https://github.com/molssi-seamm/xnn_step
Author: Paul Saxe
Author-email: psaxe@molssi.org
License: BSD-3-Clause
Keywords: SEAMM,SEAMMplugin,flowchart
Platform: Linux
Platform: Mac OS-X
Platform: Unix
Platform: Windows
Classifier: Environment :: Plugins
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: seamm
Requires-Dist: seamm-manager>=2026.10.5.1
Requires-Dist: seamm-util>=2026.9.27.1
Requires-Dist: seamm-widgets
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

=================
SEAMM xnn Plug-in
=================

.. image:: https://img.shields.io/github/issues-pr-raw/molssi-seamm/xnn_step
   :target: https://github.com/molssi-seamm/xnn_step/pulls
   :alt: GitHub pull requests

.. image:: https://github.com/molssi-seamm/xnn_step/workflows/CI/badge.svg
   :target: https://github.com/molssi-seamm/xnn_step/actions
   :alt: Build Status

.. image:: https://codecov.io/gh/molssi-seamm/xnn_step/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/molssi-seamm/xnn_step
   :alt: Code Coverage

.. image:: https://github.com/molssi-seamm/xnn_step/workflows/CodeQL/badge.svg
   :target: https://github.com/molssi-seamm/xnn_step/security/code-scanning
   :alt: Code Quality

.. image:: https://github.com/molssi-seamm/xnn_step/workflows/Release/badge.svg
   :target: https://molssi-seamm.github.io/xnn_step/index.html
   :alt: Documentation Status

.. image:: https://img.shields.io/pypi/v/xnn_step.svg
   :target: https://pypi.python.org/pypi/xnn_step
   :alt: PyPi VERSION

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

Features
--------

* Advertises every xnn checkpoint found in the directories listed in ``xnn.ini`` to
  the Model Chemistry step as ``xnn:MLFF@<model>``.
* Launches ``xnn mdi`` -- the checkpoint served as a resident MDI engine -- for any step
  that drives a model chemistry over MDI: Energy (single points for many structures),
  LAMMPS (MD with the MLFF as the QM engine), Dimer Builder, Normal Mode Sampling.
* Molecular and periodic systems (energy, forces and stress); runs on the CPU or a GPU
  (``device`` in ``xnn.ini``).
* There is no xnn step to place in a flowchart: the models are used through
  Model Chemistry + Energy (or LAMMPS).

.. _xnn: https://github.com/molssi-ai/xnn

Note: xnn is published on PyPI under the name ``xnns``; the import name and the ``xnn``
command are unchanged.

Acknowledgements
----------------

This package was created with the `molssi-seamm/cookiecutter-seamm-plugin`_ tool, which
is based on the excellent Cookiecutter_.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`molssi-seamm/cookiecutter-seamm-plugin`: https://github.com/molssi-seamm/cookiecutter-seamm-plugin

Developed by the Molecular Sciences Software Institute (MolSSI_),
which receives funding from the `National Science Foundation`_ under
award CHE-2136142.

.. _MolSSI: https://molssi.org
.. _`National Science Foundation`: https://www.nsf.gov


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

2026.9.19.1 (2026-09-19)
------------------------

* Bugfix: the ``seamm-xnn`` environment file no longer installs PyTorch with conda. On
  Linux conda-forge resolves ``pytorch`` to a CPU-only build, so updating an environment
  that held a pip CUDA build of PyTorch silently lost the GPU and broke every compiled
  extension built against it, such as ``vesin-torch``. PyTorch now comes from pip, which
  leaves a suitable existing installation alone.
* Bugfix: ``pymdi`` now comes from conda-forge rather than pip. Only that build links the
  MDI library against MPI, which the ``-method MPI`` launch used for LAMMPS dynamics
  needs; with the PyPI build the engine stopped at "Error in MDI_Init: Failed to
  initialize MPI".
* Bugfix: ``xnn-step-installer`` reported the xnn version as "unknown" because it looked
  for a distribution named ``xnn``, though the code is published as ``xnns``.
* Documented the two default model directories and their ``personal:``/``local:``
  prefixes, the MPI launch path, and the effect of pointing ``xnn.ini`` at an
  environment shared with another code.


2026.9.19 (2026-09-19)
----------------------

* Model directories in ``xnn.ini`` may be given as ``personal:<subdir>``
  (``~/.seamm.d/data/Forcefields/<subdir>``) or ``local:<subdir>``
  (``~/SEAMM/data/Forcefields/<subdir>``), the same convention as the Forcefield
  step; the default is ``personal:xnn`` then ``local:xnn``, a personal model
  shadowing a machine one of the same name. Each model's source (e.g.
  ``personal:xnn/water.pt``) is reported to the Model Chemistry step.
* Installs xnn from PyPI as ``xnns``; documents the Apple mps constraints.


2026.9.18 (2026-09-18)
----------------------

* Initial release. Provides xnn machine-learned force fields as ``xnn:MLFF@<model>``
  model chemistries (checkpoints discovered from the directories in ``xnn.ini``) and
  launches ``xnn mdi`` as the MDI engine for the Energy, LAMMPS and other MDI-driving
  steps. Includes ``xnn-step-installer`` for the ``seamm-xnn`` conda environment.
* Plug-in created using the SEAMM plug-in cookiecutter.
