# 環境構築手順 (Environment Setup)

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

## 前提条件 (Prerequisites)

| ツール | 用途 | 入手元 |
| --- | --- | --- |
| Git | リポジトリ操作 | https://git-scm.com/download/win |
| GitHub CLI（`gh`） | PR 作成・マージ | https://cli.github.com/ |
| 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; mitsuba.set_variant('llvm_rgb'); print(mitsuba.__version__)"
```

Mitsuba のバージョンが表示されれば OK．

### 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` を尊重する

### `mitsuba.set_variant('llvm_rgb')` でエラー

- LLVM ランタイムが Mitsuba wheel に同梱されているはずだが，万一エラーになる場合は `scalar_rgb` に切り替えて挙動を切り分け．恒久対応は upstream 側 issue を参照

### Python 3.12 が手元にない

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

## GPU 対応（任意）

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

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

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