YAML Reference¶
This page lists, section by section, the keys and default values you can set in a YAML configuration file (--config). The list of sections, the order of precedence, and the mapping from CLI flags to YAML keys come first.
Section |
Description |
Used by |
|---|---|---|
Geometry and coordinate settings |
opt, scan, scan2d, scan3d, tsopt, freq, irc, path-opt, path-search, dft, sp |
|
Machine-learning interatomic potential (MLIP) backend configuration |
opt, scan, scan2d, scan3d, tsopt, freq, irc, path-opt, path-search, sp, dft ( |
|
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 (GSM) string: nodes, climbing image, reparameterization |
path-opt, path-search |
|
Direct Max Flux settings |
path-opt, path-search |
|
StringOptimizer, which moves the GSM string; its |
path-opt, path-search |
|
IRC integration settings |
irc |
|
Vibrational analysis settings |
freq ( |
|
Thermochemistry settings |
freq |
|
DFT calculation settings of the |
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 |
|
|
Single-point options ( |
sp |
Configuration precedence¶
Settings are applied in the following order (later sources override earlier ones):
built-in defaults < --config (YAML) < CLI flags
Built-in defaults — the values shown by
pdb2reaction <subcmd> --help-advancedand as[default: …]in the Command Reference.--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). Options left at their CLI default do not mask YAML values.
For example, if the YAML sets calc.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, dft, and sp.
To check the values a run uses, run it with -v 3, which prints each section as its name, a dashed underline, and the values in effect:
opt
---
thresh: gau
max_cycles: 100000
…
--show-config (not on scan, scan2d, or scan3d) prints the loaded YAML file and its top-level keys.
A misspelled section name prints [config] WARNING: YAML section(s) … are not recognized and were ignored. A misspelled key inside a section is handled by section:
calcprints[backend] WARNING: … ignored calc setting(s) …and goes on.freq,thermo,bias,bond,search,sp, the keys directly underhessian_dimer, andgeomin the scan and path commands ignore it without a message. With-v 3it appears as an extra line in that section’s block.Every other section stops with an error that names the key.
Common CLI-to-YAML mapping¶
CLI flag |
YAML key |
Section |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(YAML only) |
|
|
|
|
|
|
|
Command-specific: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(CLI only) |
— |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Command-specific: |
Note
Name mismatch — --pressure vs pressure_atm. Both take atm (converted to Pa internally); only the YAML key names the unit.
Default --thresh per subcommand¶
Subcommand |
Default |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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. 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_tolanddft.max_cycle, not thegau/bakerpreset family.
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 force threshold for adding new string nodes
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 # RS iteration limit per step
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 (search.max_nodes_segment in path-search) / --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. DMF builds its initial path with FB-ENM (flat-bottom elastic network model) or, with correlated: true, CFB-ENM (correlated FB-ENM).
dmf:
backend: gpu # gpu (dmf.torch / CUDA, default) | cpu (dmf / NumPy)
max_cycles: 3000 # Maximum DMF/IPOPT iterations (overridden by --dmf-max-iterations)
tol: tight # IPOPT dual_inf_tol: tight (0.04) | middle (0.10) | loose (0.20) or a positive float (overridden by --dmf-tol)
correlated: true # Build the initial path with CFB-ENM instead of FB-ENM
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 # Recursive subdivision levels allowed (0 = no subdivision)
stitch_rmsd_thresh: 0.0001 # RMSD threshold (Bohr) for stitching segments
bridge_rmsd_thresh: 0.0001 # RMSD threshold (Bohr) 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. stopt.lbfgs and stopt.rfo set the single-structure optimizers, in the same way as opt.lbfgs and opt.rfo.
stopt:
type: string # Optimizer type label
thresh: gau_loose # StringOptimizer convergence preset
stop_in_when_full: 300 # Always set to max_cycles in path-opt/path-search
align: false # Always false in path-opt/path-search; the images are superposed separately by a Kabsch fit
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
A key set in only one of opt and the active section applies to both;
different values in the two stop the run. With thresh in neither, TS optimization uses baker,
not the gau shown under opt.
hessian_dimer¶
Hessian Guided Dimer TS optimization settings.
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 # n_imag cutoff (cm⁻¹); see the freq section
flatten_amp_ang: 0.1 # Flattening amplitude (Å)
flatten_max_iter: 0 # Flatten rounds (0 = off); --flatten uses 50 when this is 0
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 set here: each L-BFGS run
between Hessian updates takes at most the cycles left in opt.max_cycles.
Note
flatten_max_iter. --flatten removes extra imaginary modes in up to
flatten_max_iter rounds (50 when the value is 0), and --no-flatten turns it
off. With neither flag, a positive value set here turns it on. See
When --flatten is on.
rsirfo¶
RS-I-RFO / RS-P-RFO TS optimization settings.
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 # RS iteration limit per step
augment_bonds: false # Augment reaction path based on bond analysis
min_line_search: false # Always false: RS-P-RFO does not use line searches
max_line_search: false # Always false: RS-P-RFO does not use line searches
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 # Once a TS mode is found, reject steps that lose it and retry with a smaller trust radius
mode_loss_trust_floor: 1.0e-05 # Smallest trust radius for those retries
max_mode_loss_rejections: 5 # Rejections allowed at that floor before stopping
verify_saddle: true # At convergence, count n_imag with an exact Hessian; n_imag = 0 is not accepted
saddle_imaginary_threshold_cm: 5.0 # n_imag cutoff (cm⁻¹); see the freq section
saddle_recovery_step: 0.01 # Uphill step used to leave a minimum (n_imag = 0)
saddle_recovery_check_interval: 50 # Steps between exact-Hessian checks during that recovery
saddle_recovery_max_cycles: 0 # Maximum recovery steps; 0 turns recovery off
out_dir: ./result_tsopt/ # Output directory
# Also inherits rfo-like settings: trust_radius, trust_update, etc.
In RS-P-RFO, an explicit true for min_line_search or max_line_search
prints a warning and falls back to false. RS-I-RFO and TRIM ignore both keys,
and Dimer uses hessian_dimer.lbfgs.line_search.
Note
--flatten precedence. The flatten loop of the RS-P-RFO, RS-I-RFO, and TRIM
paths also reads hessian_dimer.flatten_max_iter, with the same rules as in the
note under hessian_dimer. See When --flatten is on.
IRC Section¶
irc (section)¶
IRC integration settings.
irc:
step_length: 0.1 # Integration step length (Bohr, unweighted Cartesian; --step-size)
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 # IRC starts only if the root mode has ν ≤ this value (cm⁻¹)
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
corr_func selects the corrector step of the predictor–corrector IRC integrator (EulerPC). Only "mbs" (modified Bulirsch–Stoer) is registered; other values raise a construction error.
Vibrational Analysis Sections¶
freq (section)¶
Vibrational frequency analysis settings.
freq:
zero_cutoff_cm: 5.0 # Imaginary modes satisfy ν < -zero_cutoff_cm
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
The default imaginary-mode criterion is ν < −5.00 cm⁻¹. freq, opt
(flattening), and tsopt count n_imag with this freq.zero_cutoff_cm;
irc does not read it. tsopt also takes this cutoff from
hessian_dimer.neg_freq_thresh_cm or rsirfo.saddle_imaginary_threshold_cm;
if two of the three keys are set explicitly to different values, the run stops
with an error. n_negative_modes also counts the negative
frequencies between −zero_cutoff_cm and 0, which n_imag does not count. n_negative_modes does not decide
whether an optimization has converged. Whatever the cutoff, the output keeps
every signed frequency, and thermochemistry uses every positive mode.
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-svp # 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)
solvent: none # Native PySCF solvent name
solvent_model: smd # pcm | smd
pyscf: {} # PySCF object-name attribute forwarding
lowmem: true # Low-memory direct JK; false enables density fitting
scf_stepwise_grid: true # Coarse-grid first SCF stage (--scf-stepwise-grid)
nprocs: auto # PySCF/OpenMP threads from scheduler/affinity
memory: auto # Host RAM limit, e.g. 64GB (not GPU VRAM)
verbose: 0 # PySCF verbosity (0-9); applies at -v 0/1; at the default -v 2 and at -v 3 it is raised to at least 4
out_dir: ./result_dft/ # Output directory root
Scan Sections¶
Scan coordinates go in -s/--scan-lists, not in the --config YAML.
See Scan-list spec for the syntax.
bias¶
Harmonic bias settings for scan, scan2d, and scan3d.
bias:
k: 300 # Harmonic bias strength (eV·Å⁻² for distances, eV·rad⁻² for angles)
Shared spring constant across subcommands. The same physical harmonic penalty (k) appears in the following places with the same default of 300:
YAML key |
Used by |
CLI flag |
|---|---|---|
|
|
|
|
|
— (YAML only) |
opt also applies --restraint-k (same default) to its --distance-restraint pairs, but reads it only from the CLI, not from the bias: 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 enforces near-rigid pinning.
bond¶
Bond-change detection from element covalent radii.
bond:
device: auto # Device for the distance calculation: "cuda", "cpu", or "auto"
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¶
# pdb2reaction configuration example
geom:
coord_type: cart
freeze_atoms: []
calc:
backend: uma
model: uma-s-1p2 # Model name for the selected backend (UMA: 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
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-svp
grid_level: 3
Notes¶
workersandworkers_per_nodetake effect only with the UMA backend.With
workers > 1, UMA cannot compute analytical Hessians: an explicithessian_calc_mode: Analyticalstops the run with an error. Useworkers: 1orFiniteDifference; see Workers and analytical Hessians.freqandircalways use the partial Hessian, whatevercalc.return_partial_hessianis set to.allpasses the same file to each stage it runs, and each stage reads the sections listed for that command in the Used by column of the section table at the top of this page. For example, the TS stage reads thetsoptsections, includingopt,hessian_dimer, andrsirfo, and thedftsection takes effect withall --dft.opt.lbfgsandopt.rfoare other names forlbfgsandrfo, andfreq.thermois another name forthermo. Two different values for the same setting stop the run with an error, for examplelbfgs.max_cyclesandopt.lbfgs.max_cycles, oropt.max_cyclesandlbfgs.max_cycleswhen L-BFGS is the selected optimizer.-o/--out-diroverrides theout_dirkeys, andallsets the output directory of each stage itself.
See Also¶
all - End-to-end workflow
opt - Single-structure optimization
tsopt - Transition state optimization
path-search - Recursive MEP search
freq - Vibrational analysis
dft - DFT calculations
Backends - MLIP backend details
Troubleshooting - Common errors and fixes