トラブルシューティング¶

症状ベースで当たりを付けたい場合は、先に典型エラー別レシピを参照してください。

実行前チェックリスト¶

長い計算を回す前に、最低限次を確認してください。

UMA のモデルがダウンロードできる（Hugging Face のログイン/トークンが利用可能）
酵素系ワークフローでは、入力 PDB に水素と 元素記号（element column） が入っている
複数の PDB を与える場合、同じ原子が同じ順序 で並んでいる（座標だけが異なる）

入力 / 抽出の問題¶

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

典型的なメッセージ:

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

対処:

次を実行して element 列（元素記号列）を補完します。
```
pdb2reaction add-elem-info -i input.pdb -o input_with_elem.pdb
```
その後、extract / all を補完後の PDB で再実行します。

原因:

PDB の element 列が空だったり不統一だったりすることが多く、extract は原子タイプ判定のために元素記号を必要とします。

「[multi] Atom count mismatch …」「[multi] 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 Å）
--selected-resn で残基を強制包含してください（例: --selected-resn 'A:123,B:456'）。残基 ID 仕様の詳細は CLI 規約の --selected-resn は残基 ID を取る（残基名ではない）を参照。
以前に --exclude-backbone を明示的に有効化していて、その削除が強すぎる場合は当該フラグを外す（または --no-exclude-backbone を渡す）ことで主鎖原子を保持できます

エネルギー・障壁の計算値が不正確¶

症状:

計算されたエネルギーや反応障壁が不合理に見える
モデルサイズを大きくすると結果が大幅に変わる

対処:

抽出された活性部位モデルが小さすぎると、エネルギーや障壁の計算値が不正確になることがあります。抽出半径を大きくする（例: -r 4.0 以上）ことで、タンパク質環境をより多く含めて精度を改善できます:
```
pdb2reaction extract -i complex.pdb -c 'SUB' -o model.pdb -r 4.0
```

非標準残基が正しく切断されない¶

抽出された活性部位モデルに非標準の 3 文字コードを持つ修飾アミノ酸残基（リン酸化セリン、メチル化リシンなど）が含まれている場合、デフォルトでは主鎖切断やキャップ水素付加が適用されません。--modified-residue で登録してください:

pdb2reaction extract -i complex.pdb -c PRE --modified-residue "SEP,TPO,MLY" -o pocket.pdb

--modified-residue で対応できない場合（残基の主鎖トポロジーが特殊な場合など）は、活性部位モデルを手動で構築し、下流のコマンド（opt、tsopt、path-opt など）に直接渡してください。

電荷 / スピンの問題¶

「電荷が必須」系のエラー（非 GJF 入力）¶

.gjf でない入力では、複数ステージで総電荷が必要になります。-q/--charge を省略した場合、ワークフローは --ligand-charge/-l（PDB のみ）または .gjf テンプレートから電荷を導出しようとしますが、いずれの経路でも解決できないと上記のエラーで停止します。

対処:

電荷と多重度を明示する:

pdb2reaction path-search -i R.pdb P.pdb -q 0 -m 1

あるいは（抽出ありの場合）残基名ごとの電荷マッピングを与える:
```
pdb2reaction extract -i R.pdb P.pdb -c 'SAM,GPP' -l 'SAM:1,GPP:-3'
```

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

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

症状:

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

対処:

環境/マシンごとに一度ログインします。
```
hf auth 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())"

`[orb]` のインストールで torch_scatter のビルドに失敗する¶

症状:

pip install "pdb2reaction[orb]" が torch_scatter のビルド時に No module named 'torch' で失敗する。

対処:

torch_scatter は PyPI にバイナリ wheel がなく（sdist のみ）、PEP517 のビルド分離下ではソースビルドが失敗します。torch+CUDA タグに一致する PyG の prebuilt-wheel インデックスからインストールします:
```
pip install "pdb2reaction[orb]" -f https://data.pyg.org/whl/torch-2.8.0+cu129.html
```
フォールバック（CUDA ツールチェーンがある場合）: pip install torch_scatter --no-build-isolation

DMF モードが動かない（`cyipopt` がない、または `No module named 'dmf'`）¶

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

対処:

pdb2reaction を入れる前に conda-forge から cyipopt を入れるのが簡単です。
```
conda install -c conda-forge cyipopt
```
pydmf は pdb2reaction の依存として同梱されています。No module named 'dmf' が出る場合は pip install --force-reinstall pdb2reaction で再インストールしてください。

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

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

対処:

headless Chrome を一度入れます。
```
plotly_get_chrome -y
```

計算 / 収束の問題¶

最適化が `max_cycles` に達し、`max(force)` が閾値をわずかに超える¶

症状:

オプティマイザが max_cycles 上限まで回りきり、最終サマリで max(force) や rms(force) が目標をわずかに上回る（例: baker の 3×10⁻⁴ au に対して 4×10⁻⁴ au）。
一方で、エネルギー自体は明らかに平坦化しており、10⁻⁵–10⁻⁴ au レベルで振動している。

原因:

MLIP（機械学習ポテンシャル）の勾配（力）計算には小さな確率的ノイズフロアがあり（10⁻⁴ Hartree/Bohr オーダー）、これが力ベースの収束閾値（baker = 3×10⁻⁴ au）を上回る場合があります。その結果、構造はすでに収束しているにもかかわらず、力閾値を満たすことができません。

対処:

平坦なエネルギー地形によるフォールバック収束が自動でこの状況を処理します: opt.energy_plateau: true のとき、直近 opt.energy_plateau_window（デフォルト 50）ステップのエネルギーレンジが opt.energy_plateau_thresh（デフォルト 1×10⁻⁴ au ≈ 0.06 kcal/mol）を下回ると収束と判定されます。多くの場合、ユーザー側での対応は不要です。
自動フォールバックを上書きしたい場合は、力の閾値を手動で緩めてください: --thresh gau（opt のデフォルト）または --thresh gau_loose。
opt.energy_plateau_thresh / opt.energy_plateau_window は YAML からチューニングでき、opt.energy_plateau: false で無効化できます。
注意: この平坦地形フォールバックは chain-of-states オプティマイザ（path-opt、path-search の string/GSM（Growing String Method）/DMF（Direct Max Flux）段階）ではスキップされます（単一のスカラーエネルギー履歴ではなく、イメージごとのエネルギー配列を保持しているため）。

TS 最適化が収束しない¶

症状:

TS 最適化が多くのサイクルを回しても収束しない
最適化後もHessian行列に複数の負の固有値が残る（虚振動数が 2 本以上）

対処の例（CLI フラグと YAML キーは補完的、必要に応じて併用してください）:

オプティマイザモードを切り替えてください: --opt-mode grad（Dimer 法）または --opt-mode hess（RS-I-RFO 法、デフォルト）
余分な虚振動数モードのフラット化を有効にしてください: --flatten（単独の tsopt、opt、および pdb2reaction all で利用可能。デフォルトは無効）
最大サイクル数を増やしてください: --max-cycles 20000（単独の tsopt の場合）、--tsopt-max-cycles 20000（all の場合）
より厳しい収束閾値を使ってください: --thresh baker または --thresh gau_tight
YAML でステップサイズ / 信頼半径を縮小してください — L-BFGS/Dimer: lbfgs.max_step / hessian_dimer.lbfgs.max_step、RFO/RS-I-RFO: rfo.trust_radius / rfo.trust_min / rfo.trust_max（および rsirfo セクション）。セクション構成は YAML リファレンスを参照

IRC が正常に終了しない¶

症状:

IRC が明確な極小構造に到達する前に停止する
エネルギーが振動したり勾配ノルムが大きいままになる

対処の例:

ステップサイズを減らしてください: --step-size 0.05（デフォルト: 0.10 bohr、質量重み付けなしのデカルト座標）
最大サイクル数を増やしてください: --max-cycles 200
IRC 実行前に TS 候補の虚振動数が ちょうど 1 本 であることを確認してください。検出カットオフは hessian_dimer.neg_freq_thresh_cm（デフォルト 5 cm⁻¹）。

MEP（最小エネルギー経路）探索（GSM/DMF）が失敗または予期しない結果¶

症状:

経路探索が有効な MEP なしで終了
結合変化が正しく検出されない

対処の例:

--max-nodes をデフォルトの 20 より増やしてください（複雑な反応には 30 や 40 など）
端点の事前最適化を有効にしてください: --preopt
別の MEP 手法を試してください: --mep-mode dmf（GSM が失敗した場合）またはその逆
YAML で結合検出パラメータを調整してください（bond.bond_factor、bond.delta_fraction）

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

VRAM 不足: --radius の値を減らして活性部位モデルを小さくする、--max-nodes を減らす、軽い最適化設定にする（--opt-mode grad）
解析Hessian（Analytical Hessian）が遅いまたは OOM: デフォルトの FiniteDifference を維持してください。--hessian-calc-mode Analytical は 16 GB 以上の VRAM がある場合のみ使用してください。16 GB で収まるのは ~200 原子程度までです（下記の VRAM 目安表を参照）
workers > 1: HPC で UMA の処理速度は改善しますが、解析Hessianとは併用できません（workers > 1 で解析Hessianを要求すると RuntimeError が発生します）。明示的に --hessian-calc-mode FiniteDifference を指定するか、Hessianを使うモードでは --workers 1 で実行してください
大規模系（1000 原子以上）: より小さな活性部位モデル（--radius 2.5 Å）を抽出するか、マルチ GPU セットアップでの実行を検討してください
HPC で DFT を回すとき（数百原子規模）: PySCF / GPU4PySCF は積分・中間ファイルを $PYSCF_TMPDIR（未設定なら $TMPDIR、最後は /tmp）に書き出します。ノードローカル /tmp は容量が小さい / tmpfs であることが多く、SCF の途中で枯渇する場合があります。dft 起動前に PYSCF_TMPDIR をジョブの作業ファイルシステム配下に設定してください（例: export PYSCF_TMPDIR="$PBS_O_WORKDIR"）

バックエンド選択ガイド¶

以下は 16 GB VRAM の consumer GPU で小〜中規模クラスターモデルを L-BFGS 1 ステップ動かした場合の目安値です。バックエンド選択の参考用で、厳密なベンチマークではありません。

バックエンド (`-b/--backend`、モデル ID)	速度 (中央値 s/step)	VRAM	備考
`uma` (`uma-s-1p1`、デフォルト)	0.03 s	~2 GB	高速、探索向き
`uma` (`uma-m-1p1`)	0.22 s	~8 GB	中規模モデル、VRAM 大
`mace` (`MACE-OMOL-0`)	0.37 s	~4 GB	別 conda 環境が必要（`e3nn` 競合）
`orb` (`orb_v3_conservative_omol`)	0.02 s	~2 GB	最速。注意点は下を参照

推奨:

まずデフォルトの UMA モデルで高速スクリーニングし、その後 MACE または大型 UMA で主要結果を相互確認してください。
SAM 依存 S~N~2 / メチル転移反応では、MACE とデフォルト UMA は相補的に働く傾向があるので、片方の TS が疑わしいときはもう片方で検証するのが有効です。
Orb は反応座標自体は正しく捉えるものの、TS が虚振動を複数持つ状態に収束しやすく、クリーンな単一虚振動 TS は保証されません。Orb は反応機構の構造変化を確認する用途であれば使用できますが、定量的な反応速度論や振動解析には UMA / MACE / DFT で再評価するか backend を切り替えてください。

GPU メモリ (VRAM) 目安¶

系のサイズ別のおおよその VRAM 使用量は次のとおりです。

原子数	L-BFGS 最適化	Hessian（解析的）	Hessian（有限差分）
50	~2 GB	~3 GB	~2 GB
100	~3 GB	~6 GB	~3 GB
200	~4 GB	~12 GB	~4 GB
500	~6 GB	16 GB で OOM	~6 GB

torch.cuda.OutOfMemoryError が出た場合は次を試してください。

--hessian-calc-mode FiniteDifference を指定する（速度は落ちますが VRAM 使用量を抑えられます）
--radius を小さくしてクラスターモデルのサイズを縮小する
より小さいモデルを使う（YAML 設定で calc.model: uma-m-1p1 の代わりに uma-s-1p1 を指定）

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

実行したコマンド（コピペ可能な形）
summary.log（またはコンソール出力）
再現する最小入力（可能なら）
OS / Python / CUDA / PyTorch バージョン

トラブルシューティング¶

実行前チェックリスト¶

入力 / 抽出の問題¶

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

「[multi] Atom count mismatch …」「[multi] Atom order mismatch …」¶

「活性部位モデル（バインディングポケット）が空っぽ / 必要な残基が落ちる」¶

エネルギー・障壁の計算値が不正確¶

非標準残基が正しく切断されない¶

電荷 / スピンの問題¶

「電荷が必須」系のエラー（非 GJF 入力）¶

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

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

CUDA / PyTorch の不整合¶

[orb] のインストールで torch_scatter のビルドに失敗する¶

DMF モードが動かない（cyipopt がない、または No module named 'dmf'）¶

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

計算 / 収束の問題¶

最適化が max_cycles に達し、max(force) が閾値をわずかに超える¶

TS 最適化が収束しない¶

IRC が正常に終了しない¶

MEP（最小エネルギー経路）探索（GSM/DMF）が失敗または予期しない結果¶

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

バックエンド選択ガイド¶

GPU メモリ (VRAM) 目安¶

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

`[orb]` のインストールで torch_scatter のビルドに失敗する¶

DMF モードが動かない（`cyipopt` がない、または `No module named 'dmf'`）¶

最適化が `max_cycles` に達し、`max(force)` が閾値をわずかに超える¶