freq

Compute ML/MM vibrational frequencies and thermochemistry (zero-point energy (ZPE), Gibbs energy, etc.) on a layered enzyme PDB, with partial-Hessian vibrational analysis (PHVA) support.

When to use mlmm freq:

• Validate stationary-point character of an optimized minimum, transition state, or IRC endpoint (a minimum has no imaginary frequencies; a transition state has exactly one).

• Compute quasi-rigid-rotor-harmonic-oscillator (QRRHO) thermochemistry.

The command runs vibrational analysis with the ML/MM calculator, honoring frozen atoms via PHVA. It exports normal-mode animations as _trj.xyz and .pdb (mapped back onto the enzyme ordering), and prints a Gaussian-style thermochemistry summary when the optional thermoanalysis package is installed.

Imaginary frequencies appear as negative values. When VRAM permits, --hessian-calc-mode Analytical speeds up Hessian evaluation.

Examples

Basic frequency analysis:

mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --out-dir ./result_freq

Limit the number of exported modes for quick inspection:

# Limit the number of exported modes for quick inspection
mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --max-write 6 --out-dir ./result_freq_quick

PHVA with explicit frozen atoms and dump thermo payload:

# PHVA with explicit frozen atoms and dump thermo payload
mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --freeze-atoms "1,3,5,7" --dump --out-dir ./result_freq_phva

Analytical Hessian mode on VRAM-rich nodes:

# Analytical Hessian mode on VRAM-rich nodes
mlmm freq -i pocket.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --hessian-calc-mode Analytical --out-dir ./result_freq_analytical

Workflow

1. ML/MM calculator setup — The ML region is supplied via --model-pdb; Amber parameters are read from --parm. --hessian-calc-mode selects analytical or finite-difference Hessians. The calculator may return either the full 3N x 3N Hessian or an active degree-of-freedom (DOF) sub-block.

2. PHVA & translation/rotation (TR) projection — With frozen atoms, eigenanalysis occurs inside the active subspace with translation/rotation modes projected there. Both 3N x 3N and active-block Hessians are accepted, and frequencies are reported in cm^-1 (negatives = imaginary).

3. Active DOF mode — --active-dof-mode selects which atoms enter the analysis (default partial); see the CLI options table for the four modes.

4. Mode export — --max-write limits how many modes are animated. Modes are sorted by value (or absolute value with --sort abs). Each exported mode writes _trj.xyz (XYZ-like trajectory) and .pdb files (PDB animation mapped back onto the enzyme ordering). The sinusoidal animation amplitude (--amplitude-ang) and frame count (--n-frames) match the YAML defaults.

5. Thermochemistry — If thermoanalysis is installed, a QRRHO-like summary (EE, ZPE, E/H/G corrections, heat capacities, entropies) is printed using PHVA frequencies. CLI pressure in atm is converted internally to Pa. When --dump, a thermoanalysis.yaml snapshot is also written.

6. Device selection — ml_device="auto" triggers CUDA when available, otherwise CPU. The internal TR projection/mode assembly runs on the same device to minimize transfers.

7. Exit behavior — Keyboard interrupts exit with code 130; other failures print a traceback and exit with code 1.

Outputs

out_dir/ (default: ./result_freq/)
├─ mode_XXXX_±freqcm-1_trj.xyz   # Per-mode animations (XYZ-like trajectory)
├─ mode_XXXX_±freqcm-1.pdb       # PDB animation mapped back onto the enzyme ordering
├─ frequencies_cm-1.txt           # Full frequency list using the selected sort order
└─ thermoanalysis.yaml            # Present when thermoanalysis is importable and --dump is True

• Console blocks summarizing resolved geom, calc, freq, and thermochemistry settings.

CLI options

mlmm freq --help shows core options; mlmm freq --help-advanced shows the full option list. The full flag list is in the generated command reference; the table below covers the options that need explanation.

Option	Description	Default
Input & charge
-i, --input PATH	Full enzyme PDB (no link atoms).	Required
--parm PATH	Amber parm7 topology for the full enzyme.	Required
--model-pdb PATH	PDB defining the ML region. Optional when --detect-layer is enabled.	None
--model-indices TEXT	Explicit ML-region atom indices (alternative to --model-pdb).	None
--model-indices-one-based / --model-indices-zero-based	Indexing convention for --model-indices.	True (1-based)
--detect-layer / --no-detect-layer	Auto-detect ML/MM layers from B-factors.	True
-q, --charge INT	ML region charge.	None (required unless -l is given)
-l, --ligand-charge TEXT	Per-resname charge mapping (e.g., GPP:-3,SAM:1). Derives net charge when -q is omitted.	None
-m, --multiplicity INT	Spin multiplicity (2S+1).	1
--ref-pdb FILE	Reference PDB topology for non-PDB inputs.	None
Backend & compute
-b, --backend CHOICE	MLIP backend for the ML region: uma (default), orb, mace, aimnet2.	uma
--precision [fp32|fp64]	MLIP backend precision; routed to backend-native kwarg (UMA precision, ORB precision, MACE default_dtype; aimnet2: fp32 no-op, fp64 rejected).	fp32
--mm-backend [hessian_ff|openmm]	MM backend (analytical Hessian vs OpenMM finite-difference).	hessian_ff
--link-atom-method [scaled|fixed]	Link-atom placement: scaled ($g$-factor) or fixed 1.09/1.01 Å.	scaled
--cmap/--no-cmap	Enable CMAP (backbone cross-map dihedral correction) in model parm7. Default: disabled (consistent with Gaussian ONIOM).	--no-cmap
--embedcharge/--no-embedcharge	Enable xTB point-charge embedding correction for MM-to-ML environmental effects (experimental).	False
--embedcharge-cutoff FLOAT	Cutoff radius (Å) for embed-charge MM atoms.	12.0
--hess-device CHOICE	Device for Hessian assembly/diagonalization: auto, cuda, cpu. Use cpu to avoid VRAM issues with large systems.	auto
Active-region freezing & Hessian
--freeze-atoms TEXT	1-based comma-separated frozen atom indices.	None
--active-dof-mode CHOICE	Active DOF selection: all, ml-only, partial, unfrozen.	partial
--hess-cutoff FLOAT	Cutoff distance for Hessian-target MM atoms.	None
--movable-cutoff FLOAT	Cutoff distance for movable-MM layer.	None
--hessian-calc-mode CHOICE	Hessian mode (Analytical or FiniteDifference).	FiniteDifference
--dump-hess PATH	Save computed Hessian to a compressed .npz file. Can be loaded by mlmm irc --read-hess.	None
Mode export
--max-write INT	Number of modes to export.	10
--sort CHOICE	Mode ordering: value (cm^-1) or abs.	value
--amplitude-ang FLOAT	Mode animation amplitude (angstrom).	0.8
--n-frames INT	Frames per mode animation.	20
--convert-files/--no-convert-files	Toggle XYZ/TRJ to PDB companions when a PDB template is available.	True
Thermochemistry
--temperature FLOAT	Thermochemistry temperature (K).	298.15
--pressure FLOAT	Thermochemistry pressure (atm).	1.0
--dump/--no-dump	Write thermoanalysis.yaml.	False
Output & config
-o, --out-dir TEXT	Output directory.	./result_freq/
--out-json/--no-out-json	Write machine-readable result.json to out_dir.	False
--config FILE	Base YAML configuration applied before explicit CLI options.	None
--show-config/--no-show-config	Print resolved YAML layers/config and continue.	False
--dry-run/--no-dry-run	Validate and print execution plan without running frequency analysis. Shown in --help-advanced.	False

YAML configuration

Provide mappings with merge order defaults < config < explicit CLI < override. Shared sections reuse YAML Reference. An additional thermo section is supported for thermochemistry controls.

geom:
 coord_type: cart                  # coordinate type: cartesian vs dlc internals
 freeze_atoms: []                  # 1-based frozen atoms merged with CLI/link detection
calc:
 charge: 0                         # net charge (CLI override)
 spin: 1                           # spin multiplicity 2S+1
mlmm:
 real_parm7: real.parm7            # Amber parm7 topology
 model_pdb: ml_region.pdb          # ML-region definition
 backend: uma                      # MLIP backend: uma | orb | mace | aimnet2
 embedcharge: false                # xTB point-charge embedding correction
 uma_model: uma-s-1p1              # uma-s-1p1 | uma-m-1p1
 uma_task_name: omol                # UMA task name (UMA backend only)
 ml_device: auto                   # ML backend device selection
 hessian_calc_mode: FiniteDifference   # Hessian mode (FiniteDifference default; Analytical for higher VRAM jobs)
 out_hess_torch: true              # request torch-form Hessian
 mm_fd: true                       # MM finite-difference toggle
 return_partial_hessian: true      # allow partial Hessians (PHVA default)
freq:
 amplitude_ang: 0.8                # displacement amplitude for modes (Å)
 n_frames: 20                      # number of frames per mode
 max_write: 10                     # maximum number of modes to write
 sort: value                       # sort order: value vs abs
thermo:
 temperature: 298.15               # thermochemistry temperature (K)
 pressure_atm: 1.0                 # thermochemistry pressure (atm)
 dump: false                       # write thermoanalysis.yaml when true

See Also

• tsopt — Optimize TS candidates (validate with freq/IRC; expected: one imaginary frequency)

• opt — Geometry optimization (often precedes freq)

• dft — Single-point DFT for higher-level energy refinement

• all — End-to-end workflow with --thermo

• Common Error Recipes — Symptom-first failure routing

• Troubleshooting — Detailed troubleshooting guide

• YAML Reference — Full freq and thermo configuration options

• Glossary — Definitions of ZPE, Gibbs Energy, Enthalpy, Entropy