`tsopt`¶

Overview¶

Summary: Optimize a transition-state candidate using Dimer (--opt-mode grad) or RS-I-RFO (--opt-mode hess, default). Microiteration (--microiter, default on) alternates ML 1-step RS-I-RFO and MM relaxation in hess mode. A validated TS should show exactly one imaginary frequency; always confirm the mode/connectivity with freq/IRC.

Choosing `--opt-mode`¶

Use --opt-mode hess (RS-I-RFO) when you want the default, conservative optimizer and you can afford Hessian work. With --microiter (default on), ML and MM regions are optimized alternately.
Use --opt-mode grad (Dimer) when you want a lighter-weight search, or when you plan to iterate quickly from several TS guesses. --ml-only-hessian-dimer uses only the ML-region Hessian for dimer orientation (faster).

mlmm tsopt carries out transition-state optimization tailored to the ML/MM calculator. The optimizer starts from a TS guess and refines it to a first-order saddle point.

Key characteristics¶

Partial Hessian guided Dimer: During the loose/final Dimer loops, the hessian_ff finite-difference Hessian is disabled (mm_fd=False). The ML backend Hessian is embedded into the full 3N x 3N space with MM atoms zero-padded, providing a partial Hessian that still guides the Dimer direction updates.
Flatten loop with full Hessian: Once the search enters the flatten loop, a full ML/MM Hessian (including the MM finite-difference block) is computed exactly once and then updated by Bofill steps in the active subspace between Dimer segments.
PHVA + TR projection: Active-DOF projection and mass-weighted translation/rotation removal mirror freq.py, ensuring consistent imaginary-mode analysis and mode writing.
Output conversion: With --convert-files (default), PDB inputs can be mirrored to .pdb (when --dump), and the imaginary mode is exported as .pdb alongside _trj.xyz.

Minimal example¶

mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --out-dir ./result_tsopt

Output checklist¶

result_tsopt/final_geometry.pdb (or final_geometry.xyz)
result_tsopt/vib/final_imag_mode_*_trj.xyz
result_tsopt/vib/final_imag_mode_*.pdb

Common examples¶

Use light mode with analytical Hessian when VRAM is sufficient.

mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --opt-mode light --hessian-calc-mode Analytical --out-dir ./result_tsopt_light

Keep a full optimization trajectory for inspection.

mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --dump --out-dir ./result_tsopt_dump

Run heavy mode with YAML overrides.

mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --opt-mode heavy --config tsopt.yaml --out-dir ./result_tsopt_heavy

Use the MACE backend for TS optimization.

mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
 -q 0 -m 1 --backend mace --out-dir ./result_tsopt_mace

Workflow¶

Input handling – Load the enzyme PDB, Amber topology, and ML-region definition. Resolve charge/spin. Freeze atoms from CLI and YAML are merged.
ML/MM calculator setup – Build the ML/MM calculator (MLIP backend + hessian_ff). The -b/--backend option selects the MLIP (uma, orb, mace, or aimnet2; default uma). The --hessian-calc-mode controls whether the ML backend evaluates Hessians analytically or via finite difference. When --embedcharge is enabled, xTB point-charge embedding is applied for MM-to-ML environmental corrections.
Light mode (Dimer):
- The Hessian Dimer stage periodically refreshes the dimer direction by evaluating an exact Hessian (active subspace, TR-projected).
- When the flatten loop is enabled (--flatten), the stored active Hessian is updated via Bofill using displacements and gradient differences. Each loop estimates imaginary modes, flattens once, refreshes the dimer direction, and runs a dimer + LBFGS micro-segment.
Heavy mode (RS-I-RFO):
- Runs the RS-I-RFO optimizer with optional Hessian reference files and micro-cycle controls defined in the rsirfo YAML section.
- When --flatten is enabled and more than one imaginary mode remains after convergence, the workflow flattens extra modes and reruns RS-I-RFO until only one imaginary mode remains or the flatten iteration cap is reached.
Mode export & conversion – The converged imaginary mode is always written to vib/final_imag_mode_*_trj.xyz and mirrored to .pdb when the input was PDB and conversion is enabled. The optimization trajectory and final geometry are also converted to PDB via the input template when --dump.

CLI options¶

Option	Description	Default
`-i, --input PATH`	Starting geometry (PDB or XYZ). If XYZ, use `--ref-pdb` for topology.	Required
`--ref-pdb FILE`	Reference PDB topology when input is XYZ.	None
`--parm PATH`	Amber parm7 topology for the whole enzyme.	Required
`--model-pdb PATH`	PDB containing the ML-region atoms. Optional when `--detect-layer` is enabled.	None
`--model-indices TEXT`	Comma-separated atom indices for the ML region (ranges allowed).	None
`--model-indices-one-based / --model-indices-zero-based`	Interpret `--model-indices` as 1-based or 0-based.	`True` (1-based)
`--detect-layer / --no-detect-layer`	Detect ML/MM layers from input PDB B-factors.	`True`
`-q, --charge INT`	Total charge of the ML region.	None (required unless `-l` is given)
`-l, --ligand-charge TEXT`	Per-resname charge mapping (e.g., `GPP:-3,SAM:1`). Derives total charge when `-q` is omitted. Requires PDB input or `--ref-pdb`.	None
`-m, --multiplicity INT`	Spin multiplicity (2S+1) for the ML region.	None (defaults to 1)
`--freeze-atoms TEXT`	Comma-separated 1-based indices to freeze (merged with YAML `geom.freeze_atoms`).	None
`--radius-hessian, --hess-cutoff FLOAT`	Distance cutoff (Å) from ML region for MM atoms to include in Hessian calculation. Applied to movable MM atoms. `0.0` means ML-only partial Hessian.	`0.0`
`--movable-cutoff FLOAT`	Distance cutoff (Å) for movable MM atoms.	None
`--hessian-calc-mode CHOICE`	ML Hessian mode: `Analytical` or `FiniteDifference`.	`FiniteDifference`
`--max-cycles INT`	Maximum total optimizer cycles.	`10000`
`--opt-mode CHOICE`	TS optimizer mode: `grad` (Dimer) or `hess` (RS-I-RFO). Aliases `light`/`heavy` and `dimer`/`rsirfo` accepted.	`hess`
`--microiter/--no-microiter`	Microiteration: alternate ML 1-step (RS-I-RFO) + MM relaxation (LBFGS). Only effective in `hess` mode.	`True`
`--ml-only-hessian-dimer/--no-ml-only-hessian-dimer`	Use ML-region-only Hessian for dimer orientation in `grad` mode. Faster but less accurate.	`False`
`--flatten/--no-flatten`	Enable/disable extra imaginary-mode flattening loop. `--flatten` uses default iter (50); `--no-flatten` forces it to 0. Applies to both light and heavy modes.	None (YAML/defaults; effectively enabled with 50 iterations)
`--dump/--no-dump`	Write concatenated trajectory `optimization_all_trj.xyz`.	`False`
`--convert-files/--no-convert-files`	Toggle XYZ/TRJ to PDB companions for PDB inputs.	`True`
`-o, --out-dir TEXT`	Output directory.	`./result_tsopt/`
`--thresh TEXT`	Convergence preset (`gau_loose\|gau\|gau_tight\|gau_vtight\|baker\|never`).	None
`--partial-hessian-flatten / --full-hessian-flatten`	Use partial Hessian (ML only) for imaginary mode detection in flatten loop.	`True` (partial)
`--active-dof-mode CHOICE`	Active DOF for final frequency analysis: `all`, `ml-only`, `partial`, `unfrozen`.	`partial`
`--config FILE`	Base YAML configuration file applied before explicit CLI options.	None
`--show-config/--no-show-config`	Print resolved config layers and continue execution.	`False`
`-b, --backend CHOICE`	MLIP backend for the ML region: `uma` (default), `orb`, `mace`, `aimnet2`.	`uma`
`--embedcharge/--no-embedcharge`	Enable xTB point-charge embedding correction for MM-to-ML environmental effects.	`False`
`--embedcharge-cutoff FLOAT`	Cutoff radius (Å) for embed-charge MM atoms.	`12.0`
`--dry-run/--no-dry-run`	Validate inputs/config and print the execution plan without running TS optimization. Shown in `--help-advanced`.	`False`

Outputs¶

out_dir/ (default: ./result_tsopt/)
├── final_geometry.xyz             # Always written
├── final_geometry.pdb             # When the input was PDB
├── optimization_all_trj.xyz       # Concatenated Dimer segments (when --dump)
├── optimization_all.pdb           # PDB companion (when --dump and input was PDB)
├── vib/
│   ├── final_imag_mode_±XXXX.Xcm-1_trj.xyz  # Imaginary mode trajectory
│   └── final_imag_mode_±XXXX.Xcm-1.pdb      # Imaginary mode PDB companion
└── .dimer_mode.dat                # Dimer orientation seed (light mode)

YAML configuration¶

Settings are applied with defaults < config < explicit CLI < override. Shared sections reuse YAML Reference. Keep the full block below intact if it already matches your workflow – adjust only the values you need to change.

geom:
 coord_type: cart                  # coordinate type: cartesian vs dlc internals
 freeze_atoms: []                  # 0-based frozen atoms merged with CLI/link detection
calc:
 charge: 0                         # total 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
 ml_hessian_mode: Analytical        # Hessian mode selection
opt:
 thresh: baker                     # convergence preset (Gaussian/Baker-style)
 max_cycles: 10000                 # optimizer cycle cap
 print_every: 100                  # logging stride
 min_step_norm: 1.0e-08            # minimum norm for step acceptance
 assert_min_step: true             # stop if steps fall below threshold
 rms_force: null                   # explicit RMS force target
 rms_force_only: false             # rely only on RMS force convergence
 max_force_only: false             # rely only on max force convergence
 force_only: false                 # skip displacement checks
 converge_to_geom_rms_thresh: 0.05  # geom RMS threshold when converging to ref
 overachieve_factor: 0.0           # factor to tighten thresholds
 check_eigval_structure: false     # validate Hessian eigenstructure
 line_search: true                 # enable line search
 dump: false                       # dump trajectory/restart data
 dump_restart: false               # dump restart checkpoints
 prefix: ""                        # filename prefix
 out_dir: ./result_tsopt/          # output directory
hessian_dimer:
 thresh_loose: gau_loose           # loose convergence preset
 thresh: baker                     # main convergence preset
 update_interval_hessian: 500      # Hessian rebuild cadence
 neg_freq_thresh_cm: 5.0           # negative frequency threshold (cm^-1)
 flatten_amp_ang: 0.1              # flattening amplitude (Å)
 flatten_max_iter: 50              # flattening iteration cap (disabled when --no-flatten)
 flatten_sep_cutoff: 0.0           # minimum distance between representative atoms (Å)
 flatten_k: 10                     # representative atoms sampled per mode
 flatten_loop_bofill: false        # Bofill update for flatten displacements
 mem: 100000                       # memory limit for solver
 device: auto                      # device selection for eigensolver
 root: 0                           # targeted TS root index
 dimer:
  length: 0.0189                   # dimer separation (Bohr)
  rotation_max_cycles: 15          # max rotation iterations
  rotation_method: fourier         # rotation optimizer method
  rotation_thresh: 0.0001          # rotation convergence threshold
  rotation_tol: 1                  # rotation tolerance factor
  rotation_max_element: 0.001      # max rotation matrix element
  rotation_interpolate: true       # interpolate rotation steps
  rotation_disable: false          # disable rotations entirely
  rotation_disable_pos_curv: true  # disable when positive curvature detected
  rotation_remove_trans: true      # remove translational components
  trans_force_f_perp: true         # project forces perpendicular to translation
  bonds: null                      # bond list for constraints
  N_hessian: null                  # Hessian size override
  bias_rotation: false             # bias rotational search
  bias_translation: false          # bias translational search
  bias_gaussian_dot: 0.1           # Gaussian bias dot product
  seed: null                       # RNG seed for rotations
  write_orientations: true         # write rotation orientations
  forward_hessian: true            # propagate Hessian forward
 lbfgs:
  thresh: baker                    # LBFGS convergence preset
  max_cycles: 10000                # iteration limit
  print_every: 100                 # logging stride
  min_step_norm: 1.0e-08           # minimum accepted step norm
  assert_min_step: true            # assert when steps stagnate
  max_step: 0.3                    # maximum step length
  control_step: true               # control step length adaptively
  double_damp: true                # double damping safeguard
  keep_last: 7                     # history size for LBFGS buffers
  beta: 1.0                        # initial damping beta
  mu_reg: null                     # regularization strength
  max_mu_reg_adaptions: 10         # cap on mu adaptations
rsirfo:
 thresh: baker                     # RS-IRFO convergence preset
 trust_radius: 0.10                # initial trust radius (smaller for ONIOM)
 trust_update: true                # adaptive trust radius update
 trust_min: 1.0e-04                # minimum trust radius
 trust_max: 0.30                   # maximum trust radius
 max_energy_incr: null             # max allowed energy increase per step
 hessian_update: bofill            # Hessian update scheme override
 hessian_init: calc                # initial Hessian source
 hessian_recalc: 200               # recalculate Hessian every N steps
 hessian_recalc_adapt: null        # adaptive Hessian recalculation
 small_eigval_thresh: 1.0e-08      # threshold for small eigenvalues
 alpha0: 1.0                       # initial shift parameter
 max_micro_cycles: 50              # micro-iterations per macro cycle

tsopt¶