典型エラー別レシピ

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

早見表

各行の「詳細」列は トラブルシューティング の該当セクションへ直接リンクします。

症状	最初にやること	詳細（セクション）
入力 / 抽出
元素カラム欠落で抽出が止まる	元の PDB に add-elem-info を適用してください	入力 / 抽出の問題
[multi] Atom count mismatch / [multi] Atom order mismatch	同じ前処理ツール・設定で全 PDB を再生成。最初に原子順序を固定したら並べ替えない	入力 / 抽出の問題
電荷 / スピン
-q/--charge is required 系エラー	-q/--charge または -l/--ligand-charge を明示指定してください	電荷 / スピンの問題
計算は通るが状態/エネルギーが不自然	CLI 規約 の電荷解決順序を再確認してください	電荷 / スピンの問題
計算 / 収束
--workers > 1 で --hessian-calc-mode Analytical を指定すると RuntimeError が送出される（警告なく FiniteDifference にダウングレードはされない）	解析 Hessian が必要なら --workers 1 に下げる、不要なら FiniteDifference（デフォルト）のまま	workers > 1 によるHessianのダウングレード
実行時に CUDA OOM	--radius を縮小して再抽出（extract / all のみ）、--opt-mode grad に切替、有限差分 Hessian のまま、または VRAM の大きい GPU へ	計算 / 収束の問題
TS は収束したが小さい虚振動が複数残る	--flatten を追加（tsopt、opt、pdb2reaction all 共通）	計算 / 収束の問題
TSOPT が収束しない	L-BFGS/Dimer: max_step を縮小。RFO/RS-I-RFO: trust_radius/trust_min/trust_max を縮小。サイクル上限を増やし、TS 品質を確認	計算 / 収束の問題
IRC が正常に終了しない	--step-size を縮小、--max-cycles を増加、虚振動数が 1 本のみか確認	計算 / 収束の問題
opt/TSOPT が max_cycles で停止し、max(force) が閾値をわずかに超える	通常は opt.energy_plateau フォールバックが自動で処理します。手動回避は --thresh gau または --thresh gau_loose	計算 / 収束の問題
MEP 探索（GSM/DMF）が失敗	--max-nodes をデフォルト 20 から増やす、--preopt 有効化（デフォルト: all/path-search/path-opt で True、scan* で False）、別の --mep-mode を試す	計算 / 収束の問題
インストール / 環境
DMF モードの import エラー（cyipopt）、または No module named 'dmf'	conda install -c conda-forge cyipopt（pydmf は pdb2reaction の依存として自動インストールされる）	インストール / 環境の問題
UMA モデルで 401/403 / gated repo エラー	hf auth login でログインし、UMA モデルのライセンスに同意してください	インストール / 環境の問題
e3nn / fairchem-core の import 競合（UMA env に MACE を入れた）	MACE 専用 conda env を使用（mace-torch は e3nn==0.4.4 を pin し、fairchem-core の e3nn>=0.5 と共存不可）。pip uninstall -y fairchem-core && pip install mace-torch	インストール / 環境の問題
CUDA/GPU 実行時エラー	torch.cuda.is_available() と CUDA バージョンの整合を確認してください	インストール / 環境の問題
ImportError: orb-models is required（AIMNet2 / MACE も同様）	バックエンド extras をインストール: pip install "pdb2reaction[orb]"（MACE は別 env）	インストール / 環境の問題
図の出力失敗	plotly_get_chrome -y で Chrome ランタイムを導入してください	インストール / 環境の問題

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

• 兆候:

• 元素情報不足、原子数不一致、活性部位モデル（バインディングポケット）の抽出結果が空に近い。

• 最初の確認:

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

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

• 典型的な修正手順:

• pdb2reaction add-elem-info -i input.pdb -o input_fixed.pdb で元素列を修復 — 抽出再実行 — 活性部位モデルサイズ（--radius）/残基選択（--selected-resn）を再確認。残基 ID 仕様の詳細は CLI 規約の --selected-resn は残基 ID を取る（残基名ではない） を参照。

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

• 兆候:

• 特に非 .gjf 入力で総電荷未解決エラーが出る。

• 最初の確認:

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

• --ligand-charge/-l の各残基キーが妥当か検証する。

• 結果が物理的に不自然な場合は CLI 規約 の電荷解決順序を再確認。

• 典型的な修正手順:

• 重要な実行では -q/--charge または -l/--ligand-charge と -m を明示し、scan/path/tsopt を再試行。

レシピ 3: 環境依存で止まる

• 兆候:

• DMF import 失敗、CUDA 不整合、図出力バックエンド不在。

• 最初の確認:

• 実行環境にオプション依存パッケージ（cyipopt 等）が入っているか。

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

• 典型的な修正手順:

• 先に環境を修復し、pdb2reaction --version や python -c "import torch; print(torch.cuda.is_available())" で確認後、--dry-run で事前チェックしてから本実行。

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

• 兆候:

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

• 最初の確認:

• TS 候補が虚振動数 1 本のみを持ち、対応する虚振動モードが反応座標方向の変位を示すか。検出カットオフは hessian_dimer.neg_freq_thresh_cm（デフォルト 5 cm⁻¹）。

• 虚振動数の本数が誤っている場合（偽の 2 本目の小さいモード、または支配的な反応モードが無い）は、--precision fp64 で精度を上げる、および／または --coord-type dlc に切り替え、残った小さいモードは --flatten を追加します。これらの手法は補完的です。tsopt: 最適化後に虚振動数の本数が誤っている場合 を参照。

• ステップサイズ / 信頼半径（YAML キー max_step, trust_radius/trust_min/trust_max）と、最適化モード / フラット化（CLI フラグ --opt-mode, --flatten）は併用してください。YAML セクション構成は YAML リファレンス、正規の修正手順は 計算 / 収束の問題 を参照。

• max_cycles 到達時に力のノルムが閾値をわずかに超えているだけで、エネルギー地形がほぼ平坦になっている場合は 計算 / 収束の問題 を参照してください — opt.energy_plateau フォールバックが自動処理します。

• 典型的な修正手順:

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

レシピ 5: CPCM-X を有効にした xTB のソースビルド

conda install -c conda-forge xtb で導入される xTB は ALPB（デフォルト --solvent-model alpb）のみ対応で、CPCM-X は含まれません。--solvent-model cpcmx を使うには、CPCM-X 機能を有効化してソースからビルドする必要があります。

ビルド（upstream xtb の指針では GCC ≥ 8。CMake が BLAS/LAPACK を自動検出できない場合は -DBLAS_LIBRARIES=... -DLAPACK_LIBRARIES=... を指定）:

git clone --depth 1 https://github.com/grimme-lab/xtb.git
cd xtb
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DWITH_CPCMX=ON
# tblite の並列ビルド競合を避けるため 2 段階で実行:
make -C build tblite-lib -j8
make -C build xtb-exe -j8

実行時に CPXHOME を <xtb-checkout>/build/_deps/cpcmx-src/ に設定（cpcmx.toml と DB/ パラメータフォルダを含むディレクトリ）。<xtb-checkout>/build を $PATH に追加するか、calc.xtb_cmd（YAML）/ --xtb-cmd（公開されている場合）でカスタムバイナリを指定してください。