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

Overview

pdb2reaction is a Python CLI for elucidating enzymatic reaction pathways from PDB or mmCIF structures using machine-learning interatomic potentials (MLIPs). Given (i) two or more reaction-ordered structures, (ii) one structure with --scan-lists, or (iii) one TS candidate with --tsopt, it can run an MEP search and optionally chain TS optimization → IRC → thermochemical correction → DFT single-point. Active-site extraction is performed only when -c/--center is supplied; otherwise the PDB/mmCIF/XYZ/GJF model is used as-is. Each stage is also exposed as an individual subcommand.

Test a reaction mechanism in a single command:

# Multi-PDB mode (R + P endpoints → MEP, with TS optimization + thermo)
pdb2reaction all -i R.pdb P.pdb -c 'LIG' -l 'LIG:-1' --tsopt --thermo

Protein structures can be supplied in PDB or mmCIF format, including mmCIF files with multi-character chains and large residue IDs. Small molecules are accepted in PDB, mmCIF, XYZ, or GJF format, and prebuilt cluster models can also be supplied as PDB/mmCIF.

Prerequisites: PDB/mmCIF inputs must already contain hydrogens; reaction-ordered structures must share the same atom identities and order (only coordinates differ). Small-molecule .xyz / .gjf inputs work when --center/-c and --ligand-charge/-l are omitted.

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.

Related tools

pdb2reaction bundles a GPU-optimized pysisyphus fork that is not compatible with upstream pysisyphus — do not install it into an environment that already has upstream pysisyphus.

Documentation

• Getting Started · mmCIF and large structures · Installation · Examples · Troubleshooting
• YAML Reference · JSON Output Schema
• Full site: https://t-0hmura.github.io/pdb2reaction/

System requirements

CPU-only execution works but is usually much slower; benchmark the selected backend/model. Full requirement and tuning details: docs/installation.md.

Installation

# 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
pip install pdb2reaction

# 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) is not a pip extra: mace-torch pins e3nn==0.4.4, which conflicts with fairchem-core's e3nn>=0.5 (UMA), so it needs a dedicated environment — pip uninstall -y fairchem-core && pip install mace-torch (see 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

Examples use GPP C6-methyltransferase BezA (Tsutsumi et al., Angew. Chem. Int. Ed. 2022, 61, e202111217). Run the commands below from the repository root; the complete MEP and scan examples are in examples/run.sh.

# Multi-structure MEP (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 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 (single 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 -q 0 --tsopt --thermo --out-dir result_cluster

For hand-built clusters, standardize backbone ends at Cα (CA), place other boundaries on aliphatic C–C single bonds whenever possible, avoid cutting peptide/polar/conjugated/metal bonds, and use the identical atom order and cap topology for every state. See the cluster-boundary checklist.

Per-stage walkthrough (extract → opt → path-opt → tsopt → irc → freq → dft): docs/getting-started.md and docs/quickstart-all.md.

Output

A non-dry all run writes the deliverables reached by its enabled stages to --out-dir (default ./result_all/):

• segments/seg_NN/{reactant,ts,product}.* — the canonical R / TS / P structures to cite
• mep_trj.xyz (plus mep.pdb when topology is available and mep.cif for bridged inputs) — the merged reaction path in MEP/scan-list modes
• energy_diagram_MEP.png — MEP diagram when MEP construction and static-image export succeed
• summary.log / summary.json

Pipeline scratch lives under _work/ (safe to delete). Full layout and filename conventions: docs/output-layout.md.

CLI Subcommands

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.

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

Agent Skills

Agent Skills for Claude Code / Codex / Cursor etc. in skills/ — copy into your project's skill location (e.g. .claude/skills/) to let an agent drive pdb2reaction workflows and subcommands.

Known limitations

• MACE + UMA cannot coexist (e3nn version conflict). Use separate conda envs.
• DFT single-point cost depends strongly on basis, functional, grid, elements, and hardware; pilot one representative structure before batching.
• Every backend's TS requires frequency and IRC connectivity checks. Use tsopt's terminal PHVA for saddle-order validation; a separate freq run is optional for further analysis. The pdb2reaction ORB default is fp64; independently validate frequencies and IRC results when selecting fp32/TF32.
• CPU-only execution is supported but usually much slower than GPU.

Contributing

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

License

GNU General Public License v3 (GPL-3.0).