Metadata-Version: 2.4
Name: xnn_step
Version: 2026.9.19
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.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: seamm
Requires-Dist: seamm-installer
Requires-Dist: seamm-util
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: 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.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.
