`path-search`¶

Builds a continuous minimum-energy path (MEP) from two or more structures in reaction order (R → … → P). Use it when you need a single stitched MEP with automatic refinement. For just two endpoints with no recursive refinement, path-opt is the simpler option.

The path is generated by one of two engines — GSM (default, --mep-mode gsm, string-based) or DMF (--mep-mode dmf, Direct Max Flux) — and refined only where covalent bond changes are detected. Refinement targets either the highest-energy image and its immediate neighbors (HEI±1, --refine-mode peak) or the nearest local minima on each side (--refine-mode minima); the default is peak for GSM and minima for DMF. The resolved subpaths are stitched into one trajectory, and the highest-energy image (HEI) of each reactive refinement segment is exported as a TS candidate (validate with tsopt + IRC).

Recursive decomposition uses bond-change evidence to propose narrower reactive segments for a possible multistep reaction. The segmentation is a geometry heuristic: it does not prove that each segment is one elementary step or contains exactly one TS. Validate every exported HEI with tsopt, a one-imaginary-mode check, and IRC connectivity. Complex mechanisms may require manual adjustment of input intermediates, scan specifications, or convergence thresholds.

Examples¶

Command form:

pdb2reaction path-search -i R.pdb [I.pdb ...] P.pdb [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [--multiplicity 2S+1]
 [-b/--backend uma|orb|mace|aimnet2]
 [--workers N] [--workers-per-node N]
 [--mep-mode {gsm|dmf}] [--freeze-links/--no-freeze-links] [--thresh PRESET] [--thresh-gsm PRESET] [--thresh-dmf TOL]
 [--refine-mode {peak|minima}]
 [--max-nodes N] [--max-cycles-gsm N] [--max-cycles-dmf N] [--climb/--no-climb]
 [--opt-mode grad|hess] [--dump/--no-dump]
 [--out-dir DIR] [--preopt/--no-preopt]
 [--align/--no-align] [--write-ref-merge/--no-write-ref-merge] [--ref-full-pdb FILE...] [--ref-pdb FILE...]
 [--convert-files/--no-convert-files]
 [--show-config/--no-show-config] [--dry-run/--no-dry-run]

Two endpoints (reactant → product):

pdb2reaction path-search -i reactant.pdb product.pdb -q 0 -m 1 \
 --out-dir ./result_path_search

Provide explicit intermediates for a multistep path:

# Provide explicit intermediates for a multistep path
pdb2reaction path-search -i R.pdb IM1.pdb IM2.pdb P.pdb -q -1 -m 1 \
 --out-dir ./result_path_search_multi

Create full-system coordinate composites for inspection with an aligned static template:

# Insert the active-site path into a static template for visualization
pdb2reaction path-search -i R.pdb IM1.pdb P.pdb -q 0 -m 1 \
 --write-ref-merge --ref-full-pdb holo_template.pdb \
 --out-dir ./result_path_search_merge

mep_w_ref* / hei_w_ref* files are written only when --write-ref-merge, --ref-full-pdb, and --align are all active.

Use DMF mode with minima refinement:

# Use DMF mode with minima refinement
pdb2reaction path-search -i reactant.pdb product.pdb -q 0 -m 1 \
 --mep-mode dmf --refine-mode minima --out-dir ./result_path_search_dmf

Workflow¶

Initial segment per pair (GSM/DMF) – run GrowingString or DMF between each adjacent input (A→B) to obtain a coarse MEP and identify the highest-energy image (HEI).
Local relaxation around HEI – refine either HEI ± 1 (refine-mode=peak) or the nearest local minima on each side of the HEI (refine-mode=minima) with the chosen single-structure optimizer (opt-mode) to recover nearby minima (End1, End2).

Default: When --refine-mode is omitted, it defaults to peak for GSM and minima for DMF.
Decide between kink vs. refinement:

If no covalent bond change is detected between End1 and End2, treat the region as a kink — a conformational rearrangement with no bond breaking or formation (see Glossary): insert search.kink_max_nodes linear nodes and optimize each individually.
Otherwise, the region is a reactive segment — a segment in which covalent bond changes are detected between the endpoints (see Glossary). Launch a refinement segment (GSM/DMF) between End1 and End2 to sharpen the barrier.

Selective recursion – compare bond changes for (A→End1) and (End2→B) using the bond thresholds. Recurse only on sub-intervals that still contain covalent updates. Recursion depth is capped by search.max_depth.
Stitching & bridging – concatenate resolved subpaths, dropping duplicate endpoints when RMSD ≤ search.stitch_rmsd_thresh. If the RMSD gap between two stitched pieces exceeds search.bridge_rmsd_thresh, insert a bridge segment — a connecting segment between two non-adjacent intermediates (see Glossary) — using GSM/DMF. When the interface itself shows a bond change, a new recursive segment replaces the bridge.
Alignment & coordinate merging for inspection (optional) – with --align (default), pre-optimized structures are rigidly aligned to the first input and freeze_atoms are reconciled. --write-ref-merge together with --ref-full-pdb writes coordinate composites for inspection.

Bond-change detection relies on bond_changes.compare_structures with thresholds surfaced under the bond YAML section. All MLIP backends are constructed once and shared across structures for efficiency.

Outputs¶

out_dir/ (default:./result_path_search/)
├─ mep_trj.xyz # Primary MEP trajectory
├─ mep.pdb # PDB/mmCIF topology companion when conversion is enabled
├─ mep.cif # mmCIF/oversized-PDB bridge inputs; original IDs restored
├─ mep.gjf # Gaussian companion when a Gaussian template is detected
├─ mep_w_ref.pdb # Active-site path in a static full-system template (--write-ref-merge)
├─ mep_w_ref.cif # Bridge-template companion for inspection (--write-ref-merge)
├─ mep_seg_XX_trj.xyz # Reactive refinement segments only: MEP trajectory (XYZ)
├─ mep_seg_XX.pdb # Reactive refinement segment PDB companion (when conversion is enabled)
├─ mep_seg_XX.cif # Reactive refinement segment bridge-input companion
├─ mep_seg_XX.gjf # Reactive refinement segment Gaussian companion (template required)
├─ mep_w_ref_seg_XX.pdb # Per-segment coordinate composite for inspection
├─ mep_w_ref_seg_XX.cif # Bridge-template companion for inspection
├─ hei_seg_XX.xyz # Reactive refinement segments only: highest-energy image
├─ hei_seg_XX.pdb # Reactive refinement segment HEI companion (conversion enabled)
├─ hei_seg_XX.cif # Reactive refinement segment HEI bridge-input companion
├─ hei_seg_XX.gjf # Reactive refinement segment HEI Gaussian companion (template required)
├─ hei_mode_seg_XX.txt # Reactive refinement segment energy-upwinding tangent
├─ hei_w_ref_seg_XX.pdb # HEI coordinate composite for inspection
├─ hei_w_ref_seg_XX.cif # HEI bridge-template companion for inspection
├─ summary.json # Barrier and classification summary for every recursive segment
├─ summary.log # Text summary
├─ mep_plot.png # ΔE profile generated via `trj2fig` (kcal/mol, reactant reference)
├─ energy_diagram_MEP.png # Static export of the MEP state-energy diagram (relative to reactant)
└─ seg_NNN_*/ # GSM/DMF dumps, HEI snapshots, kink/refinement diagnostics per segment

Console reports covering resolved configuration blocks (geom, calc, gs, stopt, opt.*, bond, search); see Verbosity levels.

CLI options¶

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

The table is grouped by purpose; within each group the most-used options come first.

Option	Description	Default
Input & charge
`-i, --input PATH...`	Two or more structures in reaction order (reactant → product). Pass all files after a single `-i`/`--input`.	Required
`-q, --charge INT`	Net charge. Required for non-`.gjf` inputs unless `--ligand-charge/-l` derivation succeeds from PDB/mmCIF topology. Overrides `--ligand-charge/-l` when both are set.	Required unless template/derivation applies
`-l, --ligand-charge TEXT`	Either a scalar integer or a per-residue mapping that derives the total from PDB/mmCIF input topology. Bare XYZ needs `-q`; `--ref-pdb` is for final merging and does not add charge derivation here. A valid GJF can instead supply charge/spin in its header.	None
`-m, --multiplicity INT`	Spin multiplicity (2S+1).	`.gjf` template value or `1`
Backend & compute
`-b, --backend {uma,orb,mace,aimnet2}`	MLIP backend.	`uma`
`--workers`, `--workers-per-node`	UMA predictor parallelism; `workers_per_node` is forwarded to the parallel predictor. `workers > 1` cannot be combined with an explicit analytical Hessian request. See workers > 1 is incompatible with analytical Hessians (UMA backend).	`1`, `1`
Active-region freezing
`--freeze-links/--no-freeze-links`	When loading PDB/mmCIF active-site topology, freeze the parent atoms of cap hydrogens. 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
MEP search
`--mep-mode {gsm\|dmf}`	Segment generator: GSM (string-based) or DMF (Direct Max Flux).	`gsm`
`--dmf-backend {cpu\|gpu}`	DMF compute backend (`--mep-mode dmf` only): `gpu` (`dmf.torch`/CUDA) or `cpu` (`dmf`/NumPy). On a GPU out-of-memory error, retry with `cpu`.	`gpu`
`--preopt/--no-preopt`	Pre-optimize each endpoint with the selected single-structure optimizer (L-BFGS/RFO) before MEP search.	`True`
`--max-nodes INT`	Internal nodes per MEP segment (GSM string images or DMF images).	`20`
`--gsm-param {equi\|energy}`	GSM node parameterization after string growth. `energy` concentrates nodes in high-energy regions and may be tried when an equidistant path skips the reaction-coordinate region near the HEI; it does not identify a TS.	`equi`
`--max-cycles-gsm INT`	Maximum GSM string-optimizer cycles.	`300`
`--max-cycles-dmf INT`	Maximum DMF IPOPT iterations.	`300`
`--climb/--no-climb`	Enable climbing image for GSM segments (bridge segments always run without climbing).	`True`
Refinement
`--refine-mode {peak\|minima}`	Seeds for refinement: `peak` optimizes HEI±1; `minima` searches outward from the HEI toward the nearest local minima on each side. Defaults to `peak` for GSM and `minima` for DMF when omitted.	Auto
`--opt-mode TEXT`	Single-structure optimizer for HEI±1/kink nodes. `grad` maps to L-BFGS; `hess` maps to RFO. See --opt-mode (subcommand-dependent) for how the same token maps across subcommands (tsopt uses Dimer/RS-P-RFO, not L-BFGS/RFO).	`grad`
Convergence thresholds
`--thresh TEXT`	Override convergence preset for single-structure optimizations only (`opt.lbfgs/rfo.thresh`).	`gau`
`--thresh-gsm TEXT`	Override convergence preset for the GSM string optimizer (`stopt.thresh`).	`gau_loose`
`--thresh-dmf TEXT`	Override the IPOPT dual-infeasibility tolerance of the DMF optimizer (`dmf.tol`): `tight` (0.04), `middle` (0.10), `loose` (0.20), or a positive float. Gaussian presets are rejected.	`tight`
Merge & alignment
`--align/--no-align`	Align all inputs to the first structure before searching.	`True`
`--write-ref-merge/--no-write-ref-merge`	Write `mep_w_ref` / `hei_w_ref` coordinate composites for inspection.	`False`
`--ref-full-pdb PATH...`	Static full-size PDB/mmCIF template for coordinate composites used for inspection. Use the template corresponding to the first `-i` input.	None
`--ref-pdb PATH...`	Active-site model PDB/mmCIF references used for final full-system merge when inputs are XYZ/GJF (one per input, matching input order).	None
Output & config
`-o, --out-dir TEXT`	Output directory.	`./result_path_search/`
`--dump/--no-dump`	Dump GSM and single-structure optimizer trajectories. Accepted but unused by the DMF path solver. Restart YAML is written only when enabled in YAML.	`False`
`--convert-files/--no-convert-files`	Toggle XYZ/TRJ → PDB/CIF/GJF companions. Bridge inputs add CIF with original IDs; XYZ/GJF inputs do not produce a PDB companion without a reference topology.	`True`
`--config FILE`	Base YAML configuration layer applied before explicit CLI values.	None
`--show-config/--no-show-config`	Print resolved configuration (including YAML layer metadata) and continue.	`False`
`--dry-run/--no-dry-run`	Validate options and print the execution plan without running path search.	`False`

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

YAML configuration¶

The YAML root must be a mapping. Shared sections reuse YAML Reference: geom/calc mirror single-structure options (with --freeze-links augmenting geom.freeze_atoms for PDBs), and stopt inherits the StringOptimizer knobs documented for path-opt (see path-opt.md).

bond and search are central to the recursion logic and shown below; stopt, opt.lbfgs, and opt.rfo are reproduced only for the path-search-specific out_dir overrides.

bond carries the MLIP-based bond-change detection parameters shared with scan: device, bond_factor, margin_fraction, and delta_fraction.

`path-search`-specific overrides¶

stopt:
 out_dir: ./result_path_search/ # path-search override (canonical default: ./result_path_opt/)
opt:
 lbfgs:
   out_dir: ./result_path_search/ # path-search override (canonical default: ./result_opt/)
 rfo:
   out_dir: ./result_path_search/ # path-search override (canonical default: ./result_opt/)

bond and search are kept here because they are central to the path-search recursion logic:

bond:
 device: auto # MLIP device for bond analysis
 bond_factor: 1.2 # covalent-radius scaling
 margin_fraction: 0.05 # tolerance margin for comparisons
 delta_fraction: 0.05 # minimum relative change to flag bonds
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 # optional refinement strategy (auto-chooses when null)

path-search¶