tsopt¶
mlmm tsopt はレイヤー分けした酵素 PDB の遷移状態候補を一次サドル点まで精密化します。単独の TS（遷移状態）推測構造でも、path-search が抽出する最高エネルギー像（HEI）でも実行できます。
オプティマイザは 2 系統です。gradient 系は Hessian-Guided Dimer
（grad/dimer）、Hessian 系は RS-P-RFO（hess/rsprfo、デフォルト）、
RS-I-RFO（rsirfo）、TRIM（trim）を提供します。
RS-P-RFO（
--opt-mode hess）がデフォルトです。マイクロイテレーション（--microiter、デフォルト有効）は、ML 領域の RS-P-RFO macro step 1 回と MM L-BFGS 緩和を交互に実行します。RS-I-RFO は--opt-mode rsirfoで明示的に選択できます。Hessian-Guided Dimer（
--opt-mode grad）は初期および定期的な方向決定 Hessian を使うため、自由度の多い系ではランダムな初期方向より頑健です。--ml-only-hessian-dimerを付けると ML 領域のみの Hessian を Dimer 方向決定に使用できます（高速）。
tsopt は、YAML 上書き後も鞍点探索を担う RFO 系および Dimer
optimizer の reject_uphill を常に false に固定します。TS 探索では
反応モードに沿った物理エネルギー上昇を許す必要があるためです。
--reject-uphill/--no-reject-uphill は最小値最適化（opt と all の
IRC 後エンドポイント再最適化）だけに適用されます。マイクロイテレーション
内部の MM-only 緩和は最小化の部分問題なので、この区別を維持します。
--flatten を明示的に有効化した場合だけ、余剰虚モード除去ループが質量重み付け変位で余分な負のモードを整理します。--flatten 無効時は終端 exact PHVA を 1 回だけ行い、終端候補を一次、高次、虚振動なし、または検証不能として保持します。一次 TS 認定には、目的反応座標に沿う虚振動が 1 つであることと、正しい irc 接続性が引き続き必要です。
通常の終端outcomeと致命的errorの境界¶
条件 |
|
|
|---|---|---|
収束条件未達、明示cycle上限到達、またはopt-inのenergy plateau |
最終構造とtrajectoryを保持し、終端PHVAをskip |
TS成果物を登録後、IRC前停止 |
終端PHVA失敗、または |
構造を保持し、 |
成果物登録後にIRC前停止 |
不正入力/geometry、または |
structured error envelopeへ進み、それ以前に書かれたfileだけをbest effortで保持 |
通常の数値非収束へ読み替えずstageを中断 |
まず TS 候補を構築する¶
tsopt は候補を精密化するもので、ゼロから探索するわけではありません。手元にある情報に合った経路を選び、その結果を tsopt → irc → freq（または mlmm all --tsopt）に渡します。
経路 |
サブコマンド |
内容 |
使う場面 |
|---|---|---|---|
(a) MEP / 経路探索 |
|
再帰的 GSM/DMF 最小エネルギー経路探索。端点間で TS を挟み込み、セグメント間のギャップを橋渡しし、セグメントごとに TS を 1 つ出力。 |
反応物（任意で生成物や中間体）があり、経路を探索させたいとき。 |
(b) 距離拘束による構築 |
反応ペアごとに調和拘束 |
使える第 2 端点も TS 推測構造もないとき — 反応結合を直接駆動する。 |
# 経路 (a): 経路を探索し、その最高エネルギー像を精密化
mlmm path-search -i r.pdb p.pdb --parm enzyme.parm7 -l 'LIG:Q' -o result_mep
# 経路 (b): 反応距離を駆動して TS 候補を構築
mlmm scan -i r.pdb --parm enzyme.parm7 -l 'LIG:Q' \
--scan-lists '[(1,5,1.40)]' -o result_scan
Note
opt --restraint フラグは存在しません。拘束付きの極小化には opt の --dist-freeze を使い、強さを --bias-k で指定します。TS 候補へ距離を駆動する場合は scan、経路を構築する場合は path-search を使います。
虚振動数の数が正しくないとき¶
クリーンな一次サドルは虚モードを正確に 1 つだけ持ちます。その変位が反応座標に対応することも確認します。よくある失敗は、余計な 2 つ目の小さな虚モードが出る、あるいは反応モードがまったく出ないことです。
症状 |
対処 |
|---|---|
|
失敗として扱い、TS 初期構造または MEP を改善する。 |
|
バックエンドの本計算精度で再計算し、 |
1 モードだが原子運動が意図と異なる |
経路/初期構造を改善し IRC で接続性を確認する。モード数だけでは目的反応を同定できない。 |
--flatten は余分な虚モードの平坦化ループを実行します（grad:
Dimer loop、hess: RS-P-RFO 後処理）。--no-flatten は
flatten_max_iter=0 に強制します。追加 Hessian 評価を伴うため opt-in
です。経路自体が粗い場合は TS 最適化の前に all --refine-path
（または path-search）で MEP を精密化します。再帰精密化は悪い経路を
複数セグメントに分割して計算量を大きく増やす場合があるため、これも
デフォルトでは無効です。
mlmm tsopt -i ts_guess.pdb --parm enzyme.parm7 -l 'LIG:Q' -b uma \
--precision fp64 --coord-type dlc -o result_ts
--coord-type は最適化の座標系（cart | redund | dlc | tric、デフォルト cart）を選びます。dlc（非局在化内部座標）は低速ですが、ねじれの多い系やクリーンな一次サドルへの収束でより堅牢です。
Warning
--coord-type dlc はHessianベースのオプティマイザが必要です。デフォルトの L-BFGS（--opt-mode grad）の opt では警告を出して cart に戻ります。tsopt（RS-P-RFO / RS-I-RFO / TRIM）または opt --opt-mode hess で使ってください。path-opt / path-search は cart と dlc のみ受け付けます。DLC + リンク原子 と DLC + 3 層凍結 MM は数値的に未検証なため、cart がデフォルトです。
同じ症状からの切り分けについては 典型エラー別レシピ — レシピ 4 を参照してください。
高度な MEP 参照モード¶
--ref-mode は Hessian ベース TS optimizer 用の内部的な高度 handoff で、
通常の standalone 実行では必須ではありません。.npz、.npy、または空白区切り
text から、同じ原子順の Cartesian 3N 候補を 1 本または複数（単一 vector または
2-D candidate table）読み込みます。mlmm all は RS-I-RFO、RS-P-RFO、TRIM に
CPU/file cache した MEP tangent 候補を自動で渡します。Dimer は --ref-mode を
使用しません。all --no-tsopt-from-mep-tan では cache の作成・利用を停止し、
TSOPT は初期構造 Hessian の振動モードから初期 root を選びます。
参照方向は負の Hessian root の identity と overlap 追跡を補助しますが、初期
Hessian そのものを置き換えるものではありません。鞍点次数は終端 exact PHVA が
決定します。数値収束済み高次停留点は optimization_status: "converged"、
saddle_validation: "higher_order" のまま保持され、一次 TS 認定にはなりません。
有効な負 root がある場合、all は警告付き診断 IRC に進むことがあります。数値
非収束、虚振動 0 本、PHVA 失敗/skip、または有効な負 root なしでは、TS 成果物を
保持した後、IRC 前で停止します。
対照を揃えた変異体 vs 野生型（あるいは機構 vs 機構）の比較¶
Important
変異体と野生型では、それぞれの系内で求めた活性化エネルギーまたは 自由エネルギー障壁を比較します。組成が異なる系の絶対エネルギーを直接 差し引いてはいけません。
ML/MM backend、力場、収束基準、熱化学条件、温度を揃え、化学的に対応する ML/可動領域を定義します。変異で追加・削除された原子は明示的に割り当て、各系の電荷と多重度を個別に決めてください。各 TS は虚振動 1 つ、その変位、IRC endpoint の化学種を独立に検証します。
実行例¶
コマンド形式は mlmm tsopt -i TS_GUESS --parm PARM7 --model-pdb ML_REGION -q CHARGE -m MULT [options] です。mlmm tsopt --help で主要オプション、mlmm tsopt --help-advanced で全オプション一覧を表示します。
デフォルト実行:
mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --out-dir ./result_tsopt
Dimer + 解析的 Hessian:
# Dimer と解析的 Hessian を使用する
mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --opt-mode grad --hessian-calc-mode Analytical --out-dir ./result_tsopt_grad
RS-P-RFO + YAML 上書き:
# RS-P-RFO を YAML 上書きと併用する
mlmm tsopt -i ts_guess.pdb --parm real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --opt-mode hess --config tsopt.yaml --out-dir ./result_tsopt_hess
# --dump で最適化軌跡を保存、--backend mace で MACE バックエンドを使用
処理の流れ¶
入力処理 — 酵素 PDB、Amber トポロジー、ML 領域定義を読み込みます。電荷/スピンを解決します。CLI と YAML の凍結原子がマージされます。
ML/MM calculatorの構築 — ML/MM calculator（MLIP バックエンド + hessian_ff）を構築します。
-b/--backendで ML バックエンドを選択し（デフォルト:uma）、--hessian-calc-modeは MLIP が Hessian を解析的に評価するか有限差分で評価するかを制御します。Dimer:
Hessian Dimer ステージはアクティブ部分空間の部分 Hessian を評価して Dimer 方向を定期的に更新します。固定の constrained 処理は凍結 anchor と両立する全系剛体運動だけを除去します。保存・回転・試行する全方向で凍結Cartesian成分をゼロに保ち、中心外のforce評価でも凍結座標を中心imageと厳密に一致させます。
平坦化ループが有効な場合（
--flatten）、保存されたアクティブ Hessian は変位と勾配差分を使用した Bofill 更新により更新されます。各ループで虚振動数モードを推定し、1 回平坦化し、Dimer 方向を更新し、Dimer + L-BFGS マイクロセグメントを実行します。
Hessian TS オプティマイザ:
デフォルトの RS-P-RFO、または明示的に選択した RS-I-RFO / TRIM を、
rsirfoYAML セクションの共通設定で実行します。--flattenが有効で収束後に 2 つ以上の虚振動数モードが残る場合、余分なモードを平坦化し、1 つだけ残るか反復上限に達するまで選択中のオプティマイザを再実行します。
モードエクスポートと変換 — 最終振動解析で得た虚振動数モードを
vib/imag_*_trj.xyzに書き出し、PDB 入力で変換が有効なら.pdbにもミラーリングします。共有freq.zero_cutoff_cmにより|frequency| <= cutoffのモードを鞍点分類とtrajectory出力の両方から除外します。PDB 入力で変換が有効な場合、最終構造は独立して PDB に変換されます。--dumpは最適化軌跡の出力と変換を追加します。
出力¶
result.json は数値最適化と終端 exact PHVA の分類を分離します。
optimization_status は converged / not_converged / stalled、
saddle_validation は first_order / higher_order / no_imaginary /
unavailable、hessian_status は終端 PHVA の completed / failed / skipped /
unavailable を表します。終端 PHVA は数値収束後だけ実行し、非収束または
stalledなら最終構造を保持してPHVAをskipします。PHVA が失敗しても構造を
破棄せず、振動数を捏造せずに理由を記録します。
数値収束済み高次停留点は、有効な負 root がある場合に限り警告付き診断 IRC に
使うことがありますが、一次 TS 認定ではありません。数値非収束、虚振動 0 本、
PHVA 失敗/skip、または有効な負 root なしでは、all は TS 成果物登録後に IRC
前で停止します。明示的な --skip-final-freq は最終構造を保持しますが鞍点次数と
負の IRC 方向を検証できないため、all では IRC 前停止になります。
最適化が成功すると 3 種類の成果物が result_tsopt/ に出力されます。
result_tsopt/final_geometry.pdb（またはfinal_geometry.xyz）result_tsopt/vib/imag_*_trj.xyzresult_tsopt/vib/imag_*.pdb
out_dir/ (デフォルト: ./result_tsopt/)
├── result.json # --out-json 時。rigid_projection provenance を含む
├── final_geometry.xyz # 常に書き出し
├── final_geometry.pdb # 入力が PDB の場合
├── optimization_all_trj.xyz # 連結 Dimer セグメント（--dump 時）
├── optimization_all.pdb # 対応する PDB（--dump かつ入力が PDB の場合）
├── vib/
│ ├── imag_NN_±XXXX.XXcm-1_trj.xyz # 虚振動数モード軌跡
│ └── imag_NN_±XXXX.XXcm-1.pdb # 虚振動数モードに対応する PDB
└── .dimer_mode.dat # Dimer 方向シード
CLI オプション¶
完全なフラグ一覧は生成されたコマンドリファレンスを参照してください。以下の表は説明が必要なオプションのみを扱い、網羅一覧の手動複製は行いません。
オプション |
説明 |
デフォルト |
|---|---|---|
入力と電荷 |
||
|
開始ジオメトリ（PDB または XYZ）。XYZ の場合はトポロジーに |
必須 |
|
入力が XYZ の場合の参照 PDB トポロジー。 |
None |
|
全酵素の Amber parm7 トポロジー。 |
必須 |
|
ML 領域原子を含む PDB。 |
None |
|
ML 領域のカンマ区切り原子インデックス（範囲指定可）。 |
None |
|
|
|
|
入力 PDB の B 因子から ML/MM レイヤーを自動検出。 |
有効 |
|
ML 領域の総電荷。 |
None（ |
|
残基ごとの電荷マッピング（例: |
None |
|
ML 領域のスピン多重度 (2S+1)。 |
None（デフォルト 1） |
アクティブ領域の凍結 |
||
|
凍結する 1 始まりカンマ区切りインデックス（YAML |
None |
|
ML 領域からの Hessian-MM 原子の距離カットオフ (Å)。未指定時は最終解析に必要な可動 MM 原子をすべて含めます。 |
None |
|
可動 MM 原子の距離カットオフ (Å)。 |
None |
TS 探索とオプティマイザモード |
||
|
MLIP Hessian モード: |
|
|
|
None |
|
最大総オプティマイザサイクル。 |
|
|
TS オプティマイザモード: |
|
|
マイクロイテレーション: 1 ステップの macro TS 移動（RS-I-RFO / RS-P-RFO / TRIM）+ MM 緩和（L-BFGS）を交互に実行。任意の Hessian モード（ |
|
|
|
|
収束と平坦化 |
||
|
収束プリセット（ |
None |
|
余分な虚振動数モード平坦化ループの有効化/無効化。 |
None（CLI デフォルトは無効 = |
|
平坦化ループでの虚振動数モード検出に active-coordinate Hessian block または full Hessian を使用。 |
|
|
最終振動解析のアクティブ自由度: |
|
|
終端 frequency/PHVA 検証をスキップ。最終 TS 候補は保持しますが鞍点次数と負の IRC 方向は未検証となり、 |
|
バックエンドと計算 |
||
|
ML 領域の MLIP バックエンド: |
|
|
MLIP バックエンド精度。省略時は UMA/AIMNet2 fp32、ORB/MACE fp64。AIMNet2 は fp64 を拒否。 |
バックエンド依存 |
|
UMA predictor worker 数。2 以上は |
|
|
UMA 並列 predictor のノード当たり worker 数。 |
None |
|
警告を出した上で ML 領域の電荷・多重度の電子パリティ検証を省略。開殻の ML 領域には整合する多重度を指定してください。共有結合を切断した領域など、意図的な非標準入力の場合のみ使用。 |
off |
|
REAL と MODEL の両 MM 層で CMAP を保持します。 |
|
|
MM backend。 |
|
|
link atom 配置方式。 |
|
出力と設定 |
||
|
連結軌跡 |
|
|
PDB 入力時の XYZ/TRJ から対応する PDB の生成を切り替え。 |
|
|
出力ディレクトリ。 |
|
|
明示 CLI オプションより前に適用するベース YAML 設定ファイル。 |
None |
|
解決後の設定レイヤーを表示して実行を継続。 |
|
|
machine-readable |
|
|
実行せずに入力/設定を検証し、実行計画を表示。 |
|
YAML 設定¶
設定は デフォルト < config < 明示 CLI の順で適用されます。 共有セクションは YAML リファレンス を再利用します。ワークフローに合致している場合は以下のブロック全体をそのまま保持し、変更が必要な値のみ調整してください。
geom:
coord_type: cart # 座標タイプ: デカルト vs dlc 内部座標
freeze_atoms: [] # 1 始まり凍結原子（CLI/リンク検出とマージ）
tr_projection: constrained # 固定の内部 PHVA 処理
calc:
model_charge: 0 # 総電荷（CLI 上書き）
model_mult: 1 # スピン多重度 2S+1
real_parm7: real.parm7 # Amber parm7 トポロジー
model_pdb: ml_region.pdb # ML 領域定義
backend: uma # ML バックエンド (uma/orb/mace/aimnet2)
uma_model: uma-s-1p2 # uma-s-1p2 | uma-m-1p1
uma_task_name: omol # UMA タスク名 (backend=uma 時)
ml_device: auto # ML デバイス選択
hessian_calc_mode: Analytical # Hessianモード（デフォルトは FiniteDifference; Analytical は opt-in）
opt:
thresh: baker # 収束プリセット（Gaussian/Baker 式）
max_cycles: 100000 # オプティマイザサイクル上限
print_every: 100 # ログ出力間隔
min_step_norm: 1.0e-08 # ステップ受け入れの最小ノルム
assert_min_step: true # ステップが閾値以下で停止
rms_force: null # 明示的 RMS 力目標
rms_force_only: false # RMS 力収束のみに依存
max_force_only: false # 最大力収束のみに依存
force_only: false # 変位チェックをスキップ
converge_to_geom_rms_thresh: 0.05 # 参照への収束時の geom RMS 閾値
overachieve_factor: 0.0 # 閾値を厳しくする係数
check_eigval_structure: false # Hessian固有値構造の検証
line_search: true # ラインサーチを有効化
dump: false # 軌跡/リスタートデータのダンプ
dump_restart: false # リスタートチェックポイントのダンプ
prefix: "" # ファイル名プレフィックス
out_dir: ./result_tsopt/ # 出力ディレクトリ
hessian_dimer:
thresh_loose: gau_loose # ゆるい収束プリセット
thresh: baker # メイン収束プリセット
update_interval_hessian: 500 # Hessian再構築間隔
neg_freq_thresh_cm: 5.0 # freq.zero_cutoff_cm の互換alias (cm^-1)
flatten_amp_ang: 0.1 # flattening振幅 (Å)
flatten_max_iter: 50 # flattening反復上限（--no-flatten 時は無効）
flatten_sep_cutoff: 0.0 # 代表原子間の最小距離 (Å)
flatten_k: 10 # モードごとにサンプルされる代表原子数
flatten_loop_bofill: false # flattening変位に対する Bofill 更新
mem: 100000 # ソルバーのメモリ上限
device: auto # 固有値ソルバーのデバイス選択
root: 0 # 対象 TS ルートインデックス
dimer:
length: 0.0189 # Dimer 間隔 (Bohr)
rotation_max_cycles: 15 # 最大回転反復数
rotation_method: fourier # 回転オプティマイザ手法
rotation_thresh: 0.0001 # 回転収束閾値
rotation_tol: 1 # 回転許容係数
rotation_max_element: 0.001 # 回転行列の最大要素
rotation_interpolate: true # 回転ステップの補間
rotation_disable: false # 回転を完全に無効化
rotation_disable_pos_curv: true # 正の曲率検出時に無効化
rotation_remove_trans: true # 選択した剛体null成分を除去
trans_force_f_perp: true # 並進に垂直な力を射影
bonds: null # 拘束用の結合リスト
N_hessian: null # Hessianサイズの上書き
bias_rotation: false # 回転探索にバイアス
bias_translation: false # 並進探索にバイアス
bias_gaussian_dot: 0.1 # ガウスバイアスの内積
seed: null # 回転用の RNG シード
write_orientations: false # 回転方向を書き出し（明示的な true も可）
forward_hessian: true # Hessianを前方伝播
lbfgs:
thresh: baker # L-BFGS 収束プリセット
print_every: 100 # ログ出力間隔
min_step_norm: 1.0e-08 # 受け入れ最小ステップノルム
assert_min_step: true # ステップ停滞時にアサート
max_step: 0.3 # 最大ステップ長
control_step: true # 適応的ステップ長制御
double_damp: true # ダブルダンピングセーフガード
keep_last: 7 # L-BFGS バッファの履歴サイズ
beta: 1.0 # 初期ダンピングベータ
mu_reg: null # 正則化強度
max_mu_reg_adaptions: 10 # mu 適応の上限
line_search: false # Dimer 内側では必須（true は拒否）
rsirfo:
thresh: baker # Hessian TS 収束プリセット
trust_radius: 0.10 # 初期信頼半径（ONIOM 向けに小さめ）
trust_update: true # 適応的信頼半径更新
trust_min: 1.0e-04 # 最小信頼半径
trust_max: 0.10 # 最大信頼半径（ML/MM 安定性のため調整）
max_energy_incr: null # ステップごとの最大許容エネルギー増加
hessian_update: bofill # Hessian更新方式の上書き
hessian_init: calc # 初期Hessianソース
hessian_recalc: 500 # N ステップごとにHessian再計算
hessian_recalc_adapt: null # 適応的Hessian再計算
small_eigval_thresh: 1.0e-08 # 小固有値の閾値
alpha0: 1.0 # 初期シフトパラメータ
max_micro_cycles: 50 # マクロサイクルごとのマイクロイテレーション
track_mode_by_overlap: false # ステップ間の固有ベクトル重なりで TS モードを追跡
Tip
最適化中に TS モードが別のルートに切り替わる場合（例: 複数の虚振動数が存在する場合）は rsirfo.track_mode_by_overlap: true を設定してください。
Tip
TS 収束が遅い場合や最適化中に TS モードが失われる場合は、rsirfo セクションの hessian_recalc を小さくしてみてください（例: 50–200）。正確なHessian再計算の頻度を上げることで、追加のHessian評価コストと引き換えに堅牢性が向上します。
注記¶
凍結境界 PHVA と質量加重 TR 処理は freq.py と共通です。
constrained（デフォルト）は、凍結 anchor をすべて動かさない全系剛体運動だけを
除去します。一般的な有効 rank は anchor が 0/1/2/非共線の 3 個以上のとき
6/3/1/0 で、実用的な ML/MM 境界では通常 0 です。全原子凍結は明示的なエラーになります。
Dimer は中心imageが変わるたびにこの基底を再構築して方向と回転forceに適用し、
凍結境界に対する有限曲率運動であるactive fragmentの並進は差し引きません。
固定の constrained 剛体モード処理と --ref-mode は別の機能です。後者はTS root選択と
overlap追跡に使う高度な 3N MEP 接線を与えます。geom.tr_projection の古い非constrained値は明示的に拒否されます。
--out-json 時は
result.json.rigid_projection に treatment、有効 rank、Hessian source、Hessian shape を記録します。
Note
rsirfo.trust_max のデフォルトは 0.10 bohr です。TS 近傍での ML/MM 安定性が改善します。
共有 opt ブロックには エネルギープラトー停止（デフォルト無効、--stop-plateau で有効化）があります。plateau では stalled として停止し、未収束の max_cycles 到達時と同様に終端 PHVA を実行しません。MM micro 反復には適用されません。詳細は yaml-reference を参照してください。
関連項目¶
典型エラー別レシピ — 症状起点の切り分け
トラブルシューティング — 詳細なトラブルシューティングガイド
opt — 単一構造の構造最適化
freq — 検証済み TS の単一虚振動数を確認
irc — 最適化された TS からの反応経路追跡
all — ML/MM モデル構築 -> MEP 探索 -> tsopt -> IRC -> freq を連鎖させる一気通貫ワークフロー
YAML リファレンス —
hessian_dimer（Hessian ガイド付き Dimer）とrsirfoの完全な設定オプション用語集 — TS、Dimer、RS-I-RFO、Hessian の定義