トラブルシューティングと 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 を必要とします。インストールの章 のように 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 の章）。

ValueError: unknown iop key "…"

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

RI-MP2 がエラー、または誤った数を返す

RI-MP2 は相関フィッティング補助基底が必要です — qc.chk.new(...) に ric=（例 ric="cc-pvdz-ri/mp2fit"）を設定します。非 RI の MP2 経路はありません（ポスト SCF の章）。

すべての結合が約 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 の章）。

eri="4c-incore" でメモリ不足

全積分集合が RAM に収まりません。4c-auto（自動フォールバック）、4c-direct（再計算）、または RI ファミリを 使います（ERI 戦略）。

開殻（例 対称なクラスターカチオン）が ROHF で収束しない

準縮退/非局在ホール状態は多参照で、単一行列式の ROHF になれません。UHF/UKS を、多くは guess(..., spin_break="mix") とともに使います（SCF の章）。

並列（MPI / スレッド）

コアを増やしても（nthread=）速くならない

分子が小さく、ボトルネックがスレッド化された XC/BLAS 領域ではなく（逐次の）積分組み立てです（Amdahl）。より 大きな DFT ジョブはスケールします（スレッドの章）。

クラスタの MPI ジョブがエラーなく起動時にハングする

相互接続トランスポートが未選択です。cat /sys/class/infiniband/*/ports/*/state を確認（ACTIVE のはず）; 明示的に選ぶか、共有メモリ --mca pml ob1 --mca btl self,sm にフォールバック （MPI の章）。

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）は、エラーと ビルド設定を読んで通常 1 ステップで診断できます — これが意図された qc-rs のワークフローです。バグは、プロジェクト は GitHub Issues を使います。