JAX-LaB Documentation

JAX-LaB provides differentiable lattice Boltzmann solvers for single-phase, multiphase, multicomponent, and thermal simulations on JAX-supported hardware.

Run a first simulation

Install the package from a source checkout, including optional visualization dependencies:

1

pip install -e ".[io]"

Run the two-dimensional lid-driven cavity example:

1

python examples/isothermal/singlephase/cavity2d.py

The example defines the lattice, solver, initial fields, boundary conditions, and output callback in one file. Use it as a compact template for a new single-phase simulation.

Choose an example

• Start with examples/isothermal/singlephase/ for single-phase flows.
• Use examples/isothermal/multiphase/shanchen/ for Shan-Chen (pseudopotential) multiphase and multicomponent flows.
• Use examples/isothermal/multiphase/vof/ for volume-of-fluid two-phase flows with sharp interfaces, large density and viscosity contrasts, and evaporation.
• Use examples/thermal/ for coupled fluid-temperature simulations.
• Use examples/isothermal/differentiable/ for inverse and differentiable workflows.
• Use examples/rendering/ for simulations with JAX-native in-situ rendering.

Package layout

The simulation code is organized under jax_lab.core. Import lattices, collision models, boundary conditions, equations of state, thermal solvers, and utilities from their corresponding core modules:

1
2
3

from jax_lab.core.boundary_conditions import BounceBack
from jax_lab.core.lattice import LatticeD2Q9
from jax_lab.core.models import BGKSim

Rendering is an independent package under jax_lab.render:

1

from jax_lab.render import Scene, SurfaceRendering

The most commonly used solver classes remain available directly from jax_lab for concise application code. The API reference uses the explicit module paths so that each class’s implementation location is clear.

Validate a source checkout

Install the development and documentation dependencies, then run the tests and build the Zensical site:

1
2
3

pip install -e ".[dev,docs,io]"
pytest
zensical build --clean

Project overview

JAX-LaB

A Python-based, differentiable, massively parallel lattice Boltzmann library for modeling multiphase and multiphysics flows & physics-based machine learning.

Key Features

• JAX Ecosystem Integration: Works with machine learning libraries such as Equinox, Flax, Haiku, and Optax.
• Differentiable LBM: Provides differentiable kernels for physics and deep learning applications.
• Scalable and Portable: Runs on multi-core CPUs, GPUs, and TPUs, with distributed support for simulations spanning hundreds of GPUs and billions of cells.
• Broad LBM Support: Includes several boundary conditions and collision kernels, along with Shan-Chen and volume-of-fluid (VoF) multiphase, multiphysics, and multicomponent flow modeling.
• User-Friendly Python Interface: Written entirely in Python, simplifying simulation setup and making library easy to extend.
• JAX Array and Shardmap: Offers a NumPy-like interface while leaving performance optimization to the compiler.
• GPU-Optimized: Per-shard boundary indices, scalar wetting/force stencils, and a fused symbolic MRT collision path reduce memory traffic and compiled kernel size.
• Visualization: Supports multiple output options, including JAX-native ray tracer for in situ surface, volume, and vector-field rendering of GPU/TPU arrays.

Capabilities

Multiphase Flow Modeling

1. Shan-Chen

• Support for high density ratio flows (tested for density ratios > 10¹⁰) using 4th-order isotropic explicit finite difference (EFM) method for gradient computation.
• Incorporates Equation of State (EOS) to model multiphase flows. Currently implemented EOS include Carnahan-Starling, Peng-Robinson, Redlich-Kwong, Redlich-Kwong-Soave and VanderWaals.
• Density ratio independent surface tension control by directly modifying pressure tensor (MRT model).

Multicomponent Flow Support

Computations use pytrees to model any number of components, each with its own equation of state, initial condition, and boundary conditions, without requiring library modifications.

Wetting model

• Geometric wetting scheme
• Improved virtual density scheme

2. Thermal Flow

• Hybrid thermal LBM solver for two- and three-dimensional single-phase, multiphase, and multicomponent flows.
• Thermal equation is solved using lattice-based finite-difference stencils and fourth-order Runge-Kutta time integration.

3. Volume of Fluid (VoF)

• Two-lattice free-surface LBM (Mohammadrezaei et al., 2026): liquid and gas each evolve on their own lattice and are coupled only at interface cells, enabling physical density ratios (e.g., air-water 1:1000) with a sharp interface.
• Surface tension from the interface curvature, contact angles at walls, and an optional viscous normal-stress jump.
• BGK and MRT collision on D2Q9 and D3Q19; interface work runs only on a compacted band of interface cells, so its cost scales with interface size.

Collision Models

• BGK
• Multi-Relaxation Time (MRT)
• Cascaded (Central Moment)
• KBC

Lattice

• D2Q9
• D3Q19
• D3Q27

Machine Learning

• Easy integration with JAX’s ecosystem of machine learning libraries
• Differentiable LBM kernels both for single and multiphase flows
• Differentiable boundary conditions

Compute Capabilities

• Distributed Multi-GPU support
• Mixed-Precision support (store vs compute)
• Local, per-shard boundary condition indices instead of global lists replicated on every device
• Scalar neighbor stencils for wetting and Shan-Chen force, avoiding per-direction streamed arrays
• Fused, symbolic MRT collision matrix

Output

• Binary and ASCII VTK output using PyVista
• HDF5/XDMF output using h5py
• JAX-native in-situ surface, refractive volume, and vector-field rendering and image output
• Distributed asynchronous checkpointing using orbax
• 3D mesh voxelizer using trimesh

Boundary Conditions

• Equilibrium: Sets prescribed velocity or pressure using equilibrium populations.
• Full-Way Bounceback: Reflects populations to impose a stationary, no-slip wall.
• Half-Way Bounceback: Imposes a no-slip wall halfway between fluid and solid nodes.
• Do Nothing: Allows populations to pass through unmodified.
• Zou-He: Imposes a prescribed velocity or pressure profile.
• Regularized: Provides a more stable, but more expensive, alternative to Zou-He.
• Extrapolation Outflow: Reduces wave reflections using extrapolation.
• Non-Equilibrium Extrapolation: Open boundary condition with prescribed density.
• Exact Non-Equilibrium Extrapolation: Mass-corrected open boundary condition with prescribed density.
• Interpolated Bounceback: Applies the Bouzidi scheme to curved or off-lattice walls.
• Convective Outflow: Supports outflow in applications such as porous media flow.
• Dirichlet: Prescribes temperature at the boundary.
• Neumann: Prescribes the normal temperature gradient.

Documentation

Complete API documentation is available here, or you can build and preview it locally:

1
2

pip install -e ".[docs]"
zensical serve

Installation Guide

JAX-LaB is distributed as the jax-lab package (import name jax_lab). The default install targets CPU:

1

pip install jax-lab

Accelerator support

Hardware acceleration is selected through dependency extras, which delegate the compiled backend packages to JAX’s own extras:

1
2
3
4

pip install "jax-lab[cuda13]"   # NVIDIA GPU (CUDA 13, bundled)
pip install "jax-lab[cuda12]"   # NVIDIA GPU (CUDA 12, bundled)
pip install "jax-lab[tpu]"      # Google TPU
pip install "jax-lab[rocm]"     # AMD GPU (ROCm, local toolkit)

Optional I/O and visualization dependencies

The I/O and visualization utilities load their dependencies lazily (at call time, not at import time), so the core solver runs without them. The following packages are only needed if you call the corresponding functions:

Calling one of these functions without its dependency installed raises an ImportError naming the missing package. The io extra installs all of them at once (recommended for running the examples, most of which write VTK or image output):

1

pip install "jax-lab[io]"

Development install

To work on JAX-LaB itself or run the bundled examples, install from source in editable mode:

1
2
3

git clone https://github.com/piyush-ppradhan/JAX-LaB
cd JAX-LaB
pip install -e ".[dev,io]"

[!NOTE] On macOS, please use the standard CPU installation, as JAX does not support GPU acceleration on this platform.

Run an example:

1

python3 examples/isothermal/singlephase/cavity2d.py

Citation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

@article{pradhan_jax-lab_2026,
    title = {{JAX}-{LaB}: {A} {High}-{Performance}, {Differentiable} {Lattice} {Boltzmann} {Library} for {Modeling} {Multiphase} {Fluid} {Dynamics} in {Geosciences} and {Engineering}},
    volume = {18},
    copyright = {© 2026 The Author(s). Journal of Advances in Modeling Earth Systems published by Wiley Periodicals LLC on behalf of American Geophysical Union.},
    issn = {1942-2466},
    shorttitle = {{JAX}-{LaB}},
    url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2025MS005313},
    doi = {10.1029/2025MS005313},
    language = {en},
    number = {2},
    urldate = {2026-02-20},
    journal = {Journal of Advances in Modeling Earth Systems},
    author = {Pradhan, Piyush and Gentine, Pierre and Kelly, Shaina},
    year = {2026},
    keywords = {GPU, JAX, Lattice Boltzmann method, Python, Shan-Chen method, multiphase flow},
    pages = {e2025MS005313},
}