tsopt（遷移状態の構造最適化）¶
tsopt サブコマンドは、層を定義した ML/MM の酵素モデルで遷移状態（TS）の候補構造を 1 次の鞍点へ最適化し、final geometry で Hessian を計算して虚振動の数（n_imag）を数えます。TS 最適化が成功すると、反応モードの虚振動が 1 つ出ます。
主な用途¶
TS 候補の仕上げ:
path-opt/path-searchの最高エネルギーのイメージ（HEI）やscanの頂点を、最適化した TS に仕上げる自作の構造の検証: 手で作った候補が TS か（n_imag = 1）を確かめ、反応モードをアニメーションで確認する
allの TS 段のやり直し:allで得た TS を、設定を変えて単独で最適化し直す
ML 領域の計算バックエンドのデフォルトは、Meta が公開した学習済みの機械学習原子間ポテンシャル（MLIP） の UMA です。-b/--backend で ORB、MACE、AIMNet2、DFT も選べます。MM 領域には --parm7 の Amber パラメータを使います。
候補がまだ無い場合は、先に次のコマンドで作ってください。
手元にあるもの |
候補を作るコマンド |
|---|---|
反応物と生成物 |
|
反応物だけ、または動かしたい結合がある |
|
候補を tsopt で最適化し、得られた TS から irc を実行してください。all を使えば、これらを一度に実行できます。
基本的な実行例¶
以下の例では、ts_guess.pdb が real.parm7 に対応する全系の候補構造、ml_region.pdb が ML 領域の定義です。
1. 標準の実行（RS-P-RFO）¶
ML 領域の電荷とスピン多重度を明示して実行します。
mlmm tsopt -i ts_guess.pdb --parm7 real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --out-dir ./result_tsopt
2. Dimer 法¶
完全な Hessian を繰り返し計算するのが重い場合や、難しい候補で別の方法を試したい場合に使います。
mlmm tsopt -i ts_guess.pdb --parm7 real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --opt-mode dimer --out-dir ./result_tsopt_dimer
3. 余分な虚振動の除去¶
候補に虚振動が 2 つ以上ある場合は --flatten を付けます。
mlmm tsopt -i ts_guess.pdb --parm7 real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --flatten --out-dir ./result_tsopt_flatten
4. 保存した Hessian から開始¶
同じ構造で freq などが --dump-hess で保存した Hessian を読み込み、計算し直さずに始めます。
mlmm tsopt -i ts_guess.pdb --parm7 real.parm7 --model-pdb ml_region.pdb \
-q 0 -m 1 --read-hess ts_guess_hess.npy --out-dir ./result_tsopt
処理の仕組みと計算仕様¶
モデルの読み込みと境界の固定: ML 領域を
--model-pdbから、可動 MM 層と固定 MM 層を入力 PDB の B-factor から読み込みます。ML 領域の 電荷 は-qまたは-lから決まります。固定 MM 層と--freeze-atomsで指定した原子は固定したままで、最後の Hessian は--active-dof-modeで選んだ原子だけで扱います（PHVA: 部分 Hessian 振動解析）。.xyzの候補には、原子の順序と層を与える全系の PDB を--ref-pdbで渡してください。最適化法の選択（
--opt-mode）:hess（デフォルト）は完全な Hessian を使う RS-P-RFO（制限ステップ分割有理関数最適化）を実行し、rsirfoとtrimはそれぞれ RS-I-RFO（restricted-step image RFO）と TRIM（trust-region image minimization）を選びます。dimer（またはgrad）は Hessian-guided Dimer 法で、勾配を使って最低固有モードを追い、ときどき厳密な Hessian で方向を更新します。反応モードに沿った探索: 反応モードの方向にはエネルギーを上り、それ以外の方向には下りながら、収束条件（
--thresh）を満たすまで構造を動かします。デフォルトのbakerは、力の最大値 3 × 10⁻⁴ 未満、力の RMS 2 × 10⁻⁴ 未満、ステップの最大値 3 × 10⁻⁴ 未満、ステップの RMS 2 × 10⁻⁴ 未満（原子単位）、エネルギー変化 10⁻⁶ hartree 未満の 5 つをすべて同時に求めます。どの値も Gaussian のデフォルト（gau）より厳しい条件です。RS-P-RFO は Bofill 式で Hessian を更新し、1 ステップを信頼半径 0.1 bohr（rsirfo.trust_max）以内に収めます。マイクロイテレーション（--microiter）はデフォルトで有効で、各マクロステップで ML 領域とそれに結合した境界の MM 原子を動かし、続いて可動 MM 原子を L-BFGS で緩和します。マイクロイテレーションでは最適化の行が[microiter]で始まり、Dimer 法と--no-microiterでは[tsopt]の形で出ます。最後の確認: 収束すると、final geometry で Hessian を計算して n_imag を数え、各虚振動モードをアニメーションとして書き出します。固定原子の扱いは
freqと同じです。--flattenによる余分な虚振動の除去: 虚振動が 2 つ以上残る場合は、余分なモードに沿って構造をずらして最適化し直し、1 つになるか回数の上限に達するまで繰り返します。Dimer 法では、各回で厳密な Hessian を計算し直してダイマー方向を更新し、短い Dimer + L-BFGS の区間を実行します。
TS の判定¶
結果は、実行がどう終わったかで決まります。
終わり方 |
端末の判定の行 |
|
|
|---|---|---|---|
収束 |
|
final geometry、n_imag、虚振動モード |
n_imag ≥ 1 なら IRC へ進み、n_imag = 0 なら IRC の前で止まる |
エネルギーが変わらなくなって停止 |
|
final geometry と n_imag |
IRC の前で止まる |
|
|
final geometry（Hessian なし） |
IRC の前で止まる |
|
|
final geometry（Hessian なし） |
反応モードを確かめられないため、IRC の前で止まる |
最後の Hessian の計算に失敗 |
|
final geometry と、 |
IRC の前で止まる |
n_imag は次のように読みます。
n_imag |
意味 |
|---|---|
1 |
1 次の鞍点。モードが狙った原子を動かしているかを確かめてから、 |
0 |
虚振動なし。構造が極小点の側へ緩和しています |
2 以上 |
高次の鞍点。余分な虚振動が残っています。 |
ν < −5.00 cm⁻¹ のモードを虚振動として数えます。−5.00 以上 0 cm⁻¹ 未満の値は数値誤差として扱います。
最適化後に n_imag が 1 でない場合¶
n_imag が 1 でない場合や、モードが狙った反応の原子を動かしていない場合は、次を試してください。これらは組み合わせて使えます。
結果 |
試すこと |
|---|---|
n_imag = 0 |
候補が鞍点から遠い状態です。経路探索や scan でよりよい候補を作ってください。 |
n_imag ≥ 2 |
各モードの動きを確かめてください。 |
モードは 1 つだが動きが違う |
どの原子が動くかを確かめ、狙った反応に近い候補から始めてください |
例として、fp64 で、flatten を有効にしてやり直す場合は次のようにします。
mlmm tsopt -i ts_guess.pdb --parm7 real.parm7 --model-pdb ml_region.pdb -q 0 -m 1 \
--precision fp64 --flatten -o result_tsopt
ほかの手は TS が取れないとき に、そのほかの失敗は トラブルシューティング にあります。
主な出力ファイル¶
実行が終わると、--out-dir（デフォルト: ./result_tsopt/）に次のファイルができます。
result_tsopt/
├─ final_geometry.xyz # final geometry（常に出力）
├─ final_geometry.pdb # 同じ構造の PDB（B-factor が層を表す）
├─ vib/
│ ├─ imag_01_-385.20cm-1_trj.xyz # 虚振動モードごとのアニメーション
│ └─ imag_01_-385.20cm-1.pdb # 同じアニメーションの PDB
├─ optimization_all_trj.xyz # 最適化の軌跡（--dump）
├─ optimization_all.pdb # 同じ軌跡の PDB（--dump）
├─ .dimer_mode.dat # Dimer の今の方向（Dimer 法のとき）
└─ result.json # 結果の要約（--out-json）
mmCIF の入力 と、PDB の欄に入りきらない大きな PDB の入力では、元の識別子を保った .cif も書きます。
final geometry:
final_geometry.*を、ircに渡す TS として使います。final_geometry.pdbの B-factor は、ML 領域が 0、可動 MM 原子が 10、固定 MM 原子が 20 です。反応モード:
vib/imag_*_trj.xyzを PyMOL や VMD で開き、生成・切断される結合に沿って原子が動いているかを確かめてください。要約:
--out-jsonを付けると、result.jsonに終わり方（optimization_status:converged、stalled、not_converged）、hessian_status、n_imag が記録されます。
主な CLI オプション¶
ML/MM の計算コマンドに共通のオプションは ML/MM の共通オプション に 1 か所でまとめてあります。下の表は tsopt に固有のものだけです。
オプション |
引数の型 |
デフォルト |
説明 |
|---|---|---|---|
|
パス |
（必須） |
全系の構造 1 つ（ |
|
整数 |
|
ML 領域の電荷。 |
|
整数 |
|
ML 領域のスピン多重度（2S+1） |
|
文字列 |
|
未知のリガンドの総電荷、または残基名ごとの電荷（例: |
|
パス |
|
出力先ディレクトリ |
|
文字列 |
|
ML 領域のバックエンド（ |
|
|
|
最適化法: RS-P-RFO / Dimer / RS-I-RFO / TRIM（ |
|
パス |
|
反応モードの参照方向（ |
|
フラグ |
|
各マクロ TS ステップと、可動 MM 原子の L-BFGS 緩和を交互に実行。Dimer 法では使わず、 |
|
|
|
ML 領域の Hessian の計算法（有限差分 / 解析的） |
|
フラグ |
|
余分な虚振動を除く |
|
文字列 |
|
追加で固定する原子（1 始まり、カンマ区切り: 例 |
|
|
|
最後の振動解析に入れる原子: 全原子 / ML 領域だけ / ML 領域と可動 MM 原子 / 固定層以外のすべての原子 |
|
プリセット |
|
収束条件（ |
|
整数 |
|
最適化サイクルの上限 |
|
フラグ |
|
エネルギーが変わらなくなったら（直近 50 サイクルの幅が 1e-4 hartree 未満）止め、Hessian を計算 |
|
フラグ |
|
収束後の最後の Hessian を省く |
|
パス |
|
Hessian を計算せず |
|
パス |
|
final geometry の Hessian を |
|
|
バックエンドごと（ |
バックエンドの精度。 |
|
|
|
最適化に使う座標系：デカルト座標 / 冗長内部座標 / 非局在化内部座標（DLC）/ 並進・回転を含む内部座標（TRIC） |
|
パス |
|
コマンドラインのオプションより前に適用する YAML ファイル |
|
フラグ |
|
最適化の軌跡 |
|
フラグ |
|
結果の要約を |
全オプションは mlmm tsopt --help-advanced または 自動生成のオプションの一覧（英語のみ） を参照してください。
補足: YAML では、Dimer 法は
hessian_dimer:ブロックを読み、RS-P-RFO・RS-I-RFO・TRIM はrsirfo:ブロックを共用し、マイクロイテレーションはmicroiter:ブロックを読みます。キーは YAML 設定の一覧のrsirfo、hessian_dimer、microiterにあります。
補足: 最適化の途中で反応モードが別の Hessian 固有ベクトル（root）に入れ替わる場合は、
rsirfo.track_mode_by_overlap: trueを設定してください。
補足: 収束が遅い場合は、
rsirfo.hessian_recalc（デフォルト500）を 50〜200 に下げてください。厳密な Hessian を計算し直す間隔が短くなり、計算は増えますが収束しやすくなります。
使用上の注意点¶
--flatten を使うとき¶
--flatten はデフォルトで無効です。flatten の回数は、Dimer 法でも RS-P-RFO・RS-I-RFO・TRIM でも、YAML の 1 つのキー hessian_dimer.flatten_max_iter で決まります。
コマンドライン |
flatten の回数 |
|---|---|
|
|
|
YAML の値（正の値の場合）、無ければ |
|
YAML に値があっても |
--flatten は余分な虚振動を除きますが、欠けている反応モードを作ることはできません。n_imag = 0 の場合は、よりよい候補を作ってください。
そのほかの注意¶
上り方向のステップは常に許可: 鞍点探索では反応モードに沿ってエネルギーを上る必要があるため、YAML で指定しても
tsoptはreject_uphill: falseを保ちます。--reject-uphill/--no-reject-uphillは、optとallの端点の最適化で使うフラグです。生成物側から scan した障壁: この候補を作った scan が生成物から始まった場合、障壁の読み方は scan: 障壁の向き を参照してください。
追う固有ベクトル（root）は 1 つ: 最適化は 1 つの固有ベクトルに沿って上ります（
0が最も低い固有値）。rsirfo.roots: [0]のように 1 要素のリストで指定します。Dimer 法ではhessian_dimer.rootを使います。tsoptに--rootフラグはありません。そのほかの RS-P-RFO の設定:
trust_norm: max_atomはステップ全体ではなく原子ごとの変位を制限し（Cartesian 座標だけ）、hessian_update: ts_bfgsは Bofill の代わりに TS-BFGS で Hessian を更新します。どちらも信頼半径は変えません。追加の探索は指定したときだけ: 収束後は、n_imag が 1 でなくても、自動では追加の探索をしません。
--flattenを使うか、rsirfo.saddle_recovery_max_cyclesを0より大きくしてください（デフォルト0）。後者では、厳密な Hessian に虚振動が無いとき、RS-P-RFO・RS-I-RFO・TRIM がエネルギーを上る向きにステップを進めます。併用できない組み合わせ:
--skip-final-freqと--dump-hess、2 以上の--uma-workers（MLIP の並列ワーカー数）と--hessian-calc-mode Analytical。--skip-final-freqと--flatten: RS-P-RFO・RS-I-RFO・TRIM では、--skip-final-freqを付けると、最後の Hessian を使う--flattenも省かれます。--read-hessを RS-P-RFO・RS-I-RFO・TRIM で使う場合: ファイルの Hessian が最初の厳密な Hessian の代わりになるので、rsirfo.hessian_initはデフォルトのcalcのままにしてください。ほかの値ではエラーで止まります。マイクロイテレーションの MM 緩和の収束条件:
microiter.micro_threshで MM 緩和の収束条件を指定します。指定しないときはマクロステップと同じ条件を使います。エネルギーの停滞とマイクロイテレーション:
--stop-plateauが見るのはマクロステップで、MM 緩和を止めることはありません。--ref-modeと固定原子:--ref-modeは MEP から反応の方向を与えるだけで、固定境界の扱いは変えません。全原子固定の禁止: すべての原子を固定すると、
tsoptはエラーで停止します。エラーでの停止: 入力や構造が不正な場合や、最適化を続けられないエラーが起きた場合は、エラーメッセージを出して止まります。それまでに書いたファイルだけが残ります。
関連ドキュメント¶
irc — 最適化した TS からの反応経路の追跡
freq — 完全な振動解析と熱化学補正
path-opt / path-search / scan — TS 候補の作成
all — モデル作成・MEP・TS 最適化・IRC・振動解析を一度に実行するワークフロー
反応機構を調べるコツ — TS が取れないときに試すこと
トラブルシューティング — 実行が失敗したときの切り分け
YAML 設定の一覧 —
rsirfo・hessian_dimer・microiterのすべての設定用語集 — TS、Dimer、Hessian などの用語
終了コード — 終了ステータスの意味