pdb2reaction Documentation¶

pdb2reaction is a Python CLI toolkit for analyzing reaction mechanisms in enzyme complexes and small molecules with machine-learning interatomic potentials (MLIPs), starting from PDB/mmCIF/XYZ/GJF structures.

New to pdb2reaction? Start with Getting Started.

Getting Started Installation Open in Google Colab

Quick start¶

Analyze the mechanism end to end from the structures before and after the reaction

Quickstart: all in Endpoint mode

Analyze the mechanism end to end from one structure

Quickstart: all in Scan-list mode

Analyze the mechanism end to end from a TS structure

Quickstart: TS-only mode

Goal	Page
Build, trim, or extend the cluster model	Building the cluster model
Analyze a small-molecule reaction	Small-molecule reactions
Study a mechanism, or the TS search fails	Tips for studying reaction mechanisms
Optimize the TS structure with DFT	Refine an MLIP TS with DFT
A run failed	Troubleshooting

Subcommands¶

Subcommand	Description
`all`	Optional extraction; one of the three input modes (Endpoint mode, Scan-list mode, TS-only 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` removes leftover imaginary modes)
`tsopt`	Transition state optimization (Dimer or RS-P-RFO; optional `--flatten` removes extra imaginary modes)
`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 calculator energy + forces / Hessian (MLIP or `-b dft`)
`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 and reference¶

Topic	Page
Common options and input requirements	Common options and selectors
Frozen atoms and distance restraints (`--freeze-atoms`, `--distance-restraint`)	Freeze atoms and restrain distances
Common errors and fixes	Troubleshooting
CLI command reference	Command Reference
YAML configuration options	YAML Reference
MLIP backend settings	MLIP Backends
Files each command writes	Output Directory Layout
Keys of `result.json` and `summary.json`	JSON Output Reference
Running on several GPU nodes (PBS + Ray)	HPC example
Using pdb2reaction from an AI agent	Agent skills
Code structure (for developers)	Architecture
Terminology	Glossary

System requirements¶

Hardware¶

OS: Linux (on Windows, install it in Linux under WSL2).
GPU: an NVIDIA driver compatible with the backend and PyTorch wheel. CPU execution is also supported but slower.
VRAM / RAM: depends on the model, the system size, and the Hessian mode; measure the peak on a representative run.

Software¶

Python >= 3.11.
CPU or CUDA-enabled PyTorch. Prebuilt wheels include their CUDA runtime; a local toolkit is normally needed only for source builds.

See Installation for setup.

Agent skills¶

skills/ contains guides for CLI commands, structure I/O, backends, workflows, output analysis, and HPC use. To install them, tell your AI agent:

Import https://github.com/t-0hmura/pdb2reaction/tree/main/skills as skills, and install pdb2reaction by following pdb2reaction-install.

If you cloned the GitHub repository, you can give the local skills/ path instead. Then you can ask, for example:

Read the paper, build a model from the PDB structure PDB ID, and study the mechanism of the reaction step with the pdb2reaction skills.

For details, see Skills for AI Agents.

Citation¶

If you use pdb2reaction in your research, cite the ACS Omega paper:

@article{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},
  journal = {ACS Omega}, year = {2026}, doi = {10.1021/acsomega.6c08242}
}

To cite the software or a specific release, use the Zenodo record:

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

License¶

GNU General Public License v3 (GPL-3.0).

Getting Help¶

# General help
pdb2reaction --help

# Command help
pdb2reaction <subcommand> --help

# Advanced options (internal tuning)
pdb2reaction <subcommand> --help-advanced

Report problems and feature requests on GitHub Issues.