Enhanced Sampling and Hybrid Potentials#

Beyond standard MD and distance scans, Enerzyme supports PLUMED-biased dynamics, PLUMED flexible scans, and hybrid internal/external calculators. PLUMED workflows integrate with Enerzymette CV plugins.

PLUMED steered MD (task: plumed)#

Requires py-plumed and a PLUMED-enabled library build.

Minimal config (enerzyme/config/plumed.yaml):

Simulation:
    task: plumed
    idx_start_from: 1
    neighbor_list: full
    sampling:
        params:
            plumed_setup:
            - "UNITS LENGTH=A TIME=0.010180505671156723 ENERGY=96.48533288249877"
            - "FLUSH STRIDE=20"
    integrate:
        integrator: Langevin
        time_step: 0.5
        temperature_in_K: 300
        friction: 0.01
        n_step: 100000

Caution

The UNITS line must match ASE unit conventions for your model’s Hartree_in_E and time step. Incorrect units are a common source of unstable biased MD.

Enerzyme writes plumed.dat and runs Langevin dynamics with the PLUMED wrapper. Trajectory: plumed.traj.xyz.

CV plugins via -pp#

For reaction-specific collective variables, pass a PLUMED patch module:

enerzyme simulate -c config.yaml -o out/ -m model_dir/ -pp /path/to/sammt.py

When plumed_config_generator is set, Enerzyme calls a named generator instead of static plumed_setup lines:

Simulation:
    task: plumed
    plumed_config_generator:
        name: SAMMTConfigGenerator
        method: standard_steered_md
    sampling:
        params:
            plumed_config:
                dump_interval: 20
                lower_bound: -1.5
                upper_bound: 1.5
                reference_pdb_file: ref.pdb

Enerzymette registers built-in plugins (e.g. sammt) and resolves them with get_plumed_patch(key). See the Enerzymette PLUMED plugin README.

PLUMED flexible scan (task: plumed_scan)#

Unlike legacy task: scan (ASE distance + FixBondLengths), plumed_scan restrains a CV at each scan point via PLUMED:

Simulation:
    task: plumed_scan
    plumed_config_generator:
        name: SAMMTConfigGenerator
        method: scan
    optimize:
        optimizer: LBFGS
    sampling:
        cv: plumed
        params:
            x0: 0.42
            x1: -1.2
            num: 25
            plumed_config:
                lower_bound: -1.5
                upper_bound: 1.5

Output: scan_optim.xyz (same as bond-distance scan).

Dual scan paths#

Path

task

CV mechanism

Legacy bond scan

scan

ASE distance

CV plugin scan

plumed_scan

Enerzymette PLUMED plugin

Enerzymette launchers#

Enerzymette automates scan and AL workflows:

enerzymette enerzyme_scan

Flexible bond or PLUMED CV scans. For each elementary reaction: optimize reactant → scan → optimize product → analyze path. Key flags:

  • -q — TeraChem input or YAML scan config (charge, frozen atoms, scan bond)

  • -pp — PLUMED plugin key (e.g. sammt); switches to plumed_scan

  • -psc — YAML with CV parameters (lower_bound, reference_pdb_file, etc.); required when -pp is set

Example scan config for bond-distance mode (-q scan_config.yaml):

reference_pdb: cluster.pdb
reference_sdf: ligands.sdf
multiplicity: 1
freeze_index_types: [backbone, Calpha]
constraint_scan:
    bond:
        plugin: sammt
        substrate: G
        nucleophile: "O2'"

Supporting utility: enerzymette update_terachem_scan refreshes coordinates in a TeraChem scan input after a structure update.

enerzymette enerzyme_neb

NNP-driven NEB through ORCA ExtOpt and a running enerzyme listen server. Requires -r, -p, -q (reference TeraChem input), -c (server config), and -m (model directory). See Prediction Server and Enerzymette Integration.

enerzymette enerzyme_active_learning

Runs the external active-learning loop around Enerzyme simulation, extraction, QM annotation, and retraining. --initial-scan runs chained plumed_scan jobs before iteration 0 to populate a structure pool. See Active Learning for Neural Network Potentials for the expected task-folder layout and template input files.

Hybrid and external calculators#

enerzyme/config/uma.yaml shows blending an external ASE calculator with an internal MLFF:

Simulation:
    external_calculator:
        name: uma_calculator
        weight: 1.0
    uncertainty_calculator:
        name: UDD
        params:
            A: 4
            B: 1
    internal_calculator_weight: 0.0
    task: md

Provide the external calculator via a patch module:

enerzyme simulate -c uma.yaml -o out/ -m model_dir/ -cp my_calculator_patch.py

The patch module must expose a factory (e.g. get_uma_calculator) referenced by external_calculator.name. UDD applies uncertainty-driven debiasing when an internal model remains loaded (internal_calculator_weight > 0).

When to use hybrid mode#

  • Long-range or electronic effects missing from the MLFF

  • Uncertainty-aware correction during exploration

  • Pure external potential MD with ML uncertainty monitoring (internal_calculator_weight: 0)

Next steps#