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/core/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.
These are the three layers exposed by the public CLI. Internal compatibility parameters used by embedded Python callers do not add another public command-line configuration layer.
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) |
|
|
|
|
|
|
|
Command-specific: |
|
|
|
|
|
|
|
|
|
|
|
Command-specific optimizer/path owner ( |
|
(CLI 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, dft |
|
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, path-opt |
|
RFO optimizer settings |
opt, scan, scan2d, scan3d, path-search, path-opt |
|
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-P-RFO / 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
gs.max_nodes / --max-nodes is the number of movable internal images for both GSM and DMF. Both engines retain two endpoints, so the complete path contains max_nodes + 2 images. See path-opt.
gs.param accepts equi or energy. Energy weighting is applied only after the GSM string is fully grown and shifts node density toward high-energy regions.
dmf¶
Direct Max Flux settings for MEP optimization.
Note
For DMF, --max-nodes is forwarded as DirectMaxFlux(nmove=...); the installed DMF API defines nmove as movable interior evaluation points and constructs nmove + 2 images including endpoints.
dmf:
backend: gpu # gpu (dmf.torch / CUDA, default) | cpu (dmf / NumPy)
max_cycles: 300 # Maximum DMF/IPOPT iterations (overridden by --max-cycles-dmf)
tol: tight # IPOPT dual_inf_tol: tight (0.04) | middle (0.10) | loose (0.20) or a positive float (overridden by --thresh-dmf)
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
ipopt_options: {} # Raw IPOPT options, e.g. {dual_inf_tol: 0.04}
k_fix: 300.0 # Harmonic constant for restraints (top-level dmf key, NOT under dmf_options)
dmf.tol is the tolerance the DMF solve applies last, so it takes precedence over an ipopt_options.dual_inf_tol set in the same file. Set only ipopt_options.dual_inf_tol (and leave dmf.tol unset) to pin the raw IPOPT option instead. Gaussian presets such as gau_tight are rejected here; they belong to --thresh and --thresh-gsm.
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: 20 # 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 rsprfo(orhess, default),rsirfo, ortrim→ usesrsirfosection
When the same setting is written in opt and the active algorithm section,
different explicit values are rejected. One explicit value is used by both;
otherwise the algorithm-specific default wins.
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
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 the selected rigid-null 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: false # Write rotation orientations (explicit true is allowed)
forward_hessian: true # Propagate Hessian forward
lbfgs: # sibling of `dimer` under `hessian_dimer`, not nested inside it
# Same keys as the top-level lbfgs section
thresh: baker
line_search: false # Required: Dimer effective force is not energy-conjugate
Inner L-BFGS settings live under hessian_dimer.lbfgs, not the top-level
lbfgs section. Shared print_every and energy_plateau* values follow the
conflict rule above. line_search is fixed to false; setting it to true is
rejected because Dimer’s projected/inverted effective force is not the gradient
of the reported physical energy. max_cycles is not configurable because each
segment receives the cycles remaining from opt.max_cycles.
Note
flatten_max_iter default exception. The CLI seeds
hessian_dimer.flatten_max_iter = 0 before applying YAML, so an omitted toggle
keeps an explicit YAML value while leaving flattening off when YAML is silent.
--flatten enables the configured value (or the built-in 50), and
--no-flatten forces zero. rsirfo has no separate flatten counter. See
--flatten precedence caveat for the full behavior table.
rsirfo¶
RS-I-RFO / RS-P-RFO TS optimization settings (used by tsopt --opt-mode rsirfo, rsprfo (the hess default), and trim).
rsirfo:
thresh: baker # RS-IRFO convergence preset
max_cycles: 100000 # Shared with opt.max_cycles; conflicting explicit values are rejected
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] # Exactly one target root index (first-order TS only)
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: false # RS-P-RFO only: interpolate in the minimization subspace
max_line_search: false # RS-P-RFO only: interpolate in the maximization subspace
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
reject_mode_loss: false # Optional trial rejection after established mode loss
mode_loss_trust_floor: 1.0e-05 # Positive emergency trust-radius floor for those retries
max_mode_loss_rejections: 5 # Rejections allowed at that floor before stopping
verify_saddle: true # Require exact-Hessian projected first-order-saddle validation
saddle_recovery_step: 0.01 # Positive uphill recovery displacement cap in optimizer coordinates
saddle_recovery_check_interval: 50 # Exact PHVA cadence during n_imag=0 recovery
saddle_recovery_max_cycles: 0 # Automatic n_imag=0 recovery disabled
out_dir: ./result_tsopt/ # Output directory
# Also inherits rfo-like settings: trust_radius, trust_update, etc.
min_line_search and max_line_search are consumed by --opt-mode rsprfo.
They default to false, but explicit YAML values are preserved. RS-I-RFO and
TRIM do not implement this subspace line-search step. Dimer uses the separate
hessian_dimer.lbfgs.line_search setting shown above.
Note
--flatten precedence. The flatten loop for Hessian-Dimer and RFO TS paths
is configured under hessian_dimer.flatten_max_iter; rsirfo has no separate
counter. With neither toggle, an explicit YAML value is retained. --flatten
uses that value or the built-in 50, while --no-flatten forces zero. See
--flatten precedence caveat.
IRC Section¶
irc (section)¶
IRC integration settings.
irc:
step_length: 0.1 # Integration step length
never_stop: false # Ignore physical endpoint criteria and trace to max_cycles
max_cycles: 125 # Maximum steps along IRC
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
energy_increase_thresh: 0.0 # Stop on any one-step rise in ordinary mode
dump_every: null # Disabled; positive cadence writes a coordinate/energy/gradient checkpoint without a Hessian
dump_fn: irc_data.h5 # Checkpoint filename used only when dump_every is set
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 (only "mbs" is currently registered)
The corr_func key selects the corrector step used by the predictor–corrector IRC integrator (EulerPC). Only "mbs" (the pysisyphus-native modified Bulirsch–Stoer implementation, default) is currently registered; other values raise a construction error.
Vibrational Analysis Sections¶
freq (section)¶
Vibrational frequency analysis settings.
freq:
zero_cutoff_cm: 5.0 # Remove modes with |frequency| <= this value (cm^-1)
amplitude_ang: 0.8 # Displacement amplitude for modes (Å)
n_frames: 20 # Number of frames per mode trajectory
max_write: 10 # Maximum number of modes to write
sort: value # Sort order: "value" or "abs"
out_dir: ./result_freq/ # Output directory
freq.zero_cutoff_cm is the single cutoff used by standalone freq, opt
flattening, Dimer, and Hessian-family TS optimization. The legacy
hessian_dimer.neg_freq_thresh_cm and
rsirfo.saddle_imaginary_threshold_cm spellings remain accepted as aliases;
conflicting values are rejected.
thermo¶
Thermochemistry settings.
thermo:
temperature: 298.15 # Thermochemistry temperature (K)
pressure_atm: 1.0 # Thermochemistry pressure (atm)
symmetry_number: null # Auto-detect; a positive integer is an advanced override
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
engine: gpu # SCF backend: "gpu" (GPU4PySCF) or "cpu" (PySCF)
lowmem: true # Use gpu4pyscf rks_lowmem.RKS for closed-shell GPU runs
verbose: 0 # PySCF verbosity (0-9); CLI -v 2/3 raises runtime PySCF verbosity to >=4
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 # Harmonic bias strength (eV·Å⁻²)
Shared spring constant across subcommands. The same physical harmonic penalty (k, in eV·Å⁻²) appears in the following places with the same default of 300:
YAML key |
Used by |
CLI flag |
|---|---|---|
|
|
|
|
|
— (YAML only) |
opt also accepts --bias-k (applied to --dist-freeze pairs) but reads it only from the CLI flag, which defaults to the same 300.0 constant; it does not honor the bias: YAML section.
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-1p2 # uma-s-1p2 | uma-m-1p1
device: auto
hessian_calc_mode: FiniteDifference # Portable default; benchmark Analytical before opting in
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:
max_cycles: 100000
rfo:
max_cycles: 100000
bond:
bond_factor: 1.2
delta_fraction: 0.05
search:
max_depth: 10
max_nodes_segment: 20
freq:
max_write: 10
amplitude_ang: 0.8
thermo:
temperature: 298.15
pressure_atm: 1.0
symmetry_number: null
dft:
func: wb97m-v
basis: def2-tzvpd
grid_level: 3