典型エラー別レシピ

症状は分かっているものの、どのサブコマンドのページから見ればよいか迷うときに使います。 詳細は トラブルシューティング を並行して参照してください。

症状別の早見表

症状

まず確認

次に読む

入力 / 抽出

元素カラム欠損 / 抽出が中断

元の PDB に対して add-elem-info を実行

入力 / 抽出

電荷 / スピン

Total charge is unresolved. Provide -q/--charge or --ligand-charge. エラー

-q/--charge または -l/--ligand-charge を明示的に指定

電荷 / スピン

実行後にエネルギー/状態がおかしい

CLI 規約の電荷/多重度ポリシーを再確認

電荷 / スピン

インストール / 環境

mm-parm が実行できない（tleap/antechamber/parmchk2 が見つからない）

AmberTools の利用可能性を先に修正

AmberTools / mm-parm

hessian_ff の import/ビルドエラー

ネイティブ拡張（hessian_ff/native）を再ビルド

hessian_ff ビルド

DMF モードの import エラー（cyipopt）

アクティブ環境に cyipopt をインストール

DMF モード

GPU / CUDA

CUDA/GPU ランタイム不整合

torch.cuda.is_available() と CUDA ビルドの組み合わせを確認

CUDA / PyTorch

収束

TSOPT/IRC が収束しない

ステップ長を縮小（RFO/RS-I-RFO では trust_radius、L-BFGS では max_step）、サイクル数を増やし、まず TS の品質を検証

計算 / 収束

エネルギーが平坦なのに最適化が停滞（MLIP のノイズフロア）

デフォルトの energy_plateau フォールバックに任せる。判定が早すぎ/遅すぎる場合のみ energy_plateau_thresh / energy_plateau_window を調整

プラトー・フォールバック

プロット

プロット出力の失敗

Plotly エクスポート用の Chrome ランタイムをインストール

プロット出力

レシピ 1: MEP 前に抽出で止まる

兆候:

  • 元素情報不足、原子数不一致、ポケット抽出結果が空に近い。

最初の確認:

  • 入力構造が同じ前処理フローで作られ、原子順が揃っているか。

  • extract / all 前に元素カラムが埋まっているか。

典型的な修正手順:

  • 元素修復 -> 抽出再実行 -> ポケットサイズ/残基選択を再確認。

レシピ 2: 電荷/スピンの解決で止まる

兆候:

  • ログに不自然な電荷が表示される場合（例: タンパク質電荷が間違っている、総電荷が期待と異なる）、電荷解決ルールを確認する。

最初の確認:

  • 対象状態に対して総電荷・多重度が妥当か。

  • --ligand-charge の残基キーが入力構造と一致しているか。

  • 結果が物理的に不自然な場合は CLI Conventions の解決ルールを再確認。

典型的な修正手順:

  • 重要な実行では -q / -m を明示し、scan/path/tsopt を再試行。

レシピ 3: ビルド・環境依存で止まる

兆候:

  • mm-parm 必須ツール不在、hessian_ff import 失敗、CUDA 不整合。

最初の確認:

  • 実行環境に必要実行ファイル・拡張モジュールが存在するか。

  • GPU 可視性と PyTorch CUDA 互換性に問題がないか。

典型的な修正手順:

  • 先にツールチェイン/ビルドを修復し、--help-advanced で再確認後に本実行。

レシピ 4: 収束・後処理で止まる

兆候:

  • TSOPT が停滞、IRC が不安定、MEP 精密化が途中停止。

最初の確認:

  • TS 候補に支配的な虚振動数モードが 1 つ存在するか。

  • ステップ長（trust_radius / max_step）を縮小し、サイクル上限を増やす。RFO/RS-I-RFO の trust_max デフォルトは 0.10 bohr です。

  • エネルギーが既に平坦化していないか確認します。直近 50 サイクル程度で |dE| < 1e-4 au（原子単位）かつ力も平坦なら、原因は最適化のバグではなく機械学習原子間ポテンシャル（MLIP）の力ノイズフロアです。この場合はデフォルトの energy_plateau フォールバックが自動的に収束宣言します（トラブルシューティング を参照）。

典型的な修正手順:

  • 小規模ケースで条件を詰め、安定化後に本番条件へ戻す。