# 環境構築手順 (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 .` |

## LLVM のインストール（Windows）

Mitsuba 3 の `llvm_*` variant（CPU JIT レンダリング）は `LLVM-C.dll` を必要とする．
`sm-render` を使う場合はこのセクションの手順を完了してから進むこと．

### インストール手順

1. [LLVM GitHub Releases](https://github.com/llvm/llvm-project/releases) から
   `LLVM-<バージョン>-win64.exe`（最新安定版）をダウンロードする
2. インストーラを実行する．インストール先は既定の `C:\Program Files\LLVM\` を推奨
3. 完了後，以下のコマンドでファイルの存在を確認する：

```powershell
Test-Path 'C:\Program Files\LLVM\bin\LLVM-C.dll'
```

`True` が表示されれば OK．

> **補足**: `winget install LLVM.LLVM` でもインストール可能（管理者権限プロンプトの承認が必要）．

### DRJIT_LIBLLVM_PATH の設定（任意）

**コード側（`sm_tias_lightsim.runtime.llvm_init`）が起動時に標準パスを自動探索するため，
通常は環境変数の手動設定は不要．**

LLVM を非標準パスにインストールした場合のみ，以下の PowerShell コマンドで永続化する：

```powershell
[Environment]::SetEnvironmentVariable(
    'DRJIT_LIBLLVM_PATH',
    'C:\<インストール先>\bin\LLVM-C.dll',
    'User'
)
```

> 注意: 既に起動済みのプロセスには反映されない．新規 PowerShell を開いた時点から有効化．

### 動作確認

インストール後，以下のコマンドで sm-render が正常起動することを確認する：

```powershell
uv run sm-render --scene configs/scene_baseline.yaml --output output/_check 2>&1 | Select-Object -First 10
```

初回ログに以下が出力されれば LLVM JIT 経路で正常動作している：

```
INFO ... Mitsuba variant=llvm_ad_rgb, LLVM JIT 経路で実行（DRJIT_LIBLLVM_PATH=C:\Program Files\LLVM\bin\LLVM-C.dll）
```

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

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

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

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

- コード側が自動探索を試みるが，LLVM が標準パス以外にインストールされているか，
  未インストールの場合はこのエラーが発生する
- まず `Test-Path 'C:\Program Files\LLVM\bin\LLVM-C.dll'` でファイルの存在を確認する
- ファイルがない場合: `winget install LLVM.LLVM` を管理者として実行
- ファイルはあるが標準パス以外にある場合: `DRJIT_LIBLLVM_PATH` 環境変数で明示指定する
  （「LLVM のインストール」セクション参照）

### 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 公式ドキュメントを参照．