Seeded Active Learning

The seeded active learning example shows how to start ALF from user-provided structures and optional existing labeled data. Use this when you already have reasonable starting configurations, a small labeled dataset, or both, and want to avoid a random bootstrap stage.

The files needed to run the example are located in examples/seeded_active_learning.

Before You Run

This example assumes you can provide starting structures, prior HDF5 data, or both.

Convert starting structures to ASE-readable .cfg files and place them in fragment_library.
Place optional prior labeled data in h5store using ALF/HIPPYNN HDF5 format.
Edit hippynn_config.json so architecture, species, and data keys match the provided HDF5 data.
Edit orca_config.json so QM_run_command points to the local ORCA executable.
Edit parsl_configs.py for the target machine.

Workflow Pattern

This example uses ALF’s standard tasks:

Stage	Task
Builder	`alframework.builders.builders.simple_cfg_loader_task`
Sampler	`alframework.samplers.mlmd_sampling.simple_mlmd_sampling_task`
QM	`alframework.qm_interfaces.orca5_interface.orca_calculator_task`
ML	`alframework.ml_interfaces.hippynn_interface.train_HIPPYNN_ensemble_task`

The builder reads .cfg structures from fragment_library. The ML task is the normal HIPPYNN ensemble training task, so this example does not require a pretrained model or a custom task.

Seed The Run

Place starting structures in the fragment library:

fragment_library/water_seed.cfg
fragment_library/your_structure.cfg
...

Set shake in builder_config.json to 0.0 to reuse those structures exactly, or to a small value such as 0.05 to perturb each loaded structure before sampling.

If you already have labeled data in ALF/HIPPYNN HDF5 format, place it in the run’s HDF5 store:

h5store/data-0000.h5
h5store/data-0001.h5
...

When status.txt is absent and h5store/data-0000.h5 exists, ALF detects the existing HDF5 store. Because labeled data already exists, ALF skips the random bootstrap-labeling stage and trains models/model-0000 from the provided data before starting ML-driven sampling.

Recommended Bring-Up Commands

From examples/seeded_active_learning:

python -m alframework --master master_config.json --test_builder
python -m alframework --master master_config.json --test_ml
python -m alframework --master master_config.json --test_sampler
python -m alframework --master master_config.json --test_qm

Run --test_ml only after at least one HDF5 file exists in h5store. Run --test_sampler after models/model-0000 has been trained or placed under models/.

After the stage checks pass, start ALF:

python -m alframework --master master_config.json

Expected Outputs

During a seeded run, ALF writes the standard outputs:

Path	Purpose
`status.txt`	Restart state, including current HDF5 and model ids.
`models/model-0000`	First ensemble trained from the provided HDF5 data.
`h5store/data-*.h5`	Existing and newly labeled data batches.
`sampling/metadata-*.p`	MLMD sampling metadata and uncertainty diagnostics.
`qm_scratch/`	ORCA input, output, and scratch directories for selected structures.

Use this example when you want ALF to start from your own structures or data. Use the fine-tuning example when you also want to initialize training from existing model weights.