環境構築手順 (Environment Setup)

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

前提条件 (Prerequisites)

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)

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 を開いた時点から有効化．

別の方法として，環境変数 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 で実行が遅すぎる場合のオプション．導入は 任意：

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

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

研究室サーバ編 (Lab Server Setup)

研究室の GPU サーバでレンダを回すための初回セットアップ．編集は手元（Windows）で行い，sm-remote でコードを送ってサーバの tmux 上で実行し，結果を持ち帰る（日常の操作は ENV_04 開発コマンド の「研究室サーバでの実行」）． GitHub の認証情報はサーバに置かない（計算して結果を受け取るだけなので，サーバでは git を使わず常に手元から送る）．

SSH 接続設定 (SSH Config)

ssh は Windows 11 標準の OpenSSH（C:\Windows\System32\OpenSSH\ssh.exe）を使う．PowerShell からも Git Bash からも使える．Windows には rsync が無いため，転送は sm-remote（tar over ssh）で行う．

C:\Users\<ユーザー名>\.ssh\config に Host を登録する（例）:

Host Newton
    HostName Newton.local
    User hasegawa
    IdentityFile ~/.ssh/id_ed25519

Host Einstein
    HostName 192.168.23.13
    User hasegawa
    IdentityFile ~/.ssh/id_ed25519

Host Archimedes
    HostName 192.168.23.15
    User hasegawa
    IdentityFile ~/.ssh/id_ed25519

鍵の生成と登録 (SSH Key)

鍵が無ければ生成する（Git Bash．パスフレーズなし）:

ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519

Windows には ssh-copy-id が無いので，PowerShell から公開鍵を流し込んで登録する（パスワードを 1 回聞かれる．重複登録はしない）:

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | ssh Newton 'k=$(cat); mkdir -p ~/.ssh && chmod 700 ~/.ssh && touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys && (grep -qxF "$k" ~/.ssh/authorized_keys || echo "$k" >> ~/.ssh/authorized_keys)'

ssh Newton hostname がパスワード無しで通れば OK．

uv と Python 3.12 の導入 (uv & Python)

サーバにログインして実行する:

curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH=1 sh
~/.local/bin/uv python install 3.12

• UV_NO_MODIFY_PATH=1 はシェルの設定ファイルを書き換えないため．Ubuntu の ~/.profile は ~/.local/bin があればログイン時に PATH へ足すので，対話ログインでは uv で呼べる
• ただし ssh Newton 'コマンド' の非ログイン実行では ~/.profile が読まれず uv が PATH に入らない．sm-remote は ~/.local/bin/uv を絶対パスで呼ぶ（--uv / 環境変数 SM_REMOTE_UV で変更可）．ジョブ内では uv のディレクトリを PATH に足すので，スクリプトが呼ぶ uv run sm-render も動く
• tmux は /usr/bin/tmux に入っている（sm-remote run が使う）

コードの転送 (Code Transfer)

手元のリポジトリで実行する:

uv run sm-remote push

• 送り先: Newton:~/lab/SmTIAS-LightSim（--host / --remote-dir，または環境変数 SM_REMOTE_HOST / SM_REMOTE_DIR で変更可）
• 送らないもの: .venv/（Windows 用）・output/・.git/・__pycache__/・.pytest_cache/・.ruff_cache/・configs/_tmp_*（スイープ生成物．約 450 MB．必要なら --include / --only で個別に送る）
• gitignore 対象でも送るもの: lightsim/・reference_measurement/・REFERENCE/（実測参照データ．サーバでの評価に使う）
• 全体で約 160 MB．初回（2026-09-13，tar + ssh の手動転送）は LAN で 39 秒，以後の sm-remote push は 10 秒前後だった．日本語ファイル名（configs/meshes/*.stl）もそのまま展開される

依存の同期 (uv sync)

ssh Newton 'cd ~/lab/SmTIAS-LightSim && ~/.local/bin/uv sync'

以後の uv run は実行のたびに uv.lock との差分を自動で同期するので，pyproject.toml / uv.lock を変えて push した後も明示の uv sync は通常不要．

動作確認 (Verification)

サーバにログインして実行する:

cd ~/lab/SmTIAS-LightSim
uv run python -c "import mitsuba as mi; mi.set_variant('cuda_ad_rgb'); print(mi.__version__, mi.variant())"
uv run python -c "import mitsuba as mi; mi.set_variant('llvm_ad_rgb'); print(mi.__version__, mi.variant())"

3.7.1 cuda_ad_rgb / 3.7.1 llvm_ad_rgb と表示されれば OK．全テストは手元から次のように回せる（2026-09-13 に全テスト通過を確認済み）:

uv run sm-remote run --name pytest-all --yaml-variant -- python -m pytest -m ""
uv run sm-remote logs pytest-all -f

PowerShell で -m '""' と書くと "" の 2 文字がそのまま渡り，pytest が「Wrong expression passed to '-m'」で止まる．空文字は -m "" と書く．

VS Code から接続する（任意）(VS Code Remote)

サーバのファイルを見たり，ログを追ったりするだけなら VS Code の Remote - SSH 拡張でも接続できる．

1. 拡張 ms-vscode-remote.remote-ssh を入れる（code --install-extension ms-vscode-remote.remote-ssh）
2. F1 →「Remote-SSH: Connect to Host...」→ Newton を選ぶ（~/.ssh/config の Host 名がそのまま出る）
3. フォルダ ~/lab/SmTIAS-LightSim を開く

• サーバ上では編集しない．sm-remote push は手元の作業ツリーで上書き展開するので，サーバで直接直した内容は次の push で消える．編集は常に手元で行う
• サーバの端末で sm-remote を実行すると，自分自身へ ssh しようとするので止まって案内が出る．サーバ上で直接回すときは tmux new -s <名前> の中で uv run ... を実行する

学外から接続する（研究室 PC 経由）(Off-campus Access)

Newton は研究室 LAN 内のアドレスなので，学外からは直接つながらない．研究室の自分の PC（DESKTOP-1QLOO91．サーバとは別）が Tailscale に登録されているので，これを SSH の踏み台（ProxyJump）にする．Newton 側の設定は不要（手元の鍵がそのまま Newton まで届く）．

手元の PC ──Tailscale──▶ 研究室 PC（100.89.10.108）──研究室 LAN──▶ Newton

研究室 PC（リモートデスクトップで操作．実行前に hostname で DESKTOP-1QLOO91 と出ることを確かめる）の管理者 PowerShell で，OpenSSH Server を入れて Tailscale からの接続だけを受け付ける:

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
Set-NetFirewallRule -Name OpenSSH-Server-In-TCP -RemoteAddress 100.64.0.0/10

手元の公開鍵（~/.ssh/id_ed25519.pub の中身）を研究室 PC に登録する．研究室 PC のアカウント（papin）は管理者なので，Windows の OpenSSH の規則により鍵はユーザーの .ssh ではなく C:\ProgramData\ssh\administrators_authorized_keys に置き，権限を Administrators と SYSTEM だけに絞る（絞らないと sshd がファイルを無視する）:

$key = '<手元の id_ed25519.pub の中身>'
Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys -Value $key
icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"

手元の ~/.ssh/config に追記する:

Host labpc
    HostName 100.89.10.108
    User papin

Host Newton-via-lab
    HostName Newton.local
    User hasegawa
    ProxyJump labpc

ssh labpc hostname と ssh Newton-via-lab hostname がパスワード無しで通れば OK（2026-09-13 に確認．Newton まで 2 秒）．sm-remote は接続先を変えるだけで同じように使える:

$env:SM_REMOTE_HOST = "Newton-via-lab"   # この PowerShell の間だけ有効．毎回 --host Newton-via-lab を付けてもよい
uv run sm-remote status

• 研究室にいるときは従来どおり Newton を使う（踏み台を経由しない分速い）
• 手で ssh Newton-via-lab 'cat ...' > ファイル のように出力を受け取るとき，応答が返らず止まることがあった（hostname のような短いコマンドは通る．原因は未確認）．ssh -n（標準入力を閉じる）を付けると通った．sm-remote は標準入力を閉じて ssh を呼ぶので影響しない
• Tailscale が直接つながらず中継サーバ（DERP）経由になっていると転送が遅い（tailscale ping desktop-1qloo91 で via DERP と出る）．学外からの push は --only src のように変えた部分だけにする
• 失敗パターン: 研究室 PC と手元 PC の管理者 PowerShell はプロンプトが同じ（PS C:\Windows\system32>）ため，鍵の登録を手元 PC で実行してしまい，研究室 PC で Permission denied (publickey,...) になった．sshd のログ（Get-WinEvent -LogName OpenSSH/Operational）には理由が出ず Connection reset ... [preauth] だけだった
• 研究室 PC で SSH サーバを動かしてよいかは研究室のルールに照らして確認する（上の設定で受け付けるのは Tailscale の中＝自分のアカウントの機器からだけ）

既知事項 (Known Issues)

• Einstein はホームディレクトリ /home/hasegawa が無い．ログイン時に「Could not chdir to home directory」「mkdir: cannot create directory '/home/hasegawa': Permission denied」が出て，鍵登録・VS Code Remote ができない．管理者によるホーム作成待ち（Newton では sudo グループだが，Einstein の権限は未確認）
• Archimedes は鍵が未登録．使う場合は「鍵の生成と登録」の手順で登録する
• GPU は他ユーザーが 1・2 番を使っていることがある（研究室の利用ルールは特に無い）．sm-remote status で空きを見てから --gpu で指定する
• LLVM: Ubuntu では /usr/lib/x86_64-linux-gnu/libLLVM-15.so（libLLVM-<版>.so 形式）で提供され，libLLVM-C.so は無い．runtime/llvm_init.py はこの形式と /usr/lib/llvm-*/lib/ も探索する（以前は見つけられず「libLLVM-C.so が見つかりません」と誤警告していた．Dr.Jit 自身は見つけるので llvm_ad_rgb は元から動いていた）
• 共用サーバの CPU: llvm_ad_rgb は既定で全 64 スレッドを使う（loadavg が 33 から 87 に上がるのを実測）．CPU で回すときは sm-remote run --threads N（環境変数 SM_DRJIT_THREADS）で上限を付ける（--threads 16 で CPU 使用率 1698% を実測）
• サーバの uv run は毎回 build_system.requires = ["uv-build>=0.11.7,<0.12.0"] does not contain the current uv version 0.12.13 という警告を出す．ビルドバックエンド（uv_build）の版とサーバの uv 本体の版の食い違いを知らせるだけで，動作には影響しない