WSL2にAutodesk XLBをインストールし、exampleを実行する
AutodeskのXLBは、格子ボルツマン法（Lattice Boltzmann Method: LBM）による2次元・3次元流体計算をPythonから実行できるライブラリです。JAX、NVIDIA Warp、Neonの複数バックエンドを備え、CPUから単一GPU、複数GPUまで段階的に構成できます。
本稿では、Windows上のWSL2へXLBの開発版をインストールし、公式のlid_driven_cavity_2d.pyを小規模設定で実行して、PNG画像とVTKファイルが生成されるところまでを扱います。
最初はGPUを使わないJAX/CPU構成で導入を確認します。その後、NVIDIA GPUがある環境向けに、JAX/CUDAおよびWarpバックエンドへの切り替え方も説明します。
本稿の前提
本稿は2026年8月31日時点の次の構成を基準にしています。
- Windows 11またはWSL2対応のWindows 10
- WSL2
- Ubuntu 24.04 LTSを想定
- Python 3.11以上
- XLB
mainブランチのコミット9470e54a8d7ccd68d8e5563ca7a573040841ea8c - CPU確認ではJAXバックエンド
- GPU確認ではNVIDIA GPUと最新のWindows用NVIDIAドライバー
XLBのmainブランチは、本稿の基準コミットではパッケージバージョン0.3.2、Python要件>=3.11です。公開リリースとmainブランチの内容が一致しない時期もあるため、本稿ではリポジトリをcloneし、コードとexampleを同じコミットにそろえます。
Ubuntu 22.04など、Python 3.10が標準の環境では、そのままでは現在のXLBをインストールできません。Python 3.11以上を用意するか、Ubuntu 24.04以降を使ってください。
1. WSL2とUbuntuをインストールする
管理者権限のPowerShellを開き、WSLを更新します。
wsl --update
インストール可能なディストリビューション名を確認します。
wsl --list --online
一覧にUbuntu-24.04がある場合は、次のようにインストールします。
wsl --install -d Ubuntu-24.04
一覧にその名前がない場合は、表示されたUbuntuの名前を指定してください。インストール後、必要に応じてWindowsを再起動し、Ubuntuを起動してLinux側のユーザー名とパスワードを設定します。
WSL2になっていることをPowerShellで確認します。
wsl --list --verbose
表示例です。
NAME STATE VERSION
* Ubuntu-24.04 Running 2
VERSIONが1なら、ディストリビューション名を指定してWSL2へ変換します。
wsl --set-version Ubuntu-24.04 2
2. Ubuntu側の基本パッケージを用意する
ここからはUbuntuのターミナルで操作します。
sudo apt update
sudo apt upgrade -y
sudo apt install -y \
git \
build-essential \
python3 \
python3-pip \
python3-venv \
libgl1 \
libglib2.0-0t64
Pythonのバージョンを確認します。
python3 --version
Python 3.11以上であれば続行できます。
ソースはLinux側のファイルシステムへ置く
XLBのように多数のPythonファイルを読むプロジェクトは、/mnt/c/...ではなく、WSLのLinuxファイルシステム、たとえば~/srcへ置く方が扱いやすく、ファイルI/Oの面でも有利です。
mkdir -p ~/src
cd ~/src
Windowsのエクスプローラーから現在のLinuxディレクトリを開くときは、次を実行できます。
explorer.exe .
3. XLBをcloneしてバージョンを固定する
公式リポジトリをcloneします。
cd ~/src
git clone https://github.com/Autodesk/XLB.git
cd XLB
本稿と同じ内容で再現する場合は、コミットを固定します。
git checkout 9470e54a8d7ccd68d8e5563ca7a573040841ea8c
最新版を追従したい場合は、このgit checkoutを省略してmainブランチを使用します。ただし、exampleや依存関係が更新され、本稿の出力と異なる可能性があります。
現在位置とコミットを確認します。
pwd
git rev-parse --short HEAD
4. Python仮想環境を作成する
リポジトリ直下に仮想環境を作ります。
cd ~/src/XLB
python3 -m venv .venv
source .venv/bin/activate
プロンプトの先頭に(.venv)が付けば有効化されています。インストールツールを更新します。
python -m pip install --upgrade pip setuptools wheel
以降、別のターミナルを開いたときは次を再実行してください。
cd ~/src/XLB
source .venv/bin/activate
5. まずCPU構成でXLBをインストールする
リポジトリのコードをeditable installします。
cd ~/src/XLB
python -m pip install -e .
editable installにしておくと、cloneしたXLB本体と同じリビジョンのexampleを実行できます。
通常のJAX/CPUまたはWarp導入では、リポジトリ直下の
requirements.txtを直接インストールしません。このファイルにはCUDA向けJAXなども含まれており、公式READMEでは主にNeon導入手順の中で使われています。通常構成ではpip install -e .またはextrasを使う方が意図が明確です。
インストールを確認します。
python - <<'PY'
import jax
import xlb
print("XLB version :", xlb.__version__)
print("JAX version :", jax.__version__)
print("JAX devices :", jax.devices())
PY
CPU構成では、JAX devicesにCpuDeviceが表示されれば正常です。たとえば次のような形になります。
XLB version : 0.3.2
JAX version : 0.8.x
JAX devices : [CpuDevice(id=0)]
JAXの細かなバージョン番号は、インストール時点の依存関係解決によって変わります。
6. 公式exampleを短時間で試せるラッパーを作る
公式のexamples/cfd/lid_driven_cavity_2d.pyは、既定値が500×500格子、50,000ステップです。導入確認としては大きいため、公式クラスをそのまま再利用しつつ、格子数とステップ数だけコマンドラインから小さくできるラッパーを作ります。
リポジトリ直下で次のファイルを作成します。
cd ~/src/XLB
nano run_lid_cavity_quick.py
以下を貼り付けて保存します。
"""Small, configurable runner for XLB's lid-driven cavity example."""
from __future__ import annotations
import argparse
import xlb
from examples.cfd.lid_driven_cavity_2d import LidDrivenCavity2D
from xlb.compute_backend import ComputeBackend
from xlb.precision_policy import PrecisionPolicy
BACKENDS = {
"jax": ComputeBackend.JAX,
"warp": ComputeBackend.WARP,
}
def positive_int(value: str) -> int:
parsed = int(value)
if parsed <= 0:
raise argparse.ArgumentTypeError("0より大きい整数を指定してください")
return parsed
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="XLB lid-driven cavity exampleを小規模設定で実行します。"
)
parser.add_argument("--backend", choices=BACKENDS, default="jax")
parser.add_argument("--grid-size", type=positive_int, default=64)
parser.add_argument("--steps", type=positive_int, default=200)
parser.add_argument("--output-interval", type=positive_int, default=100)
return parser.parse_args()
def main() -> None:
args = parse_args()
backend = BACKENDS[args.backend]
precision = PrecisionPolicy.FP32FP32
grid_shape = (args.grid_size, args.grid_size)
velocity_set = xlb.velocity_set.D2Q9(
precision_policy=precision,
compute_backend=backend,
)
reynolds_number = 200.0
lid_velocity = 0.05
characteristic_length = grid_shape[0] - 1
viscosity = lid_velocity * characteristic_length / reynolds_number
omega = 1.0 / (3.0 * viscosity + 0.5)
print(
f"backend={args.backend}, grid={grid_shape}, "
f"steps={args.steps}, omega={omega:.6f}"
)
simulation = LidDrivenCavity2D(
omega=omega,
prescribed_vel=lid_velocity,
grid_shape=grid_shape,
velocity_set=velocity_set,
compute_backend=backend,
precision_policy=precision,
)
simulation.run(
num_steps=args.steps,
post_process_interval=args.output_interval,
)
if __name__ == "__main__":
main()
構文だけ先に確認します。
python -m py_compile run_lid_cavity_quick.py
何も表示されなければ構文エラーはありません。
7. JAX/CPUでexampleを実行する
出力ファイルを分けて管理するため、実行用ディレクトリを作ります。
cd ~/src/XLB
mkdir -p runs/jax-quick
cd runs/jax-quick
64×64格子、200ステップで実行します。
python ../../run_lid_cavity_quick.py \
--backend jax \
--grid-size 64 \
--steps 200 \
--output-interval 100
JAXは最初の計算時にコンパイルを行うため、初回ステップだけ間が空くことがあります。処理が進むと、VTK保存時に次のようなログが表示されます。
backend=jax, grid=(64, 64), steps=200, omega=...
Saved ./lid_driven_cavity_0000000.vtk in ... seconds.
Saved ./lid_driven_cavity_0000100.vtk in ... seconds.
Saved ./lid_driven_cavity_0000199.vtk in ... seconds.
生成物を確認します。
ls -lh
この設定では、おおむね次のファイルが生成されます。
lid_driven_cavity_0000.png
lid_driven_cavity_0100.png
lid_driven_cavity_0199.png
lid_driven_cavity_0000000.vtk
lid_driven_cavity_0000100.vtk
lid_driven_cavity_0000199.vtk
現在の出力ディレクトリをWindows側で開きます。
explorer.exe .
PNGを開いて速度場の画像が表示され、VTKファイルも作成されていれば、XLBのインストールからexample実行まで成功です。VTKはParaViewなどで読み込めます。
さらに軽く試す
CPUが遅い場合は、32×32格子、50ステップまで減らせます。
python ../../run_lid_cavity_quick.py \
--backend jax \
--grid-size 32 \
--steps 50 \
--output-interval 25
8. 公式exampleを既定設定のまま実行する
軽量版が動いた後で、公式スクリプトをそのまま実行できます。
cd ~/src/XLB
python examples/cfd/lid_driven_cavity_2d.py
ただし、既定設定は500×500格子・50,000ステップなので、CPUでは長時間かかり得ます。まず軽量ラッパーで環境が正しいことを確認してから実行するのが安全です。
NVIDIA GPUを使う場合
ここからは任意です。Windows PCに対応するNVIDIA GPUがある場合、WSL2からJAX/CUDAまたはWarpを利用できます。
9. Windows側のNVIDIAドライバーを確認する
NVIDIAのWSL対応では、Windows側へ最新のNVIDIAドライバーをインストールします。WSL内へLinux用のNVIDIAディスプレイドライバーを別途インストールしてはいけません。Windows側のドライバーが、WSLへCUDAドライバー機能を公開します。
WSLのUbuntuで確認します。
nvidia-smi
コマンドがPATHにない場合は次も試せます。
/usr/lib/wsl/lib/nvidia-smi
GPU名とDriver Versionが表示されれば、WSLからGPUが認識されています。
認識されない場合は、PowerShellでWSLを更新して再起動します。
wsl --update
wsl --shutdown
その後、Ubuntuを起動し直してください。
本稿のJAX導入はCUDAランタイムを含むpip wheelを使います。XLBやJAXそのものをソースからCUDAビルドしない限り、WSL内へフルCUDA Toolkitを先に入れる必要はありません。
10-A. JAXバックエンドをCUDA 13対応にする
XLBの現在のcuda extraはjax[cuda13]を指定しています。
cd ~/src/XLB
source .venv/bin/activate
python -m pip install -e ".[cuda]"
JAXからGPUが見えることを確認します。
python - <<'PY'
import jax
print(jax.devices())
PY
次のようにCudaDeviceまたはGPUデバイスが表示されれば成功です。
[CudaDevice(id=0)]
CUDA 13用JAX wheelは、対応するGPU世代と十分に新しいドライバーを必要とします。JAX公式ドキュメントの現行要件では、CUDA 13はSM 7.5以上、Linuxドライバー580以上が基準です。
追記：CUDAエラーが発生した場合は、JAXはバージョン0.10.1、WARPはバージョン1.14.0にダウングレード推奨
CUDA 12 wheelへ切り替える場合
GPUが古い、またはドライバーがCUDA 13要件を満たさない場合は、XLB本体を通常インストールしたうえでJAXのCUDA 12 wheelへ切り替えます。
cd ~/src/XLB
source .venv/bin/activate
python -m pip install -e .
python -m pip install --upgrade "jax[cuda12]"
JAX公式の現行要件では、CUDA 12 wheelのLinuxドライバーは525以上が基準です。GPUとドライバーの組み合わせに合うwheelを選んでください。
GPU版JAXで軽量exampleを実行します。
cd ~/src/XLB
mkdir -p runs/jax-gpu-quick
cd runs/jax-gpu-quick
python ../../run_lid_cavity_quick.py \
--backend jax \
--grid-size 128 \
--steps 500 \
--output-interval 250
--backend jaxのままでも、jax.devices()にGPUが出ていればGPUで計算されます。
10-B. Warpバックエンドを使う
XLBのWarpバックエンドは単一GPU向けです。仮想環境を有効化し、Warp extraを指定してインストールします。
cd ~/src/XLB
source .venv/bin/activate
python -m pip install -e ".[warp]"
Warpが使うデバイスを確認します。
python - <<'PY'
import warp as wp
wp.init()
print("Warp default device:", wp.get_device())
PY
CUDAが利用できる環境では通常cuda:0、利用できなければcpuが既定デバイスになります。
Warpバックエンドでexampleを実行します。
cd ~/src/XLB
mkdir -p runs/warp-quick
cd runs/warp-quick
python ../../run_lid_cavity_quick.py \
--backend warp \
--grid-size 128 \
--steps 500 \
--output-interval 250
Warpで計算した配列も、公式exampleの後処理でJAX配列へ変換され、PNGとVTKが保存されます。
Neonバックエンドは複数GPU・マルチレゾリューション向けで、独自のWarp forkを使います。公式READMEは
warpとneonを同じ仮想環境へ入れないよう案内しています。Neonを試す場合は別の.venvを作ってください。
トラブルシューティング
error: externally-managed-environmentが出る
仮想環境が有効になっていない可能性があります。
cd ~/src/XLB
source .venv/bin/activate
python -m pip --version
pipのパスに~/src/XLB/.venv/が含まれていることを確認します。
Package 'xlb' requires a different Pythonと表示される
Pythonが3.11未満です。
python --version
Python 3.11以上の環境を使ってください。Ubuntu 24.04の新規WSL環境を使うのが簡単です。
nvidia-smi: command not foundになる
まず次を試します。
/usr/lib/wsl/lib/nvidia-smi
それでも動かない場合は、Windows側のNVIDIAドライバーとWSL更新を確認します。WSL内へLinux用NVIDIAディスプレイドライバーを入れて解決しようとしないでください。
jax.devices()がCPUしか返さない
順に確認します。
nvidia-smi
python -m pip show jax jaxlib
python -c "import jax; print(jax.devices())"
そのうえで、GPUとドライバーに合う方を再インストールします。
python -m pip install --upgrade "jax[cuda13]"
または、
python -m pip install --upgrade "jax[cuda12]"
ローカルに別のCUDAをインストール済みでライブラリ競合が疑われる場合は、現在の設定を確認します。
echo "$LD_LIBRARY_PATH"
pip同梱のCUDAライブラリを使う構成では、古いCUDAパスがLD_LIBRARY_PATHに入っていると競合することがあります。必要に応じて、そのシェルだけ一時的に解除して再確認します。
unset LD_LIBRARY_PATH
python -c "import jax; print(jax.devices())"
Warpの既定デバイスがcpuになる
まずWSL側でGPUを確認します。
nvidia-smi
次にWarpの初期化情報を確認します。
python - <<'PY'
import warp as wp
wp.init()
print(wp.get_device())
PY
Warpの現行PyPIビルドが要求するドライバー要件と、Windows側ドライバーが合っているか確認してください。
libGL.so.1などの共有ライブラリエラーが出る
可視化・VTK周辺の共有ライブラリを入れ直します。
sudo apt update
sudo apt install -y libgl1 libglib2.0-0t64
メモリ不足または処理が重い
格子とステップを小さくします。
python ../../run_lid_cavity_quick.py \
--backend jax \
--grid-size 32 \
--steps 50 \
--output-interval 25
2次元でも格子数と分布関数の配列が増えると、使用メモリと計算量が大きくなります。まず小さい設定で成功させてから段階的に増やしてください。
出力ファイルが見つからない
公式exampleは、基本的に実行時のカレントディレクトリへPNGとVTKを書き出します。
pwd
find . -maxdepth 1 -type f \( -name '*.png' -o -name '*.vtk' \) -print
本稿のようにruns/...へ移動してから実行すると、出力場所を分離できます。
更新とアンインストール
XLBを最新版へ更新する
コミット固定を解除し、mainへ戻して更新します。
cd ~/src/XLB
source .venv/bin/activate
git switch main
git pull --ff-only
python -m pip install -e .
更新後は、exampleの引数や依存関係が変わっていないかREADMEと差分を確認してください。
仮想環境を削除する
XLB専用環境が不要になった場合は、仮想環境だけ削除できます。
cd ~/src/XLB
deactivate 2>/dev/null || true
rm -rf .venv
cloneしたソースも不要なら、~/src/XLB全体を削除します。
まとめ
WSL2上でXLBを導入するときの要点は次の通りです。
- Python 3.11以上のWSL2環境を用意する。
- ソースは
/mnt/cではなく~/srcなどLinux側へ置く。 -
venvを作り、cloneしたXLBをpip install -e .で入れる。 - 最初はJAX/CPUと64×64・200ステップ程度の軽量設定で確認する。
- PNGとVTKが生成されたら、JAX/CUDAまたはWarpへ切り替える。
- WSLのGPUドライバーはWindows側で管理し、WSL内へLinuxディスプレイドライバーを入れない。
まず小さい格子で一連の処理を通し、その後に格子数・ステップ数・GPUバックエンドを段階的に増やすと、問題の切り分けが容易になります。