Running Simulations with a Trained Model#

Enerzyme wraps trained models as ASE calculators for geometry optimization, scans, molecular dynamics, and nudged elastic band (NEB) calculations. Reference configs live in enerzyme/config/.

Basic command#

enerzyme simulate -c opt.yaml -o sim_out/ -m model_dir/ -mc train.yaml

Arguments:

  • -c — simulation YAML (Simulation + System)

  • -m — trained model directory

  • -mc — training config (defaults to model_dir/config.yaml)

  • -o — output directory for trajectories and logs

  • -cp — optional external calculator patch module (hybrid potentials)

  • -pp — optional PLUMED CV plugin module (see Enhanced Sampling and Hybrid Potentials)

Shared configuration blocks#

System#

System:
    structure_file: "initial.xyz"
    charge: -1
    multiplicity: 1

structure_file is an ASE-readable path. For NEB it may contain multiple frames (see below).

Simulation#

Common keys:

  • task — sp, opt, scan, md, neb, plumed, or plumed_scan

  • environment — ase (currently the only backend)

  • neighbor_list — must match training (full or on-the-fly)

  • idx_start_from — 1 for 1-based or 0 for 0-based atom indices

  • dtype — float64 recommended for optimization

  • cuda — GPU inference when available

  • constraint — fix_atom, Hookean_allpairs, etc.

Caution

Units. Model Hartree_in_E and Bohr_in_R from training define energy and force units in ASE. MD configs may set fs_in_t and Hartree_in_E under Simulation for time-step conversion.

Single-point energy (task: sp)#

Computes energy (and available properties) for each frame in structure_file. Output: sp.xyz.

Geometry optimization (task: opt)#

See enerzyme/config/opt.yaml.

Simulation:
    task: opt
    optimize:
        optimizer: LBFGS
    constraint:
        fix_atom:
            indices: [1, 2, 3, 4, 5]

Outputs: traj-opt.xyz (optimization path), optim.xyz (final structure).

Distance scan (task: scan)#

See enerzyme/config/scan.yaml. Scans the distance between two atoms while optimizing all other degrees of freedom at each point.

Simulation:
    task: scan
    sampling:
        cv: distance
        params:
            i0: 100
            i1: 101
            x0: 3.812
            x1: 1.492
            num: 25

Outputs: scan_optim.xyz, per-point traj-<i>.xyz.

Note

For chemistry-specific collective variables and PLUMED-based scans, use task: plumed_scan with Enerzymette CV plugins (Enhanced Sampling and Hybrid Potentials).

NVT molecular dynamics (task: md)#

See enerzyme/config/nvt_md.yaml.

Simulation:
    task: md
    fs_in_t: 1
    integrate:
        integrator: Langevin
        time_step: 0.5
        temperature_in_K: 300
        friction: 0.01
        n_step: 100000

Output trajectory: md.traj.xyz. Optional initialize block sets Maxwell–Boltzmann velocities.

NEB and CI-NEB (task: neb)#

See enerzyme/config/neb.yaml.

Simulation:
    task: neb
    sampling:
        params:
            num_images: 25
            spring_constants: 0.1
            climb: true
            interpolation:
                method: idpp
                apply_constraints: true

Structure file formats (multi-frame XYZ):

  • 2 frames — reactant and product; Enerzyme interpolates num_images with IDPP

  • 3 frames — reactant, TS guess, product; two-stage interpolation

  • num_images frames — use pre-built path as-is

By default endpoints are relaxed before interpolation (relax_endpoints: true). Outputs include neb.xyz, ci-neb.xyz when climbing is enabled, and per-image XYZ files.

Note

To build an initial path externally, Enerzymette provides enerzymette idpp (see Bond Assignment and Utility Tools).

Supported optimizers#

Geometry and NEB: BFGS, LBFGS, MDMin, FIRE, GPMin, and line-search variants. NEB-specific: odesolver, static.

Next steps#