path-search

概要

要約: 2 構造以上から、GSM（デフォルト）または DMF（--mep-mode dmf）で連続的な MEP を構築します。共有結合変化のある領域のみを自動で精密化し、最高エネルギー画像（HEI）を TS 候補として出力します（tsopt + IRC で検証）。

要点

• 想定場面: R → … → P のように 2 構造以上を入力として、自動精密化を含めた連続 MEP を構築したい場合に使います。

• 手法: GSM/DMF セグメントを連鎖し、結合変化が残る区間だけを再帰的に精密化します。

• 主な出力: mep_trj.xyz（主軌跡）、summary.json（セグメントごとの結果）、必要に応じてプロットやマージ済み PDB。

• デフォルト値: --mep-mode gsm、--opt-mode grad（LBFGS）、--no-preopt、--align、--thresh gau、--thresh-stopt gau_loose。

• 次にやること: HEI は TS 候補であり、単独では TS 検証になりません。続けて tsopt（内部で虚振動数チェック済み）→ irc を実行してください。

pdb2reaction path-search は反応順に並んだ 2 構造以上を入力とし、連続的な最小エネルギー経路（MEP）を構築します。共有結合変化が検出される領域のみを選択的に精密化し、解決済みのサブパスを連結して 1 本の軌跡にまとめます。

--convert-files が有効（デフォルト）な場合、参照 PDB があれば軌跡の .pdb コンパニオンを、Gaussian テンプレートがあれば HEI スナップショットの .gjf コンパニオンを生成します。XYZ/GJF 入力では --ref-pdb が活性部位モデル（バインディングポケット） PDB トポロジーを提供し（XYZ 座標は保持）、--ref-full-pdb によりフルテンプレートへのマージが可能です（XYZ/GJF 入力では PDB コンパニオンは生成されません）。

再帰的分解により多段階反応を自動検出し、各素反応ステップの詳細な MEP を構築します。ただし、複雑な多段階反応の検出は困難な場合があり、入力中間体やスキャン仕様、収束閾値の調整など手動での試行錯誤が必要になることがあります。

2 端点だけで再帰精密化が不要な場合は、path-opt の方がシンプルです。

最小例

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

出力の見方

• result_path_search/mep_trj.xyz

• result_path_search/summary.json

• result_path_search/summary.log

• result_path_search/mep_plot.png（プロット生成時）

よくある例

1. 中間体を明示して多段の経路を与える。

pdb2reaction path-search -i R.pdb IM1.pdb IM2.pdb P.pdb -q -1 -m 1 \
 --out-dir ./result_path_search_multi

2. テンプレート参照を使って全系マージ出力を有効化する。

pdb2reaction path-search -i R.pdb IM1.pdb P.pdb -q 0 -m 1 \
 --ref-full-pdb holo_template.pdb --out-dir ./result_path_search_merge

3. DMF + minima リファインで探索する。

pdb2reaction path-search -i reactant.pdb product.pdb -q 0 -m 1 \
 --mep-mode dmf --refine-mode minima --out-dir ./result_path_search_dmf

使用法

pdb2reaction path-search -i R.pdb [I.pdb ...] P.pdb [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [--multiplicity 2S+1] \
 [-b/--backend uma|orb|mace|aimnet2] [--solvent SOLVENT] [--solvent-model alpb|cpcmx] \
 [--workers N] [--workers-per-node N] \
 [--mep-mode {gsm|dmf}] [--freeze-links/--no-freeze-links] [--thresh PRESET] [--thresh-stopt PRESET] \
 [--refine-mode {peak|minima}] \
 [--max-nodes N] [--max-cycles N] [--climb/--no-climb] \
 [--opt-mode grad|hess] [--dump/--no-dump] \
 [--out-dir DIR] [--preopt/--no-preopt] \
 [--align/--no-align] [--ref-full-pdb FILE...] [--ref-pdb FILE...] \
 [--convert-files/--no-convert-files] \
 [--show-config/--no-show-config] [--dry-run/--no-dry-run]

例

• 活性部位モデルのみの2つのエンドポイント間のMEP:

  pdb2reaction path-search -i reactant.pdb product.pdb -q 0
  

• YAML 上書きとマージされた全系出力を使用したマルチステップ探索:

  pdb2reaction path-search \
  -i R.pdb IM1.pdb IM2.pdb P.pdb -q -1 \
  --ref-full-pdb holo_template.pdb --out-dir ./run_ps
  

CLI オプション

オプション	説明	デフォルト
-i, --input PATH...	反応順序の2つ以上の構造（反応物 → 生成物）。すべてのファイルを単一の -i/--input の後ろに並べて指定	必須
-q, --charge INT	総電荷。非.gjf入力では --ligand-charge の導出が成功しない限り必須。両方指定時は -q が優先	テンプレート/導出が適用されない限り必須
-l, --ligand-charge TEXT	残基別電荷マッピング（例: GPP:-3,SAM:1）。PDB の残基電荷から全系の電荷を自動導出します（手動計算不要）。-q 省略時に使用（PDB 入力、または --ref-pdb 付き XYZ/GJF）	None
--workers, --workers-per-node	UMA予測器の並列度（workers > 1 で解析ヘシアン無効; workers_per_node は並列予測器に渡されます）。診断上の注意は workers > 1 による暗黙的な FD ダウングレード を参照。	1, 1
-m, --multiplicity INT	スピン多重度（2S+1）	.gjf テンプレート値または 1
--freeze-links/--no-freeze-links	PDB 活性部位モデル読み込み時、リンク水素の親原子を凍結。詳細は extract を参照	True
--freeze-atoms TEXT	凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: '1,3,5'）。--freeze-links と併用可、任意の入力形式に適用。	None
--max-nodes INT	MEPセグメントごとの内部ノード	20
--max-cycles INT	最大MEP最適化サイクル（GSM/DMF）	300
--climb/--no-climb	GSMセグメントのクライミングイメージを有効化（ブリッジは無効）	True
--opt-mode TEXT	HEI±1/ねじれノード用の単一構造オプティマイザー（grad=LBFGS、hess=RFO）。同じトークンが tsopt では Dimer / RS-I-RFO へ対応する点については --opt-mode（サブコマンド依存） を参照してください。	grad
--mep-mode {gsm|dmf}	セグメント生成器: GSM（string）またはDMF（direct flux）	gsm
--refine-mode {peak|minima}	精密化シード: peak はHEI±1、minima はHEIから最寄り局所極小点へ外側探索。未指定時はGSMでpeak、DMFでminima	Auto
--dump/--no-dump	MEP（GSM/DMF）と単一構造軌跡/リスタートをダンプ	False
--convert-files/--no-convert-files	PDB/Gaussian入力のXYZ/TRJ → PDB/GJFコンパニオンを切り替え	True
-o, --out-dir TEXT	出力ディレクトリ	./result_path_search/
--thresh TEXT	単一構造最適化のみの収束プリセットを上書き（opt.lbfgs/rfo.thresh）	gau
--thresh-stopt TEXT	ストリングオプティマイザーの収束プリセットを上書き（stopt.thresh）	gau_loose
--config FILE	明示 CLI 指定より前に適用されるベース YAML	None
--show-config/--no-show-config	解決済み設定（YAML レイヤ情報を含む）を表示して実行継続	False
-b, --backend {uma,orb,mace,aimnet2}	MLIP バックエンド	uma
--solvent TEXT	xTB 暗黙溶媒（例: water）。none で無効化	none
--solvent-model {alpb,cpcmx}	xTB 溶媒モデル	alpb
--dry-run/--no-dry-run	実行せずに検証と実行計画表示のみを行う。	False
--preopt/--no-preopt	MEP 探索前に各エンドポイントを事前最適化。スコープ依存デフォルト: 単体の path-search では False、pdb2reaction all 経由では True に反転されます（MEP 探索オプション を参照）。	False
--align/--no-align	探索前にすべての入力を最初の構造にアライメント	True
--ref-full-pdb PATH...	フルサイズテンプレート PDB（--align があれば先頭のみ再利用可）	None
--ref-pdb PATH...	入力がXYZ/GJFの場合の活性部位モデル参照 PDB（XYZ 座標は保持）	None

ワークフロー

1. ペアごとの初期セグメント（GSM/DMF） – 各隣接入力（A→B）間で GrowingString または DMF を実行し、粗いMEPと最高エネルギー画像（HEI）を取得。

2. HEI周辺の局所緩和 – refine-mode=peak なら HEI±1、refine-mode=minima なら HEI 近傍の局所極小点を、選択した単一構造オプティマイザー（opt-mode）で精密化し End1/End2 を得る。

3. ねじれ vs. 精密化の決定 – End1 と End2 間に共有結合変化がなければ ねじれ（kink: 共有結合変化を伴わない構造変化区間）とみなし、search.kink_max_nodes の線形ノードを挿入して個別最適化。結合変化がある場合は 反応セグメント（共有結合変化を伴う区間に対して GSM/DMF で精密化するセグメント）を起動。

4. 選択的再帰 – (A→End1) と (End2→B) の結合変化を bond しきい値で比較し、共有結合更新が残るサブ区間のみ再帰的に探索。再帰深度は search.max_depth で制限。

5. スティッチング & ブリッジング – 解決済みのサブパスを連結し、RMSD ≤ search.stitch_rmsd_thresh の重複エンドポイントを除去。RMSDギャップが search.bridge_rmsd_thresh を超える場合はブリッジセグメント（隣接するサブパス間の RMSD ギャップを埋めるために挿入される補間 MEP）を挿入。境界で結合変化が検出される場合はブリッジではなく新規の再帰セグメントで置換。

6. アライメント & マージング（オプション） – --align（デフォルト）で事前最適化構造を先頭入力へ剛体アライメントし、freeze_atoms を整合。--ref-full-pdb を指定すると活性部位モデル軌跡をフルサイズPDB テンプレートへマージ（--align により先頭テンプレートの再利用が可能）。

結合変化の判定は bond_changes.compare_structures を用い、bond セクションのしきい値に従います。MLIP バックエンド（デフォルト: UMA）は全構造で共有・再利用されます。

出力

out_dir/ (デフォルト:./result_path_search/)
├─ mep_trj.xyz # 主要 MEP 軌跡
├─ mep.pdb # 入力がPDB テンプレートで変換が有効な場合のPDB コンパニオン
├─ mep_w_ref.pdb # マージされた全系MEP（参照 PDB/テンプレートが必要）
├─ mep_w_ref_seg_XX.pdb # 共有結合変化がある場合のマージされたセグメントごとのパス
├─ summary.json # すべての再帰セグメントの障壁と分類サマリー
├─ summary.log # 結果要約
├─ mep_plot.png # ΔEプロファイル（kcal/mol、反応物基準）
├─ energy_diagram_MEP.png # MEP状態エネルギーダイアグラムの静的エクスポート
└─ seg_000_*/ # セグメントごとの GSM/DMF ダンプ、HEI スナップショット、kink/精密化の診断情報

• コンソールには確定済みの設定ブロック（geom, calc, gs, stopt, opt.*, bond, search）が出力されます。

注意事項

• 症状起点で切り分ける場合は 典型エラー別レシピ を先に参照し、詳細は トラブルシューティング を確認してください。

• 入力は2つ以上が必須。満たさない場合、-i/--input の “invalid value” エラーで終了します。

• 複数テンプレートを渡す場合は --ref-full-pdb をファイルごとに繰り返して指定します。--align が有効な場合、マージでは先頭テンプレートのみが再利用されます。

• MLIP バックエンド（デフォルト: UMA）は全構造で共有・再利用されます。

• --dump が有効な場合、MEP（GSM/DMF）と単一構造最適化の軌跡が出力されます。リスタート YAML は YAML で dump_restart を有効にした場合のみ書き出されます。

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

YAML ルートはマッピングでなければなりません。共通セクションは YAML リファレンス を再利用します: geom/calc は単一構造設定を反映し（--freeze-links については リンク水素と凍結原子 を参照）、stopt は path-opt（path-opt.md）に記載の StringOptimizer 設定を継承します。

Note

リファレンスの重複について。 以下の geom, calc, gs, dmf, stopt, opt.lbfgs, opt.rfo が YAML リファレンス と食い違った場合は YAML リファレンス と pdb2reaction/defaults.py を正とします。

gs（Growing String）は pdb2reaction.path_opt.GS_KW のデフォルト値を継承し、max_nodes（セグメント内部ノード）、クライミング設定（climb, climb_rms, climb_fixed）、再パラメータ化（reparam_every_full, reparam_check）を上書きできます。

opt は HEI±1 と kink ノードに使う単一構造オプティマイザーで、lbfgs と rfo に分かれます。各サブセクションは YAML リファレンス と同じキーを持ちますが、デフォルトは out_dir: ./result_path_search/、dump: False です。

bond は UMA ベースの結合変化検出パラメータで、scan の bond セクションと共通の device, bond_factor, margin_fraction, delta_fraction を持ちます。

dmf は --mep-mode dmf 選択時に適用される Direct Max Flux + (C)FB-ENM の設定です。デフォルト値は DMF_KW を踏襲し、実行ごとに上書きできます。

path-search 固有の上書き

geom, calc, gs, dmf, stopt, opt.lbfgs, opt.rfo の全キーは YAML リファレンス を参照してください。以下のデフォルトは out_dir のみが各セクションの正準デフォルトと異なり、./result_path_search/ を指します:

stopt:
 out_dir: ./result_path_search/ # path-search 上書き（正準デフォルト: ./result_path_opt/）
opt:
 lbfgs:
   out_dir: ./result_path_search/ # path-search 上書き（正準デフォルト: ./result_opt/）
 rfo:
   out_dir: ./result_path_search/ # path-search 上書き（正準デフォルト: ./result_opt/）

bond と search は path-search の再帰ロジックの中核であるため、ここに残します:

bond:
 device: auto # MLIP device for bond analysis
 bond_factor: 1.2 # covalent-radius scaling
 margin_fraction: 0.05 # tolerance margin for comparisons
 delta_fraction: 0.05 # minimum relative change to flag bonds
search:
 max_depth: 10 # recursion depth limit
 stitch_rmsd_thresh: 0.0001 # RMSD threshold for stitching segments
 bridge_rmsd_thresh: 0.0001 # RMSD threshold for bridging nodes
 max_nodes_segment: 10 # max nodes per segment
 max_nodes_bridge: 5 # max nodes per bridge
 kink_max_nodes: 3 # max nodes for kink optimizations
 max_seq_kink: 2 # max sequential kinks
 refine_mode: null # optional refinement strategy (auto-chooses when null)

---

関連項目

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

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

• path-opt — 単一パスMEP最適化（再帰的精密化なし）

• tsopt — HEIを遷移状態として最適化

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

• all — 一気通貫ワークフロー（デフォルトで再帰的 path-search を使用; --refine-path False で path-opt に切替）

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

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