概念とワークフロー¶
このページでは、mlmm-toolkit を使ううえでの 全体像 を説明します。
ML/MM 3 層システム、ONIOM 分解、「セグメント」「画像（image）」「テンプレート」が何を指すのか、そしてトップレベルの all が各サブコマンドをどう組み合わせるのかを解説します。
ワークフローの全体像¶
一般的なワークフローは以下の通りです。
全系入力 (PDB/XYZ)
│
├─ ML 領域定義 [extract] ← --center/-c を使う場合は PDB が必要
│ ↓
│ ML 領域構造 (PDB)
│ │
│ ├─ MM トポロジー構築 [mm-parm] ← parm7/rst7 の自動生成
│ │ ↓
│ │ real.parm7 + real.rst7
│ │
│ ├─ (任意) 3層定義 [define-layer] ← B-factor による層エンコード
│ │
│ ├─ (任意) 段階的スキャン [scan] ← 単一構造ワークフロー
│ │ ↓
│ │ 順序付けられた中間体
│ │
│ └─ MEP 探索 [path-opt] または [path-search]
│ ↓
│ MEP 軌跡 (mep_trj.xyz) + エネルギーダイアグラム ← ML/MM (MLIP + hessian_ff) 計算
│
└─ (任意) TS 最適化 + IRC [tsopt] → [irc]
└─ (任意) 熱化学解析 [freq]（ΔG 取得）
└─ (任意) DFT 一点計算 [dft]
各ステージはサブコマンドとして単独実行できます。また mlmm all を使うと、複数ステージをまとめて実行できます。
Important
遷移状態: HEI や tsopt の出力は TS 候補 として扱い、freq（虚振動数モードが 1 本）と irc（両端が意図した極小へ落ちる）で検証してから解釈してください。
ML/MM 3層システム¶
mlmm-toolkit の中核は、ONIOM 的な ML/MM 結合スキームです。系を以下の 3 層に分割し、各層に異なるレベルの理論を適用します。
層 |
B-factor |
計算レベル |
説明 |
|---|---|---|---|
Layer 1: ML 領域 |
0.0 |
MLIP（UMA, ORB, MACE, AIMNet2） |
活性部位。エネルギー・力・Hessian すべてを MLIP バックエンドで計算 |
Layer 2: Movable-MM |
10.0 |
hessian_ff（MM） |
最適化時に移動可能な MM 原子 |
Layer 3: Frozen |
20.0 |
MM |
座標は固定されるが、MM エネルギー相互作用には参加 |
B-factor 値は PDB ファイルの温度因子列（列 61-66）にエンコードされます。define-layer サブコマンドが ML 領域からの距離に基づいて自動設定します（--radius-freeze（デフォルト 8.0 Å）以内を Movable-MM、それより遠方を Frozen に割り当て）。Hessian 対象 MM 原子は hess_cutoff や hess_mm_atoms で別途制御します。
Tip
B-factor エンコーディングにより、B-factor カラーリングに対応した分子ビューアで層割り当てを視覚的に確認できます。
ONIOM 的エネルギー分解¶
全系の ML/MM エネルギーは次のように計算されます:
E(ML/MM) = E_MM(real) + E_ML(model) - E_MM(model)
ここで:
E_MM(real): 全系（real system）の MM エネルギー（hessian_ff）
E_ML(model): ML 領域（model system）の MLIP エネルギー（デフォルトは UMA、ORB/MACE/AIMNet2 も利用可能）
E_MM(model): ML 領域の MM エネルギー（重複分を差し引くため）
力と Hessian も同様の ONIOM 分解で結合されます。リンク水素の寄与はヤコビアンを用いて ML 原子と MM 原子に再分配されます。
MLIP バックエンドは -b/--backend（デフォルト: uma）で選択します。orb は pip install "mlmm-toolkit[orb]"、aimnet2 は [aimnet] extra でインストールします。mace には専用 extra がなく、e3nn のピンが UMA（fairchem-core）と競合するため別の conda env でインストールします。
従来の QM/MM との比較¶
側面 |
従来の QM/MM |
mlmm-toolkit ML/MM |
|---|---|---|
高レベル手法 |
DFT、HF、post-HF |
MLIP（UMA, ORB, MACE, AIMNet2） |
低レベル手法 |
OpenMM / Amber |
hessian_ff（C++ ネイティブ拡張） |
リンク原子 |
通常必要 |
共有結合境界で自動生成 |
埋め込み |
静電埋め込みが一般的 |
機械的埋め込み |
速度 |
低速（QM がボトルネック） |
高速（GPU 上の ML 推論） |
リンク原子¶
ML/MM 境界で共有結合が切断される場合、モデル（ML）系のダングリングボンドをキャップするためにリンク水素原子が挿入されます。--link-atom-method で配置方式を選択できます:
方式 |
配置 |
推奨 |
|---|---|---|
scaled (g-factor, デフォルト) |
|
推奨（滑らかな PES、定数ヤコビアン） |
fixed |
|
非推奨（座標依存ヤコビアン） |
デフォルトは scaled（Morokuma–Dapprich g-factor法）で、Gaussian ONIOM と同じ方式です。リンク原子の位置が QM–MM 距離に比例し、滑らかな PES と定数ヤコビアンを生み出します（二次微分補正不要）。fixed 方式は QM–MM 距離に依存せず一定の距離でリンク水素を配置します。
リンク原子に作用する力はヤコビアンを介して QM/MM 親原子に再分配されます:
F_QM += (1−g) · F_link (scaled の場合)
F_MM += g · F_link
線形な scaled 配置では Hessian は H_再分配 = Jᵀ H_link J です。
fixed 配置は座標依存 Jacobian を持つため、ML/MM Calculator
に示す force-weighted second-derivative term も含みます。
マイクロイテレーション¶
可動 MM 原子が多い系では、全座標の同時最適化は高コストです。高レベル（MLIP）の勾配が毎ステップ必要なため、MM 環境の緩和中も不必要な MLIP 計算が発生します。
マイクロイテレーション（Gaussian 16 方式）は最適化をマクロ/マイクロステップに分割します:
収束するまで繰り返す:
マクロステップ — ML原子 + リンク原子MM親原子を1 RFOステップ（全ONIOM力）
マイクロステップ — 残りのMM原子をL-BFGSで緩和（MM力のみ）
マクロステップ |
マイクロステップ |
|
|---|---|---|
Calculator |
全 ONIOM ( |
MM 力場のみ ( |
最適化座標 |
ML原子 + リンク原子MM親原子 |
可動MM（リンク原子MM親を除く） |
オプティマイザ |
RFO（陽的 Hessian、BFGS更新） |
L-BFGS（Hessian 不要、毎回初期化） |
収束判定 |
|
YAML の |
Note
リンク原子 MM 親原子をマクロステップに含める理由:
scaled (g-factor) 法では r_L = (1−g)·r_QM + g·r_MM により、リンク原子の位置が QM と MM 両方の親原子に結合しています。マイクロステップで MM 親原子が（ML 寄与なしの MM 力のみで）移動すると、次のマクロステップでリンク H の位置がずれ、ML エネルギー面に不連続が生じてエネルギーが振動します。MM 親原子をマイクロステップで凍結し、マクロステップで ML と一緒に動かすことで、この結合の不整合を解消します。
収束判定基準¶
pysisyphus は複数のプリセット閾値を提供します（単位: 力は Hartree/Bohr、ステップは Bohr）:
プリセット |
max(force) |
rms(force) |
max(step) |
rms(step) |
|---|---|---|---|---|
|
2.5×10⁻³ |
1.7×10⁻³ |
1.0×10⁻² |
6.7×10⁻³ |
|
4.5×10⁻⁴ |
3.0×10⁻⁴ |
1.8×10⁻³ |
1.2×10⁻³ |
|
1.5×10⁻⁵ |
1.0×10⁻⁵ |
6.0×10⁻⁵ |
4.0×10⁻⁵ |
|
3.0×10⁻⁴ |
2.0×10⁻⁴ |
3.0×10⁻⁴ |
2.0×10⁻⁴ |
baker は4列すべてに加えて前サイクルとの |dE| < 1e-6 hartree を要求します。
文献の Baker 基準（Bakken and Helgaker, J. Chem. Phys. 117, 9160 (2002)：
max(force) <= 3e-4 かつ（|dE| < 1e-6 または max(step) <= 3e-4））より
厳しい設定で、文献形は RMS force が残る構造も収束と判定しうるためです。
step 長がゼロなら構造が動かないので、エネルギー基準は構造的に満たされます。
他のプリセットでは、overachieve_factor は収束のショートカットです。
max(force) と rms(force) の両方が threshold / overachieve_factor
を下回ると、ステップサイズ基準が未達でも収束と判定します。Baker 分岐はこの
ショートカットを使いません。デフォルト設定では、マイクロイテレーションの
MM 緩和ループを含むすべてのオプティマイザで overachieve_factor は
0.0（無効）です。非 Baker プリセットでは必要に応じて YAML で有効化できます
（例: overachieve_factor: 3）。
マイクロイテレーションは --microiter で有効化します（--opt-mode hess 時のデフォルト）:
mlmm opt -i layered.pdb --parm system.parm7 -q 0 --opt-mode hess --microiter
mlmm opt -i layered.pdb --parm system.parm7 -q 0 --opt-mode hess --no-microiter # 無効化
hessian_ff: MM エンジン¶
hessian_ff は Amber 力場パラメータ（parm7）をベースとした C++ ネイティブ拡張の力場計算エンジンです。エネルギー・力、そして特に解析 Hessianを計算します。主な特徴:
結合、角度、二面角、不正二面角項
ファン・デル・ワールス（Lennard-Jones）相互作用
静電相互作用
解析的二次微分（Hessian）
CPU 実行（GPU メモリを MLIP 推論に専有させるため）
CMAP トーション補正（parm7 に含まれる場合は両 MM 層で保持）
hessian_ff は解析 MM Hessian を提供します。OpenMM backend を選ぶ経路では MM Hessian を有限差分で構成します。
Amber parm7/rst7 トポロジー¶
内部の MM 計算には Amber トポロジーファイルが必要です:
parm7（prmtop）: Amber のトポロジーファイル。原子タイプ、結合、角度、二面角、VDW パラメータ、部分電荷などを含む
rst7（inpcrd）: Amber の座標/速度ファイル。原子座標を含む（ユーザーが直接指定する必要はない。mlmm は入力 PDB から座標を読み込む）
mm-parm サブコマンドが AmberTools（tleap、antechamber、parmchk2）を使用して PDB から parm7/rst7 を自動生成します。具体的には:
非標準残基（基質、補因子）の自動識別
GAFF2（General Amber Force Field 2）によるパラメータ化
AM1-BCC 部分電荷の割り当て
タンパク質残基には ff19SB で完全なトポロジーを構築
主要オブジェクトと用語¶
全系と ML 領域¶
全系: 元の入力構造（酵素ならタンパク質-基質複合体など）。
ML 領域: MLIP バックエンドで扱う反応部位。
extractサブコマンドで指定した基質からの距離に基づいて定義されます。
ML 領域定義は主に以下で制御します。
-c/--center: 基質の指定（残基ID、残基名、または基質のみのPDB）-r/--radius,--radius-het2het,--include-h2o,--exclude-backbone,--add-linkh,--selected-resn
ML 領域の指定には 2 通りあります。
自動切り出し（
-c/--center）:extract/allが、必要に応じて default-off の--exclude-backboneを使って Cα–Cβ 境界で主鎖を切断し、残基・--modified-residue・-l/--ligand-chargeから model 電荷を導出します。 カタログ未登録の非標準アミノ酸は--modified-residue NAME:charge、リガンドは-l NAME:chargeで与え、-qは不要です。登録済みの残基は電荷を省略しても カタログ値を保持します。手動（
--model-pdb+--parm）: ML 原子の選択を自分で与え、model 電荷は-qで明示 します。電荷が変わる原子を手で編集した場合（独自の切断・プロトン化/電荷変更で自動導出が 当てにならない場合）や、自動切り出しが扱えない異常トポロジーで確実です。この経路では--modified-residue/-lは効かず、model PDB にリンク水素を入れる必要もありません — ML/MM calculator が--parmのトポロジーから ML/MM 境界に付与します。
個別サブコマンドでは、同じ原子選択を --model-indices（デフォルトは1始まり）または
--detect-layer（B 因子 0 = ML、10 = movable MM、20 = frozen MM）でも指定できます。
優先順位は --model-pdb → --model-indices → B 因子検出です。いずれも実在原子だけを
指定し、runtime link H は含めません。
デフォルトの link_mlmm: null では、ML 選択の片側だけに端点を持つ parm7 結合を境界として
link H を自動生成します。原子間距離から境界結合を推定することはありません。座標は、
トポロジーで結合を決めた後の H 配置にだけ使います。特殊なトポロジーでは YAML の
calc.link_mlmm でペアを明示的に上書きできます。各ペアは
[ML側selector, MM側selector] の順で、全系PDBのselectorを使います。空list [] は
link Hを明示的に無効化します。
calc:
link_mlmm:
- ["A:LIG:1:C1", "A:ALA:2:CA"]
信頼できるmodel.pdbの作り方¶
model.pdb は独立に再構築したクラスターではなく、全系 PDB / parm7 から選んだ
原子選択ファイルです。原子名、残基名／番号、chain ID、full-system内の原子順序を
変えないでください。原子の再採番・並べ替え、リンク水素の手動追加、別途水素付加したモデルのエクスポートは
行いません。
反応中心、共有結合cofactor／partner、path中にprotonationまたは結合が変化する原子を 完全にML領域へ含めます。
protein主鎖断片は、両端の主鎖末端が一貫してCα（
CA）になる範囲を選び、 境界原子価はML/MM link処理に任せます。側鎖・ligand・cofactor境界は、可能な限り脂肪族のC–C単結合 （
CA–CBまたは反応中心からさらに外側）に置きます。peptide C–N、極性C–N/C–O、 芳香族／共役、S–S、金属配位結合を切らず、結合相手を含めるか境界を移します。R/IM/Pのfull systemは同一原子・同一順序とし、同一の
model.pdbselectionを再利用します。 各状態で独立にmodelを作るとatom mappingとbarrier比較が無効になります。production前に全境界を目視し、ML領域のcharge/multiplicityを確認します。
define-layerはlayerを付与するだけで、化学的に悪い境界は修復しません。
Real system と Model system（ONIOM 用語）¶
Real system（実系）: すべての原子（3 層すべて）。MM（低レベル）で評価されます。
Model system（モデル系）: ML 領域（Layer 1 のみ）。MLIP（高レベル）と MM（低レベル）の両方で評価されます。
画像（image）とセグメント¶
イメージ（image）: Growing String Method (GSM) などの Minimum Energy Path (MEP) 探索手法における経路上の 1 つの構造（1 ノード）。
セグメント: 2つの端点を結ぶ MEP。多構造入力は、隣接する端点ペアごとのセグメントに分解されます。
テンプレートとファイル変換（--convert-files）¶
mlmm-toolkit は軌跡（例: mep_trj.xyz, finished_irc_trj.xyz）を出力します。トポロジー対応の入力（PDB テンプレート）がある場合、対応するファイルも出力できます:
PDB テンプレートがあれば対応する
.pdb
この動作は --convert-files/--no-convert-files（デフォルト: --convert-files）でグローバルに制御します。
代表的な3つの使い方¶
1) 複数構造の MEP 探索（R →… → P）¶
すでに反応座標に沿った 2つ以上 の構造がある場合。
例:
mlmm -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3'
2) 単一構造のスキャン定義ワークフロー → MEP¶
複数の端点構造を用意するより、反応座標を自分で定義したい場合。
例:
mlmm -i holo.pdb -c '308,309' -l 'MMT:-1' \
--scan-lists '[("TYR,285,CA","MMT,309,C10",2.20)]'
3) TSOPT のみ（ML/MM TS 最適化）¶
TS 候補がすでにある、あるいは 1 構造で TS 最適化だけ試したい場合。
例:
mlmm -i ts_guess.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3' --tsopt
all と個別サブコマンドの使い分け¶
mlmm all を推奨するケース¶
ML/MM モデル構築 → MEP 探索 → TSOPT/IRC → freq/DFT まで まとめて 実行したい
出力ディレクトリやログ管理を 1 コマンドに寄せたい
個別サブコマンドを推奨するケース¶
各ステージを 1 つずつ実行し、その都度結果を確認したい。複雑な反応では、一括実行よりもステップごとの実行が有効なことが多い
カスタムワークフローを組みたい場合（例: 独自の端点準備）
前回の実行から parm7/rst7 と層付き PDB ファイルがすでにある場合
oniom-export --mode g16|orcaで Gaussian/ORCA ONIOM 入力を生成したい
CLI に関する重要な注意点¶
Important
ブール値オプションは
--flag/--no-flagと--flag True/False（yes/no,1/0含む）の両方を受理します。新規スクリプトでは toggle 形式を推奨します。複数 PDB を与える場合、各ファイルは 同じ原子が同じ順序 で並んでいることが重要です（座標だけが異なる）。
酵素の反応機構解析では、水素を含んだ入力 PDB を用意することを強く推奨します。
ML/MM 計算には parm7 トポロジーが必須です。
allワークフローでは自動生成されますが、個別サブコマンドでは--parm（全系トポロジー）と、--model-pdb、--model-indices、または有効な B-factor layer のいずれかによる ML 領域指定が必要です。
次に読むページ¶
入門¶
はじめに – インストールと初回実行
典型エラー別レシピ – 症状起点の切り分け
トラブルシューティング – よくあるエラーと対処法
主要サブコマンド¶
サブコマンド |
用途 |
ドキュメント |
|---|---|---|
|
一気通貫ワークフロー |
|
|
ML 領域定義 |
|
|
Amber トポロジー構築 |
|
|
3 層 ML/MM 領域定義 |
|
|
再帰的 MEP 探索 |
|
|
TS 最適化 |
|
|
振動解析 |
|
|
DFT 一点計算 |
|
|
Gaussian ONIOM / ORCA QM/MM 入力生成（ |
リファレンス¶
YAML リファレンス – 全オプションの YAML 設定
用語集 – 用語リファレンス