はじめに

概要

pdb2reaction は、機械学習原子間ポテンシャル（MLIP）を用いて PDB 構造 から 酵素反応経路 を自動的に構築する Python 製の CLI ツールキットです。

多くのケースで、次のような 1 コマンド から反応経路の**初期案（first-pass）**を得られます。

pdb2reaction -i R.pdb P.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3'

さらに --tsopt True --thermo True --dft True を追加すると、MEP 探索 → TS 最適化 → IRC → 熱化学解析 → DFT 一点計算 までまとめて実行できます。

pdb2reaction -i R.pdb P.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3' --tsopt True --thermo True --dft True

入力として、(i) 反応順に並べたタンパク質–リガンド複合体の PDB を 2 つ以上（R → … → P）、(ii) --scan-lists を指定した 1 つの PDB、または (iii) TS 候補 1 構造 + --tsopt True を与えると、pdb2reaction が次を自動化します。

  • ユーザーが指定した基質の周辺から 活性部位ポケット を抽出し、計算用の クラスターモデル を構築

  • Growing String Method (GSM) や Direct Max Flux (DMF) などの経路最適化手法で 最小エネルギー経路 (MEP) を探索

  • 必要に応じて 遷移状態 を最適化し、振動解析・IRC 計算・DFT 一点計算 を実行

Important

単一コマンドの TS 結果は「候補」として扱ってください。酵素反応では、端点の品質、ポケット定義、拘束、スキャンターゲットの調整を伴う反復的な改善が一般的です。最終解釈の前に、freq と irc の両方で TS を必ず検証してください。

UMA レベルの計算には Meta の UMA（MLIP）を用います。

一連の処理は CLI から呼び出せるように統一されており、手作業を最小化して 多段階の酵素反応メカニズム を組み立てられるように設計しています。抽出を行わない全系ワークフロー（--center/-c と --ligand-charge を省略）では .xyz / .gjf 入力も利用できます。小分子系にもそのまま適用可能です。

HPC クラスターやマルチ GPU 環境では、UMA 推論をノード間で並列化することで、大規模なクラスターモデル（必要なら 完全なタンパク質–リガンド複合体）にもスケールできます。workers と workers_per_node で並列度を設定してください（詳細は UMA 計算機）。

Important

  • 入力 PDB ファイルには水素原子が含まれている必要があります。

  • 複数の PDB を提供する場合、同じ原子が同じ順序で含まれている必要があります（座標のみが異なる状態）。一致しない場合はエラーになります。

Tip

初めて使う場合は、まず 概念とワークフロー を読むと全体像が掴みやすいです。 セットアップや実行でエラーに遭遇したら トラブルシューティング も参照してください。

CLI の規約

規約

例

備考

真偽値オプション

--tsopt True, --dft False

大文字小文字は区別しない（true/1/yes も可）。ただしフラグ形式（--tsopt のみ）は不可

残基セレクタ

'SAM,GPP', 'A:123,B:456'

複数値はシェル展開防止のためクォート

電荷マッピング

--ligand-charge 'SAM:1,GPP:-3'

コロンで名前と電荷を区切り、カンマでエントリを区切る

原子セレクタ

'TYR,285,CA' または 'TYR 285 CA'

区切り文字: 空白、カンマ、スラッシュ、バッククォート、バックスラッシュ

補足: CLI サブコマンド名は path-search（ハイフン区切り）ですが、ドキュメントファイル名は path_search.md（アンダースコア区切り）です。

水素原子付与の推奨ツール

PDB に水素原子がない場合は、pdb2reaction を実行する前に次のいずれかを使ってください。

ツール

コマンド例

備考

reduce (Richardson Lab)

reduce input.pdb > output.pdb

高速、結晶構造に広く使用

pdb2pqr

pdb2pqr --ff=AMBER input.pdb output.pqr

水素を追加し部分電荷を割り当て

Open Babel

obabel input.pdb -O output.pdb -h

汎用ケモインフォマティクスツールキット

複数の PDB 入力で同一の原子順序を確保するには、すべての構造に同じ水素付与ツールを一貫した設定で適用してください。

Warning

このソフトウェアはまだ開発中です。自己責任でご使用ください。

インストール

pdb2reaction は、CUDA 対応 GPU を備えた Linux 環境（ローカルワークステーションまたは HPC クラスター）向けに設計されています。特に PyTorch、fairchem-core (UMA)、gpu4pyscf-cuda12x などの依存関係は、動作する CUDA インストールを前提としています。

詳細は上流プロジェクトを参照してください:

クイックスタート

以下は多くの CUDA 12.9 クラスターで動作する最小限のセットアップ例です。モジュール名やバージョンはお使いの環境に合わせて調整してください。この例はデフォルトの GSM MEP モード（DMF なし）を前提としています。DMF を使用する場合は、先に conda で cyipopt をインストールしてください。

# 1) CUDA 対応の PyTorchビルドをインストール
# 2) GitHubからpdb2reactionをインストール
# 3) Plotly図表エクスポート用のヘッドレスChromeをインストール

pip install torch --index-url https://download.pytorch.org/whl/cu129
pip install git+https://github.com/t-0hmura/pdb2reaction.git
plotly_get_chrome -y

最後に、UMAモデルをダウンロードできるように Hugging Face Hub にログインします:

# Hugging Face CLI
hf auth login --token '<YOUR_ACCESS_TOKEN>' --add-to-git-credential

または

# クラシックCLI
huggingface-cli login

これはマシン/環境ごとに1回だけ行う必要があります。

  • MEP 探索で Direct Max Flux 法を使用する場合は、conda 環境を作成し、pdb2reaction のインストール前に cyipopt をインストールしてください:

    # 専用のconda環境を作成してアクティブ化
conda create -n pdb2reaction python=3.11 -y
conda activate pdb2reaction

# cyipoptをインストール（MEP 探索のDMF法に必要）
conda install -c conda-forge cyipopt -y

  • 環境モジュールを使用するHPC クラスターでは、PyTorchをインストールする前にCUDAをロードしてください:

    module load cuda/12.9

詳細なインストール手順

環境を段階的に構築する場合:

  1. CUDAをロード（HPCで環境モジュールを使用する場合）

    module load cuda/12.9

  2. conda環境を作成してアクティブ化

    conda create -n pdb2reaction python=3.11 -y
conda activate pdb2reaction

  3. cyipoptをインストール MEP 探索でDMF法を使用する場合に必要です。

    conda install -c conda-forge cyipopt -y

  4. 適切なCUDAビルドのPyTorchをインストール

    CUDA 12.9の場合:

    pip install torch --index-url https://download.pytorch.org/whl/cu129

    （クラスターが推奨する場合は別の互換バージョンを使用できます。）

  5. pdb2reaction 本体と可視化用Chromeをインストール

    pip install git+https://github.com/t-0hmura/pdb2reaction.git
plotly_get_chrome -y

  6. Hugging Face Hub (UMAモデル) にログイン

    huggingface-cli login

    参照:

  7. インストールの確認

    pdb2reaction --version

    インストールされたバージョンが表示されます（例: {{ version }}）。

コマンドの基本構成

pip でインストールされる pdb2reaction コマンドが主な起点です。内部的には Click ライブラリを使用しており、デフォルトのサブコマンドは all です。

つまり:

pdb2reaction [OPTIONS] ...
# は以下と同等
pdb2reaction all [OPTIONS] ...

all は、クラスター抽出から MEP 探索、TS 最適化、振動解析、DFT 一点計算までを 1 コマンドで一括実行するサブコマンドです。

クラスター抽出を行う場合、ワークフロー全体で共通の重要オプションが 2 つあります:

  • -i/--input: 1つ以上の完全構造（反応物、中間体、生成物）

  • -c/--center: 基質/抽出中心の定義方法（例: 残基名または残基ID）

--center/-c を省略すると、クラスター抽出はスキップされ、完全な入力構造が直接使用されます。

主要なワークフロー

複数構造MEPワークフロー（反応物 → 生成物）

推定反応座標に沿った複数の完全な PDB 構造（例: R → I1 → I2 → P）がすでにある場合に使用します。

最小例

pdb2reaction -i R.pdb P.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3'

詳細例

pdb2reaction -i R.pdb I1.pdb I2.pdb P.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3' --out-dir ./result_all --tsopt True --thermo True --dft True

処理の流れ:

  • 反応順に並んだ 2 つ以上の完全系を受け取る

  • 各構造から触媒クラスターモデルを抽出

  • デフォルトで path-search による再帰的 MEP 探索を実行（出力は path_search/）

  • --refine-path False を指定するとシングルパス path-opt に切り替え

  • PDB テンプレートがある場合、クラスターモデル MEP を完全系にマージ

  • 必要に応じて各セグメントで TS 最適化、振動解析、DFT 一点計算を実行

ドッキング、MD、手動モデリングなどで中間体を準備できる場合に推奨するモードです。

Important

pdb2reaction は複数の入力 PDB がまったく同じ原子を同じ順序で含むことを前提としています（座標のみが異なる状態）。座標以外のフィールドが入力間で異なる場合はエラーになります。入力 PDB ファイルには水素原子も含まれている必要があります。

単一構造 + 段階的スキャン（MEP 精密化への入力）

1 つの PDB 構造しかないが、反応に沿ってどの原子間距離が変化するかが分かっている場合に使用します。

--scan-lists と一緒に単一の -i を指定します:

最小例

pdb2reaction -i R.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3' --scan-lists '[("TYR 285 CA","MMT 309 C10",2.20),("TYR 285 CB","MMT 309 C11",1.80)]' '[("TYR 285 CB","MMT 309 C11",1.20)]'

詳細例

pdb2reaction -i SINGLE.pdb -c 'SAM,GPP' --scan-lists '[("TYR 285 CA","MMT 309 C10",2.20),("TYR 285 CB","MMT 309 C11",1.80)]' '[("TYR 285 CB","MMT 309 C11",1.20)]' --mult 1 --out-dir ./result_scan_all --tsopt True --thermo True --dft True

補足:

  • --scan-lists は抽出されたクラスターモデルでの段階的距離スキャンを記述

  • 各タプル (i, j, target_Å) は:

    • 'TYR,285,CA' のようなPDB原子セレクター文字列（区切り文字: スペース/カンマ/スラッシュ/バッククォート/バックスラッシュ , / ` \）または1始まりの原子インデックス

    • クラスターモデルのインデックスに自動的に再マッピング

  • 1 つの --scan-lists リテラルで 1 ステージを実行。複数リテラルを渡すと順次ステージとして実行されます。--scan-lists フラグは 1 回だけ指定し、その後に複数リテラルを並べてください（フラグの繰り返しは不可）

  • 各ステージは stage_XX/result.pdb を書き出し、候補中間体または生成物として扱われる

  • デフォルトの all ワークフローは連結されたステージを再帰的 path-search で精密化

  • --refine-path False を使用すると、シングルパス path-opt チェーンを実行し、再帰的精密化をスキップ（マージされた mep_w_ref*.pdb なし）

このモードは単一構造から反応経路を構築するのに便利です。

単一構造 TSOPT のみモード

すでに遷移状態候補があり、それを最適化して IRC 計算を行いたい場合に使用します。

PDB を 1 つだけ指定し、--tsopt を有効にします:

最小例

pdb2reaction -i TS_CANDIDATE.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3' --tsopt True

詳細例

pdb2reaction -i TS_CANDIDATE.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3' --tsopt True --thermo True --dft True --out-dir ./result_tsopt_only

処理の流れ:

  • MEP/経路探索は実行しません。

  • TS 最適化でクラスターモデル上の TS を収束させます。

  • 両方向で IRC を実行し、両端点を最適化して R および P 極小に緩和します。

  • R/TS/P に対して freq と dft を実行できます。

  • UMA、Gibbs、DFT//UMA エネルギーダイアグラムを生成します。

energy_diagram_*_all.png や irc_plot_all.png などの出力は、トップレベルの --out-dir の下にミラーされます。

Important

単一入力実行には --scan-lists（段階的スキャン → GSM）または --tsopt True（TSOPT のみ）のいずれかが必要です。これらのいずれも指定せずに単一の -i のみを渡しても、ワークフローは実行されません。

重要な CLI オプションと動作

以下はワークフロー全体で最もよく使用されるオプションです。

オプション

説明

-i, --input PATH...

入力構造。2 つ以上の PDB → MEP 探索; 1 つの PDB + --scan-lists → 段階的スキャン → GSM; 1 つの PDB + --tsopt True → TSOPT のみモード

-c, --center TEXT

基質/抽出中心を定義。残基名（'SAM,GPP'）、残基ID（A:123,B:456）、または PDB パスをサポート

--ligand-charge TEXT

電荷情報: マッピング（'SAM:1,GPP:-3'）または単一整数

-q, --charge INT

総電荷の強制上書き

-m, --mult INT

スピン多重度（例: シングレットは 1）。注: all 以外のサブコマンドでは --multiplicity を使用してください。

--scan-lists TEXT...

単一入力実行用の段階的距離スキャン

--out-dir PATH

トップレベル出力ディレクトリ

--tsopt {True|False}

TS 最適化と IRC を有効化

--thermo {True|False}

振動解析と熱化学を実行

--dft {True|False}

DFT 一点計算を実行

--refine-path {True|False}

再帰的 MEP 精密化（デフォルト） vs シングルパス

--opt-mode light|heavy

最適化手法: Light (LBFGS/Dimer) または Heavy (RFO/RS-I-RFO)

--mep-mode gsm|dmf

MEP 手法: Growing String Method または Direct Max Flux

--hessian-calc-mode Analytical|FiniteDifference

ヘシアン計算モード。VRAMが十分な場合はAnalytical推奨

すべてのオプションと YAML スキーマについては all および YAML リファレンス を参照してください。

サマリーファイル

pdb2reaction all を実行すると、以下のサマリーファイルが出力されます。

  • summary.log – 人間が読みやすい形式の結果要約

  • summary.yaml – 機械可読な YAML 形式の結果要約

主な記載内容:

  • 実行した CLI コマンド

  • MEP 全体の統計（最大障壁、経路長など）

  • セグメントごとの障壁高さと主要な結合変化

  • UMA、熱化学、DFT 後処理で得られたエネルギー（有効な場合）

path_search/ 配下の各セグメントディレクトリにも summary.log と summary.yaml があり、個別のセグメントの精密化結果を確認できます。

CLI サブコマンド

ほとんどのユーザーは pdb2reaction all を主に使用しますが、pdb2reaction opt などの個別サブコマンドも利用できます。各サブコマンドは -h/--help に対応しています。

サブコマンド

役割

ドキュメント

all

エンドツーエンドワークフロー

all

extract

活性部位ポケット（クラスターモデル）抽出

extract

opt

構造最適化

opt

tsopt

遷移状態最適化

tsopt

path-opt

MEP最適化 (GSM/DMF)

path_opt

path-search

再帰的 MEP 探索

path_search

scan

1D結合長スキャン

scan

scan2d

2D距離スキャン

scan2d

scan3d

3D距離スキャン

scan3d

irc

IRC 計算

irc

freq

振動解析

freq

dft

DFT 一点計算

dft

trj2fig

エネルギープロファイルプロット

trj2fig

energy-diagram

数値から状態エネルギーダイアグラムを描画

energy-diagram

add-elem-info

PDB元素カラム修復

add_elem_info

Important

サブコマンド（all を除く）は、extract で生成されたクラスターモデルを入力として想定しています。クラスターモデルでは、Link-H キャップに最も近い原子が自動的に凍結されます。独自にクラスターモデルを構築する場合は、Link-H の残基名を LKH、原子名を HL に設定するか、--args-yaml → geom.freeze_atoms で凍結する原子を指定してください。

Tip

all、tsopt、freq、irc では、VRAMが十分にある場合は --hessian-calc-mode Analytical を設定することを強く推奨します。

早見表

よく使うコマンドパターン:

# 基本的な MEP 探索（2 構造以上）
pdb2reaction -i R.pdb P.pdb -c 'SUBSTRATE' --ligand-charge 'SUB:-1'

# 後処理付きフルワークフロー
pdb2reaction -i R.pdb P.pdb -c 'SAM,GPP' --ligand-charge 'SAM:1,GPP:-3' \
    --tsopt True --thermo True --dft True

# 単一構造 + 段階的スキャン
pdb2reaction -i SINGLE.pdb -c 'LIG' --scan-lists '[("RES1,100,CA","LIG,200,C1",2.0)]'

# TS のみ最適化
pdb2reaction -i TS.pdb -c 'LIG' --tsopt True --thermo True

主要オプション一覧:

オプション

用途

-i

入力構造

-c

ポケット抽出用の基質定義

--ligand-charge

基質電荷（例: 'SAM:1,GPP:-3'）

--tsopt True

TS 最適化 + IRC を有効化

--thermo True

振動解析を実行

--dft True

DFT 一点計算を実行

--out-dir

出力ディレクトリ

ヘルプ

任意のサブコマンドについて:

pdb2reaction <subcommand> --help

利用可能なオプション、デフォルト値、簡単な説明が表示されます。UMA 計算機の詳細オプションについては UMA 計算機 を参照してください。

問題が発生した場合は、GitHubリポジトリ でIssueを開いてください。