active-learning-step

=============================
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.17 -- Bugfix: a committee's engine beside a GPU uses its CPU threads
    * The CPU threads torch uses now follow ``TORCH_NUM_THREADS`` before
      ``OMP_NUM_THREADS``. Next to a GPU, LAMMPS's launcher keeps ``OMP_NUM_THREADS`` at 1
      and gives torch 4 threads through ``TORCH_NUM_THREADS``, but the committee's
      engine read only ``OMP_NUM_THREADS``, so its work on the CPU, such as the spreads,
      ran on a single thread. The engine's log says which setting it used.

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.