path-search¶
概要¶
要約: 2 構造以上から、GSM（デフォルト）または DMF（
--mep-mode dmf）で連続的な MEP を構築します。共有結合変化のある領域のみを自動で精密化し、最高エネルギー画像（HEI）を TS 候補として出力します（freq/IRC で検証）。
要点¶
想定場面: R → … → P のように 2 構造以上を入力として、自動精密化を含めた連続 MEP を構築したい場合に使います。
手法: GSM/DMF セグメントを連鎖し、結合変化が残る区間だけを再帰的に精密化します。
主な出力:
mep.trj（主軌跡）、summary.yaml（セグメントごとの結果）、必要に応じてプロットやマージ済み PDB。既定値:
--mep-mode gsm、--opt-mode light（LBFGS）、--preopt True、--align True、--thresh gau。次にやること: HEI は TS 候補です。単独では TS 検証になりません。続けて tsopt → freq → 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 コンパニオンは生成されません）。
2 端点だけで再帰精密化が不要な場合は、path-opt の方がシンプルです。
使用法¶
pdb2reaction path-search -i R.pdb [I.pdb ...] P.pdb [-q CHARGE] [--ligand-charge <number|'RES:Q,...'>] [--multiplicity 2S+1]
[--workers N] [--workers-per-node N]
[--mep-mode {gsm|dmf}] [--freeze-links {True\|False}] [--thresh PRESET]
[--refine-mode {peak|minima}]
[--max-nodes N] [--max-cycles N] [--climb {True\|False}]
[--opt-mode light|heavy] [--dump {True\|False}]
[--out-dir DIR] [--preopt {True\|False}]
[--align {True\|False}] [--ref-full-pdb FILE ...] [--ref-pdb FILE ...]
[--convert-files {True\|False}]
[--args-yaml FILE]
例¶
ポケットのみの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 \ --args-yaml params.yaml --ref-full-pdb holo_template.pdb --out-dir ./run_ps
CLI オプション¶
オプション |
説明 |
デフォルト |
|---|---|---|
|
反応順序の2つ以上の構造（反応物 → 生成物）。 |
必須 |
|
総電荷。非 |
テンプレート/導出が適用されない限り必須 |
|
|
None |
|
UMA予測器の並列度（workers > 1 で解析ヘシアン無効; |
|
|
スピン多重度（2S+1） |
|
|
PDB ポケット読み込み時、リンク水素の親原子を凍結 |
|
|
MEPセグメントごとの内部ノード |
|
|
最大MEP最適化サイクル（GSM/DMF） |
|
|
GSMセグメントのクライミングイメージを有効化（ブリッジは無効） |
|
|
HEI±1/kinkノード用の単一構造オプティマイザー（ |
|
|
セグメント生成器: GSM（string）またはDMF（direct flux） |
|
|
精密化シード: |
Auto |
|
MEP（GSM/DMF）と単一構造軌跡/リスタートをダンプ |
|
|
PDB/Gaussian入力のXYZ/TRJ → PDB/GJFコンパニオンを切り替え |
|
|
出力ディレクトリ |
|
|
GSMおよびイメージごとの最適化の収束プリセットを上書き（ |
|
|
YAML 上書き（下記参照） |
None |
|
MEP 探索前に各エンドポイントを事前最適化（推奨） |
|
|
探索前にすべての入力を最初の構造にアライメント |
|
|
フルサイズテンプレート PDB（ |
None |
|
入力がXYZ/GJFの場合のポケット参照 PDB（XYZ 座標は保持） |
None |
ワークフロー¶
ペアごとの初期セグメント（GSM/DMF） – 各隣接入力（A→B）間で
GrowingStringまたは DMF を実行し、粗いMEPと最高エネルギーイメージ（HEI）を取得。HEI周辺の局所緩和 –
refine-mode=peakなら HEI±1、refine-mode=minimaなら HEI 近傍の局所極小を、選択した単一構造オプティマイザー（opt-mode）で精密化しEnd1/End2を得る。kink vs. 精密化の決定 –
End1とEnd2間に共有結合変化がなければ kink とみなし、search.kink_max_nodesの線形ノードを挿入して個別最適化。結合変化がある場合は 精密化セグメント（GSM/DMF） を起動。選択的再帰 –
(A→End1)と(End2→B)の結合変化をbondしきい値で比較し、共有結合更新が残るサブ区間のみ再帰的に探索。再帰深度はsearch.max_depthで制限。スティッチング & ブリッジング – 解決済みのサブパスを連結し、RMSD ≤
search.stitch_rmsd_threshの重複エンドポイントを除去。RMSDギャップがsearch.bridge_rmsd_threshを超える場合はブリッジMEPを挿入。境界で結合変化が検出される場合はブリッジではなく新規の再帰セグメントで置換。アライメント & マージング（オプション） –
--align（既定）で事前最適化構造を先頭入力へ剛体アライメントし、freeze_atomsを整合。--ref-full-pdbを指定するとポケット軌跡をフルサイズPDB テンプレートへマージ（--alignにより先頭テンプレートの再利用が可能）。
結合変化の判定は bond_changes.compare_structures を用い、bond セクションのしきい値に従います。UMA 計算機は全構造で共有され、効率的に再利用されます。
出力¶
out_dir/ (デフォルト: ./result_path_search/)
├─ mep.trj # 主要 MEP 軌跡
├─ mep.pdb # 入力がPDB テンプレートで変換が有効な場合のPDB コンパニオン
├─ mep_w_ref.pdb # マージされた全系MEP（参照 PDB/テンプレートが必要）
├─ mep_w_ref_seg_XX.pdb # 共有結合変化がある場合のマージされたセグメントごとのパス
├─ summary.yaml # すべての再帰セグメントの障壁と分類サマリー
├─ mep_plot.png # ΔEプロファイル（kcal/mol、反応物基準）
├─ energy_diagram_MEP.png # MEP状態エネルギーダイアグラムの静的エクスポート
└─ seg_000_*/ # セグメントごとの GSM/DMF ダンプ、HEI スナップショット、kink/精密化の診断情報
コンソールには確定済みの設定ブロック（
geom,calc,gs,opt,sopt.*,bond,search）が出力されます。
注意事項¶
入力は2つ以上が必須。満たさない場合は
click.BadParameterが発生します。--ref-full-pdbは1回の指定で複数ファイルを続けて渡せます。--alignが有効な場合、マージでは先頭テンプレートのみが再利用されます。UMA 計算機は全構造で共有され、効率化されます。
--dumpが有効な場合、MEP（GSM/DMF）と単一構造最適化の軌跡が出力されます。リスタート YAML は YAML でdump_restartを有効にした場合のみ書き出されます。電荷/スピンは
.gjfテンプレートがあればそれを継承します。-qが省略され--ligand-chargeが与えられている場合、入力は酵素–基質複合体として扱われ、PDB 入力ではextract.pyの電荷サマリーで総電荷が導出されます。明示的な-qは常に優先されます。.gjf以外で--ligand-chargeが使えない場合は実行が中断され、多重度は省略時に1がデフォルトです。
YAML 設定（--args-yaml）¶
YAML ルートはマッピングでなければなりません。YAML 値はCLIを上書きします。共通セクションは YAML リファレンス を再利用します: geom/calc は単一構造設定を反映し（PDBでは --freeze-links が geom.freeze_atoms にマージ）、opt は path-opt（path_opt.md）に記載の StringOptimizer 設定を継承します。
gs（Growing String）は pdb2reaction.path_opt.GS_KW の既定値を継承し、max_nodes（セグメント内部ノード）、クライミング設定（climb, climb_rms, climb_fixed）、再パラメータ化（reparam_every_full, reparam_check）を上書きできます。
sopt は HEI±1 と kink ノードに使う単一構造オプティマイザーで、lbfgs と rfo に分かれます。各サブセクションは YAML リファレンス と同じキーを持ちますが、デフォルトは out_dir: ./result_path_search/、dump: False です。
bond は UMA ベースの結合変化検出パラメータで、scan の bond セクション と共通の device, 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（null の場合は GSM→peak、DMF→minima を自動選択）。旧 rmsd_align フラグは互換性のため保持されますが無視されます。
dmf は --mep-mode dmf 選択時に適用される Direct Max Flux + (C)FB-ENM の設定です。既定値は DMF_KW を踏襲し、実行ごとに上書きできます。
YAML例（デフォルト値）¶
geom:
coord_type: cart # coordinate type: cartesian vs dlc internals
freeze_atoms: [] # 0-based frozen atoms merged with CLI/link detection
calc:
charge: 0 # total charge (CLI/template override)
spin: 1 # spin multiplicity 2S+1
model: uma-s-1p1 # UMA model tag
task_name: omol # UMA task name
device: auto # UMA device selection
max_neigh: null # maximum neighbors for graph construction
radius: null # cutoff radius for neighbor search
r_edges: false # store radial edges
out_hess_torch: true # request torch-form Hessian
freeze_atoms: null # calculator-level frozen atoms
hessian_calc_mode: FiniteDifference # Hessian mode selection
return_partial_hessian: false # full Hessian (avoids shape mismatches)
gs:
fix_first: true # keep the first endpoint fixed during optimization
fix_last: true # keep the last endpoint fixed during optimization
max_nodes: 10 # maximum string nodes
perp_thresh: 0.005 # perpendicular displacement threshold
reparam_check: rms # reparametrization check metric
reparam_every: 1 # reparametrization stride
reparam_every_full: 1 # full reparametrization stride
param: equi # parametrization scheme
max_micro_cycles: 10 # micro-iteration limit
reset_dlc: true # rebuild delocalized coordinates each step
climb: true # enable climbing image
climb_rms: 0.0005 # climbing RMS threshold
climb_lanczos: true # Lanczos refinement for climbing
climb_lanczos_rms: 0.0005 # Lanczos RMS threshold
climb_fixed: false # keep climbing image fixed
scheduler: null # optional scheduler backend
opt:
type: string # optimizer type label
stop_in_when_full: 300 # early stop threshold when string is full
align: false # alignment toggle (kept off)
scale_step: global # step scaling mode
max_cycles: 300 # maximum optimization cycles
dump: false # dump trajectory/restart data
dump_restart: false # dump restart checkpoints
reparam_thresh: 0.0 # reparametrization threshold
coord_diff_thresh: 0.0 # coordinate difference threshold
out_dir: ./result_path_search/ # output directory
print_every: 10 # logging stride
dmf:
max_cycles: 300 # DMF/IPOPT の最大反復数
correlated: true # correlated DMF propagation
sequential: true # sequential DMF execution
fbenm_only_endpoints: false # run FB-ENM beyond endpoints
fbenm_options:
delta_scale: 0.2 # FB-ENM displacement scaling
bond_scale: 1.25 # bond cutoff scaling
fix_planes: true # enforce planar constraints
two_hop_mode: sparse # neighbor traversal strategy
cfbenm_options:
bond_scale: 1.25 # CFB-ENM bond cutoff scaling
corr0_scale: 1.1 # Correlation scale for corr0
corr1_scale: 1.5 # Correlation scale for corr1
corr2_scale: 1.6 # Correlation scale for corr2
eps: 0.05 # Correlation epsilon
pivotal: true # Pivotal residue handling
single: true # Single-atom pivots
remove_fourmembered: true # Prune four-membered rings
two_hop_mode: sparse # Neighbor traversal strategy
dmf_options:
remove_rotation_and_translation: false # Keep rigid-body motions
mass_weighted: false # Toggle mass weighting
parallel: false # Enable parallel DMF
eps_vel: 0.01 # Velocity tolerance
eps_rot: 0.01 # Rotational tolerance
beta: 10.0 # Beta parameter for DMF
update_teval: false # Update transition evaluation
k_fix: 300.0 # Harmonic constant for restraints
sopt:
lbfgs:
thresh: gau # LBFGS convergence preset
max_cycles: 10000 # iteration limit
print_every: 100 # logging stride
min_step_norm: 1.0e-08 # minimum accepted step norm
assert_min_step: true # assert when steps stagnate
rms_force: null # explicit RMS force target
rms_force_only: false # rely only on RMS force convergence
max_force_only: false # rely only on max force convergence
force_only: false # skip displacement checks
converge_to_geom_rms_thresh: 0.05 # RMS threshold when targeting geometry
overachieve_factor: 0.0 # tighten thresholds
check_eigval_structure: false # validate Hessian eigenstructure
line_search: true # enable line search
dump: false # dump trajectory/restart data
dump_restart: false # dump restart checkpoints
prefix: "" # filename prefix
out_dir: ./result_path_search/ # output directory
keep_last: 7 # history size for LBFGS buffers
beta: 1.0 # initial damping beta
gamma_mult: false # multiplicative gamma update toggle
max_step: 0.3 # maximum step length
control_step: true # control step length adaptively
double_damp: true # double damping safeguard
mu_reg: null # regularization strength
max_mu_reg_adaptions: 10 # cap on mu adaptations
rfo:
thresh: gau # RFOptimizer convergence preset
max_cycles: 10000 # iteration cap
print_every: 100 # logging stride
min_step_norm: 1.0e-08 # minimum accepted step norm
assert_min_step: true # assert when steps stagnate
rms_force: null # explicit RMS force target
rms_force_only: false # rely only on RMS force convergence
max_force_only: false # rely only on max force convergence
force_only: false # skip displacement checks
converge_to_geom_rms_thresh: 0.05 # RMS threshold when targeting geometry
overachieve_factor: 0.0 # tighten thresholds
check_eigval_structure: false # validate Hessian eigenstructure
line_search: true # enable line search
dump: false # dump trajectory/restart data
dump_restart: false # dump restart checkpoints
prefix: "" # filename prefix
out_dir: ./result_path_search/ # output directory
trust_radius: 0.1 # trust-region radius
trust_update: true # enable trust-region updates
trust_min: 0.0 # minimum trust radius
trust_max: 0.1 # maximum trust radius
max_energy_incr: null # allowed energy increase per step
hessian_update: bfgs # Hessian update scheme
hessian_init: calc # Hessian initialization source
hessian_recalc: 200 # rebuild Hessian every N steps
hessian_recalc_adapt: null # adaptive Hessian rebuild factor
small_eigval_thresh: 1.0e-08 # eigenvalue threshold for stability
alpha0: 1.0 # initial micro step
max_micro_cycles: 50 # micro-iteration limit
rfo_overlaps: false # enable RFO overlaps
gediis: false # enable GEDIIS
gdiis: true # enable GDIIS
gdiis_thresh: 0.0025 # GDIIS acceptance threshold
gediis_thresh: 0.01 # GEDIIS acceptance threshold
gdiis_test_direction: true # test descent direction before DIIS
adapt_step_func: true # adaptive step scaling toggle
bond:
device: cuda # UMA 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
rmsd_align: true # legacy alignment flag (ignored)
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)