# エディタ設定: VSCode

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

## VSCode と必須拡張を入れる

[code.visualstudio.com](https://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](https://claude.ai) か
[Codex](https://chatgpt.com/codex) — を入れて**、VSCode の統合ターミナル（**Terminal → New Terminal**、
または `` Ctrl+` ``）で開いたままにしておくことを勧めます。これは qc-rs にとって単なる「あると便利」ではなく、
**qc-rs が本来そう使われることを意図した AI ファースト（"vibe coding"）の流儀**であり、プロジェクト自身がそれで
作られている流儀そのものです。すぐに効く具体的な理由をいくつか:

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

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

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

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

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

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

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

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

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

```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` — 実行時環境変数

```text
# 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` にあります）。選択中のインタプリタは下部のステータスバーに表示されます。

:::{note}
`.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 計算をいくつか実行し、実況の
量子化学風ログを流します。

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

1. venv に **`ipykernel`** が入っていることを確認（VSCode がそこでカーネルを起動できるように）:
   `uv add --dev ipykernel --project "$UV_PROJECT"`、その後 `make install` で qc-rs を再ビルド（`uv add` が
   拡張を prune することを思い出してください）。
2. **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=...)` の
**実況ログ**です:

```python
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")     # 量子化学風トランスクリプトを流す
```

```text
── 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` 推定（[中核概念](concepts.md)）、DIIS 加速つき SCF
サイクル表、収束チェック — が、本物の量子化学の出力です。

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

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

| オプション | 何をするか |
|---|---|
| `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 をビルドしてプレビューします:

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

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

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

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

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