環境構築手順 (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 -c "irm https://astral.sh/uv/install.ps1 | iex"

バージョンを確認：

uv --version

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

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

※ 関連リポジトリ（SmTIAS-Capture・SmTIAS-Evaluation）はローカルに置かず，必要時に gh CLI 等で GitHub から直接参照する（CLAUDE.md「外部参照リポジトリ」参照）．

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

uv sync

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

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

4. 動作確認

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. ツール類の確認

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 を使う場合はこのセクションの手順を完了してから進むこと．

インストール手順

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

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 コマンドで永続化する：

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

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

別の方法として，環境変数 LLVM_DIR を LLVM のインストールルートに設定しておくと，自動探索が $LLVM_DIR\bin\LLVM-C.dll（Windows）/ $LLVM_DIR/lib/libLLVM-C.so（POSIX）を優先候補として試す（DRJIT_LIBLLVM_PATH を DLL のフルパスで指定する代わりに使える）．

動作確認

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

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

scalar_rgb variant や ad-hoc スクリプトで `LLVM API initialization failed` が出る

llvm_init.py の自動探索が働くのは sm-render 等の CLI が llvm_ variant を要求した場合のみ*．以下の 2 ケースでは自動探索が呼ばれず，LLVM がインストール済みでも drjit 自身の探索が「jitc_llvm_init(): LLVM API initialization failed」で失敗することがある（2026-08-17 の新規構築マシンで確認）:
- variant: scalar_rgb のシーンを sm-render で実行する場合（drjit は scalar でも LLVM を初期化しようとする）
- uv run python で mitsuba を直接 import する ad-hoc スクリプト
対処: コマンド実行前に $env:DRJIT_LIBLLVM_PATH = 'C:\Program Files\LLVM\bin\LLVM-C.dll' を明示設定する（または「DRJIT_LIBLLVM_PATH の設定」セクションの手順で User scope に永続化する）．
LLVM 22.1.8（winget 導入）で llvm_ad_rgb / scalar_rgb とも動作確認済み（明示設定時）．

`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 で実行が遅すぎる場合のオプション．導入は任意：

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

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