Metadata-Version: 2.4
Name: active_learning_step
Version: 2026.10.14.1
Summary: A SEAMM plug-in for Active Learning
Home-page: https://github.com/molssi-seamm/active_learning_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: ase
Requires-Dist: molsystem
Requires-Dist: numpy
Requires-Dist: seamm
Requires-Dist: seamm-exec
Requires-Dist: seamm-util
Requires-Dist: seamm-widgets
Requires-Dist: tabulate
Requires-Dist: xnn-step>=2026.10.14
Provides-Extra: score
Requires-Dist: xnns>=0.11.1; extra == "score"
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: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

=============================
SEAMM Active Learning Plug-in
=============================

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

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

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

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

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

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

A SEAMM plug-in for query-by-committee active learning of machine-learned force
fields: a committee of models trained on different folds of the data disagrees where
the model is likely wrong, so only the frames it flags need labelling.

* Free software: BSD-3-Clause
* Documentation: https://molssi-seamm.github.io/active_learning_step/index.html
* Code: https://github.com/molssi-seamm/active_learning_step

Features
--------

* ``active_learning_step.committee``: a committee of xnn potentials and its spreads
  (energy, force, per-atom force, atomic and molecular pressure), for molecules,
  ions and charged systems.
* ``seamm-al score``: the committee's spreads for every frame of extxyz or SDF pools.
* ``seamm-al select``: rank the frames and take them within a core-hour budget, with
  caps per group and exclusions, writing the chosen frames as a verbatim subset of
  the input files.

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.14.1 -- The Active Learning step for flowcharts
    * The Active Learning step now holds four sub-steps: Train Committee, Check
      Committee, Score Pool and Select Frames, which do in a flowchart what the
      seamm-al command does. Each can use the committee, scores and thresholds made
      earlier in the job, and their dialogs show only the settings that apply.
    * Training, checking and scoring run in the MLFF environment of the xnn plug-in
      (xnn.ini) as tasks of the job, with nothing to install there; selecting runs in
      SEAMM.
    * Score Pool takes candidates from the job's database, with the standard
      selection of systems and configurations, or from extxyz and SDF files. Select
      Frames puts selected configurations from the database in a variable for later
      steps and can copy them into a new system.
    * Train Committee can save the committee as an xnn model, which the Model
      Chemistry step then offers (with xnn-step 2026.10.14 or later) for molecular
      dynamics with the committee mean, recording the members' spreads; with
      lammps-step 2026.10.14.1 or later this also runs on the CPU.
    * Candidate files may be gzipped, such as the trajectories LAMMPS writes.
    * Requires xnn-step 2026.10.14 or later.

2026.10.14 -- Initial release: query-by-committee active learning for MLFFs
    * A committee of machine-learned force fields, trained on different folds of the
      data, disagrees where the model is likely wrong; the seamm-al command uses that
      disagreement to choose what to label next. This first release provides the
      library and the command line; the SEAMM flowchart step is a placeholder.
    * seamm-al score: the committee's spreads (energy, forces, the largest per-atom
      force spread, atomic and molecular pressure) for every frame of extxyz or SEAMM
      SDF pools, with the total charge passed to the models. Molecules follow SEAMM's
      own rule (molsystem's bond perception, ions on their own), applied without
      SEAMM in MLFF environments, or a SEAMM structure's own bonds.
    * seamm-al select: rank the frames, or keep those past thresholds, and take them
      within a core-hour budget, with costs per kind or group, caps per column and
      exclusions; or draw at random (optionally stratified) before any committee
      exists. The chosen frames are copied byte for byte from the input files.
    * seamm-al train: train the k members of a committee from an xnn recipe, with
      stratified folds, a fixed share of cell batches and a manifest of the folds,
      seeds, data and code versions. Requires xnn 0.13 or later.
    * seamm-al check: whether the spreads predict the out-of-fold errors (Spearman
      correlations, threshold calibration) and the health of each member (losses,
      errors, leave-one-out spreads), with an option to drop a member.
    * seamm-al engine: the committee mean as one MDI engine for LAMMPS, writing the
      spreads every N steps and flagging frames past a threshold.
    * seamm-al data: check a LAMMPS data file for what atom_style atomic can read.

