Fork: 0
hasegawa / SmTIAS-LightSim
Transfer to URL with SHA Find file
Newer
Older
SmTIAS-LightSim / docs / 02_ENV / ENV_02_環境構築手順.md
@rintoHasegawa rintoHasegawa on 28 May 5 KB [add] Speed-1 LLVM JIT 自動検出と診断ログ強化 — runtime/llvm_init.py を新規実装．ensure_drjit_libllvm_path() で DRJIT_LIBLLVM_PATH 未設定時に Windows 標準 4 候補 (C:\Program Files\LLVM 等) + POSIX glob + LLVM_DIR + extra_candidates を順次探索して os.environ 設定（既設定なら上書きしない）．log_variant_status() で llvm_/cuda_/scalar_ 経路を INFO 明示，要求 llvm_* で実 scalar_* なら WARNING 追加．render/runner.py で variant=llvm_* 時に自動検出を呼び ImportError 時は原因明示ログ→ re-raise，mitsuba を関数内遅延 import 化．visualize/baker.py の _set_variant_once に LLVM 自動探索分岐を追加し direct/path 両方で log_variant_status を呼ぶ．cli/render.py で import 順を制御し sensors.py/lights.py のモジュールレベル mitsuba import 前に検出を確実に通す．docs/02_ENV/ENV_02 に LLVM インストール手順・DRJIT_LIBLLVM_PATH 説明・動作確認コマンドを追記．新規テスト 51 件 (runtime/test_llvm_init.py 25, render/test_runner_jit_init.py 14, visualize/test_baker_jit_init.py 8, cli/test_render_jit_init.py 4) で仕様 A1-E1 完全カバー，DRJIT_LIBLLVM_PATH 設定下で 606 件全通過．速度は不変（目的は再発防止＋診断容易化）．数値同等性は MC 内部シードで SHA256 異なるが平均相対誤差 7.23e-05 で統計同等性パス．これで環境変数消失によるサイレントクラッシュが再発しない土台が整備された．TEST_04 Speed-1 セクションを実施結果で更新．CLAUDE.md 開発進捗に Speed-1 完了追記＋実装済みモジュール一覧に runtime/llvm_init.py 追加
Raw Blame History

環境構築手順 (Environment Setup)

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

前提条件 (Prerequisites)

ツール用途入手元
Gitリポジトリ操作https://git-scm.com/download/win
GitHub CLI（gh）PR 作成・マージhttps://cli.github.com/
LLVMMitsuba 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

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 / Formatuv run ruff check . / uv run ruff format .

LLVM のインストール（Windows）

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

インストール手順

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

動作確認

インストール後，以下のコマンドで 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 を尊重する

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