# 環境構築手順 (Environment Setup)

新規参加者・別デバイス・環境を作り直す場合の手順．Windows 10 / 11 を前提とする．

## 前提条件 (Prerequisites)

| ツール | 用途 | 入手元 |
| --- | --- | --- |
| Git | リポジトリ操作 | https://git-scm.com/download/win |
| GitHub CLI（`gh`） | PR 作成・マージ | https://cli.github.com/ |
| LLVM | Mitsuba 3 が JIT 実行時に呼ぶ `LLVM-C.dll` を提供（CPU レンダリングに必須） | `winget install LLVM.LLVM`（管理者権限プロンプトを承認） |
| Fusion 360（任意） | 筐体 3D モデル編集．シミュレーション実行のみなら不要 | https://www.autodesk.co.jp/products/fusion-360 |

Python は **uv** が自動で取得するため，手動インストール不要．

## 手順 (Steps)

### 1. uv をインストール

PowerShell を開き，以下を実行する．

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

バージョンを確認：

```powershell
uv --version
```

### 2. リポジトリをクローン

```powershell
git clone https://github.com/rintoHasegawa/SmTIAS-LightSim.git
cd SmTIAS-LightSim
```

### 3. 依存と Python ランタイムを同期

```powershell
uv sync
```

このコマンドだけで以下が実行される：

- `.python-version` に書かれた Python 3.12 を uv が自動取得
- `pyproject.toml` + `uv.lock` から完全同一の依存関係を再現
- 仮想環境 `.venv/` を作成

### 4. 動作確認

```powershell
uv run python -c "import mitsuba as mi; mi.set_variant('llvm_ad_rgb'); print(mi.__version__, mi.variant())"
```

`3.8.0 llvm_ad_rgb` のように表示されれば OK．エラー（`LLVM-C.dll could not be found`）が出る場合は前提条件の LLVM が入っていない．

### 5. ツール類の確認

```powershell
uv run pytest --version    # テスト実行用
uv run ruff --version      # Lint / Format 用
```

## よくある操作 (Common Tasks)

| やりたいこと | コマンド |
| --- | --- |
| 依存追加 | `uv add <パッケージ名>` |
| 開発用依存追加 | `uv add --dev <パッケージ名>` |
| 依存更新 | `uv lock --upgrade` → `uv sync` |
| スクリプト実行 | `uv run python <スクリプト>` |
| テスト実行 | `uv run pytest` |
| Lint / Format | `uv run ruff check .` / `uv run ruff format .` |

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

### `uv sync` が遅い / 失敗する

- ネットワーク状態を確認．Mitsuba 3 の wheel はサイズが大きい（〜100 MB）
- 企業ネットワーク内ではプロキシ設定が必要：`uv` は環境変数 `HTTPS_PROXY` を尊重する

### `LLVM-C.dll could not be found` エラーが出る

- 前提条件の LLVM が入っていない可能性．`winget install LLVM.LLVM` を管理者として実行
- インストール済みでも見つからない場合は `DRJIT_LIBLLVM_PATH` 環境変数で `LLVM-C.dll` のフルパスを指定する
  - 既定: `C:\Program Files\LLVM\bin\LLVM-C.dll`

### Python 3.12 が手元にない

- `uv sync` が自動で取得する．手動インストール不要

## GPU 対応（任意）

CPU で実行が遅すぎる場合のオプション．導入は **任意**：

1. NVIDIA ドライバを更新
2. CUDA Toolkit 12.x をインストール（Mitsuba 3 のドキュメントが指定するバージョンに従う）
3. コード側で `mitsuba.set_variant('cuda_ad_rgb')` に切替え

詳細は Mitsuba 3 公式ドキュメントを参照．