MLIP Backends¶

mlmm-toolkit は、あらゆる ML/MM ワークフローステージ（opt、scan、tsopt、freq、irc、path-search,…）を単一の MLMMCore ONIOM 結合オブジェクトを通じて実行します。MLMMCore は ML 領域を、private な _create_ml_backend ファクトリ経由でバックエンドごとのアダプタ（_UMABackend / _OrbBackend / _MACEBackend / _AIMNet2Backend）にディスパッチします。このページでは、バックエンドの選択方法、バックエンドごとの kwargs、新しいバックエンドの追加方法を説明します。

Public surface¶

from mlmm.backends.mlmm_calc import MLMMCore, MLMMASECalculator, mlmm

# Primary entry: ML/MM ONIOM core. Takes parm7 + layered PDB + model-PDB and
# returns energy / forces / (partial) Hessian on the full system.
core = MLMMCore(
    input_pdb="layered.pdb",
    real_parm7="real.parm7",
    model_pdb="model.pdb",
    backend="uma",          # one of: "uma", "orb", "mace", "aimnet2"
    model_charge=0, model_mult=1,
    uma_model="uma-s-1p1",
    uma_precision="fp32",   # or "fp64" (full-precision base inference)
)

# ASE adapter (DMF and other ASE-based stages)
ase_calc = MLMMASECalculator(core)

# pysisyphus Calculator adapter (opt / tsopt / freq / irc / path-search stages)
pysis_calc = mlmm(
    input_pdb="layered.pdb",
    real_parm7="real.parm7",
    model_pdb="model.pdb",
    backend="uma",
    model_charge=0, model_mult=1,
)

内部的には、MLMMCore.__init__ が _create_ml_backend(backend, ...)（mlmm/backends/mlmm_calc.py 内の private なファクトリ）を呼び出して適切なアダプタをインスタンス化します。このファクトリは未知のバックエンドに対して ValueError を送出します。mlmm には 'auto' フォールバックはありません。ワークフローコードが CLI で解決されたバックエンド名を渡します。

File map¶

file	role
`mlmm/backends/__init__.py`	`apply_precision_to_calc_cfg()` — 統一された `--precision fp32\|fp64` CLI フラグを各バックエンドのネイティブ kwarg（`uma_precision` / `orb_precision` / `mace_dtype`）にルーティングします
`mlmm/backends/mlmm_calc.py`	`MLMMCore`（ML/MM ONIOM 結合）+ `MLMMASECalculator`（ASE）+ `mlmm`（pysisyphus Calculator）+ バックエンドごとのアダプタ（`_UMABackend`、`_OrbBackend`、`_MACEBackend`、`_AIMNet2Backend`）+ private な `_create_ml_backend` ファクトリ + FD-Hessian の組み立て + 単位変換
`mlmm/backends/xtb_embedcharge_correction.py`	MM→ML 環境効果のための xTB 点電荷埋め込み補正（`--embedcharge` フラグ）

Per-backend characteristics¶

backend	install	model identifier	precision option
`uma`	`pip install fairchem-core` + HF auth	`uma-s-1p1` / `uma-m-1p1`	`uma_precision="fp32" \| "fp64"`
`orb`	`pip install orb-models`	`orb_v3_conservative_omol`	`orb_precision="float32-high" \| "float64"`（`"float32"` も別名として受理）
`mace`	専用環境: `pip uninstall -y fairchem-core && pip install mace-torch`（`e3nn` の pin が UMA と競合）	`MACE-OMOL-0`	`mace_dtype="float32" \| "float64"`
`aimnet2`	`pip install aimnet`	`aimnet2`	n/a

UMA fp64¶

OMol で訓練された UMA をデフォルトの fp32 から fp64 に切り替えると、TSopt + Hessian に無視できない影響を与える場合があります。次のように有効化します:

mlmm tsopt -i ts.pdb --parm real.parm7 -q 0 -m 1 --precision fp64...
mlmm freq -i opt.pdb --parm real.parm7 -q 0 -m 1 --precision fp64...
mlmm irc -i ts.pdb --parm real.parm7 -q 0 -m 1 --precision fp64...

統一された --precision フラグは、mlmm/backends/__init__.py の apply_precision_to_calc_cfg によって各バックエンドのネイティブ kwarg（UMA は uma_precision、ORB は orb_precision、MACE は mace_dtype）へルーティングされます。

統一された --backend-model NAME フラグも同様に、選択中の --backend のモデル変種を上書きし、apply_backend_model_to_calc_cfg によってバックエンドのモデル kwarg （uma_model / orb_model / mace_model / aimnet2_model）へルーティングされます。未指定ならバックエンドデフォルトのモデルを使用します。

または YAML 設定経由（バックエンドごとの kwarg 名）:

calc:
 uma_precision: fp64

InferenceSettings API のために fairchem-core ≥ 2.0 が必要です。

Custom backend — bring your own ASE Calculator (`--calc-file`)¶

組み込みの MLIP バックエンドに加えて、ML 領域を実行時に --calc-file で指定した任意の ASE Calculator で駆動できます（mlmm_toolkit 本体の変更は不要）。これにより ML/MM ONIOM の ML 側を GFN-xTB（tblite / xtb-python 経由）、DFTB+、ORCA、Psi4 など ASE 互換の任意エンジンと結合できます。境界は標準の ASE Calculator インターフェース（エネルギー eV、力 eV/Å）で、既存の _ASEMLBackend アダプタがラップします。

ASE Calculator を返す get_calculator ファクトリを持つ Python ファイルを用意します:

# my_calc.py（最小の例）
from ase.calculators.emt import EMT

def get_calculator(charge=0, spin=1, device="auto", **kwargs):
    return EMT()

EMT() を使いたいエンジンに差し替えてください — 例えば GFN-xTB なら tblite.ase.TBLite(...)、DFTB+ の ASE calculator、ase.calculators.orca.ORCA(...) など。このファイルを単一ステージのサブコマンドに渡すと、custom ML バックエンドが選択され --backend を上書きします:

mlmm sp    -i complex.pdb --parm system.parm7 --calc-file my_calc.py -q 0 -m 1
mlmm opt   -i complex.pdb --parm system.parm7 --calc-file my_calc.py
mlmm freq  -i complex.pdb --parm system.parm7 --calc-file my_calc.py

補足:

ファクトリには、シグネチャが受け取る場合（または **kwargs を宣言している場合）に charge・spin（多重度。mult / multiplicity でも渡されます）・device が渡されるため、全電荷が必要なエンジン（xTB など）も設定できます。ファクトリ名を変える場合は --calc-factory NAME、モジュール直下の Calculator インスタンスも受け付けます。
カスタム calculator が駆動するのは ML 領域のみで、MM 側は通常どおり hessian_ff / OpenMM バックエンドを使い、ONIOM カップリングも変わりません。 Hessian は有限差分経路を使うため、freq や tsopt --opt-mode hess も任意エンジンで動作します。凍結原子も通常どおり尊重されます。
単一ステージのサブコマンド（sp・opt・tsopt・freq・irc・scan / scan2d / scan3d・path-opt・path-search）で利用できます。独自の --backend 名を持つ恒久的なバックエンドにする場合は、以下のレシピを参照してください。

Add-a-backend recipe (5 steps)¶

--backend xyz として公開する新しいバックエンド XYZModel を追加するには:

バックエンドアダプタを作成 — mlmm/backends/mlmm_calc.py（あるいは大きくなる場合は mlmm/backends/xyz.py のような新規ファイル）に、_MLBackend（ABC）を継承する _XYZBackend(_MLBackend) を実装します。ASE 経路が必要な場合は並行して _XYZASEBackend も実装します。どちらも共通 kwargs（charge / spin / device / freeze_atoms / hessian_calc_mode / return_partial_hessian / hessian_double / print_timing / model）と、バックエンド固有の kwargs（precision、 default_dtype など）を受け取る必要があります。
_MLBackend に準拠 — 抽象メソッド eval(atoms, need_grad=True) -> (E_eV, F_eV, opaque)（エネルギーは eV、力は eV/Å、加えてバックエンド固有の opaque オブジェクト）、hessian_analytical(opaque, n_atoms, *, dtype) -> torch.Tensor（Hessian を eV/Å² で返す）、および supports_analytical_hessian と device プロパティを実装します。_MLBackend を継承すると、汎用の有限差分 hessian_fd(...)（バックエンドが解析的 Hessian を持たない場合に使用）をそのまま利用できます。
_create_ml_backend に登録 — mlmm/backends/mlmm_calc.py のファクトリを拡張して、 backend == "xyz" を _XYZBackend(...) にディスパッチします。 MLMMCore が転送できるよう、新しいバックエンドの kwargs を _create_ml_backend(...) のシグネチャに追加します。
統一された --precision フラグを配線（任意） — バックエンドが精度の設定項目を公開する場合は、 mlmm/backends/__init__.py の _PRECISION_DISPATCH 内の "fp32" と "fp64" の両方に "xyz": (kw_name, kw_value) エントリを追加し、ユーザー向けの --precision fp32|fp64 CLI フラグが正しくルーティングされるようにします。
ドキュメント化 + smoke — このページの file map / バックエンドごとのテーブルにエントリを追加し、 model identifier + インストールコマンドを記載し、新しいバックエンドが end-to-end で動作確認されるよう tests/smoke/run.sh に xyz 行を追加します。

VRAM invariant (ML/MM-specific)¶

ML/MM ONIOM ジョブでは、ML バックエンドが PySCF（DFT 補正）、 parmed（parm7）、MM 力場配列と同一デバイス上に共存します。mlmm/backends/mlmm_calc.py 内の方向ごとの FD-Hessian ループは、この合計メモリ使用量に収まるよう設計されています。GPU smoke ゲート全体（tests/smoke/run.sh）の再実行とピーク VRAM の監視を行わない限り、方向ごとのループをバッチ化テンソルにリファクタリングしないでください。さもないと全タンパク質 ML/MM の all ジョブが OOM します。ステージランナーはステージ間で del calc を行い、all ワークフローはステージ境界で gc.collect() を実行します。これは public contract の一部であり、ワークフローのリファクタリング時に削除してはなりません。

ONIOM coupling vs raw MLIP¶

mlmm/backends/mlmm_calc.py の MLIP アダプタは、ML 領域のみを評価します。減算的 ONIOM エネルギー式（# CHEMISTRY-RULE:1）、リンク原子 Hessian の B 行列射影（# CHEMISTRY-RULE:2）、3 層 5 パスの partial Hessian 組み立て（# CHEMISTRY-RULE:8）は、同じファイル内に存在します。新しい MLIP を追加するバックエンドの作成者は ONIOM 結合を知る必要はありません。ML 領域のエネルギー / 力 / Hessian を正しい単位で返す Calculator を公開するだけで十分です。