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、新しいバックエンドの追加方法を説明します。

公開インターフェース¶

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-1p2",
    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	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 の組み立て + 単位変換

バックエンド別の特性¶

backend	install	model identifier	precision option
`uma`	`pip install fairchem-core` + HF auth	`uma-s-1p2` / `uma-s-1p1` / `uma-m-1p1`	`uma_precision="fp32" \| "fp64"`
`orb`	`pip install orb-models`	`orb_v3_conservative_omol`	`orb_precision="float32-high" \| "float32-highest" \| "float64"`（`fp32` / `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）へルーティングされます。

--precision を指定しない場合、デフォルト値はバックエンドごとに決まります。

backend	デフォルト	理由
`uma`	fp32	上流 fairchem のベースライン。
`orb`	fp64	backend default。
`mace`	fp64	MACE は上流で `default_dtype="float64"` をデフォルトとする。
`aimnet2`	fp32	精度の切り替えを持たない。

対応する両精度について、対象 backend/model/system で energy、force、 frequency、runtime、memory を比較してください。精度の選択にかかわらず frequency と IRC による独立検証が必要です。

統一された --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 が必要です。

カスタムバックエンド — 独自の 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(...) など。このファイルを各stageまたはallに渡すと、custom ML backendが選択され --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
mlmm all   -i R.pdb P.pdb --parm system.parm7 --calc-file my_calc.py -q 0 -m 1

補足:

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

バックエンド追加レシピ（5 ステップ）¶

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

バックエンドアダプタを作成 — mlmm/backends/mlmm_calc.py（あるいは大きくなる場合は mlmm/backends/xyz.py のような新規ファイル）に、_MLBackend（ABC）を継承する _XYZBackend(_MLBackend) を実装します。ASE 経路が必要な場合は並行して _XYZASEBackend も実装します。 factory は共通 adapter 引数 model_charge、model_mult、ml_device と、 uma_model/uma_precision や mace_model/mace_dtype のような model/backend 固有引数を渡します。Hessian assembly precision は backend adapter ではなく MLMMCore が所有します。
_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 不変条件（ML/MM 固有）¶

ML/MM stage では、選択した ML backend と Hessian intermediate が GPU memory を使用します。topology 処理と解析 MM force field は CPU 側で、 standalone DFT は別 stage です。mlmm/backends/mlmm_calc.py の方向ごとの FD-Hessian loop は同時 displacement 評価数を制限します。この loop を変更する場合は GPU smoke suite を再実行し、peak VRAM を確認してください。stage 間では calculator を解放します。

ONIOM 結合と生の 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 を公開するだけで十分です。