Active Learning Workflows#

Two distinct mechanisms share the name “active learning” in Enerzyme documentation.

Decision guide#

  • Enerzyme internal dataset AL — All candidates already in one labeled dataset; resample via withheld partition

  • Enerzymette-driven loop — New geometries from MD/PLUMED; QM on fragments

Enerzyme internal dataset AL#

Single command:

enerzyme train -c active_learning_train.yaml -o al_out/

Key settings:

  • Trainer.committee_size > 1

  • Trainer.active_learning_params.active: true

  • data_source: withheld

  • picking_method: max_Fa_norm_std, mean_Fa_std, or random

  • picking_params error bounds filter trivial or divergent samples

  • Splitter with small training and large withheld

Picking references:

    1. Chem. Inf. Model. 2024, 64, 6377-6387

  • Comput. Phys. Commun. 2020, 253, 107206

Does not run simulate, extract, or annotate.

Enerzymette-driven external loop#

Managed by:

enerzymette enerzyme_active_learning \
    -p parent_model_dir \
    -sc config/simulate.yaml \
    -ec config/extract.yaml \
    -ac config/annotate.yaml \
    -tc config/train.yaml \
    -n <iterations> -np <presim_steps> \
    -cp <calc_patch> -pp <plumed_plugin> \
    -rp <reference.pdb> -ts <template.sdf>

Additional flags: --initial-scan, -nis, --initial-structures-config, -ix, -mc, -cl, --reset_parameters, -rm. See Active Learning for Neural Network Potentials for descriptions.

Per-iteration stages#

  1. MD — FFxx_md/ (simulation.yaml, plumed.traj.xyz, plumed.traj.pkl)

  2. Prediction — uncertainty on trajectory frames

  3. Extraction — FFxx_extraction/FFxx_fragments.sdf

  4. Annotation — QM on fragments → fragments.pkl

  5. Training — merge data, pretrain_path from previous model, new suffix

  6. Model — FFxx/ checkpoints for next round

Structure pool#

The launcher rotates starting geometries through structure_pool.json and structure_pool/*.xyz. Pool initialization:

  • Default — System.structure_file from -sc template

  • -ix — custom initial XYZ

  • --initial-scan — initial_scan/local_minima/ after chained plumed_scan

  • --initial-structures-config — one entry per system from a manifest YAML

Multi-system manifest entries require name, reference_pdb, and simulation_config per system; optional reference_sdf and reference_xyz. Topology is written to topology/<name>/. Multi-system mode excludes --initial-scan, -rp, -ts, -ix, and proton_transfer in templates.

Task folder template#

task_root/
|-- al.sh
|-- cluster.xyz
|-- cluster.mol
|-- structure_pool.json
|-- structure_pool/
|-- config/
|   |-- simulate.yaml    # sampling policy; paths filled per round
|   |-- extract.yaml     # data_path null in template
|   |-- annotate.yaml    # Supplier.path empty in template
|   `-- train.yaml       # architecture; paths/suffix filled per round
|-- FF02-0 -> parent_pretrained_model
|-- FF02-0_md/
|-- FF02-0_prediction/
|-- FF02-0_extraction/
|-- FF02-0_fragments/
|-- FF02-0_training/
`-- FF02-1/

Template rewrite rules#

  • simulate.yaml — System.structure_file → FFxx_md/initial_structure.xyz

  • extract.yaml — Datahub.data_path → trajectory pickle; reference_mol_path → per-system topology/<name>/cluster.mol in multi-system mode

  • annotate.yaml — Supplier.path → fragment SDF

  • train.yaml — pretrain_path, suffix, dataset paths, UDD B may update from validation error

Initial scans#

  • Integrated — --initial-scan on enerzymette enerzyme_active_learning populates structure_pool/ before iteration 0

  • Standalone — enerzymette enerzyme_scan in separate scan-* folders for manual exploration or input preparation

Failure recovery#

  • Archive config.yaml and checkpoints each iteration

  • Resume training with Trainer.resume: 2 inside a round if needed; -cl sets this automatically on later AL iterations

  • Enerzymette -rm restraint mode and structure-pool state files support resuming mid-campaign

See also Active Learning for Neural Network Potentials for a tutorial-style walkthrough and Enerzymette Integration.