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

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

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

2 つの状況:

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

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

1. 既に入っているか#

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

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

エラーなくパスが出れば完了 — クイックスタートへ。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 でクローン:

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 経由で:

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 つのライブラリ集合を持つディレクトリ）にビルドします。マシンごとに一度セットアップ:

# 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 から入る）:

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 分子/軌道:

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 との突き合わせ、論文の読み込み、結果の書き出し:

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 でビルド:

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 で詳しく再登場）:

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 のときだけ必要）:

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/               # 動作確認

重要

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 でツールチェーンを入れます（マシンごとに一度）:

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 機能でビルド:

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 のセンチネルが何がコンパイルされたかを報告します:

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 自身がそれで作られているのと同じ AI ファースト（"vibe coding"）の流儀を、あなた自身のセットアップに当てはめるものです。次章 AI コーディングアシスタントで Claude Code や Codex の入れ方を示します;1 つ用意できたら、この道を優先してください。

重要

アシスタントが代わりに入れてはくれない前提アシスタントは 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 コマンドです:

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 は引数不要。

プロファイルの中身#

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

{
  "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 を編集します。

バリアント:

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

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

make install

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

注釈

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

4. 確認#

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

そしてクイックスタートを実行:-76.026772 が出れば端から端まで動いています。

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

警告

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 — 再ビルド:

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 と相互接続でゼロから教えます。
GPU（NVIDIA CUDA）。既定ビルドは CUDA フリーでどこでも動く。有効化には NVIDIA GPU（compute capability ≥ 7.0）、CUDA Toolkit（nvcc, cudart, cuBLAS）、CMake ≥ 3.19 が必要で、maturin develop に cuda 機能を追加。詳細は Part IV → GPU 計算。

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

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

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 を。qc-rs が入ったらクイックスタートへ、または次に VSCode でエディタを設定しましょう。