pdb2reaction Documentation¶

Version: v0.4.0 — 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
Reactant only — staged distance scan	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 / YAML / Glossary	CLI Conventions · YAML Reference · Glossary
Bit-reproducible runs (`--deterministic`)	Reproducibility
MLIP backend settings / HPC examples	MLIP Calculator · HPC Examples
Cluster boundary atoms (cap H, `--freeze-atoms`)	Frozen Atoms

Subcommands¶

Subcommand	Description
`all`	End-to-end workflow: extraction → scan → MEP → TS optimization → IRC → thermochemistry → DFT
`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-I-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`	1D bond-length driven scan with restraints
`scan2d`	2D distance grid scan
`scan3d`	3D distance grid scan
`freq`	Vibrational frequency analysis & thermochemistry
`irc`	Intrinsic Reaction Coordinate calculation
`dft`	Single-point DFT calculations (GPU4PySCF / PySCF)
`sp`	Single-point MLIP energy + forces
`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}, note = {ChemRxiv preprint}
}

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

License¶

GNU General Public License v3 (GPL-3.0).