In a flowchart: Active Learning step

The Active Learning step brings query by committee into SEAMM flowcharts. It holds four sub-steps, used in any order and combination:

sub-step	what it does
Train Committee	trains a committee of xnn models, each on all but one fold of the labelled data (seamm-al train)
Check Committee	checks that the members’ spread predicts their error on frames they never saw, flags members that trained badly and calibrates thresholds of the spreads (seamm-al check)
Score Pool	scores candidate structures by how much the members disagree on them (seamm-al score)
Select Frames	selects the structures to label, by spread or at random, within a budget (seamm-al select)

A round of active learning might be one flowchart: Train Committee and Check Committee, then molecular dynamics with the new committee to make candidates (see Committees as model chemistries), then Score Pool and Select Frames, and the labelling of the selected structures. The first round, before there is a committee, is Score Pool with the committee set to none and Select Frames drawing at random.

What the sub-steps share

Each sub-step can use what an earlier one made in the same job, so the defaults chain them together:

• the committee (previous) is the last one trained, checked or used to score;

• the scores (previous) are those of the last Score Pool;

• the thresholds (from Check Committee) are those calibrated by the last Check Committee.

This holds across Active Learning steps too: a flowchart can train a committee in one, run molecular dynamics, and score and select in another. Any of them can instead be given explicitly: a committee’s directory (holding the members m0, m1, …), or scores files.

Where they run

Training, checking and scoring need torch and xnn. They run in the MLFF environment of the xnn plug-in, the one named in the installation’s xnn.ini, as a task of the job like any other code, with the job’s cores (--ncores limits them). Nothing has to be installed there: the step copies this package into _code/ in its directory and puts it on that environment’s PYTHONPATH, so the code that runs is the code of the SEAMM installation. Training needs xnn 0.13 or later (see Environments). Select Frames needs neither and runs in SEAMM itself.

The device is chosen in each sub-step: by default the one in xnn.ini for checking and scoring, and the recipe’s for training.

Each sub-step leaves everything seamm-al wrote in its directory, with the command in step.out and its output in stdout.txt and stderr.txt.

Train Committee

Give the labelled structures, as extended XYZ files with the reference energies and forces (names or patterns such as data/*.extxyz), and the xnn recipe: the YAML configuration of the model and its training. The committee is written to committee/ in the step’s directory, with a manifest of the folds, seeds, code and data, and is printed with each member’s validation losses.

• Number of members is also the number of folds. Members to train trains only some of them, so a large committee can be trained by several jobs into the same directory.

• Folds split clusters and periodic cells separately by default, so every fold has its share of both; Also balance by adds keys of the structures’ info, such as the temperature.

• Share of cell batches and Cells per batch control how often periodic cells are drawn when they are far fewer, or far more costly, than clusters.

• Changes to the recipe override recipe settings, e.g. optim.lr=0.005.

• Save as the model copies the members into your xnn models, so that the Model Chemistry step offers the committee as xnn:MLFF@<name>.

Check Committee

By default the committee is checked on its own training data: each member is judged on the fold it never saw, which is what makes the check honest without new labels. New labelled structures that no member saw can be given instead. The step prints:

• the rank correlation (Spearman) of each spread with the corresponding error, which should be clearly positive for the spread to be a useful guide;

• each member’s health: its validation losses and errors, and whether it inflates the spreads; a member whose final validation loss is well above the others’ is flagged, and can be left out with Leave out members in Score Pool;

• for each NAME:ERROR[:CAPTURE] in Calibrate thresholds, the threshold of the spread that catches the fraction CAPTURE (0.98 by default) of the structures whose error is above ERROR. For example rho_forces:0.15 calibrates the force spread against force errors above 0.15 eV/Å.

Score Pool

The candidates are either structures in the job’s database, chosen with the usual system and configuration selection, or extended XYZ or SDF files (gzipped ones too, such as the trajectory.extxyz.gz the LAMMPS step writes). Structures from the database are written to pool.extxyz with their system and configuration ids, so that a selection can be traced back to them.

scores.csv has a row per candidate with its spreads (see Scoring); the step prints their median and largest values by kind, and the candidates with the largest force spreads. Keep info keys copies keys of the candidates’ info into the scores, to set costs by or to balance a random draw over. With the committee set to none, the candidates are only listed, for a random draw.

Select Frames

By default the candidates the committee disagrees on most are selected: ranked by the spreads of their kind (the molecular pressure and force spreads for cells, the force spread for clusters), and, with Thresholds, only those whose spread reaches one, as calibrated by Check Committee or given. Select random draws them at random instead, optionally spread evenly over columns of the scores.

The budget is in core-hours, with the cost per structure given by kind (and group, for structures of one kind that cost differently); without costs each structure counts one, and the budget is a number of structures. Already labelled files of configuration names keep structures from being selected twice, and At most per value caps how many come from, for example, one trajectory.

The selected structures are copied, byte for byte, from the candidates’ files into selected.extxyz (or .sdf), with selection.csv listing them and why, and rejected.csv the others and why not. When the candidates came from the database, the selected configurations are also put in a variable (selected_configurations by default), which later steps can take as their structures, and, if asked, copied into a new system.

Committees as model chemistries

A committee – a directory of members m0/best.pt, m1/best.pt, … – is a model like any other for the xnn plug-in. Saved with Train Committee’s Save as the model, or placed in one of the model directories of xnn.ini, it is offered by the Model Chemistry step as xnn:MLFF@<name>; its directory can also be given as the Model Chemistry step’s Checkpoint, for example $committee, the result of a Train Committee earlier in the job. A committee.json in the directory, such as {"members": ["m0", "m1", "m3"]}, chooses the members to use.

Energy, LAMMPS and the other steps that drive a model chemistry then run the committee as the committee-mean engine (see Committee molecular dynamics): the forces and energy are the members’ mean, and every ten steps their spreads are appended to committee_spreads.csv in the step’s directory. The Model Chemistry step’s Engine options go to this engine: --every 20 changes how often the spreads are written, --flag rho_forces=0.2 writes the frames whose spread reaches the value to flagged.extxyz, and --dtype float32 and --eeq-reuse work as for a single model. The engine is about the members’ cost together, so expect molecular dynamics several times slower than with one model on a CPU, and about twice as slow on a GPU. Without a free GPU the LAMMPS step (2026.10.14.1 or later) runs the engine on the CPU with the job’s cores, which is practical for boxes of a few hundred atoms.