`path-opt`（2 構造間の MEP 探索）¶

path-opt は、反応物と生成物の 2 つの構造の間の最小エネルギー経路（MEP）を、GSM（Growing String Method、デフォルト）または DMF（Direct Max Flux）で 1 回だけ求めます。R と P をつなぐ構造変化のトラジェクトリと、最もエネルギーの高いイメージ（HEI）を TS 候補として書き出します。

主な用途¶

R と P からの最初の MEP: 2 つの端点構造から、再帰的な精密化なしで経路とエネルギープロファイルを得る
tsopt に渡す TS 候補: hei.pdb（または hei.xyz）を tsopt の初期構造にする
GSM と DMF の比較: 同じ 2 構造を --mep-mode gsm と --mep-mode dmf で計算し、経路を見比べる

3 つ以上の構造を一度に入力したいときは、all の Endpoint モードを使ってください。R と P の間にありうる中間体を自動で検知できるか試したいなら、path-search を使うとよいでしょう。

基本的な実行例¶

1. 2 つの端点からの実行¶

反応物と生成物を 1 つの -i の後に並べ、電荷とスピン多重度を明示します。

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

端末に [write] Wrote '…/hei.xyz'. の行が出れば、TS 候補が書き出されています。--out-json で書き出した result.json の scientific_status には、指定した段（端点の事前最適化と MEP）がすべて収束すると success、そうでなければ partial か failed が入ります。barrier_kcal は最初のイメージを基準にした HEI のエネルギー、hei_index は経路上の HEI の位置です。

2. 端点の事前最適化の上限を変える¶

両端点はデフォルトで事前最適化され、--preopt-max-cycles で各回のサイクル数の上限を変えられます。端点が最適化済みなら --no-preopt で省けます。

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
  --preopt-max-cycles 20000 --out-dir ./result_path_opt_preopt

3. GSM の代わりに DMF を使う¶

DMF には cyipopt が必要です。この例では可動なイメージの数も減らしています。

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
  --mep-mode dmf --max-nodes 12 --out-dir ./result_path_opt_dmf

4. 短時間の確認（キャップ親原子を固定し、クライミングなし）¶

クライミングイメージ探索を省いて、経路の形をすばやく確かめます。キャップ水素の親原子は固定したままです。

pdb2reaction path-opt -i reactant.pdb product.pdb -q 0 -m 1 \
  --freeze-links --no-climb --out-dir ./result_path_opt_quick

処理の仕組みと計算仕様¶

端点の準備: 各端点を、デフォルトでは L-BFGS で事前最適化します（--opt-mode）。続いて生成物を固定原子で反応物に剛体で重ね合わせ、固定原子を少しずつ反応物側の位置へ動かしながら残りの原子を緩和します。キャップ水素の親原子は --freeze-links（デフォルト）で固定します。
経路の成長と精密化: GSM は 2 つの端点の間に --max-nodes 個の可動なイメージのストリングを成長させ、--thresh-gsm まで最適化します。--climb（デフォルト有効）では、続くクライミングイメージ探索で最も高いイメージを鞍点へ押し上げます。DMF は補間で作った経路を IPOPT（内点法の最適化ソルバー）で --dmf-tol まで最適化します。
HEI の書き出し: 最終経路でエネルギーが最も高いイメージを HEI とし、コメント行にエネルギーを付けて hei.xyz に書き出します。

HEI の判定¶

HEI の位置	意味	次の操作
経路の内側（`hei_index` が `1` 〜 `n_images − 2`。どちらも `result.json` のキーで、`n_images` は経路のイメージの数）	TS 候補	`tsopt` で最適化し、`irc` を実行する
端点（`hei_index` が `0` または `n_images − 1`）	TS 候補ではない（端点の間に、高いほうの端点より上にあるイメージがない）	端点を見直すか、別の方法で候補を作る（TS が取れないときを参照）

HEI は近似的な経路の頂点であり、TS そのものではありません。TS 最適化が成功すると、反応モードの虚振動が 1 つ出ます。tsopt で n_imag = 1 になり、その TS からの IRC が狙った R と P に着けば、HEI から TS が得られたことになります。

主な出力ファイル¶

--out-dir に次のファイルを書き出します。

result_path_opt/
├─ final_geometries_trj.xyz   # 最終経路の全イメージ（コメント行にエネルギー）
├─ final_geometries.pdb       # 同じ経路の PDB（PDB・mmCIF 入力のとき。DMF では final_geometries_trj.pdb）
├─ hei.xyz                    # HEI（TS 候補）。コメント行にエネルギー
├─ hei.pdb                    # 同じ HEI の PDB（PDB・mmCIF 入力のとき）
├─ align_refine/              # 端点の重ね合わせと緩和のファイル
├─ result.json                # 結果の要約（--out-json）
└─ summary.json               # result.json と同じ内容（--out-json 指定時）

経路は final_geometries_trj.xyz を開いて確かめてください。PDB・mmCIF 入力では tsopt に hei.pdb を渡すと、tsopt でも -l と --freeze-links が使えます。hei.xyz を渡すときは --ref-pdb を付けてください。PDB・mmCIF・.gjf 入力では、同じ名前でその形式のファイルも書き出します。mmCIF 入力と、PDB の欄に入りきらない大きな PDB 入力では、元の識別子を保った .cif も書き出します。DMF では経路の .gjf は書き出しません。--dump を付けると、オプティマイザの軌跡も残します。

端末には MEP の進行状況がサイクルごとに、所要時間とともに出ます。

主な CLI オプション¶

オプション	引数の型	デフォルト	説明
`-i, --input`	パス 2 つ	（必須）	反応物と生成物をこの順に 1 つの `-i` の後に並べる（`.pdb`, `.cif`, `.mmcif`, `.xyz`, `.gjf`）
`-q, --charge`	整数	`None`	系全体の総電荷。`-l`、YAML の `calc.charge`、`.gjf` 入力のどれも無ければ必須
`-m, --multiplicity`	整数	`1`	スピン多重度（2S+1）
`-l, --ligand-charge`	文字列	`None`	リガンドの総電荷（例: `-1`）または残基名ごとの電荷（例: `'GPP:-3,SAM:1'`）。`-q` を省いたときに使う（PDB/mmCIF 入力か `--ref-pdb` のとき）
`--ref-pdb`	パス	`None`	`.xyz` / `.gjf` 入力に使う PDB/mmCIF のトポロジー。両方の端点に使い、座標は `-i` から取る
`-b, --backend`	文字列	`uma`	計算バックエンド（`uma`, `orb`, `mace`, `aimnet2`, `dft`）
`-o, --out-dir`	パス	`./result_path_opt/`	出力先ディレクトリ
`--mep-mode`	`gsm` / `dmf`	`gsm`	経路の手法（Growing String Method / Direct Max Flux）
`--dmf-backend`	`gpu` / `cpu`	`gpu`	DMF の計算バックエンド（`--mep-mode dmf` のときのみ）。CUDA 上の PyTorch / NumPy
`--max-nodes`	整数	`20`	端点の間の可動なイメージの数。経路のイメージは全部で `max_nodes + 2` 個
`--preopt/--no-preopt`	フラグ	`True`	重ね合わせの前に各端点を事前最適化
`--preopt-max-cycles`	整数	`100000`	端点の事前最適化 1 回あたりの最大サイクル数
`--opt-mode`	`grad` / `hess`	`grad`	端点の事前最適化の最適化法: L-BFGS / RFO
`--thresh-gsm`	プリセット	`gau_loose`	GSM のストリングの収束条件（`gau_loose`, `gau`, `gau_tight`, `gau_vtight`, `baker`, `never`）
`--dmf-tol`	文字列	`tight`	DMF の経路の IPOPT の許容値: `tight`（0.04）、`middle`（0.10）、`loose`（0.20）、または正の数。別名 `--thresh-dmf`
`--fix-ends/--no-fix-ends`	フラグ	`True`	GSM のストリングの最適化の間、端点を固定する（DMF では使わない）
`--climb/--no-climb`	フラグ	`True`	経路の成長後に GSM のクライミングイメージ探索を行う（DMF では使わない）
`--freeze-links/--no-freeze-links`	フラグ	`True`	キャップ水素の親原子を固定（PDB/mmCIF 入力か `--ref-pdb` のとき）
`--out-json/--no-out-json`	フラグ	`False`	結果の要約を `result.json` に出力（JSON 出力の一覧）

全オプションは自動生成のオプションの一覧（英語のみ）を参照してください。

補足: YAML（--config）では、gs の節で GSM のストリングを、dmf の節で DMF の経路を、stopt の節でストリングのオプティマイザを設定できます。stopt.lbfgs・stopt.rfo でも、opt.lbfgs・opt.rfo と同じように端点のオプティマイザを設定できます。

使用上の注意点¶

DMF では固定原子が少し動く: DMF は固定原子をその場に止めず、YAML の dmf.k_fix（300 eV/Å²）の調和拘束で保持するので、参照位置からわずかにずれることがあります。GSM では固定されたままです。原子の固定と距離の拘束を参照してください。
DMF には cyipopt が必要: --mep-mode dmf を使う前に、詳細なインストール手順の手順 3 のとおり PyTorch と一緒に conda-forge からインストールしてください。pydmf は pdb2reaction に同梱されています。デフォルトの --dmf-backend gpu は CUDA が使えないとエラーで停止します。その場合と GPU のメモリ不足のときは --dmf-backend cpu を指定してください。
DMF と陰溶媒は併用できない: MLIP バックエンドで --mep-mode dmf と --solvent を同時に指定すると、エラーで停止します。溶媒を入れた経路には GSM を使ってください。
DMF で使われないオプション: --climb・--dump・--fix-ends は、指定しても DMF では使われません。
YAML のオプティマイザ設定の矛盾: 同じ YAML ファイルの中で、同じキーを opt: と実際に動くオプティマイザの節（lbfgs:・opt.lbfgs:・stopt.lbfgs:、または rfo の同等の節）とで別の値にすると、エラーで停止します。

path-opt（2 構造間の MEP 探索）¶