Extracting Fragments by Local Uncertainty#

enerzyme extract identifies substructures around locally uncertain regions in predicted structures, typically for targeted QM relabeling in an active-learning loop. The reference config is enerzyme/config/extract.yaml.

Basic command#

enerzyme extract -c extract.yaml -o extract_out/ -m model_dir/ -mc train.yaml

Arguments match predict plus:

  • -s / --skip_prediction — skip inference if prediction pickles already exist in output_dir

Workflow#

  1. Predict on a candidate structure set (committee model recommended)

  2. Rank atoms by local force uncertainty (committee std)

  3. Extract fragments centered on uncertain atoms, using a reference molecule for connectivity

  4. Annotate extracted fragments with QM (QM Data Annotation)

  5. Merge new labels into the training pool (Active Learning for Neural Network Potentials)

Configuration#

Datahub:
    data_format: pickle
    data_path: "candidates.pkl"
    features:
        N:
        Q: Q
        Ra: Ra
        Za: Za
    neighbor_list: full
    preload: true
Extractor:
    reference_mol_path: "reference.sdf"
    fragment_per_frame: 1
    local_uncertainty_radius: 5
    fragment_radius: 5

Extractor parameters#

reference_mol_path

Reference structure in SDF format. One molecule applies to all frames; multiple entries align by index with frames.

fragment_per_frame

Number of top-uncertainty fragments to extract per structure.

local_uncertainty_radius

Neighborhood radius (Å) for aggregating atomic uncertainty (J. Chem. Inf. Model. 2024, 64, 6377–6387).

fragment_radius

All heavy atoms within this radius (Å) of the uncertain center are included in the fragment.

Prerequisites#

  • A committee-trained model (committee_size > 1) for meaningful force variance

  • Prediction step (unless --skip_prediction) using the same Datahub features as training

  • RDKit (installed with Enerzyme) for fragment manipulation

Example with skip prediction#

After a prior predict or extract run saved pickles:

enerzyme extract -c extract.yaml -o extract_out/ -m model_dir/ -mc train.yaml -s

Outputs#

Extracted fragments are written under output_dir for downstream annotate or manual QC. Use consistent charge and connectivity with your reference SDF.

Closing the loop#

simulate / AL sampling  →  predict  →  extract  →  annotate  →  merge dataset  →  train

See Active Learning for Neural Network Potentials for the iterative training side and QM Data Annotation for labeling.