# トラブルシューティングと FAQ

初学者が最もよくぶつかる問題の 症状 → 原因 → 対処 のリファレンスです。段階別:**ビルド/インストール**・
**インポート**・**実行時**・**並列**。

## ビルドとインストール

**`import qc` が失敗:`undefined symbol: omp_get_num_procs`**（MKL ビルド）
: MKL スレッド層が固定されていません。**`MKL_THREADING_LAYER=GNU`**（と `MKL_INTERFACE_LAYER=LP64`）を設定
  します。`make setup` がこれらを `.vscode/my.env` と `env.sh` に書きます;シェル/カーネルがそれらを読むことを
  確認してください。

**`import qc` が失敗:`symbol not found … __gfortran_concat_string`**（macOS, `openblas-bundled`）
: 静的リンクの OpenBLAS/LAPACK がロード時に `libgfortran` を必要とします。[インストールの章](../00-intro/installation-and-make-setup.md)
  のように `RUSTFLAGS` で dylib としてリンクします（`-L $(brew --prefix gcc)/lib/gcc/current -l dylib=gfortran`）。

**ビルドが `libxc.pc` を探して失敗**
: システムの libxc が見つかりません。**同梱**ソースを使います:`--features xc-bundled`（`xc-system` の代わり）。

**素の `cargo build -p qc-py` が Python C-API シンボルで失敗**
: 拡張は素の `cargo build` ではなく **`maturin develop` / `maturin build`** でビルドします — maturin が拡張
  モジュールのリンカ設定を供給します。

## インポートと環境

**`ModuleNotFoundError: No module named 'qc'`**（ノートブックやスクリプトで）
: インタプリタ/カーネルが **qc-rs の入った uv venv でない**。VSCode では正しいカーネル（`uv` プロジェクト配下）を
  選び、シェルではその venv を有効化します。`import sys; print(sys.executable)` で確認 — `…/.venv/bin/python` の
  はずです。

**`uv add …` の直後に `import qc` が壊れる**
: **`uv add` が編集可能な `qc_rs` 拡張を venv から prune** します。再ビルドします:`make install`（または
  `maturin develop`）。依存を追加した後の想定挙動です。

**`qc.GPU_ENABLED` / `qc.XC_ENABLED` / `qc.PCM_ENABLED` が予期せず `False`**
: その機能がコンパイルされていません。機能つきで再ビルド（`--features …,cuda` / `xc-bundled` / `pcm`）。既定
  ビルドは CUDA なし（`GPU_ENABLED == False`）です。

## 実行時

**`ValueError: eri="4c-cuda" requires … the cuda feature and a CUDA GPU`**
: 非 `cuda` ビルド（または可視 GPU なし）で GPU 戦略を要求しました。`cuda` で再ビルドするか、CPU の `eri=` を
  使います（[GPU の章](../30-hpc/gpu-cuda.md)）。

**`ValueError: unknown iop key "…"`**
: 綴り間違い/存在しない IOP キー。`qc.iop.list()` で有効キーを一覧し、`qc.iop.describe(key)` で調べます
  （[IOP リファレンス](iop.md)）。

**RI-MP2 がエラー、または誤った数を返す**
: RI-MP2 は**相関フィッティング補助基底**が必要です — `qc.chk.new(...)` に `ric=`（例
  `ric="cc-pvdz-ri/mp2fit"`）を設定します。非 RI の MP2 経路はありません（[ポスト SCF の章](../20-guide/post-scf.md)）。

**すべての結合が約 1.9 倍長い / 貼った幾何で SCF が収束しない**
: **原子単位の座標を `unit="bohr"` なしで**与えました。既定はオングストロームです。`mychk.coordinates()`
  （常に bohr）で確認し、`unit=` を正しく設定します。

**`ImportError: qc.view 3D rendering needs py3Dmol`**
: ビューア依存を入れます:`uv add py3dmol --project "$UV_PROJECT"`（`uv add` が prune するので、その後 qc-rs を
  再ビルド）。2 次元の `plot_*` は matplotlib を使い影響を受けません。

**SCF が `converged == False`**
: トランスクリプトを読みます（`run(log="stdout")`）。エネルギーがまだ下降 → `max_cycle` を上げるか 2 次の
  `algorithm="qc"/"trah"`;振動 → `damping`/`level_shift` を足す、小ギャップは `smearing`
  （[SCF の章](../20-guide/scf.md)）。

**`eri="4c-incore"` でメモリ不足**
: 全積分集合が RAM に収まりません。`4c-auto`（自動フォールバック）、`4c-direct`（再計算）、または RI ファミリを
  使います（[ERI 戦略](../30-hpc/eri-jk-strategies.md)）。

**開殻（例 対称なクラスターカチオン）が ROHF で収束しない**
: 準縮退/非局在ホール状態は多参照で、単一行列式の ROHF になれません。**UHF/UKS** を、多くは
  `guess(..., spin_break="mix")` とともに使います（[SCF の章](../20-guide/scf.md)）。

## 並列（MPI / スレッド）

**コアを増やしても（`nthread=`）速くならない**
: 分子が小さく、ボトルネックがスレッド化された XC/BLAS 領域ではなく（逐次の）積分組み立てです（Amdahl）。より
  大きな DFT ジョブはスケールします（[スレッドの章](../30-hpc/threads-and-blas.md)）。

**クラスタの MPI ジョブがエラーなく起動時にハングする**
: 相互接続トランスポートが未選択です。`cat /sys/class/infiniband/*/ports/*/state` を確認（`ACTIVE` のはず）;
  明示的に選ぶか、共有メモリ `--mca pml ob1 --mca btl self,sm` にフォールバック
  （[MPI の章](../30-hpc/mpi-and-interconnects.md)）。

**`PML UCX could not be selected`**
: mpi4py が `THREAD_MULTIPLE` で初期化し、この UCX は使えません。`from mpi4py import MPI` の**前**に
  `import mpi4py; mpi4py.rc.thread_level = "serialized"` を置きます。

**`no auxiliary transport … Destination is unreachable`**（UCX）
: UCX RC トランスポートは `ud` 補助が必要です。`UCX_TLS` に `ud_verbs` を含めます（例
  `rc_verbs,ud_verbs,sm,self`）。

**`ibv_reg_mr … Cannot allocate memory`**（InfiniBand、バッチジョブで）
: `memlock` ulimit が低すぎます。管理者が計算ノードの `LimitMEMLOCK` を上げます（バッチジョブは低い上限を継承）。

**MPI ジョブがノード間で予想より遅い**
: InfiniBand ではなく **TCP/Ethernet** にフォールバックした、または通信律速の可能性。IB トランスポートを明示的に
  選び、`-x` で環境を転送し、`--map-by numa --bind-to core` でランクをバインドします。

## それでも詰まったら

ターミナルの AI コーディングアシスタント（[Claude Code / Codex](../00-intro/ai-coding-clis.md)）は、エラーと
ビルド設定を読んで通常 1 ステップで診断できます — これが意図された qc-rs のワークフローです。バグは、プロジェクト
は GitHub Issues を使います。