YAML Reference¶
Tip
Looking for the all end-to-end command? The all command consumes every section described on this page and forwards them to the appropriate subcommand. See all (in particular its “Subcommand → YAML Sections” mapping) for which sections are read by which stage.
Configuration precedence¶
Settings are resolved in the following order (later sources override earlier ones):
built-in defaults < --config (YAML) < CLI flags
Built-in defaults — hard-coded values in
pdb2reaction/defaults.py.--config— a YAML file that overrides defaults (e.g.,--config my_settings.yaml).CLI flags — explicit command-line options (e.g.,
-q -1,--thresh gau_loose). Only explicitly supplied flags override YAML; options left at their CLI default do not mask YAML values.
For example, if the YAML sets charge: 0 but the CLI passes -q -1, the charge will be -1.
This precedence applies uniformly to all, opt, tsopt, freq, irc, scan, scan2d, scan3d, path-opt, path-search, and dft. See also CLI Conventions: Configuration precedence.
Common CLI-to-YAML mapping¶
CLI flag |
YAML key |
Section |
|---|---|---|
|
|
|
|
|
|
|
|
|
(YAML only) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(YAML only) |
|
|
|
|
|
|
|
|
|
|
|
Note
Name mismatch — --pressure vs pressure_atm. On the CLI the flag is --pressure (units implicit: atm); the matching YAML key under thermo: is pressure_atm with an explicit unit suffix. Both carry atm values and get converted to Pa internally.
Note
Name mismatch — --engine vs --dft-engine. The standalone dft subcommand exposes the backend selector as --engine (gpu / cpu). In pdb2reaction all, to avoid colliding with other engines, the same flag is renamed --dft-engine — see the –engine vs –dft-engine note in CLI Conventions.
Default --thresh per subcommand¶
--thresh defaults differ per subcommand because TS optimizers use a tighter “baker” preset while minimizers use the standard “gau” preset.
Subcommand |
Default |
Backing defaults block |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Accepted values: gau_loose, gau, gau_tight, gau_vtight, baker, never. Override per run with --thresh <preset> or under opt.thresh in YAML.
Note
Subcommands without --thresh. irc, freq, and dft do not expose --thresh:
irc— convergence is governed byirc.rms_grad_thresh,irc.energy_thresh, andirc.max_cycles(seeircsection). The optimizer preset family does not apply because IRC follows a predictor–corrector integrator, not a force-based minimizer.freq— there is no optimization step, so no--thresh. Numerical accuracy is governed by--hessian-calc-modeand the underlying MLIP precision.dft— SCF convergence usesdft.conv_tol(default1e-9hartree) anddft.max_cycle, not thegau/bakerpreset family. See thedftsection.
Overview¶
Section |
Description |
Used by |
|---|---|---|
Geometry and coordinate settings |
all, opt, scan, scan2d, scan3d, tsopt, freq, irc, path-opt, path-search |
|
MLIP backend configuration |
all, opt, scan, scan2d, scan3d, tsopt, freq, irc, path-opt, path-search |
|
Shared optimizer settings |
opt, scan, scan2d, scan3d, tsopt, path-opt, path-search |
|
L-BFGS optimizer settings |
opt, scan, scan2d, scan3d, path-search |
|
RFO optimizer settings |
opt, scan, scan2d, scan3d, path-search |
|
Growing String Method settings |
path-opt, path-search |
|
Direct Max Flux settings |
path-opt, path-search |
|
StringOptimizer settings |
path-opt, path-search |
|
IRC integration settings |
irc |
|
Vibrational analysis settings |
freq |
|
Thermochemistry settings |
freq |
|
DFT calculation settings |
dft |
|
Harmonic bias settings |
scan, scan2d, scan3d |
|
Bond-change detection settings |
scan, path-search |
|
Recursive path search settings |
path-search |
|
Hessian Guided Dimer TS optimization |
tsopt |
|
RS-I-RFO TS optimization |
tsopt, all |
Path Optimization Sections¶
gs¶
Growing String Method settings.
gs:
fix_first: true # Keep first endpoint fixed
fix_last: true # Keep last endpoint fixed
max_nodes: 20 # Maximum string nodes (internal images); for GSM the total path has +2 endpoints
perp_thresh: 0.005 # Perpendicular displacement threshold
reparam_check: rms # Reparameterization check metric
reparam_every: 1 # Reparameterization stride
reparam_every_full: 1 # Full reparameterization stride
param: equi # Parameterization scheme
max_micro_cycles: 10 # Micro-iteration limit
reset_dlc: true # Rebuild delocalized coordinates each step
climb: true # Enable climbing image
climb_rms: 0.0005 # Climbing RMS threshold
climb_lanczos: true # Lanczos refinement for climbing
climb_lanczos_rms: 0.0005 # Lanczos RMS threshold
climb_fixed: false # Keep climbing image fixed
scheduler: null # Optional scheduler backend
Note
max_nodes semantics differ between GSM and DMF. For GSM (mep-mode gs), gs.max_nodes is the number of internal images — the total path length is max_nodes + 2 because the two endpoints are fixed. For DMF (mep-mode dmf), the CLI flag --max-nodes instead counts the number of movable images with no implicit endpoint expansion. See path-opt for per-method details.
dmf¶
Direct Max Flux settings for MEP optimization.
Note
--max-nodes for DMF means “number of movable images” — unlike GSM, DMF does not add +2 for fixed endpoints. See the gs.max_nodes note above for the contrast.
dmf:
max_cycles: 300 # Maximum DMF/IPOPT iterations (overridden by --max-cycles)
correlated: true # Correlated DMF propagation
sequential: true # Sequential DMF execution
fbenm_only_endpoints: false # Run FB-ENM beyond endpoints
fbenm_options:
delta_scale: 0.2 # FB-ENM displacement scaling
bond_scale: 1.25 # Bond cutoff scaling
fix_planes: true # Enforce planar constraints
cfbenm_options:
bond_scale: 1.25 # CFB-ENM bond cutoff scaling
corr0_scale: 1.1 # Correlation scale for corr0
corr1_scale: 1.5 # Correlation scale for corr1
corr2_scale: 1.6 # Correlation scale for corr2
eps: 0.05 # Correlation epsilon
pivotal: true # Pivotal residue handling
single: true # Single-atom pivots
remove_fourmembered: true # Prune four-membered rings
dmf_options:
remove_rotation_and_translation: false # Keep rigid-body motions
mass_weighted: false # Toggle mass weighting
parallel: false # Enable parallel DMF
eps_vel: 0.01 # Velocity tolerance
eps_rot: 0.01 # Rotational tolerance
beta: 10.0 # Beta parameter for DMF
update_teval: false # Update transition evaluation
k_fix: 300.0 # Harmonic constant for restraints
search¶
Recursive path search settings (path-search only).
search:
max_depth: 10 # Recursion depth limit
stitch_rmsd_thresh: 0.0001 # RMSD threshold for stitching segments
bridge_rmsd_thresh: 0.0001 # RMSD threshold for bridging nodes
max_nodes_segment: 10 # Max nodes per segment
max_nodes_bridge: 5 # Max nodes per bridge
kink_max_nodes: 3 # Max nodes for kink optimizations
max_seq_kink: 2 # Max sequential kinks
refine_mode: null # Refinement strategy: peak, minima, or null (auto)
stopt¶
StringOptimizer settings for chain-of-states path optimization (path-opt, path-search).
stopt:
type: string # Optimizer type label
thresh: gau_loose # StringOptimizer convergence preset
stop_in_when_full: 300 # Early stop threshold when the string is full
align: false # Alignment toggle (forced to False in path-opt/path-search; external Kabsch alignment is used instead)
scale_step: global # Step scaling mode
max_cycles: 300 # Maximum StringOptimizer iterations
dump: false # Dump trajectory/restart data
dump_restart: false # Dump restart checkpoints
reparam_thresh: 0.0 # Reparameterization threshold
coord_diff_thresh: 0.0 # Coordinate-difference threshold
out_dir: ./result_path_opt/ # Output directory
print_every: 10 # Logging stride
TS Optimization Sections¶
TS optimization uses two mutually exclusive algorithm sections, selected by --opt-mode:
--opt-mode dimer(orgrad) → useshessian_dimersection--opt-mode rsirfo(orhess, default) → usesrsirfosection
Shared optimizer settings (thresh, max_cycles, dump) are read from the opt section above.
hessian_dimer¶
Hessian Guided Dimer TS optimization settings (tsopt –opt-mode grad).
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 # Imaginary-frequency detection threshold (cm⁻¹)
flatten_amp_ang: 0.1 # Flattening amplitude (Å)
flatten_max_iter: 50 # Flattening iteration cap (see note below)
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:
# Same keys as lbfgs section
thresh: baker
max_cycles: 10000
Note
flatten_max_iter CLI precedence exception. The YAML value hessian_dimer.flatten_max_iter: 50 (and the analogous rsirfo.flatten_max_iter override) is overridden to 0 by the CLI unless --flatten is explicitly passed, regardless of the normal defaults < YAML < CLI ordering. See --flatten precedence caveat for the full behavior table.
rsirfo¶
RS-I-RFO TS optimization settings (tsopt –opt-mode hess).
rsirfo:
thresh: baker # RS-IRFO convergence preset
max_cycles: 10000 # Iteration cap
print_every: 100 # Logging stride
min_step_norm: 1.0e-08 # Minimum accepted step norm
assert_min_step: true # Assert when steps stagnate
roots: [0] # Target root indices
hessian_ref: null # Reference Hessian
rx_modes: null # Reaction-mode definitions
prim_coord: null # Primary coordinates to monitor
rx_coords: null # Reaction coordinates to monitor
hessian_update: bofill # Hessian update scheme
hessian_recalc: 500 # Rebuild exact Hessian every N macro steps (inherited from rfo)
hessian_recalc_reset: true # Reset recalc counter after exact Hessian
max_micro_cycles: 50 # Micro-iterations per macro cycle
augment_bonds: false # Augment reaction path based on bond analysis
min_line_search: true # Enforce minimum line-search step
max_line_search: true # Enforce maximum line-search step
assert_neg_eigval: false # Require negative eigenvalue at convergence
track_mode_by_overlap: false # Track the selected TS mode by overlap with the previous Hessian
# Also inherits rfo-like settings: trust_radius, trust_update, etc.
Note
--flatten precedence. The flatten loop for both Hessian-Dimer and RS-I-RFO paths is configured under the hessian_dimer: YAML section (key flatten_max_iter, default 50); rsirfo: does not define its own flatten counter. The CLI overrides flatten_max_iter to 0 unless --flatten is explicitly passed on the command line. See --flatten precedence caveat.
IRC Section¶
irc (section)¶
IRC integration settings.
irc:
step_length: 0.1 # Integration step length
max_cycles: 125 # Maximum steps along IRC
downhill: false # Follow downhill direction only
forward: true # Propagate in forward direction
backward: true # Propagate in backward direction
root: 0 # Normal-mode root index
hessian_init: calc # Hessian initialization source
hessian_update: bofill # Hessian update scheme
hessian_recalc: null # Hessian rebuild cadence
displ: energy # Displacement construction method
displ_energy: 0.001 # Energy-based displacement scaling
displ_length: 0.1 # Length-based displacement fallback
rms_grad_thresh: 0.001 # RMS gradient convergence threshold
hard_rms_grad_thresh: null # Hard RMS gradient stop
energy_thresh: 0.000001 # Energy change threshold
imag_below: 0.0 # Imaginary frequency cutoff
force_inflection: true # Enforce inflection detection
check_bonds: false # Check bonds during propagation
out_dir: ./result_irc/ # Output directory
prefix: "" # Filename prefix
max_pred_steps: 500 # Predictor-corrector max steps
loose_cycles: 3 # Loose cycles before tightening
corr_func: mbs # EulerPC corrector function: "mbs" (modified Bulirsch–Stoer, default) or "rk4"
The corr_func key selects the corrector step used by the predictor–corrector IRC integrator (EulerPC). "mbs" is the pysisyphus-native modified Bulirsch–Stoer implementation (default) and "rk4" requests a classical fourth-order Runge–Kutta corrector. Change this only if the default integrator is numerically unstable on your system; most users should leave it at mbs.
Vibrational Analysis Sections¶
freq (section)¶
Vibrational frequency analysis settings.
freq:
amplitude_ang: 0.8 # Displacement amplitude for modes (Å)
n_frames: 20 # Number of frames per mode animation
max_write: 10 # Maximum number of modes to write
sort: value # Sort order: "value" or "abs"
out_dir: ./result_freq/ # Output directory
thermo¶
Thermochemistry settings.
thermo:
temperature: 298.15 # Thermochemistry temperature (K)
pressure_atm: 1.0 # Thermochemistry pressure (atm)
dump: false # Write thermoanalysis.yaml
DFT Section¶
dft (section)¶
DFT calculation settings.
dft:
func: wb97m-v # Exchange-correlation functional
basis: def2-tzvpd # Basis set name
func_basis: null # Combined "FUNC/BASIS" string (overrides func/basis)
conv_tol: 1.0e-09 # SCF convergence tolerance (hartree)
max_cycle: 100 # Maximum SCF iterations
grid_level: 3 # PySCF grid level
verbose: 0 # PySCF verbosity (0-9)
out_dir: ./result_dft/ # Output directory root
Scan Sections¶
Scan coordinates are specified via --scan-lists/-s (inline or YAML file), not in the main YAML config.
See Quickstart: scan workflow for scan coordinate syntax (PDB selectors, multi-stage).
bias¶
Harmonic bias settings for scans and restraint-based optimizations.
bias:
k: 300.0 # Harmonic bias strength (eV·Å⁻²)
Shared spring constant across subcommands. The same physical harmonic penalty (k, in eV·Å⁻²) appears in three places with the same default of 300.0:
YAML key |
Used by |
CLI flag |
|---|---|---|
|
|
|
|
|
— (YAML only) |
Override any of these to tune how stiff the harmonic restraint is. A smaller value (e.g. 20.0) is appropriate when the geometry should relax against a soft guidance term; the default 300.0 enforces near-rigid pinning.
bond¶
MLIP-based bond-change detection.
bond:
device: auto # MLIP device for bond analysis
bond_factor: 1.2 # Covalent-radius scaling for cutoff
margin_fraction: 0.05 # Fractional tolerance for comparisons
delta_fraction: 0.05 # Minimum relative change to flag bond formation/breaking
Example: Complete Configuration File¶
Below is a complete example combining multiple sections:
# pdb2reaction configuration example
geom:
coord_type: cart
freeze_atoms: []
calc:
backend: uma
charge: 0
spin: 1
model: uma-s-1p1 # uma-s-1p1 | uma-m-1p1
device: auto
hessian_calc_mode: Analytical # Recommended when VRAM permits
solvent: none # Set to e.g. "water" for implicit solvent
gs:
max_nodes: 12
climb: true
climb_lanczos: true
stopt:
thresh: gau_loose
max_cycles: 300
dump: false
out_dir: ./result_all/
opt:
thresh: gau
lbfgs: # also accepted at top-level as `lbfgs:`
max_cycles: 10000
rfo: # also accepted at top-level as `rfo:`
max_cycles: 10000
bond:
bond_factor: 1.2
delta_fraction: 0.05
search:
max_depth: 10
max_nodes_segment: 10
freq:
max_write: 10
amplitude_ang: 0.8
thermo:
temperature: 298.15
pressure_atm: 1.0
dft:
func: wb97m-v
basis: def2-tzvpd
grid_level: 3