Units and Standard Fields#

Enerzyme maps dataset attributes to standard field names so the same model code works across QM packages and naming conventions. Units must stay consistent across Datahub, Modelhub, and Simulation.

Standard fields#

Defined in enerzyme/data/datatype.py:

  • N (global) — Number of atoms per frame

  • Ra (atomic) — Cartesian coordinates

  • Za (atomic) — Atomic numbers

  • E (global) — Total energy

  • Fa (atomic) — Atomic forces (not raw gradients)

  • Qa (atomic) — Atomic partial charges

  • Q (global) — Total charge

  • M2 (global) — Dipole moment (3-vector)

  • S (global) — Spin multiplicity (spin-aware models)

Custom fields can be registered under Datahub.fields with is_atomic: true (see /user_guide/data/datahub_reference).

Energy and length units#

Model build_params define conversion to internal atomic units:

  • Hartree_in_E — numeric value of one Hartree in your energy unit

  • Bohr_in_R — numeric value of one Bohr in your coordinate unit

Examples:

  • Ha and Angstrom: Hartree_in_E: 1, Bohr_in_R: 0.5291772108

  • eV and Angstrom: Hartree_in_E: 27.211386, Bohr_in_R: 0.5291772108

Simulation configs may repeat Hartree_in_E under Simulation for ASE integrators. PLUMED requires a matching UNITS line in plumed.dat (see Enhanced Sampling and PLUMED).

Forces vs gradients#

Quantum chemistry outputs are often energy gradients \(\nabla E\), while forces are \(F = -\nabla E\). Set:

transforms:
    negative_gradient: true

when Fa targets in the dataset are raw QC gradients. TeraChem parsers (e.g. scripts/picklizer.py) may already convert gradient units from Ha/Bohr to Ha/Angstrom; still apply the sign flip if needed.

Loss and metric weights#

Loss and Metric weights are not dimensionless. Force terms are typically scaled to match energy units per length unit. A common pattern for Ha and Angstrom:

loss:
    rmse:
        E: 1
        Fa: 52.917721
        M2: 1.8897261

The force weight approximates \(\mathrm{Ha}/\mathrm{Bohr}\) expressed in your target force unit (e.g. eV/Angstrom). Keep loss and validation Metric weights aligned so early stopping reflects the same scale.

Time units in MD#

Simulation.fs_in_t sets how many femtoseconds correspond to one unit of integrate.time_step and friction. Default 1 means time_step is in fs.

Uncertainty fields#

Committee or shallow-ensemble models may expose E_var, Fa_var, Qa_var. Request them via Trainer.non_target_features in predict configs. See Loss, Metrics, and Uncertainty.