MLIP バックエンド¶

pdb2reaction は pysisyphus ベースの geometry/path ステージに MLIPCalculator を使い、DMF などの ASE ベースのステージには別の ASE calculator factory を使います。DFT ステージは PySCF/GPU4PySCF を直接使います。本ページでは、バックエンドの選択方法・バックエンドごとの kwargs・新しいバックエンドの追加方法を説明します。

バックエンドディスパッチャのパターン¶

from pdb2reaction.backends import create_calculator, create_ase_calculator

calc = create_calculator(
    backend="uma",        # one of: "uma", "orb", "mace", "aimnet2", "auto"
    charge=0, spin=1,
    device="cuda", workers=1,
    model="uma-s-1p2",
)
# calc is a pysisyphus-compatible MLIPCalculator.

# ASE-based stages (e.g. DMF path optimization) use the ASE factory:
ase_calc = create_ase_calculator(backend="uma", model="uma-s-1p2", device="cuda")

create_calculator(...) は **kwargs を各バックエンドの _BACKEND_ACCEPTED_KEYS セットと照合してフィルタし、未知のキーを警告付きで破棄します。create_ase_calculator() は独立した _ASE_ACCEPTED_KEYS を使い、未知のキーを警告なしでフィルタします。

backend="auto" は UMA → Orb → MACE → AIMNet2 の順で解決し、最初にインポートに成功したものを選択します。

ファイルマップ¶

file	role
`pdb2reaction/backends/__init__.py`	`BACKEND_REGISTRY` dict + `create_calculator()` / `create_ase_calculator()` ファクトリ + `resolve_backend('auto')` の UMA 優先フォールバック
`pdb2reaction/backends/base.py`	`MLIPCalculator(pysisyphus.calculators.Calculator)` ABC + FD-Hessian 組み立て + 単位変換 + `BackendError(RuntimeError)`
`pdb2reaction/backends/uma.py`	UMA (Meta FAIR fairchem-core) — autograd Hessian path
`pdb2reaction/backends/orb.py`	Orb (Orbital Materials) — precision / compile_model
`pdb2reaction/backends/mace.py`	MACE — default_dtype
`pdb2reaction/backends/aimnet2.py`	AIMNet2 — charge-aware（p2r 論文の 5-backend ベンチマークからは除外）

バックエンドごとの特性¶

backend	install	model identifier	precision option
`uma`	`pip install fairchem-core` + HF auth	`uma-s-1p2` / `uma-s-1p1`	`precision="fp32" \| "fp64"`
`orb`	`pip install orb-models`	`orb_v3_conservative_omol`	`precision="float32-high" \| "float32-highest" \| "float64"`（`fp32` / `float32` は正規化される別名）
`mace`	専用 conda env で pdb2reaction を入れた後、`pip uninstall -y fairchem-core && pip install 'mace-torch>=0.3.8'`（現行版どうしも `e3nn` 要件が競合）	`MACE-OMOL-0`	`default_dtype="float64"`
`aimnet2`	`pip install aimnet`	`aimnet2`	n/a

精度（precision）¶

--precision はバックエンド非依存です。UMA の precision / ORB の precision / MACE の default_dtype へ自動的にルーティングされます。AIMNet2 では fp32 は何もしない指定（no-op）として扱われ、fp64 は拒否されます（モデル入力が前段で float32 にキャストされるため）。

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

backend	デフォルト	理由
`uma`	fp32	上流 fairchem のベースライン。
`orb`	fp64	ORB の fp32 は縮約された `float32-high`（TF32）matmul であり、その力のノイズが有限差分 Hessian に偽の虚振動を生じさせる。
`mace`	fp64	MACE は上流で `default_dtype="float64"` をデフォルトとする。
`aimnet2`	fp32	精度の切り替えを持たない。

OMol で学習された UMA をデフォルトの fp32 から fp64 に切り替えると、TSopt + Hessian に無視できない影響が生じることがあります。以下で有効化します。

pdb2reaction tsopt -i ts.pdb -q 0 --precision fp64 ...
pdb2reaction freq  -i opt.pdb -q 0 --precision fp64 ...
pdb2reaction irc   -i ts.pdb -q 0 --precision fp64 ...

逆に --precision fp32 はスループットのために ORB / MACE の精度を明示的に落とします（スクリーニング用途以外では非推奨）。使用する場合は、Hessian のノイズが増えるため、虚振動の本数を確認してください。

--backend-model NAME は選択中の --backend のモデル変種を上書きします（例: --backend uma --backend-model uma-s-1p2）。未指定ならバックエンドデフォルトのモデルを使用します。

または YAML 設定で:

calc:
  precision: fp64

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

カスタムバックエンド — 任意の ASE Calculator を使う（`--calc-file`）¶

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

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バックエンドが選択され --backendを上書きします:

pdb2reaction sp     -i model.xyz --calc-file my_calc.py -q 0 -m 1
pdb2reaction opt    -i model.xyz --calc-file my_calc.py -q 0 -m 1
pdb2reaction tsopt  -i ts.xyz    --calc-file my_calc.py -q 0 -m 1
pdb2reaction freq   -i ts.xyz    --calc-file my_calc.py -q 0 -m 1
pdb2reaction all    -i R.pdb P.pdb -c 'LIG' --calc-file my_calc.py -q 0 -m 1

補足:

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

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

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

pdb2reaction/backends/xyz.py を作成: XYZCalculator(MLIPCalculator)（pysisyphus パス）と XYZASECalculator(...) （ASE パス）を実装します。どちらも共通の kwargs である charge / spin / device / freeze_atoms / hessian_calc_mode / return_partial_hessian / hessian_double / print_timing / model と、バックエンド固有の kwargs（precision、 default_dtype など）を受け付ける必要があります。
MLIPCalculator を継承（backends/base.py）し、サブクラスフックである _compute_energy_forces_ev(elem, coord_ang) -> (energy_eV, forces_eV_Ang) を実装します。バックエンドが解析的 Hessian を公開している場合は、必要に応じて _compute_analytical_hessian_ev(elem, coord_ang) -> hessian_eV_Ang2 をオーバーライドします。そうでなければ、基底クラスが FD-Hessian の組み立て + 単位変換（eV/Å → Hartree/Bohr）を行います。
BACKEND_REGISTRY に登録（backends/__init__.py）: 既存のエントリの隣に "xyz": {"module": "pdb2reaction.backends.xyz", "pysis_cls": "XYZCalculator", "ase_cls": "XYZASECalculator"} を追加します。
受け付ける kwargs を宣言: _BACKEND_ACCEPTED_KEYS["xyz"] と _ASE_ACCEPTED_KEYS["xyz"] に set を追加します。resolve_backend('auto') に参加させる場合は _BACKEND_AVAILABILITY_MODULES に import probe も登録し、 fallback tuple に "xyz" を追加します。
ドキュメント化 + smoke: 本ページのファイルマップ / バックエンドごとの表にエントリを追加し、model identifier + インストールコマンドを記載し、新しいバックエンドが end-to-end で実行されるよう tests/smoke/run.sh に xyz の行を追加します。