MLIP 計算機¶

概要¶

pdb2reaction は複数の機械学習原子間ポテンシャル（MLIP）を PySisyphus 向けの計算機バックエンドとしてサポートします。デフォルトバックエンドは UMA（Meta の Universal Models for Atoms）ですが、ORB、MACE、AIMNet2 も利用可能です。各バックエンドはエネルギー/力/ヘシアンを Hartree 単位で返し、デバイス配置・単位変換を内部で処理します。pdb2reaction の最適化、経路探索、熱化学、軌跡後処理など広範に利用されます。

クイックスタート¶

import numpy as np
from pdb2reaction.uma_pysis import uma_pysis

# 例: 中性一重項の2原子系（GPUが利用可能ならGPU、なければCPU）
calc = uma_pysis(charge=0, spin=1, model="uma-s-1p1", device="auto")

# uma_pysis には Bohr 単位の座標（形状: [n_atoms, 3]）を渡します
coords_bohr = np.array([
 [0.0, 0.0, 0.0],
 [2.2, 0.0, 0.0], # 約 1.16 Å
])

symbols = ["C", "O"]

# 注: これらのメソッドは dict を返すため、適切なキーで値を取り出します
energy_h = calc.get_energy(symbols, coords_bohr)["energy"] # float (Hartree)
forces_h_bohr = calc.get_forces(symbols, coords_bohr)["forces"] # ndarray (Hartree/Bohr)
hessian_h_bohr2 = calc.get_hessian(symbols, coords_bohr)["hessian"] # ndarray (Hartree/Bohr²)

座標は Bohr で与えます。ラッパー内部で Å に変換し、UMA計算後に Hartree / Hartree·Bohr⁻¹ / Hartree·Bohr⁻² に戻します。
pysisyphus の geometry オブジェクトにアタッチするか、上記のように直接呼び出せます。

Python API: Calculator Factory¶

backends モジュールは MLIP 計算機をプログラムから生成するファクトリを提供します:

from pdb2reaction.backends import create_calculator, create_ase_calculator

関数	説明
`create_calculator(backend="uma", **kwargs)`	PySisyphus 互換の MLIP 計算機を生成します。`charge`、`spin`、`model`、`device`、`solvent`、`solvent_model`、`hessian_calc_mode`、`freeze_atoms` などバックエンド固有の kwargs も受け付けます。未知のキーはバックエンドごとに黙って除外されます。
`create_ase_calculator(backend="uma", **kwargs)`	ASE 互換の MLIP 計算機を生成します（DMF ワークフローや ASE ベースのツールで使用）。kwargs は `create_calculator` と同じです。

例¶

from pdb2reaction.backends import create_calculator

# 解析ヘシアン付き UMA 計算機
calc = create_calculator(
    backend="uma",
    charge=0,
    spin=1,
    device="auto",
    hessian_calc_mode="Analytical",
)

# 暗黙溶媒付き ORB 計算機
calc_orb = create_calculator(
    backend="orb",
    charge=-1,
    spin=1,
    solvent="water",
    solvent_model="alpb",
)

返される計算機は pysisyphus の計算機インターフェース（get_energy, get_forces, get_hessian）を実装しています。すべてのメソッドは (atoms: List[str], coords: np.ndarray) を受け取り、coords は Bohr 単位です。戻り値は "energy"（Hartree）、"forces"（Hartree/Bohr）、"hessian"（Hartree/Bohr²）を含む dict です。

バックエンド選択¶

任意のコマンドで -b/--backend を指定するか、YAML で calc.backend を設定します:

# UMA（デフォルト）
pdb2reaction opt -i input.pdb -q 0

# ORB
pdb2reaction opt -i input.pdb -q 0 -b orb

# MACE
pdb2reaction opt -i input.pdb -q 0 -b mace

# AIMNet2
pdb2reaction opt -i input.pdb -q 0 -b aimnet2

バックエンド	インストール	解析ヘシアン	マルチワーカー	備考
UMA	同梱	あり	あり	fairchem による完全機能
ORB	`pip install "pdb2reaction[orb]"`	あり（autograd）	なし	orb-models（conservative モデルのみ）
MACE	`pip uninstall -y fairchem-core && pip install mace-torch`	あり（`calc.get_hessian`）	なし	mace-torch >= 0.3.8
AIMNet2	`pip install "pdb2reaction[aimnet]"`	あり（native）	なし	aimnet

暗黙溶媒補正¶

すべてのバックエンドで xTB ベースの暗黙溶媒補正が --solvent により利用可能です:

pdb2reaction opt -i input.pdb -q 0 --solvent water
pdb2reaction opt -i input.pdb -q 0 -b orb --solvent water --solvent-model cpcmx

デルタアプローチによる補正: ΔE = E_xTB(溶媒) - E_xTB(真空) を MLIP エネルギー/力/ヘシアンに加算します。xtb が PATH 上にインストールされている必要があります。

主な特徴¶

MLIPバックエンド – デフォルトの UMA バックエンドは FAIR-Chem の pretrained_mlip ヘルパーでUMAチェックポイントを読み込み、AtomicData バッチに電荷/スピン情報を付与。代替バックエンド（ORB、MACE、AIMNet2）は -b/--backend で利用可能。
デバイス処理 – device="auto" はCUDAがあればGPU、なければCPUを選択。グラフ構築は選択デバイス上で行い、workers>1 では並列予測器が転送を管理。
凍結原子 – freeze_atoms に1始まりの原子インデックスを渡すと、凍結原子の力がゼロ化。return_partial_hessian=True で凍結自由度を除いたヘシアンを返すか、フル行列で該当行/列をゼロ化できます。
精度制御 – エネルギー/力は常にfloat64。hessian_double=False でヘシアンをモデルのネイティブdtype（通常float32）で返します。
マルチワーカー推論 – workers>1 で FAIR-Chem の ParallelMLIPPredictUnit を起動し、workers_per_node をノードごとに指定可能。バッチ処理速度の向上に有効です。

`workers > 1` による暗黙的な FD ダウングレード¶

Warning

workers > 1 の場合、hessian_calc_mode="Analytical" を明示的に指定していても解析ヘシアンは暗黙的に有限差分（force_fd=True）へ切り替わります。**このダウングレード発生時にログマーカーは出力されません。**診断する唯一の方法は、同じ原子数の解析ヘシアン基準ランと比較してヘシアン計算時間が FD 相当に長くなっていることの確認です。明示的な警告やログ行は存在しないため、「想定より長いヘシアン所要時間」だけが手掛かりとなります。この警告は --workers / --workers-per-node を持つすべてのサブコマンド（opt, tsopt, freq, irc, all, scan 系）に適用されます。

ヘシアン評価モード¶

hessian_calc_mode="Analytical" は選択されたデバイス上で2階自動微分を行い、"FiniteDifference"（デフォルト）は力の中心差分を計算します。複数の推論ワーカーを要求した場合、解析モードは自動的に無効化されます（上記の警告を参照）。

HPC での使用例: PBS + Open MPI + Ray¶

複数ノードで workers / workers_per_node を Ray クラスタに分散する PBS + Open MPI のテンプレートは HPC 実行例のページを参照してください。モジュール名、conda パス、PBS リソース要求などを環境に合わせて調整すればそのまま使えます。

設定リファレンス¶

代表的なコンストラクタ引数（右端はデフォルト値）:

オプション	説明	デフォルト
`backend`	MLIP バックエンドエンジン	`"uma"`
`charge`	総電荷	`0`
`spin`	スピン多重度（2S+1）	`1`
`model`	UMAモデル名 (`uma-s-1p1`, `uma-m-1p1`)	`"uma-s-1p1"`
`task_name`	UMAバッチに記録されるタスクタグ	`"omol"`
`device`	`"cuda"` / `"cpu"` / `"auto"`	`"auto"`
`workers` / `workers_per_node`	並列UMA予測器。`workers>1` の場合、解析ヘシアンは警告なく有限差分へダウングレードされます。`hessian_calc_mode` のデフォルトはそもそも FD のため、`Analytical` を明示的に選んだ場合のみ影響があります。	`1` / `1`
`max_neigh`, `radius`, `r_edges`	近傍構築のオプション上書き	`None`, `None`, `False`
`freeze_atoms`	1始まりの凍結原子インデックス	None
`hessian_calc_mode`	`"Analytical"` または `"FiniteDifference"`	`"FiniteDifference"`
`return_partial_hessian`	アクティブ自由度のみ返す	`True`
`hessian_double`	ヘシアンをfloat64で返す	`True`
`out_hess_torch`	ヘシアンを `torch.Tensor` で返す	`True`
`print_timing`	ヘシアン計算のタイミング内訳を表示	`True`
`print_vram`	ヘシアン計算中の CUDA VRAM 使用量を表示（UMA バックエンド限定）	`True`
`solvent`	暗黙溶媒名（例: `"water"`）または `"none"`	`"none"`
`solvent_model`	xTB 溶媒モデル: `"alpb"` または `"cpcmx"`	`"alpb"`
`xtb_cmd`	溶媒補正で使用する xTB 実行コマンド	`"xtb"`
`xtb_acc`	溶媒補正実行時の xTB 精度設定	`0.2`