pdb2reaction: End-to-End Reaction-Path Elucidation from PDB Structures Using Machine-Learning Interatomic Potentials

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.

You can test a reaction mechanism in a single command like:

pdb2reaction all -i R.pdb P.pdb -c 'LIG' -l 'LIG:-1' --tsopt --thermo

Starting from the reactant (R) and product (P) structures, the command above runs:

Active-site cluster model setup → Minimum energy path (MEP) search → TS optimization → IRC → Thermochemistry

It also works for small molecules:

pdb2reaction all -i R.xyz P.xyz -q +1 --tsopt --thermo --dft

MEP search → TS optimization → IRC → Thermochemistry → DFT single-point

Without -c, the input structures are used as they are; set the total charge with -q.

Features

• Find a reaction path and its TS from two or more structures you built, without defining a reaction coordinate (Endpoint mode).
• Build the path from one structure by driving a reaction coordinate you choose (Scan-list mode).
• Start the TS search directly from a TS candidate (TS-only mode).
• Split a multi-step reaction into steps, each with its own TS (path-search).
• Cut an active-site cluster model from a PDB/mmCIF file, with cap hydrogens and the total charge set automatically (Building the cluster model).
• Choose the MLIP: UMA, ORB, MACE, or AIMNet2 (MLIP backends).
• Refine the TS with GPU-accelerated DFT in the same tool (DFT backend).
• Run each stage on its own as a subcommand (CLI subcommands).
• Let AI agents run the workflow with the bundled skills (Agent skills).

Installation

Requirements: Linux, Python 3.11 or later (3.12 recommended; ORB requires 3.11 or 3.12), and an NVIDIA GPU with the official PyTorch 2.13 CUDA wheel that matches your driver/GPU (cu130 recommended). Details: docs/installation.md.

# 1. CUDA-enabled PyTorch (choose the official 2.13 wheel for your driver/GPU)
pip install 'torch==2.13.0' --index-url https://download.pytorch.org/whl/cu130

# 2. Install pdb2reaction and headless Chrome (for PNG export of plots)
pip install pdb2reaction
plotly_get_chrome -y

# 3. Authenticate Hugging Face once (only required for the default UMA backend)
#    Accept the FAIR Chemistry License v1 at https://huggingface.co/facebook/UMA, then:
hf auth login                               # interactive
# OR, for non-interactive CI/HPC jobs: export HF_TOKEN=hf_xxx

Optional extras (install only what you need):

The MACE backend (-b mace) does not install into the same environment as UMA; create a dedicated environment as described in docs/installation.md.

CUDA module loads, alternative-backend recipes, DMF/cyipopt setup, Plotly Chromium, and HPC job-script templates: docs/installation.md and docs/hpc-example.md.

Quick Examples

Before you start:

• PDB/mmCIF inputs must already contain hydrogens.
• Reaction-ordered structures must share the same atom identities and order (only coordinates differ).
• mmCIF files (including multi-character chains and large residue IDs) and large structures: see mmCIF and large structures.
• Small-molecule .xyz / .gjf inputs work when --center/-c and --ligand-charge/-l are omitted.

Examples use GPP C6-methyltransferase BezA (Tsutsumi et al., Angew. Chem. Int. Ed. 2022, 61, e202111217). Run the commands below from the repository root (git clone https://github.com/t-0hmura/pdb2reaction && cd pdb2reaction); the complete MEP and scan examples are in examples/run.sh.

# Endpoint mode (R + P → MEP, with TS + thermochemistry)
pdb2reaction -i examples/1.R.pdb examples/3.P.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' \
    --tsopt --thermo --out-dir result_mep

# Scan-list mode (single structure → staged bond scan → MEP)
pdb2reaction -i examples/1.R.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' \
    -s '[("CS1 SAM 320","GPP 321 C7",1.60)]' --tsopt --thermo --out-dir result_scan

# TS-only validation (your own TS candidate → tsopt → IRC → freq)
pdb2reaction -i TS_candidate.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' --tsopt --thermo --out-dir result_tsonly

pdb2reaction can also be used to investigate reaction mechanisms of small molecules and user-defined cluster models.

# Small molecule (gas-phase): .xyz / .gjf input — omit -c, set charge with -q
pdb2reaction -i reactant.xyz product.xyz -q 0 --tsopt --thermo --out-dir result_small

# Your own cluster model (already-trimmed PDB): omit -c to use it as-is
pdb2reaction -i cluster_R.pdb cluster_P.pdb -l 'LIG:+1' --tsopt --thermo --out-dir result_cluster

For a hand-built cluster, check its boundaries with the cluster-boundary checklist.

Each stage (extract → opt → path-opt → tsopt → irc → freq → dft) also runs as its own subcommand; see CLI Subcommands for the per-stage pages.

Output

Each calculation command writes to its own directory, ./result_<command>/ by default (for example ./result_opt/, ./result_tsopt/, or ./result_path_opt/); -o/--out-dir sets another. extract writes model.pdb to the current directory.

A non-dry all run writes the deliverables reached by its enabled stages to ./result_all/:

• segments/seg_NN/{reactant,ts,product}.* — the canonical R / TS / P structures to cite
• mep_trj.xyz (plus mep_trj.pdb when topology is available and mep_trj.cif for mmCIF input or very large PDB) — the merged reaction path in MEP/scan-list modes
• energy_diagram_MEP.png — MEP energy diagram
• summary.log / summary.json

Pipeline scratch lives under _work/; keep it if you may redo the post-processing with --resume-segment. Full layout and filename conventions: docs/output-layout.md.

Colab GUI workspace

An interactive GUI workspace is available in Google Colab. It brings ordered structure input, Mol* visualization and atom picking, controls generated from the live CLI, execution, and linked MEP/IRC/result inspection into one notebook. Choose a GPU runtime and open the Colab GUI workspace.

CLI Subcommands

Documentation

• Getting Started · Installation · Quickstart: all · Building the cluster model · DFT backend · Troubleshooting
• Full site: https://t-0hmura.github.io/pdb2reaction/

Agent Skills

skills/ holds Agent Skills that let an AI coding agent run pdb2reaction workflows and subcommands. Copy the skill folders into .claude/skills/ or ~/.claude/skills/ for Claude Code, or into .agents/skills/ or ~/.agents/skills/ for Codex. The list and an example copy command are in skills/README.md.

Getting Help

pdb2reaction --help                       # top-level
pdb2reaction <subcmd> --help              # core options
pdb2reaction <subcmd> --help-advanced     # full option set

Issues: https://github.com/t-0hmura/pdb2reaction/issues.

Related tools

Known limitations

• MACE + UMA cannot coexist (e3nn version conflict). Use separate conda envs.
• DFT is practical up to about 500 atoms for a single point and about 300 atoms for an optimization on an HPC GPU, and up to about 200 atoms on a consumer GPU (ωB97M-V/def2-SVP, the default; from experience).
• MACE and ORB need fp64 (--precision fp64, their default); in fp32, extra imaginary modes appear more often. fp64 is slow on consumer GPUs: on HPC GPUs, ORB in fp64 is very cost-effective, and on a consumer GPU, UMA in fp32 gives the best balance.
• CPU-only execution is supported but usually much slower than GPU.
• The bundled pysisyphus is a modified fork; do not install upstream pysisyphus in the same environment.

Citation

@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}
}

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

License

GNU General Public License v3 (GPL-3.0).