path-search

mlmm path-search builds a continuous minimum-energy path (MEP) across two or more structures using GSM. It selectively refines only those regions where covalent bond changes are detected, then stitches the resolved subpaths into a single trajectory. Use it to drive a multistep mechanism from R + (optional intermediates) + P, where the recursive segmentation auto-detects elementary steps. Complex multistep mechanisms may require manual trial-and-error—adjusting input intermediates, MEP-engine settings, or convergence thresholds—to obtain a satisfactory pathway.

Examples

mlmm path-search -i reactant.pdb product.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q 0 --out-dir ./result_path_search

Build a multistep path with explicit intermediates:

# Build a multistep path with explicit intermediates
mlmm path-search -i R.pdb IM1.pdb IM2.pdb P.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q -1 --out-dir ./result_path_search_multi

Lighter pass without pre-optimization or alignment:

# Lighter pass without pre-optimization or alignment
mlmm path-search -i reactant.pdb product.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q 0 --no-preopt --no-align --max-nodes 8 \
 --out-dir ./result_path_search_fast

General command form:

mlmm path-search -i R.pdb IM1.pdb P.pdb \
 --parm real.parm7 --model-pdb ml_region.pdb -q CHARGE [-m MULT]
 [--mep-mode gsm|dmf] [--refine-mode peak|minima]
 [--freeze-atoms "1,3,5"] [--max-nodes N] [--max-cycles N] [--climb/--no-climb]
 [--opt-mode grad]
 [--thresh PRESET] [--dump/--no-dump] [--out-dir DIR]
 [--show-config/--no-show-config] [--dry-run/--no-dry-run]

Workflow

1. Initial segment per pair (GSM/DMF) – Run the selected MEP engine (--mep-mode) between each adjacent input (A->B) to obtain a coarse MEP and identify the highest-energy image (HEI).

2. Local relaxation around HEI – Seed refinement from --refine-mode (peak: HEI+/-1, minima: nearest local minima), then optimize with the chosen single-structure optimizer (--opt-mode) to recover nearby minima (End1, End2).

3. Decide between kink vs. refinement:

• If no covalent bond change is detected between End1 and End2, treat the region as a kink: insert search.kink_max_nodes linear nodes and optimize each individually.

• Otherwise, launch a refinement segment (GSM) between End1 and End2 to sharpen the barrier.

4. Selective recursion – Compare bond changes for (A->End1) and (End2->B) using the bond thresholds. Recurse only on sub-intervals that still contain covalent bond changes. Recursion depth is capped by search.max_depth.

5. 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 MEP segment using the selected --mep-mode. When the interface itself shows a bond change, a new recursive segment replaces the bridge.

6. Optional alignment – When enabled, --align rigidly aligns all inputs to the first input (after optional pre-opt) and re-matches the freeze-atom selection. Segments are annotated for plotting/analysis.

Bond-change detection relies on bond_changes.compare_structures with thresholds surfaced under the bond YAML section.

Outputs

out_dir/ (default: ./result_path_search/)
 summary.json # MEP-level run summary (no full settings dump)
 summary.log # Human-readable summary
 mep_trj.xyz # Final MEP (always written)
 mep.pdb # Final MEP (PDB when ref template available)
 mep_seg_XX_trj.xyz / mep_seg_XX.pdb # Per-segment paths
 hei_seg_XX.xyz / hei_seg_XX.pdb # HEI per bond-change segment
 mep_plot.png # Delta-E profile vs image index (from trj2fig)
 energy_diagram_MEP.png # State-level energy diagram relative to the reactant (kcal/mol)
 seg_000_*/ # Segment-level GSM and refinement artifacts

CLI options

mlmm path-search --help shows core options; mlmm path-search --help-advanced shows the full option list. The full flag list is also in the generated command reference; the table below covers the options that need explanation.

Option	Description	Default
-i, --input PATH...	Two or more full-enzyme PDBs in reaction order. Repeat -i or pass multiple paths after one flag.	Required
--parm PATH	Amber parm7 topology for the full enzyme complex.	Required
--model-pdb PATH	PDB defining the ML (high-level) region atoms for ML/MM. Optional when --detect-layer or --model-indices is used.	None
--model-indices TEXT	Comma-separated atom indices for the ML region (ranges allowed like 1-5). Used when --model-pdb is omitted.	None
--model-indices-one-based / --model-indices-zero-based	Interpret --model-indices as 1-based or 0-based.	True (1-based)
--detect-layer / --no-detect-layer	Detect ML/MM layers from input PDB B-factors (B=0/10/20). If disabled, you must provide --model-pdb or --model-indices.	True
-q, --charge INT	Net charge of the ML region (integer). Required unless --ligand-charge is provided.	None
-l, --ligand-charge TEXT	Per-residue charge map, e.g. SAM:1,PHN:-1. Derives total charge when -q is omitted. Requires PDB input or --ref-pdb.	None
-m, --multiplicity INT	Spin multiplicity (2S+1).	1
--mep-mode [gsm|dmf]	MEP backend for segment/bridge searches.	gsm
--dmf-backend [cpu|gpu]	DMF compute backend (--mep-mode dmf only): gpu (dmf.torch/CUDA) or cpu (dmf/NumPy). Retry cpu on a GPU out-of-memory error. Requires pydmf>=1.2.	gpu
--refine-mode [peak|minima]	HEI refinement seed rule.	peak for gsm, minima for dmf
--freeze-atoms TEXT	Comma-separated 1-based indices to freeze (merged with YAML geom.freeze_atoms).	None
--hess-cutoff FLOAT	Distance cutoff (Å) from ML region for MM atoms to include in Hessian calculation. Applied to movable MM atoms.	None
--movable-cutoff FLOAT	Distance cutoff (Å) from ML region for movable MM atoms. MM atoms beyond this are frozen. Providing --movable-cutoff disables --detect-layer.	None
--max-nodes INT	Internal nodes for segment GSM.	20
--max-cycles INT	Max GSM macro-cycles.	300
--climb/--no-climb	Enable TS refinement for segment GSM.	True
--opt-mode [grad]	Single-structure optimizer preset (currently grad = LBFGS only; hess not yet wired).	grad
--preopt/--no-preopt	Pre-optimize endpoints with LBFGS before segmentation.	True
--align/--no-align	After pre-optimization, rigidly align all inputs to the first input and re-match freeze atoms.	True
--thresh TEXT	Convergence preset (gau_loose, gau, gau_tight, gau_vtight, baker, never).	None (effective: gau_loose)
--mm-backend [hessian_ff|openmm]	MM backend (analytical Hessian vs OpenMM finite-difference).	hessian_ff
--dump/--no-dump	Save optimizer dumps.	False
-o, --out-dir PATH	Output directory.	./result_path_search/
--ref-pdb PATH...	Full template PDB(s) for XYZ→PDB conversion and topology reference.	None
--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. Shown in --help-advanced.	False
-b, --backend CHOICE	MLIP backend for the ML region: uma (default), orb, mace, aimnet2.	uma
--embedcharge/--no-embedcharge	Enable xTB point-charge embedding correction for MM-to-ML environmental effects (experimental).	False
--embedcharge-cutoff FLOAT	Cutoff radius (Å) for embed-charge MM atoms.	12.0
--cmap/--no-cmap	Enable CMAP (backbone cross-map dihedral correction) in model parm7. Default: disabled (consistent with Gaussian ONIOM).	--no-cmap
--convert-files/--no-convert-files	Toggle XYZ/TRJ to PDB companions when a PDB template is available.	True

YAML configuration

Merge order is defaults < config < explicit CLI < override. The YAML root must be a mapping. The relevant sections are geom/calc(alias mlmm)/gs/opt (shared with path-opt) plus lbfgs (HEI+/-1 single-structure refinement), bond (bond-change detection), and search (recursive segmentation logic, path-search only).

# Minimal path-search YAML (every key and default: see YAML Reference)
calc:
  backend: uma
search:
  max_depth: 10            # recursion depth cap
  refine_mode: null        # peak | minima | null (auto)
bond:
  bond_factor: 1.2         # covalent-radius scaling for bond-change cutoff

Full schema (every key and default): YAML Reference.

Notes

• If you only have two endpoints and do not need recursive refinement, prefer path-opt.

See Also

• Common Error Recipes — Symptom-first failure routing

• Troubleshooting — Detailed troubleshooting guide

• path-opt — Single-pass MEP optimization (no recursive refinement)

• opt — Single-structure geometry optimization

• all — End-to-end workflow (uses single-pass path-opt by default; --refine-path for recursive path-search)

• trj2fig — Plot energy profiles from MEP trajectories

• YAML Reference — Full gs, bond, search configuration options