トラブルシューティング

このページでは、mlmm でよく遭遇するエラーと対処法をまとめます。 エラーメッセージでページ内検索すると、該当するセクションを素早く見つけることができます。 症状から先に当たりを付けたい場合は、先に 典型エラー別レシピ を見てからこのページに戻ってください。

実行前チェックリスト

長時間の計算を実行する前に、以下を確認してください。

  • mlmm -h でヘルプが表示される

  • UMA のモデルがダウンロードできる（Hugging Face のログイン/トークンが利用可能）

  • 酵素系ワークフローでは、入力 PDB に 水素 と 元素記号（element column） が入っている

  • 複数の PDB を与える場合、同じ原子が同じ順序 で並んでいる（座標だけが異なる）

  • AmberTools（tleap, antechamber, parmchk2）が PATH 上にある（mm-parm を使う場合）

  • hessian_ff の C++ 拡張がビルド済み（cd hessian_ff/native && make）

入力 / 抽出の問題

「Element symbols are missing… add-elem-info を実行してください」

典型的なメッセージ:

Element symbols are missing in '...'.
Please run `mlmm add-elem-info -i...` to populate element columns before running extract.

対処:

  • 次を実行して element 列（元素記号列）を補完します:

mlmm add-elem-info -i input.pdb -o input_with_elem.pdb

  • その後、extract / all を補完後の PDB で再実行します。

なぜ発生するか:

  • 多くの PDB では元素カラムが一貫して埋められていません。extract は正確な原子型判定のために元素記号を必要とします。

「Atom count mismatch」「Atom order mismatch」

典型的なメッセージ:

[multi] Atom count mismatch between input #1 and input #2:...
[multi] Atom order mismatch between input #1 and input #2.

対処:

  • すべて の構造を同じ前処理ワークフロー（同じプロトン化ツール、同じ設定）で作り直します。

  • 水素付加を行う場合は、全フレームで一貫した原子順序になる方法を使用してください。

ヒント:

  • MD 由来のアンサンブルでは、異なるツールで作った PDB を混在させるのではなく、同一のトポロジー/軌跡 からフレーム抽出する方が安全です。

「ポケットが空っぽ / 必要な残基が落ちる」

症状:

  • 抽出ポケットが想定より小さい

  • 触媒残基が含まれない

対処の例:

  • --radius を増やす（例: 2.6 → 3.5 Angstrom）

  • --selected-resn で残基を強制包含する（例: --selected-resn 'A:123,B:456'）

  • 主鎖削除が強すぎる場合は --no-exclude-backbone を試す

電荷 / スピンの問題

「電荷が必須」系のエラー

計算系サブコマンドでは -q/--charge を必ず明示する必要があります。 all では電荷は -q/--charge 上書き -> 抽出サマリー -> （抽出スキップ時）--ligand-charge フォールバック の順で解決されます。

対処:

  • 電荷と多重度を明示的に指定します:

mlmm path-search -i R.pdb P.pdb --parm real.parm7 --model-pdb model.pdb -q 0 -m 1

  • あるいは、抽出経由で自動導出させるため all を使い、残基名ごとの電荷マッピングを与えます:

mlmm -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3'

AmberTools / mm-parm の問題

tleap が見つからない

典型的なメッセージ:

FileNotFoundError: tleap not found on PATH

または

mm-parm requires AmberTools (tleap, antechamber, parmchk2).

対処:

  • conda で AmberTools をインストールします:

conda install -c conda-forge ambertools -y

  • HPC クラスターでは環境モジュールでロードする場合もあります:

module load ambertools

  • 利用可能か確認します:

which tleap
which antechamber
which parmchk2

  • AmberTools なしでも、--parm を手動で用意すれば opt、tsopt、path-search 等は動作します。

antechamber が失敗する

症状:

  • mm-parm 実行中にリガンドパラメータ化が失敗する

  • 原子型割り当てや電荷計算に関するエラーが出る

対処の例:

  • リガンドの PDB で元素記号と結合構造が正しいか確認する

  • --ligand-charge が正しく指定されていることを確認: -l 'GPP:-3,SAM:1'

  • --keep-temp を付けて再実行し、<resname>.antechamber.log を確認する:

mlmm mm-parm -i input.pdb -l 'LIG:-1' --keep-temp

  • 水素が正しく付加されているか、TER レコードが適切か確認する

  • 抽出されたリガンド PDB に対して antechamber を手動実行して原因を切り分ける:

antechamber -i ligand.pdb -fi pdb -o ligand.mol2 -fo mol2 -c bcc -nc -3 -at gaff2

parm7/rst7 の不整合エラー

典型的なメッセージ:

Atom count in parm7 (...) does not match input PDB (...)

または

RuntimeError: parm7 topology does not match the input structure

または

Coordinate shape mismatch for... got (N, 3), expected (M, 3)

対処:

  • parm7 を生成した PDB と、計算に使う PDB が同一の原子セット（同じ順序）であることを確認します。

  • mm-parm で parm7 を再生成してください。

  • mm-parm 実行後に PDB の原子を編集・並べ替え しない でください。

  • tleap が水素を追加/削除している可能性があるため、mm-parm 出力の PDB（<prefix>.pdb）を計算入力として使用してください。

parm7 の元素順序が PDB と一致しない

症状:

  • oniom-export で「Element sequence mismatch at atom index…」

対処:

  • --no-element-check で元素チェックを無効化（結果を手動で検証すること）

  • 正しい対処は、parm7 生成時と同じ PDB を -i に指定することです。

hessian_ff ビルドの問題

ビルドが失敗する（”make” エラー）

典型的な症状:

  • hessian_ff/native/ での make がコンパイルエラーを出す

  • ImportError: cannot import name 'ForceFieldTorch' from 'hessian_ff'

  • RuntimeError: hessian_ff build attempts failed: ...

対処の例:

  • C++ コンパイラ（g++ >= 9）がインストールされていることを確認:

g++ --version

  • PyTorch のヘッダが利用可能であることを確認:

python -c "import torch; print(torch.utils.cmake_prefix_path)"

  • HPC ではコンパイラモジュールをロード:

module load gcc/11

  • クリーンしてリビルド:

conda install -c conda-forge ninja -y
cd hessian_ff/native && make clean && make

hessian_ff の import エラー

典型的なメッセージ:

ImportError: cannot import name 'ForceFieldTorch' from 'hessian_ff'

または:

RuntimeError: hessian_ff build attempts failed: ...
To rebuild hessian_ff native extensions in this environment:
  conda install -c conda-forge ninja -y
  cd $(python -c "import hessian_ff; print(hessian_ff.__path__[0])")/native && make clean && make

対処:

  • C++ ネイティブ拡張を先にビルドする必要があります:

cd hessian_ff/native && make

  • hessian_ff パッケージが Python パス上にあることを確認してください（pip install -e . でインストールしていれば問題ありません）。

B-factor レイヤー割り当ての問題

レイヤー割り当てが想定と異なる

症状:

  • 原子が想定外のレイヤーに割り当てられる

  • ML 領域が小さすぎる、または大きすぎる

対処の例:

  • レイヤーが割り当てられた PDB を分子ビューアで可視化（B-factor で色分け）する

  • --model-pdb が正しく ML 領域の原子を定義しているか確認する

  • define-layer の距離カットオフを調整する:

  • --radius-freeze（デフォルト 8.0 Angstrom）: Movable-MM/Frozen の境界を制御

  • 必要に応じて、計算オプション（hess_cutoff, hess_mm_atoms）でヘシアン対象 MM を別途制御する

  • YAML で use_bfactor_layers: true を使う場合、B-factor 値が期待されるエンコーディング（0.0, 10.0, 20.0; 許容差 1.0）と一致するか確認する

B-factor 値が認識されない

典型的な症状:

  • 計算機がすべての原子を Frozen または ML として扱う

  • B-factor 値が {0.0, 10.0, 20.0} のいずれでもない

対処:

  • define-layer を再実行して正しい B-factor エンコーディングを確保してください。

  • 許容差 1.0 が適用されます: 0/10/20 に近い B-factor が ML/Movable/Frozen にマッピングされます。

  • B-factor を任意の値に手動編集しないでください。

–detect-layer が想定どおりに働かない

症状:

  • B-factor からのレイヤー自動判定で、ML / Movable / Frozen の分割が想定と異なる

  • --detect-layer 有効時に --model-pdb なしで実行すると失敗する

対処の例:

  • 入力が PDB（または --ref-pdb 付き XYZ）であることを確認する

  • define-layer で B-factor を明示的に再付与し、生成された PDB を使う

  • 距離ベース制御を使う場合は hess_cutoff / movable_cutoff を指定し、必要なら --no-detect-layer に切り替える

  • --movable-cutoff を与えると --detect-layer が無効化される点に注意する

インストール / 環境の問題

UMA のダウンロード/認証エラー（Hugging Face）

症状:

  • モデルをダウンロードできない、認証が必要、といったエラー。

対処:

  • 環境/マシンごとに一度ログインします:

huggingface-cli login

  • HPC では、計算ノードから HF キャッシュ（ホームディレクトリ等）に書き込み可能か確認してください。

CUDA / PyTorch の不整合

症状:

  • GPU があるのに torch.cuda.is_available() が False

  • import 時に CUDA runtime error が出る

対処:

  • クラスタの CUDA バージョンに適合する PyTorch をインストールしてください。

  • GPU が見えているか確認します:

nvidia-smi
python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"

DMF モードが動かない（cyipopt がない）

DMF（--mep-mode dmf）を使うときに IPOPT/cyipopt の import エラーが出る場合:

対処:

  • mlmm をインストールする前に、conda-forge から cyipopt をインストールしてください:

conda install -c conda-forge cyipopt

図のエクスポートが失敗する（Chrome がない）

Plotly/Chrome 系のエラーで静的画像が出ない場合:

対処:

  • headless Chrome をインストールしてください:

plotly_get_chrome -y

計算 / 収束の問題

CUDA メモリ不足（OOM）

症状:

  • torch.cuda.OutOfMemoryError: CUDA out of memory

  • 「CUDA out of memory」メッセージ

  • ヘシアン計算中にシステムがハングまたはクラッシュする

ML/MM 系は純粋なクラスターモデルよりも一般的に大きいため、VRAM の負荷が高くなります。

対処の例:

  • ML 領域サイズを縮小: 抽出半径を小さくするか、--model-pdb を手動で絞る

  • 有限差分 ML ヘシアンを使用: --hessian-calc-mode FiniteDifference（VRAM 消費が少ないが低速）

  • MM を CPU に移動: YAML で mm_device: cpu を指定（デフォルト）

  • ヘシアン対象 MM 領域を縮小: hess_cutoff を小さくする

  • 3 層 + Hessian 対象制御を活用: hess_cutoff と movable_cutoff を設定し、ヘシアン計算対象の原子数を制限:

calc:
  hess_cutoff: 3.6
  movable_cutoff: 8.0

  • define-layer で事前に層を定義 し、use_bfactor_layers: true で読み取る

  • GPU メモリが大きいカードに変更: 500 原子以上の ML 領域には 24 GB 以上推奨、1000 原子以上には 48 GB 以上推奨

  • ポケットサイズを縮小: 抽出時の --radius を小さくする

TS 最適化が収束しない

症状:

  • TS 最適化が多くのサイクルを回しても収束しない

  • 最適化後も複数の虚振動数が残る

対処の例:

  • オプティマイザモードを切り替える: --opt-mode grad (Dimer) または --opt-mode hess (RS-I-RFO)

  • 余分な虚モードのフラット化を有効にする: --flatten

  • 最大サイクル数を増やす: --max-cycles 20000

  • より厳しい収束閾値を使う: --thresh baker または --thresh gau_tight

  • hess_cutoff を調整して、ヘシアン計算に含む原子の範囲を広げる

IRC が正常に終了しない

症状:

  • IRC が明確な極小に到達する前に停止

  • エネルギーが振動したり勾配が大きいまま

対処の例:

  • ステップサイズを減らす: --step-size 0.05（デフォルトは 0.10）

  • 最大サイクル数を増やす: --max-cycles 200

  • IRC 実行前に TS 候補で虚数振動数が 1 本であることを確認

MEP 探索（GSM/DMF）が失敗または予期しない結果

症状:

  • 経路探索が有効な MEP なしで終了

  • 結合変化が正しく検出されない

対処の例:

  • --max-nodes を増やす（複雑な反応には 15 や 20 など）

  • 端点の事前最適化を有効にする: --preopt

  • 別の MEP 手法を試す: --mep-mode dmf（GSM が失敗した場合）またはその逆

  • YAML で結合検出パラメータを調整（bond.bond_factor、bond.delta_fraction）

パフォーマンス / 安定性のヒント

  • VRAM 不足: ML 領域サイズを縮小、ヘシアン対象 MM 領域を縮小、ノード数を削減（--max-nodes）、または軽量なオプティマイザ設定（--opt-mode grad）を使用。

  • 解析ヘシアンが遅いまたは OOM: --hessian-calc-mode FiniteDifference を使用。Analytical は十分な VRAM がある場合のみ推奨（ML 原子 300 以上には 24 GB 以上推奨）

  • MM ヘシアン: mm_fd: true（デフォルト）は MM ヘシアンに有限差分を使用。解析 MM ヘシアン（mm_fd: false）は小規模系では高速だがメモリ消費が増える場合がある

  • MM ヘシアン計算が遅い: hess_cutoff を設定して Hessian-MM 原子数を制限する

  • 大規模系（2000 原子以上）: define-layer で Frozen 層（B=20）を適切に設定し、可動自由度数を削減する

  • マルチ GPU: ML を 1 つの GPU（ml_cuda_idx: 0）、MM を別の GPU（mm_device: cuda, mm_cuda_idx: 1）に配置可能

  • ML と MM の並列実行: デフォルトで ML（GPU）と MM（CPU）は並列実行されます。mm_threads で CPU スレッド数を調整可能

バックエンド固有の問題

–backend orb/mace/aimnet2 で ImportError が出る

症状: ImportError: orb-models is required for the ORB backend のようなエラーが表示される

対処: 使用するバックエンドに対応するオプション依存パッケージをインストールします:

pip install "mlmm-toolkit[orb]"      # ORB バックエンド
pip install "mlmm-toolkit[aimnet2]"  # AIMNet2 バックエンド
# MACE: pip uninstall fairchem-core && pip install mace-torch（別環境が必要）

非 UMA バックエンドで CUDA メモリ不足になる

症状: ORB、MACE、AIMNet2 の使用時に RuntimeError: CUDA out of memory が発生する

対処: 非 UMA バックエンドは有限差分ヘシアンを使用するため、より多くの VRAM を消費します。以下の方法を試してください:

  • --radius-partial-hessian を小さくし、ヘシアン対象の原子数を制限する

  • --hessian-calc-mode FiniteDifference を明示的に指定し、hess_cutoff を小さめに設定する

  • YAML で ml_device: cpu を指定する（遅くなるが VRAM 制限を回避できる）

–embedcharge 使用時に xTB が見つからない

症状: FileNotFoundError: xtb command not found が表示される

対処: xTB をインストールし、$PATH 上にあることを確認します:

conda install -c conda-forge xtb

不具合報告のときに添えると助かる情報

  • 実行したコマンド（コピペ可能な形）

  • summary.log（またはコンソール出力）

  • 再現する最小入力（可能なら）

  • OS / Python / CUDA / PyTorch バージョン

  • AmberTools / hessian_ff のバージョン