path-opt¶
概要¶
要約: 2 つの構造（R → P）から、GSM（デフォルト）または DMF（
--mep-mode dmf）で MEP を最適化します。経路軌跡を書き出し、最高エネルギー画像（HEI）を TS 候補として出力します。
要点¶
想定場面: 反応物と生成物の 2 端点が揃っていて、まず MEP の初期推定を得たい場合に使います。
手法: デフォルトは GSM。
--mep-mode dmfで DMF に切り替え可能。主な出力:
final_geometries_trj.xyz（経路）とhei.xyz（HEI）。変換が有効なら.pdb/.gjfコンパニオンも生成。デフォルト値:
--opt-mode grad（LBFGS）、--climb、--max-nodes 20、--thresh gau、--thresh-stopt gau_loose。次にやること: HEI は TS 候補です。
tsopt（内部で虚振動数チェック済み、1 つ であること）→ircで検証します。
pdb2reaction path-opt は 2 端点間の最小エネルギー経路（MEP）を探索し、最高エネルギー画像（HEI）を報告します。HEI は 候補 に過ぎないため、tsopt（内部で虚振動数チェック済み）→ irc による接続性の確認が必須です。2 つ以上の構造を入力して反応領域だけを自動で精密化したい場合は、path-search を使用してください。
path-optとpath-searchの使い分け: 端点が 2 構造だけで再帰精密化が不要な場合はpath-optを使います。2 構造以上を入力し、結合変化のある領域を自動で再帰精密化したい場合はpath-searchを使います。
MLIP バックエンド（デフォルト: UMA、-b/--backend で ORB・MACE・AIMNet2 も選択可能）で各イメージのエネルギー/勾配/ヘシアンを評価します。最適化の前に剛体アライメントを行い、ストリングの安定性を向上させます。freeze_atoms を指定した場合、RMSD フィットにはその原子群のみを使用しますが、変換自体は全原子に適用されます。
Note
DMF モードでの凍結原子は、GSM で使用される pysisyphus のハード座標凍結ではなく、HarmonicFixAtoms（k=300 eV/Ų の調和拘束）を使用します。そのため、DMF での凍結原子は参照位置からわずかに移動する可能性があり、GSM モードの剛体凍結とは挙動が異なります。
最小例¶
pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
--out-dir ./result_path_opt
出力の見方¶
result_path_opt/final_geometries_trj.xyzresult_path_opt/hei.xyzresult_path_opt/hei.pdb（PDB 変換が有効な場合）
よくある例¶
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 モードで実行する。
pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
--mep-mode dmf --max-nodes 12 --out-dir ./result_path_opt_dmf
リンク親原子を凍結し、climb を切って短時間で確認する。
pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
--freeze-links --no-climb --out-dir ./result_path_opt_fast
使用法¶
pdb2reaction path-opt -i REACTANT.{pdb|xyz} PRODUCT.{pdb|xyz} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [-m MULT] \
[-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] [--max-nodes N] [--max-cycles N] \
[--climb/--no-climb] [--dump/--no-dump] [--thresh PRESET] [--thresh-stopt PRESET] \
[--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 番目以降のエンドポイントは最初の構造に対して Kabsch アライメントされます。いずれかのエンドポイントで
freeze_atomsが定義されている場合、RMSD フィットにはその原子のみを使用しますが、得られた変換は全原子に適用されます。--freeze-linksが有効な場合、リンク水素の親原子は自動的に凍結されます（リンク水素と凍結原子 を参照）。
ストリング成長とHEIエクスポート
経路の成長・精密化後、内部ノード間の局所極大のうちエネルギーが最も高いものを優先的に選択します。内部の局所極大がない場合は内部ノードの最大値に、内部ノードもない場合は全体の最大値にフォールバックします。
最高エネルギー画像（HEI）は
.xyzとして書き込まれます。PDB 参照がある場合は.pdb、Gaussian テンプレートがある場合は.gjfも出力します（いずれも--convert-filesの設定に従います）。
主要な挙動¶
エンドポイント: 入力は2構造のみ。形式は
geom_loaderに準拠。PDB 入力（または--ref-pdb付きXYZ/GJF）で軌跡/HEIのPDB 出力が有効。電荷/スピン: 電荷の解決順序の詳細は CLI 規約: 電荷の指定 を参照してください。
MEPセグメント:
--max-nodesは内部ノード数を制御します。GSM の場合、総画像数はmax_nodes + 2（固定端点を含む）。DMF の場合、max_nodesはチェーン上の移動可能なイメージ数です。GSM成長およびクライミング精密化の収束プリセットは--thresh-stoptまたはstopt.thresh（gau_loose,gau,gau_tight,gau_vtight,baker,never）で指定します。エンドポイント事前最適化:
--threshは--opt-modeで選ばれた単一構造最適化（opt.lbfgs.thresh/opt.rfo.thresh）のみに適用されます。クライミングイメージ:
--climbは標準のクライミング手順とLanczos接線リファインの両方を切り替え。ダンプ:
--dumpで StringOptimizer のstopt.dump=Trueに対応し、out_dir内に軌跡ダンプを出力します。リスタート YAML は YAML で有効化した場合のみ書き出されます。終了コード: 終了コードは CLI 規約の 終了コード を参照。
CLI オプション¶
オプション |
説明 |
デフォルト |
|---|---|---|
|
反応物と生成物構造 |
必須 |
|
総電荷（ |
テンプレート/導出がない限り必須 |
|
残基別電荷マッピング（例: |
None |
|
UMA予測器の並列度（workers > 1 で解析ヘシアン無効; |
|
|
スピン多重度 |
テンプレート/ |
|
PDBのみ: リンクH親を凍結（YAMLとマージ）。詳細は extract を参照 |
|
|
凍結する原子の 1 始まりインデックスをカンマ区切りで明示的に指定（例: |
None |
|
内部ノード数。GSM: 総イメージ数 = |
|
|
GSM（ストリングベース）またはDMF（ダイレクトフラックス）経路生成器を選択 |
|
|
オプティマイザーマクロイテレーション上限 |
|
|
クライミングイメージ精密化を有効化 |
|
|
MEP軌跡/リスタートをダンプ |
|
|
エンドポイント事前最適化用の単一構造オプティマイザー（ |
|
|
PDB/Gaussian入力用のXYZ/TRJ → PDB/GJFコンパニオン出力の切り替え |
|
|
XYZ/GJF 入力用の参照 PDB トポロジー（XYZ 座標は保持し PDB 変換を有効化） |
None |
|
出力ディレクトリ |
|
|
エンドポイント事前最適化のみの収束プリセットを上書き（ |
|
|
ストリングオプティマイザーの収束プリセットを上書き（ |
|
|
明示 CLI 指定より前に適用されるベース YAML |
None |
|
解決済み設定（YAML レイヤ情報を含む）を表示して実行継続 |
|
|
MLIP バックエンド |
|
|
xTB 暗黙溶媒（例: |
|
|
xTB 溶媒モデル |
|
|
実行せずに検証と実行計画表示のみを行う。 |
|
|
アライメント/MEP 探索前に各エンドポイントを事前最適化（GSM/DMF）。スコープ依存デフォルト: 単体の |
|
|
エンドポイント事前最適化サイクルの上限 |
|
|
GSM成長/精密化中にエンドポイント構造を固定 |
|
|
|
|
出力¶
out_dir/
├─ final_geometries_trj.xyz # XYZ経路（コメント行にエネルギーを保持）
├─ final_geometries_trj.pdb # PDB 参照が利用可能で変換が有効な場合
├─ hei.xyz # 最高エネルギー画像
├─ hei.pdb # PDB 参照が利用可能な場合のHEI（変換有効時）
├─ hei.gjf # Gaussian テンプレートを使用して書き込まれたHEI（変換有効時）
├─ align_refine/ # 剛体アライメント/リファイン段階の中間ファイル（アライメント実行時）
└─ <オプティマイザーダンプ/リスタート>
コンソールには解決済みYAMLブロックが出力され、GSM/DMFのMEP進行状況とタイミングが報告されます。
設定の優先順位は CLI 規約: 設定の優先順位 を参照してください。
Note
正規定義は YAML リファレンス および pdb2reaction/defaults.py を参照してください（齟齬がある場合はそちらが優先）。以下は path-opt 固有のデフォルト（例: out_dir）を含む抜粋です。
path-opt で使用される 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)
関連項目¶
典型エラー別レシピ – 症状起点の切り分け
トラブルシューティング – 詳細な対処ガイド
path-search — 自動精密化を伴う再帰的MEP 探索（2+構造用）
tsopt — HEI を TS 候補として最適化（内部で虚振動数チェック済み）。続けて IRC で接続性を確認
extract — path-opt入力用の活性部位モデルPDBを生成
all — 一気通貫ワークフロー（デフォルトで再帰的 path-search を使用;
--refine-path Falseで path-opt に切替。--refine-pathフラグはpdb2reaction allにのみ属します — 定義は MEP 探索オプション を参照してください）YAML リファレンス —
gs、dmf、stopt、optの完全な設定オプション用語集 — MEP、GSM、DMF、HEIの定義