pdb2reaction Documentation

Version: v0.4.12 — Python CLI for enzymatic reaction-path elucidation from PDB structures using machine-learning interatomic potentials (MLIPs).

Quick start

Goal	Page
Install + run a first end-to-end pipeline	Installation · Getting Started
End-to-end pipeline from a PDB	Quickstart: all
Single-structure scan-seeded MEP workflow	Quickstart: scan
TS candidate available — tsopt → IRC → freq	Quickstart: TS-only
Choosing precision / TS route / imaginary-mode fix / controlled comparison	tsopt
Staged-vs-concerted scan / barrier direction	scan
Run failure / error	Common Error Recipes · Troubleshooting
CLI conventions / structure formats / YAML	CLI Conventions · mmCIF and large structures · YAML Reference
Same-stack repeatability (--deterministic)	Reproducibility
MLIP backend settings / HPC examples	MLIP Calculator · HPC Examples
Cluster boundary atoms (cap-H, --freeze-atoms)	Frozen Atoms

Subcommands

Subcommand	Description
all	Optional extraction; endpoint-MEP, scan-list, or TS-only entry mode; optional TS/IRC, thermochemistry, and DFT stages
extract	Extract active site model (binding pocket) from protein–ligand complex
fix-altloc	Resolve PDB alternate locations
add-elem-info	Repair PDB element columns (77–78)
opt	Single-structure geometry optimization (L-BFGS or RFO; optional flatten)
tsopt	Transition state optimization (Dimer or RS-P-RFO; optional flatten)
path-opt	Single-step MEP optimization via GSM or DMF (from 2 structures)
path-search	Recursive multi-step MEP search with automatic refinement (2+ structures)
scan	Restrained distance scan supporting concerted multi-distance and multistage scans
scan2d	Two-dimensional energy-landscape exploration and PES mapping
scan3d	Three-dimensional energy-landscape exploration and PES mapping
freq	Vibrational frequency analysis & thermochemistry
irc	Intrinsic Reaction Coordinate calculation
dft	Single-point DFT calculations (GPU4PySCF / PySCF)
sp	Single-point MLIP energy + forces / Hessian
trj2fig	Plot energy profiles from XYZ trajectories
energy-diagram	Draw an energy diagram from numeric values
bond-summary	Detect and report covalent bond changes between consecutive structures

Getting Help

# General help
pdb2reaction --help

# Command help
pdb2reaction <subcommand> --help

# Advanced options (dry-run, internal tuning, etc.)
pdb2reaction <subcommand> --help-advanced

Citation

@misc{ohmura2026pdb2reaction,
  author = {Ohmura, Takuto and Sato, Hajime and Terada, Tohru},
  title  = {pdb2reaction: End-to-End Reaction-Path Elucidation from PDB Structures Using Machine-Learning Interatomic Potentials},
  year   = {2026}, doi = {10.26434/chemrxiv.15003538/v1}, note = {ChemRxiv preprint}
}

A Zenodo software record is also available (DOI 10.5281/zenodo.19197865).

License

GNU General Public License v3 (GPL-3.0).