`path-opt` (MEP between two structures)¶

path-opt finds a minimum-energy path (MEP) between two structures, a reactant and a product, in one pass with GSM (growing string method, the default) or DMF (direct max flux). It writes the trajectory of the structural change that connects R and P, and the highest-energy image (HEI) as a TS candidate.

What it is for¶

A first MEP from R and P: get a path and its energy profile from two endpoint structures, without recursive refinement.
A TS candidate for tsopt: hei.pdb (or hei.xyz) is the starting structure for tsopt.
Comparing GSM and DMF: run the same pair with --mep-mode gsm and --mep-mode dmf and compare the paths.

To give three or more structures at once, use the Endpoint mode of all. To try whether intermediates between R and P can be detected automatically, use path-search.

Examples¶

1. Two endpoints¶

Give the reactant and the product after one -i, with the charge and the spin multiplicity.

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 --out-json --out-dir ./result_path_opt

The console line [write] Wrote '…/hei.xyz'. shows that the TS candidate was written. In result.json (--out-json), scientific_status is success when every requested stage (endpoint pre-optimization, MEP) converged, otherwise partial or failed. barrier_kcal is the HEI energy relative to the first image, and hei_index is the position of the HEI on the path.

2. Set the endpoint pre-optimization limit¶

Both endpoints are pre-optimized by default; --preopt-max-cycles caps each pass, and --no-preopt skips it for optimized endpoints.

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
  --preopt-max-cycles 20000 --out-dir ./result_path_opt_preopt

3. DMF instead of GSM¶

DMF needs cyipopt; here we also use fewer movable images.

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
  --mep-mode dmf --max-nodes 12 --out-dir ./result_path_opt_dmf

4. Quick pass: freeze cap parents, no climbing¶

Skip the climbing-image search for a fast first look; the parents of cap hydrogens stay frozen.

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
  --freeze-links --no-climb --out-dir ./result_path_opt_quick

How it works¶

Preparing the endpoints: Each endpoint is pre-optimized, with L-BFGS by default (--opt-mode). The product is then rigidly aligned to the reactant on the frozen atoms, and the frozen atoms are moved step by step onto their reactant positions while the other atoms relax. The parents of cap hydrogens are frozen by default (--freeze-links).
Growing and refining the path: GSM grows a string of --max-nodes movable images between the two endpoints and optimizes it to --thresh-gsm. With --climb (on by default), a climbing-image search then pushes the highest image toward the saddle. DMF instead builds an interpolated path and optimizes it with IPOPT (an interior-point optimizer) to --dmf-tol.
Writing the HEI: The image with the highest energy on the final path becomes the HEI. hei.xyz holds it with its energy on the comment line.

Reading the HEI¶

Where the HEI is	Meaning	Next step
Inside the path (`hei_index` between `1` and `n_images − 2`; both are keys of `result.json`, and `n_images` is the number of images on the path)	A TS candidate	Optimize it with `tsopt`, then run `irc`
At an endpoint (`hei_index` is `0` or `n_images − 1`)	Not a TS candidate: no image between the endpoints lies above the higher endpoint	Check the endpoints, or get a candidate another way (see When a TS search fails)

The HEI is the top of an approximate path, not a TS. A successful TS optimization gives one imaginary mode along the reaction coordinate; the HEI becomes a TS once tsopt gives n_imag = 1 and IRC from that TS reaches the intended R and P.

Output files¶

path-opt writes these files to --out-dir:

result_path_opt/
├─ final_geometries_trj.xyz   # Final path, every image, energies on the comment lines
├─ final_geometries.pdb       # Same path as PDB (PDB/mmCIF input; DMF names it final_geometries_trj.pdb)
├─ hei.xyz                    # HEI, the TS candidate, with its energy on the comment line
├─ hei.pdb                    # Same HEI as PDB (PDB/mmCIF input)
├─ align_refine/              # Endpoint alignment and relaxation files
├─ result.json                # Summary (--out-json)
└─ summary.json               # Same content as result.json (with --out-json)

Open final_geometries_trj.xyz to watch the path. Pass hei.pdb to tsopt for PDB/mmCIF input, so that -l and --freeze-links apply there; with hei.xyz, add --ref-pdb. For PDB, mmCIF, or .gjf input, the outputs are also written in that format under the same name; mmCIF input, and PDB input too large for the PDB columns, also get .cif files that keep the original identifiers. With DMF, the path is not written as .gjf. --dump also keeps the optimizer trajectories.

The console prints the MEP progress cycle by cycle, with timings.

Main options¶

Option	Type	Default	Description
`-i, --input`	2 paths	(required)	Reactant and product, in that order, after one `-i` (`.pdb`, `.cif`, `.mmcif`, `.xyz`, `.gjf`)
`-q, --charge`	integer	`None`	Total charge. Required unless `-l`, YAML `calc.charge`, or a `.gjf` input gives it
`-m, --multiplicity`	integer	`1`	Spin multiplicity (2S+1)
`-l, --ligand-charge`	text	`None`	Total ligand charge (for example `-1`) or a charge per residue name (for example `'GPP:-3,SAM:1'`), used when `-q` is omitted (PDB/mmCIF input or `--ref-pdb`)
`--ref-pdb`	path	`None`	PDB/mmCIF topology for `.xyz` / `.gjf` inputs, used for both endpoints; the coordinates come from `-i`
`-b, --backend`	text	`uma`	Backend (`uma`, `orb`, `mace`, `aimnet2`, `dft`)
`-o, --out-dir`	path	`./result_path_opt/`	Output directory
`--mep-mode`	`gsm` / `dmf`	`gsm`	Path method: growing string method / direct max flux
`--dmf-backend`	`gpu` / `cpu`	`gpu`	DMF compute backend (`--mep-mode dmf` only): PyTorch on CUDA / NumPy
`--max-nodes`	integer	`20`	Movable images between the endpoints; the path has `max_nodes + 2` images
`--preopt/--no-preopt`	flag	`True`	Pre-optimize each endpoint before alignment
`--preopt-max-cycles`	integer	`100000`	Maximum cycles of each endpoint pre-optimization
`--opt-mode`	`grad` / `hess`	`grad`	Optimizer of the endpoint pre-optimization: L-BFGS / RFO
`--thresh-gsm`	preset	`gau_loose`	Convergence criteria of the GSM string (`gau_loose`, `gau`, `gau_tight`, `gau_vtight`, `baker`, `never`)
`--dmf-tol`	text	`tight`	IPOPT tolerance of the DMF path: `tight` (0.04), `middle` (0.10), `loose` (0.20), or a positive number; alias `--thresh-dmf`
`--fix-ends/--no-fix-ends`	flag	`True`	Keep the endpoints fixed while the GSM string is optimized (not used by DMF)
`--climb/--no-climb`	flag	`True`	Run the GSM climbing-image search after the path is grown (not used by DMF)
`--freeze-links/--no-freeze-links`	flag	`True`	Freeze the parent atoms of cap hydrogens (PDB/mmCIF input or `--ref-pdb`)
`--out-json/--no-out-json`	flag	`False`	Write a summary to `result.json` (JSON Output Reference)

See the generated CLI reference for every option.

Note: In YAML (--config), the gs section sets the GSM string, dmf the DMF path, and stopt the string optimizer. stopt.lbfgs and stopt.rfo also set the endpoint optimizers, as opt.lbfgs and opt.rfo do.

Notes¶

Frozen atoms move slightly with DMF: DMF holds frozen atoms with a harmonic restraint (k = 300 eV/Å², YAML dmf.k_fix) instead of fixing them, so they can drift a little from their reference positions; GSM keeps them fixed. See Freeze atoms and restrain distances.
DMF needs cyipopt: install it with PyTorch from conda-forge, as in step 3 of Step-by-step installation, before you run --mep-mode dmf; pydmf comes with pdb2reaction. The default --dmf-backend gpu stops with an error when CUDA is unavailable; use --dmf-backend cpu then, or after a GPU out-of-memory error.
DMF and implicit solvent cannot be combined: with an MLIP backend, --mep-mode dmf together with --solvent stops with an error. Use GSM for a path with solvent.
Options DMF ignores: --climb, --dump, and --fix-ends are accepted but not used by DMF.
Conflicting optimizer settings in YAML: setting the same key to different values in opt: and in the section of the optimizer that runs (lbfgs:, opt.lbfgs:, stopt.lbfgs:, or the rfo equivalents) stops the run with an error.

path-opt (MEP between two structures)¶