tsopt¶
mlmm tsopt はレイヤー分けした酵素 PDB の遷移状態候補を一次サドル点まで精密化します。単独の TS（遷移状態）推測構造でも、path-search が抽出する最高エネルギー像（HEI）でも実行できます。
オプティマイザは 2 種類あり、--opt-mode で選択します。
RS-I-RFO（
--opt-mode hess）はデフォルトで、Hessian計算のコストを許容できる場合の保守的な選択肢です。マイクロイテレーション（--microiter、デフォルト有効）が ML 1 ステップ RS-I-RFO と MM L-BFGS 緩和を交互に実行します。Hessian-Guided Dimer（
--opt-mode grad）はより軽量な代替で、低コストな探索や複数の TS 推測構造からの素早い反復に向きます。--ml-only-hessian-dimerを付けると ML 領域のみのHessianを Dimer 方向決定に使用できます（高速）。
収束後は --flatten の余剰虚モード除去ループが質量重み付け変位で余分な負のモードを整理します。検証済み TS は正確に 1 つの虚振動数を示すべきで、必ず freq / irc でモードと結合性を確認してください。
まず 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 は拘束なしのオプティマイザです。TS 候補の拘束付き構築は scan（距離を駆動）または path-search（経路 a）で行います。
虚振動数の数が正しくないとき¶
クリーンな一次サドルは反応座標に沿った支配的な虚モードを正確に 1 つだけ持ちます。よくある失敗は、余計な 2 つ目の小さな虚モードが出る、あるいは支配的な反応モードがまったく出ないことです。
症状 |
対処 |
|---|---|
余計な 2 つ目の小さい虚モード、または支配的な反応モードがない |
|
それでもクリーンなサドルにならない |
これらを組み合わせ、 |
--flatten は余分な虚モードの平坦化ループを実行します（grad: ダイマーループ、hess: RS-I-RFO 後処理）。--no-flatten は flatten_max_iter=0 に強制します。支配的な反応モードに残留する小さい虚モードが伴う場合に特に有効です。例えば、ある変異型コリスミ酸ムターゼの TS は支配的な Claisen モード −223 cm⁻¹ に加え残留 −12.5 cm⁻¹ を伴って収束しましたが、--flatten でクリーンな単一虚振動数のサドルへ駆動できます。
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（RFO / RS-I-RFO）または opt --opt-mode hess で使ってください。path-opt / path-search は cart と dlc のみ受け付けます。DLC + リンク原子 と DLC + 3 層凍結 MM は数値的に未検証なため、論文掲載値の背後では cart がデフォルトのままです。
同じ症状からの切り分けについては 典型エラー別レシピ — レシピ 4 を参照してください。
対照を揃えた変異体 vs 野生型（あるいは機構 vs 機構）の比較¶
Important
変異体 vs 野生型（あるいは機構 vs 機構）のバリア比較では、比較するすべてのモデルが同じ原子集合 — 原子数と残基が同一 — を使わなければなりません。 さもないとエネルギー基準が異なり、対照実験として成立しません。変異体上で幾何学的に再導出した ML/可動/凍結分割は、見かけの軟モードも生みます（tsopt.n_imaginary ≥ 2、いずれも微小 → IRC が中断）。
mlmm では、野生型の B 因子レイヤーエンコーディングを変異構造に移植し --detect-layer で実行することで、野生型の ML/MM レイヤリングを保持します。
手順 |
操作 |
|---|---|
1 |
変異体を構築。残基集合は野生型と同じに保つ（変異残基の種類だけが異なる）。 |
2 |
野生型の原子ごとの B 因子レイヤーコードを |
3 |
|
mlmm all -i mutant_layered.pdb -l 'LIG:Q' \
--tsopt True --thermo True -o result_mutant
フラグ |
操作 |
理由 |
|---|---|---|
|
維持（デフォルト |
移植した B 因子を読み、ML / 可動 / 凍結レイヤーを野生型と完全に同一にする |
|
省略 |
幾何学的抽出は変異体上で異なるポケットを再導出してしまう。 |
|
維持 |
非標準リガンドの電荷は標準アミノ酸表にない。 |
|
渡さない |
|
同じ原子集合の原則は、同一酵素上で 2 つの機構を比較するときも同様に適用されます。両モデルで原子集合を同一に保ち、反応座標だけを変えます。
実行例¶
コマンド形式は 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
light モード（Dimer）+ 解析的Hessian:
# VRAM に余裕がある場合に light モード + 解析的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
heavy モード（RS-I-RFO）+ YAML 上書き:
# heavy モードを 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を解析的に評価するか有限差分で評価するかを制御します。--embedchargeで xTB 点電荷埋め込み補正を有効化できます。Light モード（Dimer）:
Hessian Dimer ステージは、部分Hessian（アクティブ部分空間、TR 射影済み）を評価して Dimer 方向を定期的に更新します。
平坦化ループが有効な場合（
--flatten）、保存されたアクティブHessianは変位と勾配差分を使用した Bofill 更新により更新されます。各ループで虚振動数モードを推定し、1 回平坦化し、Dimer 方向を更新し、Dimer + LBFGS マイクロセグメントを実行します。
Heavy モード（RS-I-RFO）:
RS-I-RFO オプティマイザを、
rsirfoYAML セクションで定義されたオプションのHessian参照ファイルとマイクロサイクル制御とともに実行します。--flattenが有効で収束後に 2 つ以上の虚振動数モードが残る場合、余分なモードを平坦化し、1 つだけ残るか平坦化反復上限に達するまで RS-I-RFO を再実行します。
モードエクスポートと変換 — 収束した虚振動数モードは常に
vib/imag_*_trj.xyzに書き出され、入力が PDB で変換が有効な場合は.pdbにもミラーリングされます。最適化軌跡と最終ジオメトリも--dump時に入力テンプレート経由で PDB に変換されます。
出力¶
最適化が成功すると 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/)
├── 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 方向シード（light モード）
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 原子に適用。 |
|
|
可動 MM 原子の距離カットオフ (Å)。 |
None |
TS 探索とオプティマイザモード |
||
|
MLIP Hessianモード: |
|
|
最大総オプティマイザサイクル。 |
|
|
TS オプティマイザモード（Choice: |
|
|
マイクロイテレーション: ML 1 ステップ（RS-I-RFO）+ MM 緩和（LBFGS）を交互に実行。 |
|
|
|
|
収束と平坦化 |
||
|
収束プリセット（ |
None |
|
余分な虚振動数モード平坦化ループの有効化/無効化。 |
None（CLI デフォルトは無効 = |
|
平坦化ループでの虚振動数モード検出に部分Hessian（ML のみ）を使用。 |
|
|
最終振動解析のアクティブ自由度: |
|
|
収束後の振動解析と虚振動数モード平坦化をスキップ。大規模非凍結系でHessian対角化が高コストな場合に有用。TS の鞍点次数は未検証のままになる。 |
|
バックエンドと計算 |
||
|
ML 領域の MLIP バックエンド: |
|
|
xTB 点電荷埋め込み補正（実験的機能）の有効化。MM 環境から ML 領域への静電的影響を考慮。 |
|
|
xTB 埋め込み用 MM 原子のカットオフ半径（Å）。 |
|
|
model parm7 に CMAP（骨格クロスマップ二面角補正）を含めるかどうか。デフォルト: 無効（Gaussian ONIOM と同一）。 |
|
出力と設定 |
||
|
連結軌跡 |
|
|
PDB 入力時の XYZ/TRJ から対応する PDB の生成を切り替え。 |
|
|
出力ディレクトリ。 |
|
|
明示 CLI オプションより前に適用するベース YAML 設定ファイル。 |
None |
|
解決後の設定レイヤーを表示して実行を継続。 |
|
|
実行せずに入力/設定を検証し、実行計画を表示。 |
|
YAML 設定¶
設定は デフォルト < config < 明示CLI < override の順で適用されます。 共有セクションは YAML リファレンス を再利用します。ワークフローに合致している場合は以下のブロック全体をそのまま保持し、変更が必要な値のみ調整してください。
geom:
coord_type: cart # 座標タイプ: デカルト vs dlc 内部座標
freeze_atoms: [] # 1 始まり凍結原子（CLI/リンク検出とマージ）
calc:
charge: 0 # 総電荷（CLI 上書き）
spin: 1 # スピン多重度 2S+1
mlmm:
real_parm7: real.parm7 # Amber parm7 トポロジー
model_pdb: ml_region.pdb # ML 領域定義
backend: uma # ML バックエンド (uma/orb/mace/aimnet2)
embedcharge: false # xTB 点電荷埋め込み補正
uma_model: uma-s-1p1 # uma-s-1p1 | 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: 10000 # オプティマイザサイクル上限
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 # 負の振動数閾値 (cm^-1)
flatten_amp_ang: 0.1 # フラットニング振幅 (Å)
flatten_max_iter: 50 # フラットニング反復上限（--no-flatten 時は無効）
flatten_sep_cutoff: 0.0 # 代表原子間の最小距離 (Å)
flatten_k: 10 # モードごとにサンプルされる代表原子数
flatten_loop_bofill: false # フラットニング変位に対する 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 # 並進成分を除去
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: true # 回転方向を書き出し
forward_hessian: true # Hessianを前方伝播
lbfgs:
thresh: baker # LBFGS 収束プリセット
max_cycles: 10000 # 反復上限
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 # LBFGS バッファの履歴サイズ
beta: 1.0 # 初期ダンピングベータ
mu_reg: null # 正則化強度
max_mu_reg_adaptions: 10 # mu 適応の上限
rsirfo:
thresh: baker # RS-IRFO 収束プリセット
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 をミラーリングし、一貫した虚振動数モード解析とモード書き出しを保証します。
Note
rsirfo.trust_max のデフォルトは 0.10 bohr です。TS 近傍での ML/MM 安定性が改善します。
共有 opt ブロックには エネルギープラトー・フォールバック（energy_plateau: true、energy_plateau_thresh: 1.0e-4 au を energy_plateau_window: 50 ステップにわたって適用、いずれもデフォルト）も備わっています。MLIP の力ノイズフロアが thresh プリセットを下回れない場合でも、エネルギー自体が停滞した時点でクリーンに収束終了します。詳細は 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の定義