エディタ設定: VSCode

エディタ設定: VSCode#

qc-rs はどのエディタでも使えますが、Visual Studio Code（VSCode）は良い既定です。無料で、どの OS でも同じように動き、Python と Jupyter のサポートが優秀で、そして量子化学で重要なことに、リモートマシン（クラスタ）のコードをローカルのように編集・実行できます。この章では快適な qc-rs ワークスペースを整えます。任意なので、別のエディタが好みならクイックスタートへ飛んでかまいません。

VSCode と必須拡張を入れる#

code.visualstudio.com から VSCode を入れ、いくつかの拡張を追加します（拡張パネルはサイドバーの四角いアイコン、または Ctrl/Cmd+Shift+X）:

Python と Pylance（Microsoft）— 言語サポート、補完、インタプリタ管理;
Jupyter（Microsoft）— ノートブックと対話セルの実行;
Remote - SSH（Microsoft）— リモートマシンでの編集・実行（下記）;
任意:Live Preview（本マニュアルの HTML プレビュー）、Rust コアを触るなら rust-analyzer。

推奨:AI コーディングアシスタント#

先に進む前に、AI コーディングアシスタント — Claude Code か Codex — を入れて、VSCode の統合ターミナル（Terminal → New Terminal、または Ctrl+`）で開いたままにしておくことを勧めます。これは qc-rs にとって単なる「あると便利」ではなく、 qc-rs が本来そう使われることを意図した AI ファースト（"vibe coding"）の流儀であり、プロジェクト自身がそれで作られている流儀そのものです。すぐに効く具体的な理由をいくつか:

qc-rs をビルドしてくれる。 新しいマシンでは、make setup / make install を実行してビルドプロファイルを保存するよう頼めば、BLAS/MPI/Python を検出してフラグを自分で直します。これはインストール §3.1 の推奨ビルド手順です。
リポジトリの中から「どうやるの？」に答える。 ソースと本マニュアルを読むので、計算の回し方・オプションの意味・ビルド失敗の原因を、エディタを離れずに尋ねられます。
一緒にコードを書き・直す。 アシスタントはターミナルに常駐するので、VSCode で開いているまさにそのファイルを編集します;その差分はエディタのソース管理ビューでレビューできます。

次章はこれらのツールの導入と操作に充てています（Node.js 不要の curl … | sh 一行インストーラ）。Claude Code には公式の VSCode 拡張もあり（拡張パネルで "Claude Code" を検索）、ターミナル CLI にサイドパネルを重ねられます。GUI が好みならこちらを。

リモートマシン（クラスタ）で作業する#

量子化学のジョブは、手元のノート PC ではなく共有サーバで動くことがよくあります。Remote - SSH を使うと、リモートマシンを VSCode の中に開けます:

Ctrl/Cmd+Shift+P → "Remote-SSH: Connect to Host…" → サーバを選ぶ（または追加）、例 you@cluster。
新しい VSCode ウィンドウがサーバ上で開きます。File → Open Folder… で qc-rs のチェックアウトを選択。
これ以降、ターミナル・Python・マニュアルのビルドなど、すべてがサーバ上で動きます。手元の PC は画面とキーボードにすぎません。

Tip

Remote-SSH はポートも自動転送します。これが、ローカルで配信した Web ページ（ビルドしたマニュアルなど）を手元のブラウザで見る仕組みです — 下の「マニュアルをプレビュー」参照。

VSCode を qc-rs 環境に向ける#

VSCode には、どの Python を使うか — qc-rs が入った uv venv — を教える必要があります。make setup が既にやってくれています:git-ignore の .vscode/ フォルダに 4 つのファイルを生成します。VSCode がどのように venv を使い、Rust コアを再ビルドし、正しい環境で実行するのかが分かるので、読む価値があります。（これらはすべてプロファイル由来です — インストール → プロファイルの中身参照。）

`settings.json` — ワークスペース設定#

{
  "python.defaultInterpreterPath": "/home/you/local/myproj/.venv/bin/python",
  "python.envFile": "${workspaceFolder}/.vscode/my.env",
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  "python.terminal.activateEnvironment": true,
  "terminal.integrated.env.linux": { "UV_PROJECT": "/home/you/local/myproj" },
  "rust-analyzer.cargo.noDefaultFeatures": true,
  "rust-analyzer.cargo.features": ["intel-mkl-system", "xc-bundled", "pcm"],
  "rust-analyzer.cargo.extraEnv": { "MKLROOT": ".../mkl/2025.2", "MKL_THREADING_LAYER": "GNU" }
}

python.defaultInterpreterPath — VSCode をあなたの venv の Python（qc-rs 入り）に向け、Run とターミナルが自動でそれを使う。
python.envFile — コード実行時に .vscode/my.env（下記）から環境変数を読み込む。
python.testing.pytestEnabled / pytestArgs — Testing パネルを有効にし pytest tests を実行 — 個々のテストをクリックで実行・デバッグできる。
python.terminal.activateEnvironment / terminal.integrated.env.linux.UV_PROJECT — 新しい統合ターミナルで venv を自動有効化し UV_PROJECT を設定するので、uv コマンドが正しいプロジェクトに作用する。
rust-analyzer.cargo.* — Rust コアを編集する場合のみ関係:Rust 言語サーバをビルドと同じ機能/環境でコンパイルさせ、インラインエラーを実際と一致させる。

`my.env` — 実行時環境変数#

# GENERATED by mytools/setup/bootstrap.py — do not edit by hand.
MKL_THREADING_LAYER=GNU
MKL_INTERFACE_LAYER=LP64
LD_LIBRARY_PATH=.../mpi/2021.16/lib

拡張が実行時に必要とする変数です（MKL のスレッド/インターフェース層;MPI ライブラリパス）。settings.json とデバッグ構成がこのファイルを読むので、Run や F5 が何も export せずに「そのまま動き」ます。

`tasks.json` — ビルドタスク#

"maturin develop (MKL, myproj)" のようなラベルのシェルタスクが 1 つ。そのコマンドはビルド環境を source し（~/.cargo/env・venv・oneAPI vars.sh）、RUSTFLAGS を設定し、あなたの機能一覧で maturin develop を実行 — つまりプロファイルの build.pre / rustflags / maturin_args そのものです。Ctrl/Cmd+Shift+P → "Tasks: Run Build Task" で make install を打つ代わりに実行します。

`launch.json` — 実行/デバッグ構成#

2 つの debugpy 構成、"Python: Current File (qc-rs)" と "Python: helloworld.py"。それぞれ:あなたのインタプリタで統合ターミナルで実行し、.vscode/my.env を読み込み、justMyCode: false（ライブラリコードにもステップイン可）を設定し、そして重要なことに preLaunchTask を上のビルドタスクに設定 — なので VSCode はデバッグ実行のたびに qc-rs を再ビルドします。F5 を押すと、編集した Rust コアが再コンパイルされ、スクリプトが走ります。

なので make setup の後、VSCode は既に正しいインタプリタを選んでいるはずです。もし選ばれていなければ、 Ctrl/Cmd+Shift+P → "Python: Select Interpreter" で uv venv の下のものを選びます（そのパスは settings.json にあります）。選択中のインタプリタは下部のステータスバーに表示されます。

注釈

.vscode/ は make setup が生成したgit-ignore の機械設定で、あなた専用でありコミットされません。再生成が必要なら（venv やバックエンドを変えたときなど）make setup を再実行してください。

コードの実行とデバッグ#

スクリプト実行。 .py を開いて右上の ▷ Run ボタン、または F5 でデバッガ付き実行。
エディタから qc-rs を再ビルド。 Rust コアを変更したら、Ctrl/Cmd+Shift+P → "Tasks: Run Build Task" で make install を打つ代わりに maturin ビルドタスクを実行。
対話 / ノートブック。 .ipynb ノートブック（または .py に # %% セルマーカー）を作り、セルを 1 つずつ実行 — 計算の探索、収束のプロット、分子の表示に最適。ノートブックでは %matplotlib inline でセル内に図を表示。
デバッグ。 行番号の左（ガター）をクリックしてブレークポイントを置き、F5。そこで実行が止まり変数を調べられます — スクリプトが思い通りに動かないときに非常に有用。

Tip

Python メモ .ipynb ノートブックは、コードセルとその出力（数値・表・図）を 1 つの文書に交互に並べます。qc-rs を試す最も初心者向けの方法です:セルを実行し、結果を見て、編集し、また実行。

Jupyter ノートブックと `helloworld.ipynb`#

ノートブックは qc-rs を探索する最も楽しい方法です:セルを 1 つ実行し、結果を見て、いじって、また実行。リポジトリには遊べるものが同梱されています — myworkspace/helloworld.ipynb — 本物の SCF 計算をいくつか実行し、実況の量子化学風ログを流します。

ノートブック環境を整える#

venv に ipykernel が入っていることを確認（VSCode がそこでカーネルを起動できるように）: uv add --dev ipykernel --project "$UV_PROJECT"、その後 make install で qc-rs を再ビルド（uv add が拡張を prune することを思い出してください）。
Jupyter 拡張を入れる（本章上部の拡張一覧）。

正しいカーネルを選ぶ — `import qc` が動くように#

ここが皆がつまずく唯一のステップです。ノートブックはカーネル（ある Python）に対して動き、それは qc-rs が入った uv venv の Python でなければなりません — さもないと最初のセルが ModuleNotFoundError: No module named 'qc' で失敗します。make setup はそのインタプリタを既に .vscode/settings.json（python.defaultInterpreterPath）に記録しているので、VSCode は通常それを提示します。確実にするには:myworkspace/helloworld.ipynb を開き、ノートブック右上の "Select Kernel" → "Python Environments…" → uv プロジェクト配下のインタプリタ（例 …/myproj/.venv/bin/python、settings.json に表示されるのと同じパス）を選びます。

Tip

カーネル = VSCode インタプリタ = あなたの uv Python ノートブックのカーネル、VSCode のインタプリタ（python.defaultInterpreterPath）、そして uv プロジェクトの python は、すべて同じ venv でなければなりません。ずれると import qc が壊れます。迷ったらセルで import sys; print(sys.executable) を実行 — …/.venv/bin/python が出るはずです。

遊ぶ、そしてログを見る#

myworkspace/helloworld.ipynb を開き、セルを実行（セルの ▷、または Run All）。水のチェックポイントを作り SCF を実行し、次に重い例（ECP + RI + DFT + 分散の銀錯体）を実行します。一番の見どころは run(log=...) の 実況ログです:

mychk = qc.chk.new(atom="O 0 0 0; H 0.757 0.586 0; H -0.757 0.586 0",
                   ao="def2-svp", unit="angstrom")
mychk = mychk.scf(ref="r").run(log="stdout")     # 量子化学風トランスクリプトを流す

── System ───────────────────────────────────────────────
  formula H2O
  charge 0   spin 1 (2S+1)   electrons 10 (5α / 5β)
  basis sets (spherical AOs):  AO def2-svp   24 functions
  nuclear repulsion: 9.1939131606 Eh
── plan ──────────────────────────────────────────────────
  2 steps (topological order)
    1  guess:sad        [auto]         ⇒ guess, density, mo
    2  scf:rhf          [user]  ← 1    ⇒ scf-ref, mo, density
── SCF rhf ────────────────────────────────────────────────
 cycle        E / Eh             dE       RMS[grad]  accel
     1       -75.465273843             -      2.56e-1      —
     …
     9       -75.961008958     -9.42e-11      2.37e-7  cdiis
✓ converged in 9 cycles

このトランスクリプト — システム要約、自動挿入された sad 推定（中核概念）、DIIS 加速つき SCF サイクル表、収束チェック — が、本物の量子化学の出力です。

いくつかの `run(...)` オプション#

.run() は出力と並列のオプションを取ります。まず手を伸ばすであろう少数（全体はログと出力の章）:

オプション	何をするか
`log="stdout"`	実況トランスクリプトをセルに流す（ファイルパスやオブジェクトも可）
`log_style="modern"` / `"orca"`	トランスクリプトの見た目のスタイルを選ぶ
`plot=True`	SCF 収束プロットをインライン描画（matplotlib + `%matplotlib inline` が必要）
`nthread=8`	この実行に CPU スレッド 8 本を使う

実行後は再計算なしにトランスクリプトを再表示・確認できます:mychk.log() はテキストで表示（format="markdown"/"jsonl" も）、mychk.show() は現在の状態と結果のスナップショットを描画、 mychk.run_events() は生イベントを JSON で返します。

マニュアルをプレビュー#

編集しながら本マニュアルを読むには、HTML をビルドしてプレビューします:

make docs-html          # docs/user/{en,ja}/_build/html をビルド（jupyter-book が必要）

そのあと、docs/user/en/_build/html/index.html を右クリック → "Open with Live Preview"、または配信して VSCode にポート転送させます:

python -m http.server 8000 --directory docs/user/en/_build/html

ブラウザで http://localhost:8000 を開きます（Remote-SSH がポート 8000 を自動転送）。

エディタとノートブックが整ったら、クイックスタートで最初の計算を実行しましょう。