`irc`¶

Runs EulerPC (Euler Predictor-Corrector)-based intrinsic reaction coordinate (IRC) integration from an optimized transition state (validated by tsopt) toward reactants and products, confirming endpoint connectivity (R ↔ TS ↔ P). By default both forward and backward branches are computed; use --no-backward (or --no-forward) to follow only one direction. Hessians default to finite differences; analytical autograd is an explicit alternative whose speed and memory cost depend on the backend, model, system size, precision, and GPU, so validate it on the target setup instead of treating it as a blanket recommendation. For XYZ/GJF inputs, --ref-pdb supplies a reference PDB/mmCIF topology while keeping the XYZ coordinates, enabling format-aware companion output. A typical workflow is tsopt → irc.

Examples¶

Command synopsis:

pdb2reaction irc -i INPUT.{pdb|xyz|trj|...} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] \
 [-b/--backend uma|orb|mace|aimnet2] \
 [--workers N] [--workers-per-node N] [-m 2S+1] \
 [--max-cycles N] [--step-size Δs] [--never-stop/--no-never-stop] [--root k] \
 [--forward/--no-forward] [--backward/--no-backward] \
 [--freeze-links/--no-freeze-links] \
 [--out-dir DIR] [--config FILE] \
 [--convert-files/--no-convert-files] [--ref-pdb FILE] \
 [--hessian-calc-mode Analytical|FiniteDifference] \
 [--show-config] [--dry-run]

Basic run with both branches:

pdb2reaction irc -i ts.pdb -q 0 -m 1 --max-cycles 50 --out-dir ./result_irc

Forward-only branch, finite-difference Hessian, larger step size:

# Forward-only branch, finite-difference Hessian, larger step size
pdb2reaction irc -i ts.pdb -q 0 -m 1 --no-backward \
 --step-size 0.2 --hessian-calc-mode FiniteDifference --out-dir ./irc_fd/

Request an analytical Hessian explicitly:

# Keep workers at 1 when requesting an analytical UMA Hessian
pdb2reaction irc -i ts.pdb -q 0 -m 1 \
 --hessian-calc-mode Analytical --out-dir ./result_irc_analytical

If a branch stops after only one or two steps, first reduce the maximum EulerPC step. 0.05 Bohr is a useful retry value:

pdb2reaction irc -i ts.pdb -q 0 -m 1 --step-size 0.05 \
 --out-dir ./result_irc_small_step

To trace unconditionally through all physical endpoint criteria, add --never-stop. This opt-in mode ignores RMS-gradient, hard-gradient, energy-increase, and energy-change stops. It continues until --max-cycles unless a numerical/integration failure or external interruption prevents further propagation:

pdb2reaction irc -i ts.pdb -q 0 -m 1 --step-size 0.05 --never-stop \
 --max-cycles 250 --out-dir ./result_irc_continue

Workflow¶

Input preparation – The common bridge accepts PDB, mmCIF, and formats supported by geom_loader. When a PDB/mmCIF reference topology is available, EulerPC trajectories are converted to PDB; bridge inputs also receive CIF with original IDs. --freeze-links augments geom.freeze_atoms by freezing parents of cap hydrogens for topology inputs.
EulerPC integration – The EulerPC predictor-corrector integrator traces the IRC path from the transition state. Forward and/or backward branches are run according to --forward/--backward flags. The default constrained rigid-mode treatment removes only full-system translations/rotations compatible with the frozen anchors before selecting the initial mode. Each step then uses an Euler predictor along the mass-weighted steepest-descent direction (with the gradient approximated via a second-order Taylor expansion using the current Hessian), followed by a modified-Bulirsch–Stoer corrector on a distance-weighted-interpolation surface.
Trajectory output – Finished, forward, and backward IRC trajectories are written as XYZ files. With a reference topology and --convert-files, PDB companions are generated; mmCIF/oversized-PDB bridge inputs also receive CIF companions.

Outputs¶

out_dir/ (default:./result_irc/)
├─ <prefix>finished_irc_trj.xyz   # Complete IRC trajectory
├─ <prefix>finished_first.xyz     # Raw first endpoint used for endpoint comparison
├─ <prefix>finished_last.xyz      # Raw last endpoint used for endpoint comparison
├─ <prefix>finished_irc.pdb       # PDB companion (when ref PDB available + conversion enabled)
├─ <prefix>finished_irc.cif       # Bridge-input companion with original IDs
├─ <prefix>forward_irc_trj.xyz    # Present when the forward branch runs
├─ <prefix>forward_irc.pdb        # Forward-branch PDB companion (same gating)
├─ <prefix>forward_irc.cif        # Bridge-input companion
├─ <prefix>backward_irc_trj.xyz   # Present when the backward branch runs
├─ <prefix>backward_irc.pdb       # Backward-branch PDB companion (same gating)
└─ <prefix>backward_irc.cif       # Bridge-input companion

finished_first.xyz and finished_last.xyz are directional endpoint artifacts; their order alone does not establish chemical reactant/product identity.

When irc.prefix is non-empty, EulerPC inserts one underscore before the filename; for example, prefix: trial produces trial_finished_irc_trj.xyz. result.json.files records the normalized names.

Low-level periodic HDF5 checkpointing is available only through YAML: irc.dump_every defaults to null and a positive value writes <prefix>irc_data.h5. The file is overwritten with the current direction’s coordinates, energies, and gradients; it is not a final combined IRC artifact, contains no Hessian, and is omitted from result.json.files.

Console summaries of resolved geom, calc, and irc configurations plus wall-clock timing.

CLI options¶

The full flag list is in the generated command reference; the table below covers the options that need explanation.

Option	Description	Default
`-i, --input PATH`	Transition-state structure accepted by `geom_loader`.	Required
`-q, --charge INT`	Total charge. Explicit `-q` has highest priority; otherwise see Charge specification.	Required unless YAML/template/derivation applies
`-l, --ligand-charge TEXT`	Either a scalar integer (e.g., `-1`) for the total ligand charge, or a per-residue mapping (e.g., `GPP:-3,SAM:1`) that derives the total from PDB/mmCIF residue metadata. Used when `-q` is omitted (PDB/mmCIF inputs or XYZ/GJF with `--ref-pdb`).	None
`--workers INT`	UMA predictor parallelism. `workers > 1` cannot be combined with an explicit analytical Hessian request; use `workers = 1` or finite differences. See workers > 1 is incompatible with analytical Hessians (UMA backend).	`1`
`--workers-per-node INT`	Workers per node, forwarded to the parallel predictor.	`1`
`-m, --multiplicity INT`	Spin multiplicity (2S+1). Explicit `-m` overrides YAML `calc.spin`; otherwise YAML, `.gjf`, or `1` is used.	YAML/`.gjf`/`1`
`--max-cycles INT`	Maximum IRC steps. An explicit value overrides YAML `irc.max_cycles`.	`125`
`--step-size FLOAT`	Step length in unweighted Cartesian coordinates (Bohr). An explicit value overrides YAML `irc.step_length`.	`0.10`
`--never-stop/--no-never-stop`	Ignore RMS-gradient, hard-gradient, energy-rise, and one-step energy-change stops (`abs(E_n-E_{n-1}) <= energy_thresh`, default `1e-6` Hartree) and trace until `max_cycles`. Numerical/integration failures and external interruption still stop propagation.	`False`
`--root INT`	0-based index into the projected Hessian’s eigenvalues sorted in ascending order (most-negative first), used to pick the mode for the initial IRC displacement. For a validated TS with exactly one imaginary mode, leave `--root 0` (the sole negative eigenvalue). Use `--root 1`, `--root 2`, … only if you know the active imaginary mode is ranked above more-negative spurious modes. An explicit value overrides YAML `irc.root`.	`0`
`--forward/--no-forward`	Run forward branch (`irc.forward`); an explicit toggle overrides YAML.	`True`
`--backward/--no-backward`	Run backward branch (`irc.backward`); an explicit toggle overrides YAML.	`True`
`--irc-pos-def/--no-irc-pos-def`	Opt in to requiring a positive-definite projected Hessian before accepting IRC convergence. Enable this guard when a shoulder could otherwise look converged.	`False`
`--freeze-links/--no-freeze-links`	For PDB/mmCIF topology inputs, freeze cap-H parents (merged with `geom.freeze_atoms`). See extract for cap-hydrogen details.	`True`
`--freeze-atoms TEXT`	Comma-separated 1-based atom indices to freeze explicitly (e.g., `'1,3,5'`). Complements `--freeze-links`; applies to any input format.	None
`-o, --out-dir TEXT`	Output directory (`irc.out_dir`); an explicit value overrides YAML.	`./result_irc/`
`--convert-files/--no-convert-files`	Toggle XYZ/TRJ → PDB/CIF companions when a reference PDB/mmCIF topology is available.	`True`
`--ref-pdb FILE`	Reference PDB or mmCIF topology to use when the input is XYZ/GJF (keeps XYZ coordinates).	None
`--hessian-calc-mode CHOICE`	MLIP Hessian mode (`calc.hessian_calc_mode`); an explicit value overrides YAML.	`FiniteDifference`
`--config FILE`	Base YAML configuration applied before explicit CLI options.	None
`--show-config/--no-show-config`	Print resolved YAML layers/config and continue.	`False`
`--out-json/--no-out-json`	Write a machine-readable `result.json` to `out_dir`. See JSON Output Schema for the schema.	`False`
`-b, --backend {uma,orb,mace,aimnet2}`	MLIP backend.	`uma`
`--dry-run/--no-dry-run`	Validate and print execution plan without running IRC.	`False`

YAML configuration¶

See CLI Conventions: Configuration precedence for the full resolution order.

The geom, calc, and irc sections are unchanged from the canonical definitions in YAML Reference: see geom, calc, and irc. --freeze-links augments geom.freeze_atoms for PDB/mmCIF topology inputs, and --hessian-calc-mode plus CLI charge/spin values supplement the merged calc block.

irc-specific hard overrides (applied after YAML/CLI merging, regardless of YAML values):

geom:
 coord_type: cart # forced to cart for irc (YAML value ignored)
calc:
 return_partial_hessian: true # forced true for irc (partial Hessian with active-DOF processing)

Exit codes¶

See Exit codes in CLI Conventions.

Notes¶

The MLIP backend (UMA by default) is reused throughout the IRC; aggressive step_length values can destabilize EulerPC. A branch that stops almost immediately should be retried with a smaller --step-size (for example 0.05) before changing other controls.
--never-stop is intentionally off by default. It deliberately traces to the cycle limit rather than declaring convergence at a physical endpoint. Inspect the trajectory and endpoint connectivity; increase --max-cycles only when the extra path is scientifically useful.
When --freeze-links is active, cap-hydrogen parent atoms are automatically frozen (see Cap hydrogen and frozen atoms).
result.json["rigid_projection"] records the treatment, effective rank, and initial Hessian source and shape. See Frozen Atoms.

irc¶