path-search

mlmm path-search は選択した MEP engine（デフォルト GSM、または DMF）を使用して 2 つ以上の構造にわたる連続した最小エネルギー経路（MEP）を構築します。共有結合変化が検出された領域のみを選択的に精密化し、精密化済みのサブパスを 1 つの軌跡に統合します。R + （任意の中間体）+ P からなる多段機構を駆動する用途に向いており、再帰分割が素過程を自動検出します。ただし、複雑な多段階反応の検出は困難な場合があり、入力中間体・MEP エンジン設定・収束閾値の調整など手動での試行錯誤が必要になることがあります。

実行例

mlmm path-search -i reactant.pdb product.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q 0 --out-dir ./result_path_search

中間体を明示した多段経路を構築する例:

# 中間体を含む多段経路を構築する
mlmm path-search -i R.pdb IM1.pdb IM2.pdb P.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q -1 --out-dir ./result_path_search_multi

事前最適化とアライメントを無効にして軽く試す例:

# 事前最適化とアライメントを無効にして軽く試す
mlmm path-search -i reactant.pdb product.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q 0 --no-preopt --no-align --max-nodes 8 \
 --out-dir ./result_path_search_fast

YAML 上書きや凍結原子を併用する例:

# YAML 上書き、凍結原子付きマルチステップ経路
mlmm path-search -i R.pdb IM1.pdb P.pdb --parm real.parm7 \
 --model-pdb ml_region.pdb -q -1 --freeze-atoms "1,3,5" \
 --ref-pdb holo_template.pdb --out-dir ./run_ps

一般的なコマンド形式:

mlmm path-search -i R.pdb IM1.pdb P.pdb \
 --parm real.parm7 --model-pdb ml_region.pdb -q CHARGE [-m MULT]
 [--mep-mode gsm|dmf] [--refine-mode peak|minima]
 [--freeze-atoms "1,3,5"] [--max-nodes N]
 [--max-cycles-gsm N] [--max-cycles-dmf N] [--climb/--no-climb]
 [--thresh PRESET] [--dump/--no-dump] [--out-dir DIR]
 [--show-config/--no-show-config] [--dry-run/--no-dry-run]

処理の流れ

1. 初期セグメント（隣接ペア A->B ごと; GSM/DMF） – 選択した MEP エンジン（--mep-mode）を実行して粗い MEP を取得し、最高エネルギーイメージ（HEI）を特定。

2. HEI 周辺の局所緩和 – --refine-mode（peak: HEI+/-1、minima: 最近傍局所極小）で種点を選び、単一構造オプティマイザ（opt-mode）で精密化して近傍の極小（End1、End2）を得る。

3. ねじれ vs 精密化の判定:

• End1 と End2 の間に共有結合変化が検出されない場合、その領域をねじれとして扱い、search.kink_max_nodes 個の線形ノードを挿入して各ノードを個別に最適化。

• それ以外の場合、End1 と End2 の間で選択した MEP engine による精密化セグメントを起動して障壁を明確化。

4. 選択的再帰 – (A->End1) と (End2->B) の結合変化を bond 閾値で比較。共有結合の更新を含むサブ区間のみに再帰。再帰深度は search.max_depth で制限。

5. 統合とブリッジ – 精密化済みのサブパスを連結し、RMSD <= search.stitch_rmsd_thresh の重複端点を削除。2 つの統合部分の間の RMSD ギャップが search.bridge_rmsd_thresh を超える場合、選択中の --mep-mode でブリッジ MEP セグメントを挿入。インターフェース自体に結合変化がある場合、ブリッジの代わりに新たな再帰セグメントを生成。

6. 任意のアライメント/精密化 – 事前最適化後、--align で全入力を最初の入力に剛体アライン。凍結アンカーがある場合は reference への freeze-guided scan と L-BFGS 緩和も行い、凍結原子を再マッチ。セグメントをプロット/分析用にアノテーション。

結合変化検出は bond YAML セクションの閾値を使用する bond_changes.compare_structures に依存します。

出力

out_dir/ (デフォルト:./result_path_search/)
 summary.json # MEP レベルの実行サマリー（完全設定ダンプなし）
 summary.log # 人間が読めるサマリー
 mep_trj.xyz # 最終 MEP（常に書き出し）
 mep.pdb # 最終 MEP（参照テンプレート利用可能時は PDB）
 mep_seg_XX_trj.xyz / mep_seg_XX.pdb # セグメント別経路
 hei_seg_XX.xyz / hei_seg_XX.pdb # 結合変化セグメントごとの HEI
 mep_plot.png # イメージインデックスに対する Delta-E プロファイル（trj2fig より）
 energy_diagram_MEP.png # 反応物基準の状態レベルエネルギーダイアグラム（kcal/mol）
 seg_000_*/ # セグメントレベルの GSM と精密化成果物

実行結果は通常、次のファイルを開いて確認します。

• result_path_search/mep_trj.xyz

• result_path_search/summary.json

• result_path_search/summary.log

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

CLI オプション

mlmm path-search --help はコアオプションを、mlmm path-search --help-advanced は全オプションを表示します。全フラグの一覧は生成されたコマンドリファレンスにもあります。以下の表では、説明が必要なオプションを取り上げます。

オプション	説明	デフォルト
-i, --input PATH...	反応順の 2 つ以上の PDB/mmCIF 構造、または対応する --ref-pdb を伴う XYZ。-i を繰り返すか、1 つのフラグの後に複数パスを渡す。	必須
--parm PATH	完全酵素複合体の Amber parm7 トポロジー。	必須
--model-pdb PATH	ML/MM の ML（高レベル）領域原子を定義する PDB。--detect-layer または --model-indices 利用時は省略可。	None
--model-indices TEXT	ML 領域のカンマ区切り原子インデックス（範囲指定可、例: 1-5）。--model-pdb 省略時に使用。	None
--model-indices-one-based / --model-indices-zero-based	--model-indices を 1 始まりまたは 0 始まりとして解釈。	True（1 始まり）
--detect-layer / --no-detect-layer	B 因子レイヤー（B=0/10/20）を自動的に読み取ります。ML 原子集合を明示した場合は MM 側のレイヤーだけを保持し、明示しない場合は B 因子が ML 原子集合も定義します。	有効
-q, --charge INT	ML 領域の電荷（整数）。-l 未指定時は必須。	None
-l, --ligand-charge TEXT	残基ごとの電荷マッピング（例: SAM:1,PHN:-1）。-q 省略時に合計電荷を導出。PDB 入力または --ref-pdb が必要。	None
-m, --multiplicity INT	スピン多重度 (2S+1)。	1
--mep-mode [gsm|dmf]	セグメント/ブリッジ探索に使う MEP バックエンド。	gsm
--dmf-backend [cpu|gpu]	DMF 計算バックエンド（--mep-mode dmf 時のみ）: gpu（dmf.torch/CUDA）または cpu（dmf/NumPy）。GPU メモリ不足時は cpu で再実行。pydmf>=1.2 が必要。	gpu
--refine-mode [peak|minima]	HEI 精密化の種点ルール。	gsm は peak、dmf は minima
--freeze-atoms TEXT	凍結する 1 始まりカンマ区切りインデックス（YAML geom.freeze_atoms とマージ）。	None
--movable-cutoff FLOAT	ML 領域からの可動 MM 原子の距離カットオフ (Å)。これを超える MM 原子は凍結。指定時は --detect-layer が無効化。	None
--max-nodes INT	GSM／DMF セグメントごとの可動内部画像数（総画像数は max_nodes + 2）。	20
--gsm-param [equi|energy]	完全成長後のGSMノード配置。energy は高エネルギー領域へノード密度を寄せる。等間隔経路がHEI近傍の反応座標領域を飛び越える場合の試行用であり、TSを同定する機能ではない。	equi
--max-cycles-gsm INT	GSMストリング最適化サイクル上限。	300
--max-cycles-dmf INT	DMF IPOPT反復上限。	300
--climb/--no-climb	セグメント GSM の TS 精密化を有効化。	True
--preopt/--no-preopt	セグメンテーション前に端点を L-BFGS で事前最適化。	True
--align / --no-align	事前最適化後に入力をアラインし、凍結アンカーがあれば freeze-guided scan/緩和後に凍結原子を再マッチ。	有効
--thresh TEXT	単一構造 L-BFGS のみの収束プリセット（gau_loose、gau、gau_tight、gau_vtight、baker、never）。	gau
--thresh-gsm TEXT	GSM ストリング最適化の収束プリセット（stopt.thresh; --thresh と同じプリセット群）。	gau_loose
--thresh-dmf TEXT	DMF 最適化の IPOPT dual-infeasibility 許容値（dmf.tol）。tight(0.04)、middle(0.10)、loose(0.20) または正の float。Gaussian プリセットは拒否。	tight
--mm-backend [hessian_ff|openmm]	MM バックエンド。Hessian 構築法は calc.mm_fd が別に制御します（デフォルト true: 有限差分）。	hessian_ff
--dump/--no-dump	オプティマイザダンプを保存。	False
-o, --out-dir PATH	出力ディレクトリ。	./result_path_search/
--ref-pdb PATH...	XYZ→PDB 変換・トポロジー参照用の完全テンプレート PDB。	None
--config FILE	明示 CLI 指定より前に適用されるベース YAML。	None
--show-config/--no-show-config	解決済み設定（YAML レイヤ情報を含む）を表示して実行継続。	False
--dry-run/--no-dry-run	実行せずに検証と実行計画表示のみを行う。--help-advanced に表示。	False
-b, --backend CHOICE	ML 領域の MLIP バックエンド: uma（デフォルト）、orb、mace、aimnet2。	uma
--cmap/--no-cmap	REAL と MODEL の両 MM 層で CMAP を保持します。	--cmap
--convert-files/--no-convert-files	PDB テンプレート利用可能時の XYZ/TRJ から対応する PDB の生成を切り替え。	True

YAML 設定

マージ順は defaults < config < 明示指定 CLI です。

YAML ルートはマッピングでなければなりません。受け付けるセクション:

• geom – coord_type（デフォルト "cart"）、freeze_atoms（1 始まりインデックス）。

• calc / mlmm – ML/MM calculator設定: input_pdb、real_parm7、model_pdb、model_charge、model_mult、バックエンド選択（backend）、UMA 制御（uma_model、uma_task_name、hessian_calc_mode）、デバイス選択、凍結原子。

• gs – Growing String 設定: max_nodes、climb、climb_rms、climb_fixed、reparam_every_full、reparam_check。

• opt – StringOptimizer 制御: max_cycles、print_every、dump、dump_restart、out_dir。

• lbfgs – HEI+/-1 精密化用の単一構造オプティマイザ制御: keep_last、beta、gamma_mult、max_step、control_step、double_damp、mu_reg、max_mu_reg_adaptions。

• bond – 結合変化検出: bond_factor、margin_fraction、delta_fraction。

• search – 再帰ロジック: max_depth、stitch_rmsd_thresh、bridge_rmsd_thresh、max_nodes_segment、max_nodes_bridge、kink_max_nodes、max_seq_kink、refine_mode。

注記

• 端点が 2 つだけで再帰的精密化が不要な場合は、path-opt がより簡単な選択です。

関連項目

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

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

• path-opt – MEP 最適化（再帰的精密化なし）

• opt – 単一構造の構造最適化

• all – all が内部で path-opt（デフォルト）または path-search（--refine-path 指定時）を呼び出す一気通貫ワークフロー

• trj2fig – MEP 軌跡からエネルギープロファイルをプロット