path-opt

pdb2reaction path-opt は ちょうど 2 つの構造間の最小エネルギー経路（MEP）を、GSM（デフォルト）または DMF（--mep-mode dmf）で探索します。経路軌跡を書き出し、最高エネルギー画像（HEI）を TS 候補として出力します。HEI は 候補 に過ぎないため、tsopt（虚振動数チェックを内蔵）→ irc による接続性の確認が必須です。2 つ以上の構造を入力して反応領域だけを自動で精密化したい場合は、path-search を使用してください。

反応物と生成物の 2 端点（R → P）が揃っており、再帰的な精密化なしで MEP の初期推定だけが必要な場面で使用します。ストリングベースの経路生成には GSM（デフォルト）を、Direct Max Flux 生成器には --mep-mode dmf で DMF を選択します。

MLIP バックエンド（デフォルト: UMA、-b/--backend で ORB・MACE・AIMNet2 も選択可能）で MEP image の energy/force を評価します。Hessian は選択された単一構造 optimizer の step だけで使用し、GSM/DMF path scoring では要求しません。最適化の前に剛体アライメントを行い、ストリングの安定性を向上させます。freeze_atoms を指定した場合、RMSD フィットにはその原子群のみを使用しますが、変換自体は全原子に適用されます。

Note

DMF モードでの凍結原子は、GSM で使用される pysisyphus のハード座標凍結ではなく、HarmonicFixAtoms（k=300 eV/Ų の調和拘束）を使用します。そのため、DMF での凍結原子は参照位置からわずかに移動する可能性があり、GSM モードの剛体凍結とは挙動が異なります。

実行例

コマンド形式:

pdb2reaction path-opt -i REACTANT.{pdb|cif|mmcif|xyz|gjf} PRODUCT.{pdb|cif|mmcif|xyz|gjf} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [-m MULT] \
 [-b/--backend uma|orb|mace|aimnet2] \
 [--workers N] [--workers-per-node N] \
 [--mep-mode {gsm|dmf}] [--freeze-links/--no-freeze-links] [--max-nodes N] [--max-cycles-gsm N] [--max-cycles-dmf N] \
 [--climb/--no-climb] [--dump/--no-dump] [--thresh PRESET] [--thresh-gsm PRESET] [--thresh-dmf TOL] \
 [--preopt/--no-preopt] [--preopt-max-cycles N] [--opt-mode grad|hess] [--fix-ends/--no-fix-ends] \
 [--show-config/--no-show-config] [--dry-run/--no-dry-run] \
 [--convert-files/--no-convert-files] [--ref-pdb FILE]

2 端点間の MEP 探索:

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
 --out-dir ./result_path_opt

MEP 探索前に端点を事前最適化する:

# MEP 探索前に端点を事前最適化する
pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
 --preopt --preopt-max-cycles 20000 --out-dir ./result_path_opt_preopt

GSM ではなく DMF モードで実行する:

# GSM ではなく DMF モードで実行する
pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
 --mep-mode dmf --max-nodes 12 --out-dir ./result_path_opt_dmf

Note

DMF モードは追加で cyipopt が必要です（--mep-mode dmf 実行前に conda-forge からインストールしてください）。pydmf は pdb2reaction の依存として同梱されています。デフォルトの --dmf-backend gpu は PyTorch/CUDA の dmf.torch バックエンドを使用します。GPU メモリ不足時は --dmf-backend cpu（dmf/NumPy）を指定してください。

キャップ親原子を凍結し、クライミングを無効化して短時間で確認するには --freeze-links --no-climb を追加します。

処理の流れ

  1. 事前アライメント & 凍結解決

  • 2 番目以降のエンドポイントは最初の構造に対して Kabsch アライメントされます。いずれかのエンドポイントで freeze_atoms が定義されている場合、RMSD フィットにはその原子のみを使用しますが、得られた変換は全原子に適用されます。

  • --freeze-links が有効な場合、キャップ水素の親原子は自動的に凍結されます（キャップ水素と凍結原子 を参照）。

  1. ストリング成長と HEI エクスポート

  • 経路の成長・精密化後、全画像のうちエネルギーが最大の画像を HEI として出力します。HEI が端点の場合は内部の遷移状態候補ではないため、TS 固有の解析前に別途 TS 最適化が必要です。

  • 最高エネルギー画像（HEI）は .xyz として書き込まれます。PDB 参照がある場合は .pdb、Gaussian テンプレートがある場合は .gjf も出力します（いずれも --convert-files の設定に従います）。

出力

out_dir/
├─ final_geometries_trj.xyz # XYZ経路（コメント行にエネルギーを保持）
├─ final_geometries.pdb # PDB 参照が利用可能で変換が有効な場合の全画像 PDB
├─ final_geometries.gjf # GSMのみ: Gaussian template検出時（変換有効時）
├─ hei.xyz # 最高エネルギー画像（コメント行にエネルギーを保持）
├─ hei.pdb # PDB 参照が利用可能な場合のHEI（変換有効時）
├─ hei.gjf # Gaussian テンプレートを使用して書き込まれたHEI（変換有効時）
├─ align_refine/ # 剛体アライメント/リファイン段階の中間ファイル（アライメント実行時）
└─ <オプティマイザダンプ> # `--dump` 指定時の軌跡ダンプ（リスタート YAML は YAML の `dump_restart` 経由のみ）

主要な出力ファイル:

  • result_path_opt/final_geometries_trj.xyz

  • result_path_opt/hei.xyz

  • result_path_opt/hei.pdb（PDB 変換が有効な場合）

コンソールには解決済み YAML ブロックが出力され、GSM/DMF の MEP 進行状況とタイミングが報告されます。

設定の優先順位は CLI 規約: 設定の優先順位 を参照してください。

CLI オプション

完全なフラグ一覧は生成された コマンドリファレンス を参照してください。以下の表は説明が必要なオプションのみを扱い、ここでは重複して記載していません。

オプション

説明

デフォルト

-i, --input PATH PATH

反応物と生成物構造（.pdb/.cif/.mmcif/.xyz/.gjf）。入力は2構造のみ

必須

-q, --charge INT

総電荷（calc.charge）。.gjf 以外では --ligand-charge 導出が成功しない限り必須（PDB/mmCIF 入力または --ref-pdb 付き XYZ/GJF）。.gjf テンプレートがあればそれを使用し、電荷メタデータが無い .gjf 入力は -q が無いと中断。両方指定時は -q が優先。解決順序は CLI 規約: 電荷の指定 を参照

テンプレート/導出がない限り必須

-l, --ligand-charge TEXT

総電荷または残基別マッピング（-q 省略時）。PDB/mmCIF 入力（または --ref-pdb 付き XYZ/GJF）で extract と同じ全系電荷導出を起動します

None

--workers, --workers-per-node

UMA 予測器の並列度（workers_per_node は並列予測器へ転送）。workers > 1 と明示的な解析 Hessian は併用不可。workers > 1 と解析 Hessian は併用できない（UMA バックエンド） を参照

1, 1

-m, --multiplicity INT

スピン多重度（calc.spin）

テンプレート/1

--freeze-links/--no-freeze-links

PDB/mmCIF 入力（または --ref-pdb 付き XYZ/GJF）: キャップ H 親を凍結（YAML とマージ）。詳細は extract を参照

True

--freeze-atoms TEXT

凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: '1,3,5'）。--freeze-links と併用可、任意の入力形式に適用

None

--max-nodes INT

GSM/DMF の可動内部イメージ数。両エンジンとも端点2つを保持するため、総イメージ数は max_nodes + 2

20

--mep-mode {gsm|dmf}

GSM（ストリングベース）または DMF（Direct Max Flux）経路生成器を選択

gsm

--dmf-backend {cpu|gpu}

DMF 計算バックエンド（--mep-mode dmf 時のみ）: gpu（dmf.torch/CUDA）または cpu（dmf/NumPy）。GPU メモリ不足時は cpu で再実行

gpu

--gsm-param {equi|energy}

完全成長後のGSMノード配置。energy は高エネルギー領域へノード密度を寄せる。等間隔経路がHEI近傍の反応座標領域を飛び越える場合の試行用であり、TSを同定する機能ではない

equi

--max-cycles-gsm INT

GSM string optimizer のサイクル上限（stopt.max_cycles と stopt.stop_in_when_full を設定）

300

--max-cycles-dmf INT

DMF の IPOPT 反復上限（dmf.max_cycles を設定）

300

--climb/--no-climb

GSM の climbing-image 精密化を有効化（Lanczos 接線も同時切替）。DMF では受理するが未使用

True

--dump/--no-dump

GSM／単一構造 optimizer の軌跡を dump。DMF path solver では受理するが未使用。restart YAML は YAML で有効化した場合のみ書き出す

False

--opt-mode TEXT

エンドポイント事前最適化用の単一構造オプティマイザ（grad = L-BFGS、hess = RFO）

grad

--convert-files/--no-convert-files

入力トポロジー／テンプレートに応じた XYZ/TRJ → PDB/CIF/GJF companion 生成の切り替え

True

--ref-pdb FILE

XYZ/GJF 入力用の参照 PDB/mmCIF トポロジー（XYZ 座標を保持して変換を有効化）

None

-o, --out-dir TEXT

出力ディレクトリ

./result_path_opt/

--thresh TEXT

エンドポイント事前最適化のみの収束プリセットを上書き（opt.lbfgs/rfo.thresh）

gau

--thresh-gsm TEXT

GSM ストリング最適化（成長およびクライミング精密化）の収束プリセットを上書き（stopt.thresh; gau_loose, gau, gau_tight, gau_vtight, baker, never）

gau_loose

--thresh-dmf TEXT

DMF 最適化の IPOPT dual-infeasibility 許容値を上書き（dmf.tol）。tight(0.04)、middle(0.10)、loose(0.20) または正の float。Gaussian プリセットは受け付けない

tight

--config FILE

明示 CLI 指定より前に適用されるベース YAML

None

--show-config/--no-show-config

解決済み設定（YAML レイヤ情報を含む）を表示して実行継続

False

-b, --backend {uma,orb,mace,aimnet2}

MLIP バックエンド

uma

--dry-run/--no-dry-run

実行せずに検証と実行計画表示のみを行う

False

--preopt/--no-preopt

アライメント/MEP 探索前に各エンドポイントを事前最適化（GSM/DMF）。

True

--preopt-max-cycles INT

エンドポイント事前最適化サイクルの上限

100000

--fix-ends/--no-fix-ends

GSM 成長/精密化中に endpoint 構造を固定。DMF では受理するが未使用

True

--out-json/--no-out-json

out_dir に機械可読な result.json を書き出す。スキーマは JSON 出力スキーマ を参照

False

YAML 設定

path-opt で使用される YAML セクション

完全なキー一覧は YAML リファレンス を参照:

  • geom — PDB/mmCIF トポロジーでは --freeze-links が freeze_atoms にマージされます。

  • calc — MLIP バックエンド設定。

  • gs — Growing String 表現（GSM モード）。

  • dmf — Direct Max Flux + (C)FB-ENM 補間（DMF モード）。

  • stopt — StringOptimizer 設定。

  • opt.lbfgs / opt.rfo — endpoint単一構造事前最適化。CLIで --preopt-max-cycles を明示した場合はYAMLより優先し、省略時はYAML値を使用します。

path-opt 固有のデフォルト

path-opt 経由で実行した場合、以下のキーが正規デフォルトと異なります:

stopt:
 out_dir: ./result_path_opt/ # output directory (path-opt default)
opt:
 lbfgs:
   out_dir: ./result_path_opt/ # output directory (path-opt default)
 rfo:
   out_dir: ./result_path_opt/ # output directory (path-opt default)

終了コード

CLI 規約の 終了コード を参照してください。

関連項目

  • path-search — 自動精密化を伴う再帰的 MEP 探索（2+構造用）

  • tsopt — HEI を TS 候補として最適化（内部で虚振動数チェック済み）。続けて IRC で接続性を確認

  • extract — path-opt 入力用の活性部位モデル PDB を生成

  • all — 一気通貫ワークフロー（デフォルトで単一パス path-opt を使用; --refine-path で再帰的 path-search に切替。--refine-path フラグは pdb2reaction all にのみ属します — 定義は MEP 探索オプション を参照してください）

  • YAML リファレンス — gs、dmf、stopt、opt の完全な設定オプション

  • 用語集 — MEP、GSM、DMF、HEI の定義

  • 典型エラー別レシピ — 症状起点の切り分け

  • トラブルシューティング — 詳細な対処ガイド