path-search¶
R → … → P の 2 構造以上から、連続的な最小エネルギー経路（MEP）を構築します。自動精密化を含む連続 MEP を 1 本の軌跡にまとめたい場面で使用します。2 端点だけで再帰精密化が不要な場合は、path-opt の方がシンプルです。
経路は 2 つのエンジンのいずれかで生成します。GSM（デフォルト、--mep-mode gsm、string ベース）か、DMF（--mep-mode dmf、direct flux）です。共有結合変化が検出される領域のみを選択的に精密化します（--refine-mode peak は HEI±1 を最適化、--refine-mode minima は最寄り局所極小点へ外側探索、デフォルトは GSM で peak、DMF で minima）。解決済みのサブパスを連結して 1 本の軌跡にまとめ、各セグメントの最高エネルギー画像（HEI）を TS 候補として出力します（tsopt + IRC で検証）。
再帰的分解は結合変化の情報を使い、多段階反応の候補となるより狭い反応セグメントを提案します。これは幾何構造に基づくヒューリスティクであり、各セグメントが 1 つの素反応または 1 つの TS を含むことを証明しません。各 HEI を tsopt、虚振動 1 本の確認、IRC 接続性で必ず検証してください。複雑な機構では、入力中間体、スキャン仕様、収束閾値の手動調整が必要な場合があります。
実行例¶
コマンド形式:
pdb2reaction path-search -i R.pdb [-i I.pdb ...] -i P.pdb [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [--multiplicity 2S+1] \
[-b/--backend uma|orb|mace|aimnet2] \
[--workers N] [--workers-per-node N] \
[--mep-mode {gsm|dmf}] [--freeze-links/--no-freeze-links] [--thresh PRESET] [--thresh-gsm PRESET] [--thresh-dmf TOL] \
[--refine-mode {peak|minima}] \
[--max-nodes N] [--max-cycles-gsm N] [--max-cycles-dmf N] [--climb/--no-climb] \
[--opt-mode grad|hess] [--dump/--no-dump] \
[--out-dir DIR] [--preopt/--no-preopt] \
[--align/--no-align] [--write-ref-merge/--no-write-ref-merge] [--ref-full-pdb FILE...] [--ref-pdb FILE...] \
[--convert-files/--no-convert-files] \
[--show-config/--no-show-config] [--dry-run/--no-dry-run]
2 端点（反応物 → 生成物）:
pdb2reaction path-search -i reactant.pdb -i product.pdb -q 0 -m 1 \
--out-dir ./result_path_search
中間体を明示して多段の経路を与える:
# 中間体を明示して多段の経路を与える
pdb2reaction path-search -i R.pdb -i IM1.pdb -i IM2.pdb -i P.pdb -q -1 -m 1 \
--out-dir ./result_path_search_multi
アライメント済みの静的テンプレートを使って確認用の全系座標compositeを生成する:
# 活性部位経路を可視化用の静的テンプレートへ挿入する
pdb2reaction path-search -i R.pdb -i IM1.pdb -i P.pdb -q 0 -m 1 \
--write-ref-merge --ref-full-pdb holo_template.pdb \
--out-dir ./result_path_search_merge
mep_w_ref* / hei_w_ref* は、--write-ref-merge、--ref-full-pdb、
--align がすべて有効な場合だけ生成します。
DMF + minima 精密化で探索する:
# DMF + minima 精密化で探索する
pdb2reaction path-search -i reactant.pdb -i product.pdb -q 0 -m 1 \
--mep-mode dmf --refine-mode minima --out-dir ./result_path_search_dmf
処理の流れ¶
ペアごとの初期セグメント（GSM/DMF） – 各隣接入力（A→B）間で
GrowingStringまたは DMF を実行し、粗い MEP と最高エネルギー画像（HEI）を取得。HEI 周辺の局所緩和 –
refine-mode=peakなら HEI±1、refine-mode=minimaなら HEI 近傍の局所極小点を、選択した単一構造オプティマイザ（opt-mode）で精密化しEnd1/End2を得る。デフォルト:
--refine-mode省略時は GSM ではpeak、DMF ではminimaが選択されます。ねじれ vs. 精密化の決定 –
End1とEnd2間に共有結合変化がなければ ねじれ（kink: 共有結合変化を伴わない構造変化区間。用語集 参照）とみなし、search.kink_max_nodesの線形ノードを挿入して個別最適化。結合変化がある場合は 反応セグメント（端点間に共有結合変化が検出される区間。用語集 参照）として扱い、End1とEnd2間に 精密化セグメント (GSM/DMF) を起動して障壁を先鋭化。選択的再帰 –
(A→End1)と(End2→B)の結合変化をbondしきい値で比較し、共有結合更新が残るサブ区間のみ再帰的に探索。再帰深度はsearch.max_depthで制限。スティッチング & ブリッジング – 解決済みのサブパスを連結し、RMSD ≤
search.stitch_rmsd_threshの重複エンドポイントを除去。RMSD ギャップがsearch.bridge_rmsd_threshを超える場合は ブリッジセグメント（非隣接の中間体間を接続するセグメント。用語集 参照）を GSM/DMF で挿入。境界で結合変化が検出される場合はブリッジではなく新規の再帰セグメントで置換。アライメント & 確認用座標マージ（オプション） –
--align（デフォルト）で事前最適化構造を先頭入力へ剛体アライメントし、freeze_atomsを整合。--write-ref-mergeと--ref-full-pdbを指定すると確認用の座標compositeを生成します。
結合変化の判定は bond_changes.compare_structures を用い、bond セクションのしきい値に従います。MLIP バックエンドは全構造で共有・再利用されます。
出力¶
out_dir/ (デフォルト:./result_path_search/)
├─ mep_trj.xyz # 主要 MEP 軌跡
├─ mep.pdb # PDB/mmCIF topology入力で変換有効時
├─ mep.cif # mmCIF/oversized-PDB入力。元IDを復元
├─ mep.gjf # Gaussian テンプレート検出時に対応する Gaussian
├─ mep_w_ref.pdb # 静的全系テンプレートへ活性部位経路を挿入（--write-ref-merge）
├─ mep_w_ref.cif # 確認用bridge-template companion（--write-ref-merge）
├─ mep_seg_XX_trj.xyz # reactive refinement segmentのみ: MEP軌跡（XYZ）
├─ mep_seg_XX.pdb # reactive refinement segmentのPDB（変換有効時）
├─ mep_seg_XX.cif # reactive refinement segmentのbridge入力CIF
├─ mep_seg_XX.gjf # reactive refinement segmentのGaussian（template検出時）
├─ mep_w_ref_seg_XX.pdb # 確認用のsegment別座標composite
├─ mep_w_ref_seg_XX.cif # 確認用bridge-template companion
├─ hei_seg_XX.xyz # reactive refinement segmentのみ: 最高エネルギーimage
├─ hei_seg_XX.pdb # reactive refinement segmentのHEI PDB（変換有効時）
├─ hei_seg_XX.cif # reactive refinement segmentのHEI CIF
├─ hei_seg_XX.gjf # reactive refinement segmentのHEI Gaussian（template検出時）
├─ hei_mode_seg_XX.txt # reactive refinement segmentのenergy-upwinding接線
├─ hei_w_ref_seg_XX.pdb # 確認用HEI座標composite
├─ hei_w_ref_seg_XX.cif # 確認用HEI bridge-template companion
├─ summary.json # すべての再帰セグメントの障壁と分類サマリー
├─ summary.log # 結果要約
├─ mep_plot.png # `trj2fig` で生成した ΔE プロファイル（kcal/mol、反応物基準）
├─ energy_diagram_MEP.png # MEP 状態エネルギーダイアグラムの静止画出力（反応物基準）
└─ seg_NNN_*/ # セグメントごとの GSM/DMF ダンプ、HEI スナップショット、kink/精密化の診断情報
結果は通常、次のファイルを開いて確認します。
result_path_search/mep_trj.xyzresult_path_search/summary.jsonresult_path_search/summary.logresult_path_search/mep_plot.png（プロット生成時）コンソールには確定済みの設定ブロック（
geom,calc,gs,stopt,opt.*,bond,search）が出力されます。詳細は ログ詳細度 (verbosity) を参照してください。
CLI オプション¶
完全なフラグ一覧は生成された コマンドリファレンス を参照してください。以下の表は説明が必要なオプションのみを扱います。
表は目的ごとにグループ化しており、各グループ内では使用頻度の高いオプションを先に並べています。
オプション |
説明 |
デフォルト |
|---|---|---|
入力と電荷 |
||
|
反応順序の 2 つ以上の構造（反応物 → 生成物）。各ファイルごとに |
必須 |
|
総電荷。非 |
テンプレート/導出が適用されない限り必須 |
|
単一整数または残基別 mapping から PDB/mmCIF input topology の全系電荷を導出。裸の XYZ には |
None |
|
スピン多重度（2S+1） |
|
バックエンドと計算 |
||
|
MLIP バックエンド |
|
|
UMA 予測器の並列度（ |
|
活性領域の凍結 |
||
|
PDB 活性部位モデル読み込み時、キャップ水素の親原子を凍結。詳細は extract を参照 |
|
|
凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: |
None |
MEP 探索 |
||
|
セグメント生成器: GSM（string）または DMF（direct flux） |
|
|
DMF 計算バックエンド（ |
|
|
選択された単一構造オプティマイザ（L-BFGS/RFO）で MEP 探索前に各エンドポイントを事前最適化。 |
|
|
MEP セグメントごとの内部ノード（GSM string image または DMF image） |
|
|
完全成長後のGSMノード配置。 |
|
|
GSM string optimizer の最大サイクル数 |
|
|
DMF の最大 IPOPT 反復数 |
|
|
GSM セグメントのクライミングイメージを有効化（ブリッジは無効） |
|
精密化 |
||
|
精密化シード: |
Auto |
|
HEI±1/ねじれノード用の単一構造オプティマイザ（ |
|
収束閾値 |
||
|
単一構造最適化のみの収束プリセットを上書き（ |
|
|
GSM ストリング最適化の収束プリセットを上書き（ |
|
|
DMF 最適化の IPOPT dual-infeasibility 許容値を上書き（ |
|
マージとアライメント |
||
|
探索前にすべての入力を最初の構造にアライメント |
|
|
確認用の |
|
|
確認用の座標マージに使う静的全系 PDB/mmCIFテンプレート。 |
None |
|
XYZ/GJF入力の全系マージに使うactive-site PDB/mmCIF参照（入力と同数・同順） |
None |
出力と設定 |
||
|
出力ディレクトリ |
|
|
GSM と単一構造 optimizer の軌跡を dump。DMF path solver では受理するが未使用。restart YAML は YAML で有効化した場合のみ書き出す |
|
|
XYZ/TRJ → PDB/CIF/GJFを切り替え。bridge入力は元IDのCIFを追加し、XYZ/GJFは参照topologyなしではPDBを生成しません。 |
|
|
明示 CLI 指定より前に適用されるベース YAML |
None |
|
解決済み設定（YAML レイヤ情報を含む）を表示して実行継続 |
|
|
実行せずに検証と実行計画表示のみを行う |
|
設定の優先順位は CLI 規約: 設定の優先順位 を参照してください。
YAML 設定¶
YAML ルートはマッピングでなければなりません。共通セクションは YAML リファレンス を再利用します: geom/calc は単一構造設定を反映し（PDB/mmCIF トポロジーでは --freeze-links が geom.freeze_atoms を補強します。詳細は キャップ水素と凍結原子 を参照）、stopt は path-opt（path-opt.md）に記載の StringOptimizer 設定を継承します。
bond と search は path-search の再帰ロジックの中核であり、ここで詳述します。gs、dmf、stopt、opt.lbfgs、opt.rfo は path-search 固有の out_dir 上書きのみ再掲します。
bond は MLIP ベースの結合変化検出パラメータで、scan の bond セクションと共通の device, bond_factor, margin_fraction, delta_fraction を持ちます。
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:
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: 20 # 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)
注記¶
入力は 2 つ以上が必須。満たさない場合、
-i/--inputの “invalid value” エラーで終了します。
関連項目¶
典型エラー別レシピ — 症状起点の切り分け
トラブルシューティング — 詳細な対処ガイド
path-opt — 単一パス MEP 最適化（再帰的精密化なし）
tsopt — HEI を遷移状態として最適化
extract — path-search 入力用の活性部位モデル PDB を生成
all — 一気通貫ワークフロー（デフォルトで単一パス path-opt を使用;
--refine-pathで再帰的 path-search に切替）YAML リファレンス —
gs、dmf、bond、searchの完全な設定オプション用語集 — MEP、GSM、DMF、HEI の定義