# インストールとビルド（`make setup`）

qc-rs は **Rust** の数値コアを **Python** パッケージ（`qc`）で包んだものです。現在は**ソースからビルド**します
— まだ `pip install qc` はありません — ので、「qc-rs をインストールする」とは:いくつかの標準ツールを入れ、
`qc_rs` 拡張を Python 環境にコンパイルし、`import qc` が動くことを確認する、という意味です。この章は
**self-contained（自己完結）**です:必要なコマンドはすべてここにあり、*なぜ*かも説明します。素のレシピより長い
のは意図的です — 自分のマシンに合う部分を読み、残りは飛ばしてください。

2 つの状況:

1. **qc-rs が既にあなた用にインストール済み**（共有クラスタでよくある）— 下の §1 で確認するだけ。
2. **自分でビルドする** — §2 を順に進める。

最後の §3 では、各要素を理解したうえで機械固有のビルド全体を自動化する `make setup` / `make install` の
ショートカットを示します。

## 1. 既に入っているか

共有マシンでは、管理者が既に qc-rs を Python 環境にビルドしてくれているかもしれません。その環境を有効化し
（どれかは確認）、次を実行:

```bash
python -c "import qc; print('qc-rs ok:', qc.__file__)"
```

エラーなくパスが出れば完了 — [クイックスタート](quickstart.md) へ。`ModuleNotFoundError: No module named
'qc'`（または `'qc_rs'`）が出たら、下記で自分でビルドします。

## 2. 自分でビルドする

ビルドには順に:**git**（コード取得）、**Rust** ツールチェーン（コアのコンパイル）、**uv** と Python（環境）、
**BLAS/LAPACK** ライブラリ（密な線形代数バックエンド）、そして **maturin** ビルド本体、が必要です。任意の要素
— **MPI** と **CUDA GPU** — は最後に。

:::{tip} Python メモ
**仮想環境**（"venv"）とは、専用のパッケージを持つ自己完結した Python です。異なるプロジェクトが衝突しません。
qc-rs は **uv** で作成・管理します。venv を*有効化*すると、その `python` がシェルの `python` になります。
:::

### 2.1 ソースを取得

HTTPS（SSH キー不要）または GitHub CLI でクローン:

```bash
git clone https://github.com/qclo/qc_rs.git      # A) HTTPS
gh   repo  clone qclo/qc_rs                        # B) GitHub CLI（`gh auth login` を再利用）
cd qc_rs
```

### 2.2 Rust をインストール（`rustup` 経由）

qc-rs は Rust 拡張をコンパイルするので、Rust ツールチェーンが必要です — ディストリの `rustc` ではなく
**`rustup`** 経由で:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
. "$HOME/.cargo/env"          # このシェルで ~/.cargo/bin を PATH に
which rustc                    # ~/.cargo/bin 以下のパスが出るはず
```

`-y` は非対話実行で、**システムに `/usr/bin/rustc` が既にあるマシンでは必須**です（ないと `rustup-init` が
*"cannot install while Rust is installed"* で中断）。`rustup` は `~/.cargo/bin` を `/usr/bin` より前に置く
ので、`cargo`/`rustc` は rustup のツールチェーンに解決され、ディストリの `rustc` は無視されます。新しいシェル
では毎回 `~/.cargo/env` を source（またはシェル rc に記述）。

### 2.3 uv をインストールしプロジェクト venv を作る

qc-rs は、リポジトリ内の `./.venv` ではなく、`UV_PROJECT` 環境変数が指す**共有外部 uv プロジェクト**（1 つの
ライブラリ集合を持つディレクトリ）にビルドします。マシンごとに一度セットアップ:

```bash
# uv をインストール（マシンごとに一度）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 共有プロジェクトのディレクトリを決め、uv を向ける
export UV_PROJECT=~/local/myproj
mkdir -p "$UV_PROJECT"

# base プロジェクトファイル:qc-rs が前提とする共通の科学 Python スタック
cat << 'EOF' > "$UV_PROJECT/pyproject.toml"
[project]
name = "myproj"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [ "numpy>=2.4", "scipy>=1.16", "pandas>=2.3",
                 "matplotlib>=3.10", "scikit-learn>=1.8" ]
EOF

uv python install 3.14        # Python インタプリタ取得（マシンごとに一度）
uv python pin 3.14            # このプロジェクトで使う
uv sync                       # venv を作り base 依存を導入
source "${UV_PROJECT}/.venv/bin/activate"    # プロジェクト venv を有効化
```

`UV_PROJECT` が設定されているので、`uv sync` / `uv add` / `uv python pin` は `--project` なしでそのプロジェクトに
作用します。

### 2.4 qc-rs の Python 依存を追加

qc-rs 自身が必要とするパッケージを追加します。**必ず `uv add`、`uv pip install` は使わない**（numpy/matplotlib
は base から入る）:

```bash
uv add --dev maturin   --project "$UV_PROJECT"   # qc_rs 拡張をビルド（最重要）
uv add --dev pytest    --project "$UV_PROJECT"   # テストスイート
uv add mpi4py          --project "$UV_PROJECT"   # Python からの MPI（python-mpi-direct 用）
uv add h5py            --project "$UV_PROJECT"   # HDF5（.qch5）チェックポイントの読み書き
uv add geometric       --project "$UV_PROJECT"   # 構造最適化ドライバ（mychk.scf(...).opt()）
uv add --dev ipykernel --project "$UV_PROJECT"   # 任意:VS Code でノートブック
uv add --dev patchelf  --project "$UV_PROJECT"   # Linux のみ:maturin がライブラリ rpath を埋め込める
```

ここまでが**必須**セットです。以下は**推奨** — 特に理由がなければ一緒に入れてください。合わせると共有環境が
完成します:可視化、参照突き合わせ、ドキュメントツール、そして本マニュアルをビルドするツールチェーン。（基盤の
科学スタック — numpy, scipy, pandas, matplotlib, scikit-learn — は §2.3 の base `pyproject.toml` から既に
入っているので、別途 `uv add` は不要です。）

**可視化** — プロット、ノートブック内の 3D 分子/軌道:

```bash
uv add plotly ipywidgets kaleido nbformat --project "$UV_PROJECT"  # 図/ギャラリー/HTML（plotly）、対話パネル（ipywidgets）、静的 PNG 出力（kaleido）、ノートブックのインライン描画（nbformat）;qc.view の 2D/一般 3D backend も
uv add py3dmol                            --project "$UV_PROJECT"  # セル内の等値面/分子軌道描画（qc.view 3D ビューア;自己完結 HTML）
uv add anywidget                          --project "$UV_PROJECT"  # 対話モデラー（mychk.modeler(): 選択/測定/入力 emit）
```

**参照・ドキュメントツール** — PySCF との突き合わせ、論文の読み込み、結果の書き出し:

```bash
uv add --dev pyscf                 --project "$UV_PROJECT"  # テスト/ベンチの参照値
uv add --dev pyscf-dispersion      --project "$UV_PROJECT"  # PySCF の DFT-D3/D4、qc-rs の分散補正の突き合わせ用
uv add --dev pymupdf pymupdf4llm   --project "$UV_PROJECT"  # PDF/論文の読み込み（-> Markdown）
uv add --dev python-pptx           --project "$UV_PROJECT"  # .pptx スライド生成
uv add --dev openpyxl pdfplumber   --project "$UV_PROJECT"  # Excel 入出力 / PDF 表抽出
uv add --dev pillow                --project "$UV_PROJECT"  # 画像処理
```

**ドキュメントツールチェーン** — *本*マニュアル（HTML + PDF）を Jupyter Book v1 でビルド:

```bash
uv add --dev "jupyter-book<2" sphinx-design sphinx-proof sphinx-exercise sphinxcontrib-mermaid pyppeteer \
  --project "$UV_PROJECT"
# jupyter-book<2 = Jupyter Book v1（Sphinx ベース;v2/mystmd 回避のため <2 ピン）;sphinx-proof/sphinx-exercise
# = 教科書の定義/定理/演習環境;sphinxcontrib-mermaid = 図;pyppeteer = HTML->PDF（CJK に強い）。
# 詳細は docs/user/README.md。
```

:::{tip} すべて先に追加してから、最後にビルド
`uv add` は毎回**ビルド済みの `qc_rs` を prune** します（本章末の警告参照）。なので `uv add` は*すべて*先に
行い、ビルド — または `make install` での再ビルド — を最後にしてください。
:::

### 2.5 BLAS/LAPACK バックエンドを入れる

**BLAS**（Basic Linear Algebra Subprograms）と **LAPACK** は、あらゆる SCF の核にある重い行列演算 — 行列積や
固有値問題 — を担うライブラリです。qc-rs は 2 つのバックエンドに対応します。プラットフォームに合う方を選んで
ください（[Part IV](../30-hpc/threads-and-blas.md) で詳しく再登場）:

- **OpenBLAS** — オープンソースの既定（macOS、および同梱する Linux マシン）;
- **Intel MKL** — Intel の高度に最適化されたライブラリ（HPC クラスタで一般的、oneAPI 経由）。

インストール手順は OS で異なり、下記 2 つのビルドフローに織り込まれています。

### 2.6 拡張をビルド — 2 つの一般的フロー

ビルドコマンドは **`maturin develop`** で、`qc_rs` をコンパイルしてアクティブ venv に導入します。毎回重要な
のは 2 点:**`VIRTUAL_ENV` を設定**する（さもないと maturin が迷子の `./.venv` に入れる）、バックエンドに合う
**`--features`** を選ぶ（次節）。

#### Linux（例:HPC クラスタ）+ Intel MKL

多くのクラスタにはシステム OpenBLAS がなく **Intel oneAPI MKL** を使います。先に oneAPI 環境を source
（MKL は `MKLROOT` を設定;MPI は `mpicc` を PATH に置く、`python-mpi-direct` のときだけ必要）:

```bash
source ~/.cargo/env
export UV_PROJECT=~/local/myproj
source "${UV_PROJECT}/.venv/bin/activate"
export VIRTUAL_ENV="${UV_PROJECT}/.venv"

# Intel oneAPI: MKL（MKLROOT を設定）と MPI（mpicc を PATH に）— パスは環境に合わせる
. /opt/intel/oneapi/mkl/latest/env/vars.sh intel64
. /opt/intel/oneapi/mpi/latest/env/vars.sh          # python-mpi-direct のときだけ

export MKL_THREADING_LAYER=GNU                        # 下の MKL 注意点参照

"${UV_PROJECT}/.venv/bin/maturin" develop --no-default-features \
  --features intel-mkl-system,xc-bundled,pcm,python-mpi-direct
"${UV_PROJECT}/.venv/bin/pytest" tests/               # 動作確認
```

:::{important} MKL の落とし穴（なぜこの設定か）
- `intel-mkl-system` は MKL の**単一動的ライブラリ `mkl_rt`**（`MKLROOT` で探索）をリンクします。層状の
  `mkl_*` はリンカの既定 `--as-needed` で壊れます。
- `MKL_INTERFACE_LAYER` は既定の **LP64**（32bit 整数）のまま。qc-rs の BLAS/LAPACK バインディングは 32bit
  整数を渡すので、**ILP64 は静かに破壊**します — 決して ILP64 にしないこと。
- `MKL_THREADING_LAYER` は既定が *Intel* で、MKL-only の `vars.sh` が公開しない `libiomp5` を要します。
  **`GNU`**（システム `libgomp` 使用）か `SEQUENTIAL` を設定しないと拡張のロードに失敗します。
- **`patchelf`**（§2.4）がないと maturin はライブラリパス（rpath）を埋め込めないので、実行時に oneAPI の lib
  ディレクトリを `LD_LIBRARY_PATH` に残す必要があります — 上の 2 つの `vars.sh` が既にそれをします。
:::

#### macOS + Homebrew OpenBLAS

[Homebrew](https://brew.sh) でツールチェーンを入れます（マシンごとに一度）:

```bash
xcode-select --install                              # Command Line Tools（clang, ld）— あれば省略
brew install gcc openblas libomp cmake pkg-config
brew install open-mpi                                # 任意:mpi4py / python-mpi-direct 用
```

各パッケージには理由があります:**gcc** は `gfortran`/`libgfortran` を提供（OpenBLAS がリンク）;**openblas** は
BLAS/LAPACK;**libomp** は拡張の*インポート*に必要な OpenMP ランタイム;**cmake** は同梱 libxc をビルド;
**pkg-config** はライブラリ探索用。既定の `openblas-system` 機能でビルド:

```bash
export UV_PROJECT=~/local/myproj
source "${UV_PROJECT}/.venv/bin/activate"
export VIRTUAL_ENV="${UV_PROJECT}/.venv"
export OPENBLAS_PATH="$(brew --prefix openblas)"
export LIBRARY_PATH="$(brew --prefix gcc)/lib/gcc/current"
export RUSTFLAGS="-L $(brew --prefix libomp)/lib -l dylib=omp -L $(brew --prefix gcc)/lib/gcc/current -l dylib=gfortran"
export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix libomp)/lib:${OPENBLAS_PATH}/lib:${LIBRARY_PATH}:${DYLD_FALLBACK_LIBRARY_PATH:-}"

"${UV_PROJECT}/.venv/bin/maturin" develop
"${UV_PROJECT}/.venv/bin/pytest" tests/
```

`RUSTFLAGS`/`DYLD_FALLBACK_LIBRARY_PATH` の行が `libomp` と `libgfortran` をリンク・探索します。これがないと
`import qc` が *"symbol not found … `__gfortran_…`"* や OpenMP ランタイム欠如で失敗します。

### 2.7 機能フラグ（`--features`）

`maturin develop --features …` はビルド時に任意要素を選びます。**既定ビルド**は `openblas-system,
python-mpi-direct, xc-bundled, pcm, hdf5`。実際に切り替えるのは:

| 機能 | 何が得られるか |
|---|---|
| `openblas-system` | Homebrew/システム OpenBLAS（macOS 既定） |
| `openblas-bundled` | ソースから静的ビルドした OpenBLAS（システム OpenBLAS 不要） |
| `intel-mkl-system` | `mkl_rt` 経由の Intel MKL（Linux/HPC;`MKLROOT` 必要） |
| `xc-bundled` / `xc-system` | libxc（DFT 汎関数）を同梱ソース / システムパッケージから |
| `pcm` | 陰的溶媒和（PCM）モジュール |
| `python-mpi-direct` | mpi4py 初期化 Python から呼べる Rust MPI 関数 |
| `hdf5` | HDF5（`.qch5`）チェックポイント I/O |
| `cuda` | 任意の NVIDIA-GPU 積分/Fock パス（既定 OFF;§5 参照） |

`--no-default-features` はすべてを OFF にし、`--features` 一覧を厳密にします（上の MKL フローで使用）。ビルド後、
Python の**センチネル**が何がコンパイルされたかを報告します:

```python
import qc
qc.XC_ENABLED, qc.PCM_ENABLED, qc.MPI_DIRECT_ENABLED, qc.GPU_ENABLED
```

## 3. 簡単な方法:`make setup` + `make install`

§2 では、各要素を理解できるようにビルドを手で辿りました。実際にはそれを毎回打ち直すことはまれです — qc-rs は
**機械固有**の設定を共有コードベースの外に置き、**プロファイル**から再生成します。動かし方は 2 通りあり、生成
されるファイルは*同じ*です:

- **§3.1 — AI コーディングアシスタントに任せる（新しいマシンでは推奨）。**
- **§3.2 — `make setup` / `make install` を自分で実行する。**

### 3.1 AI アシスタントに任せる（推奨）

新品のマシンでビルドを正しく決めること — 適切な BLAS バックエンド、正しい `RUSTFLAGS`、厳密な `--features`、
プロファイル — は、まさに **AI コーディングアシスタント**が得意な環境固有の雑務です。これは小手先の技ではなく、
[qc-rs 自身がそれで作られている](what-is-qc-rs.md) のと*同じ* AI ファースト（"vibe coding"）の流儀を、あなた自身の
セットアップに当てはめるものです。次章 [AI コーディングアシスタント](ai-coding-clis.md) で **Claude Code** や
**Codex** の入れ方を示します;1 つ用意できたら、この道を優先してください。

:::{important} アシスタントが**代わりに入れてはくれない**前提
アシスタントは qc-rs を*設定してビルド*しますが、システムのツールチェーンは入れません。§2.1–§2.5 は自分で済ませて
おく必要があります:**git**、**uv と Python**、**Rust**（`rustup`）、**BLAS/LAPACK** ライブラリ、そして — 並列実行
が要るときだけ — **MPI**。この 5 つは始める前に揃っている前提で、アシスタントはそこから引き継ぎます。
:::

前提が入っていれば、**リポジトリのディレクトリで**アシスタントを開き、平易な言葉で頼みます — 例えば:

> `make setup` と `make install` で qc-rs をビルドして、ビルド設定をこのマシンのプロファイルに保存して。

アシスタントは環境（どの OS か、どの Python/venv か、MKL か OpenBLAS か、`nvcc` や MPI があるか）を調べ、
`mytools/setup/profiles/` 下に合った**プロファイル**を書き、`make setup` で機械固有ファイルを生成し、
`make install` で拡張をコンパイルし、そして — これが真価です — **ビルドエラーを自分で読んでフラグを直し**、
`import qc` が venv で通るまで反復します。あなたは目的を述べ、機械固有の細部はアシスタントが引き受けます。
この節の残りは、それ（またはあなた）が何をしているかを説明するので、作業を確認したり手で再現したりできます。

### 3.2 自分でやる

直接実行したい場合（またはまだアシスタントを用意していない場合）、同じプロファイル機構は 1 コマンドです:

```bash
make setup
```

`make setup` が行うことの詳細:

- **プロファイル**を読む — `mytools/setup/profiles/` 下の小さな JSON（例 `local.json`,
  `yanai-linux-mkl.json`, `yanai-mac-openblas.json`）で、*あなたの* Python インタプリタ・BLAS バックエンド・
  MPI 構成・`RUSTFLAGS`/oneAPI 環境・マシンごとの厳密な Cargo `--features` — つまり §2.6–§2.7 で手で選んだ
  すべて — を記録。
- そこから**git-ignore された機械固有ファイルを生成**:エディタ設定（`.vscode/settings.json`, `tasks.json`,
  `launch.json`, `my.env`）、シェル環境ファイル（`mytools/setup/local/env.sh`）、正しい `maturin develop` を
  実行する**インストールヘルパー**（`mytools/setup/local/install-qc.sh`）。
- プロファイルを**自動検出して記憶**（`mytools/setup/local/state.json`）するので、以後 `make setup` は引数
  不要。

(install-profile)=

### プロファイルの中身

プロファイルは小さな JSON ファイルです — 理解しておく価値があります。なぜなら、これは §2.6–§2.7 で手で行った
ことを 1 か所にまとめた*そのもの*だからです。Linux + MKL プロファイルの形を注釈付きで:

```json
{
  "os": "linux",                     // "linux" または "mac"
  "backend": "mkl",                  // "mkl" または "openblas" — BLAS 機能を決める
  "python": "/home/you/local/myproj/.venv/bin/python",   // venv インタプリタ（→ VS Code）
  "vscode": {
    "activate_env": true,            // VS Code ターミナルで venv を自動有効化
    "rust_analyzer": {               // Rust 言語サーバがコアをどうコンパイルするか
      "no_default_features": true,
      "features": ["intel-mkl-system", "xc-bundled", "pcm"],
      "extra_env": { "MKLROOT": ".../mkl/2025.2", "MKL_THREADING_LAYER": "GNU" }
    }
  },
  "my_env": {                        // 実行時 env 変数 -> .vscode/my.env
    "MKL_THREADING_LAYER": "GNU",
    "MKL_INTERFACE_LAYER": "LP64",
    "LD_LIBRARY_PATH": ".../mpi/2021.16/lib"
  },
  "build": {
    "task_label": "maturin develop (MKL, myproj)",   // VS Code ビルドタスク名
    "shell": "/bin/bash",
    "pre": [                         // ビルド前に source（env.sh にもなる）
      "source ~/.cargo/env",
      "export UV_PROJECT=~/local/myproj",
      "source \"${UV_PROJECT}/.venv/bin/activate\"",
      "export VIRTUAL_ENV=\"${UV_PROJECT}/.venv\"",
      ". .../mkl/2025.2/env/vars.sh intel64",
      ". .../mpi/latest/env/vars.sh"
    ],
    "rustflags": "-C link-arg=-Wl,-rpath,.../mkl/lib:.../mpi/lib",   // ライブラリ rpath を埋め込む
    "maturin_args": "--no-default-features --features intel-mkl-system,xc-bundled,pcm,python-mpi-direct,hdf5"
  }
}
```

フィールドごとに:

- **`os`, `backend`** — プラットフォームと BLAS 選択（`mkl` / `openblas`）。合わせて既定の `--features` を決定。
- **`python`** — venv インタプリタの絶対パス。VS Code がインタプリタに使い、ビルドはここから `VIRTUAL_ENV` を
  導出。
- **`vscode.activate_env`** — VS Code 統合ターミナルで venv を自動有効化。
- **`vscode.rust_analyzer`** — Rust 言語サーバがコアをどうコンパイルし、解析をビルドに合わせるか
  （`no_default_features`、`features` 一覧、`MKLROOT` などの `extra_env`）。Rust 側エディタ IntelliSense
  のみに影響し、Python ビルドには影響しない。
- **`my_env`** — `.vscode/my.env` にそのまま書かれ、エディタから実行/デバッグする際に使う実行時 env 変数:
  ここでは MKL のスレッド/インターフェース層と MPI の `LD_LIBRARY_PATH`。
- **`build.pre`** — ビルドの*前*に source するシェル行（venv 有効化;`~/.cargo/env` と oneAPI `vars.sh` を
  source）。この同じ行が `mytools/setup/local/env.sh` をワンショットの開発シェルにします —
  `source mytools/setup/local/env.sh` で Rust + uv + venv + MKL が一括で整う。
- **`build.rustflags`** — 追加リンカフラグ。通常はライブラリ探索パスを拡張に埋め込む `-rpath` で、
  `LD_LIBRARY_PATH` なしでインポートできるようにする。
- **`build.maturin_args`** — このマシン用の厳密な `maturin develop` 機能文字列。
- **`build.task_label`** — 生成される VS Code ビルドタスク名（*Tasks: Run Build Task* で見える）。

新品のマシンでは、`make setup` がノードごとの絶対パスを**自動検出**し、リファレンスプロファイルを上書きする
git-ignore の `profiles/local.json` を書きます — 実際には `make setup` を実行し、検出パスが誤っているときだけ
`local.json` を編集します。

バリアント:

```bash
make setup --list                 # 利用可能なプロファイルを一覧
make setup PROFILE=<name>         # 特定のプロファイルを選ぶ
make setup FORCE=1                # 既存の生成ファイルを上書き（.bak なし）
```

そして生成ヘルパーで qc-rs を venv にビルド:

```bash
make install
```

`make install` は `install-qc.sh` を実行 — あなたのマシンの機能とライブラリ rpath を埋め込んだ
`maturin develop` なので、`import qc` が追加の環境変数なしで動きます。`make setup` の**後**に実行。

:::{note} `make setup` が書くものはすべて git-ignore
*あなたの*機械設定でありコミットされません。新品のマシンは独自プロファイルが要るかも — `mytools/setup/profiles/`
の近いものをコピーし、interpreter/BLAS/MPI を編集。
:::

## 4. 確認

```bash
python -c "import qc; print('qc-rs ok')"
```

そして [クイックスタート](quickstart.md) を実行:`-76.026772` が出れば端から端まで動いています。

## 唯一の落とし穴:`uv add` は qc-rs を prune する

:::{warning}
`uv add`・`uv remove`・`uv sync` は venv をプロジェクトのロックファイルに合わせ、maturin でビルドした `qc_rs`
拡張を**アンインストール**します（`pyproject.toml` に宣言されていないため）。パッケージ追加後に急に `import qc`
が失敗したら — 例 `ModuleNotFoundError: No module named 'qc_rs'` や
`ImportError: libmkl_rt.so.2: cannot open shared object file` — 再ビルド:

```bash
make install         # または maturin develop を再実行
```

`uv` 操作を先に、再ビルドを最後に。prune を避けるには `uv pip install` / `uv pip uninstall`（ロックファイルを
触らない）か `uv sync --inexact`。
:::

## 5. 任意:MPI と GPU

- **MPI**（多数マシンで実行）。MPI 実装（`brew install open-mpi`、またはクラスタの module）と `mpi4py`（§2.4）
  を入れ、**`python-mpi-direct`** 機能（既定に含まれる）でビルド。ただし高速相互接続（InfiniBand）で実際に
  *走らせる*のは独自の難しさがあり、[Part IV → MPI と相互接続](../30-hpc/mpi-and-interconnects.md) でゼロから
  教えます。
- **GPU**（NVIDIA CUDA）。既定ビルドは **CUDA フリーでどこでも動く**。有効化には NVIDIA GPU（compute
  capability ≥ 7.0）、CUDA Toolkit（`nvcc`, `cudart`, cuBLAS）、CMake ≥ 3.19 が必要で、`maturin develop` に
  **`cuda`** 機能を追加。詳細は [Part IV → GPU 計算](../30-hpc/gpu-cuda.md)。

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

初回ビルドでよくあるエラー:

- **`symbol not found … __gfortran_…` / OpenMP 欠如（macOS）** — §2.6 の `RUSTFLAGS` /
  `DYLD_FALLBACK_LIBRARY_PATH` が欠けているか誤り（`libgfortran`/`libomp` をリンクする行）。
- **`libmkl_rt.so.2: cannot open shared object file`（Linux）** — このシェルで MKL の `vars.sh` を source
  していないか、`uv add` が拡張を prune した（`make install` で再ビルド）。
- **大サイズで結果が異常/静かに破壊（MKL）** — `MKL_INTERFACE_LAYER=ILP64` にした;既定の **LP64** を使う。
- **`xc-system` が `libxc.pc` を見つけない** — 同梱ビルドを使う:`--features xc-bundled`。
- **`uv` コマンド直後に `ModuleNotFoundError: qc_rs`** — 上記の prune;`make install`。

さらに [トラブルシューティングと FAQ](../40-reference/troubleshooting.md) を。qc-rs が入ったら
[クイックスタート](quickstart.md) へ、または次に [VSCode](editor-vscode.md) でエディタを設定しましょう。