Getting Started¶
Overview¶
pdb2reaction is a Python CLI for elucidating enzymatic reaction pathways from PDB or mmCIF structures using machine-learning interatomic potentials (MLIPs). The default backend is Meta’s UMA; orb, mace, and aimnet2 are also supported via -b/--backend. Foundation-model MLIPs can make cluster-model TS optimization, IRC verification, and QRRHO thermochemistry practical on a single GPU, depending on cluster size, backend/model, Hessian mode, precision, and hardware.
A single command generates a reasonable initial reaction path:
pdb2reaction all -i 1.R.pdb 3.P.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' # MEP only
pdb2reaction all -i 1.R.pdb 3.P.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' --tsopt --thermo --dft # full
Given (i) ≥ 2 structures (R → … → P), (ii) one structure with --scan-lists/-s, or (iii) one TS candidate with --tsopt, pdb2reaction optionally extracts an active-site cluster model when -c is supplied, runs the selected MEP/scan/TS-only entry mode, and optionally chains TS optimization, IRC, thermochemical correction, and single-point DFT. Without active-site extraction, omit only -c/--center; the full input is analyzed as given, but its charge must still come from explicit -q, residue-based -l for a PDB/mmCIF, configured calc.charge, or valid .gjf metadata.
Working examples (BezA C6-methyltransferase, both multi-structure MEP and scan modes): examples/. For setup see Installation; for symptom-first diagnosis see Common Error Recipes and Troubleshooting.
Pipeline (the all subcommand)¶
structure(s) → [extract: with -c] → [scan: with -s] → [MEP: except TS-only] → [tsopt + irc: with --tsopt] → [freq: with --tsopt --thermo] → [dft: with --tsopt --dft]
The named computational stages (extract, scan commands, path commands,
tsopt, irc, freq, and dft) also have standalone subcommands; all
runs the selected stages and writes unified summary.json +
summary.log.
Key output files¶
File |
Description |
|---|---|
|
Machine-readable results (barriers, energies, bond changes, environment) |
|
Human-readable text summary with directory tree |
|
Created when a reactive segment enters requested post-processing; canonical R/TS/P appear after successful |
|
Merged MEP trajectory; CIF companion preserves bridged input identifiers |
|
Energy profile plots (electronic / Gibbs-corrected) |
Important
Input PDB/mmCIF structures must already contain hydrogen atoms.
Multiple structures must contain the same atoms in the same order (only coordinates may differ).
CLI conventions¶
Convention |
Example |
Notes |
|---|---|---|
Residue selectors |
|
Quote multi-value strings. |
Charge mapping |
|
Colon separates name and charge; comma separates entries. |
Atom selectors |
|
Use positional |
Full table: CLI Conventions.
Hydrogen addition (if your PDB lacks H)¶
reduce input.pdb > out.pdb (fast, crystallographic structures) · obabel input.pdb -O out.pdb -h (general cheminformatics) · PyMOL h_add · AmberTools tleap (Amber force-field prep). Apply the same tool with consistent settings to every input to keep atom order matched across structures.
Quickstart routes¶
Quickstart:
pdb2reaction all— multi-structure MEPQuickstart: scan-seeded
allworkflow — one structure +--scan-listsQuickstart: TS-only mode —
pdb2reaction all --tsoptInteractive Colab GUI — upload PDB/mmCIF, pick exact residues/atoms in 3D, validate, then run
Command line basics¶
The CLI entry point is pdb2reaction (alias p2r; both register from the same setuptools entry point). The default subcommand is all:
pdb2reaction [OPTIONS]... # equivalent to: pdb2reaction all [OPTIONS]...
Two key options on the workflows that use cluster extraction:
-i/--input— one or more full structures (reactant, intermediate(s), product).-c/--center— substrate / extraction center (residue names, residue IDs, chain-qualified selectors, or PDB/mmCIF paths). Omit to skip extraction and feed the full input structure directly.
Main workflow modes¶
Mode |
Trigger |
Appropriate input |
Quickstart |
|---|---|---|---|
Multi-structure MEP |
|
Two or more endpoint/intermediate structures are available. |
|
Scan-defined single-structure workflow |
|
Reaction coordinates are specified instead of endpoint structures. |
|
TS-only |
|
A TS candidate is already available. |
Important
Single-input runs require either --scan-lists/-s or --tsopt — a bare -i ONE.pdb will not trigger a full workflow.
Common options¶
Option |
Description |
|---|---|
|
Input structures. ≥ 2 structures → MEP; 1 structure + |
|
Substrate / extraction center (residue names, residue IDs, chain-qualified selectors, or PDB/mmCIF paths). |
|
Charge mapping ( |
|
Net system charge / spin multiplicity. |
|
TS optimization + IRC / vibrational analysis / single-point DFT. Both |
|
MLIP backend (default |
Full option matrix: CLI Conventions and the generated CLI reference under reference/commands/index. Backend cost / VRAM comparison: see Troubleshooting › Choosing a backend.
Run summaries¶
An all run that reaches aggregate summary writing produces root
summary.log (human) + summary.json (machine) with the CLI command, global
MEP statistics, per-segment barriers/bond changes, and enabled post-stage
energies. Segment directories contain conditional stage artifacts; they do not
each carry an aggregate summary pair.
HPC / multi-GPU¶
pdb2reaction parallelizes UMA inference across nodes — set workers and workers_per_node to enable multi-worker mode. Job-script templates: docs/hpc-example.md. Backend configuration: MLIP Calculator.
Agent Skills¶
pdb2reaction ships agent-readable instructions under skills/ — copy into your project as .claude/skills/ (or ~/.claude/skills/ for user-global) to let Claude Code / Cursor / OpenCode drive the CLI end-to-end.
Getting help¶
pdb2reaction <subcommand> --help # core options
pdb2reaction <subcommand> --help-advanced # full option set
--help-advanced is available on the calculation / scan / extract / utility commands; for the per-command index see the documentation home.