pdb2reaction Documentation¶

Version: v0.3.7

pdb2reaction is a Python CLI toolkit for automated enzymatic reaction-path modeling directly from PDB structures using machine-learning interatomic potentials (MLIPs).

Start here¶

Goal	Workflow
First end-to-end run	Quickstart: all
Reactant only	Quickstart: scan
TS candidate available	Quickstart: tsopt + freq
Run failure / error	Common Error Recipes

Refer to Installation for prerequisites.

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)
`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

Configuration & Reference¶

Topic	Page
Getting Started	Getting Started
CLI conventions & input requirements	CLI Conventions
Cluster boundary atoms (link hydrogens, `--freeze-atoms`)	Frozen Atoms
Common errors & fixes	Troubleshooting
CLI command reference	Command Reference
YAML configuration options	YAML Reference
MLIP backend settings	MLIP Calculator
Terminology	Glossary

System Requirements¶

Hardware¶

OS: Linux
GPU: CUDA 12.x compatible
VRAM: 8 GB+ recommended
RAM: 16 GB+ recommended

Software¶

Python >= 3.11
PyTorch with CUDA support
CUDA 12.x toolkit

For setup, see Installation.

Agent Skills¶

pdb2reaction ships AI-agent instructions under .claude/skills/ covering CLI subcommands, structure I/O, backend installation, workflows, output parsing, and HPC operation. See .claude/skills/README.md for the full skill index and installation instructions.

Citation¶

A preprint describing pdb2reaction is in preparation. Currently, if you find this work helpful for your research, please cite the software itself:

@software{ohmura2026pdb2reaction,
  author       = {Ohmura, Takuto},
  title        = {pdb2reaction},
  year         = {2026},
  month        = {4},
  version      = {0.3.6},
  url          = {https://github.com/t-0hmura/pdb2reaction},
  license      = {GPL-3.0},
  doi          = {10.5281/zenodo.19197865}
}

License¶

pdb2reaction is distributed under the GNU General Public License version 3 (GPL-3.0).

Getting Help¶

# General help
pdb2reaction --help

# Command help
pdb2reaction <subcommand> --help

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

For issues and feature requests, visit the GitHub repository.