TUD LBM

A JAX-accelerated lattice Boltzmann method framework developed at Delft University of Technology. TUD-LBM supports single-phase, multiphase, wetting, hysteresis, and chemical-step simulations through a configuration-driven workflow.

Installation

TUD-LBM requires Python 3.11 or newer. We recommend uv for reproducible environments and dependency management.

git clone https://github.com/szkuds/tud_lbm.git
cd tud_lbm
uv sync
uv run tud-lbm --help

For development dependencies, use uv sync --extra dev.

Documentation

For full documentation, visit tud-lbm.readthedocs.io.

Quick Start

Python API

from src import SimulationConfig, build_setup, init_state, run

config = SimulationConfig(grid_shape=(64, 64), tau=0.8, nt=1_000)
setup = build_setup(config)
state = init_state(setup)
final_state, trajectory = run(setup, state)

SimulationConfig supplies a D2Q9 lattice, BGK collision, periodic boundaries, and rest-equilibrium initialisation by default. final_state is the state after the requested time steps; trajectory contains sampled in-memory states.

Run from a TOML configuration

tud-lbm run examples/config_simple.toml

Use --dry-run to inspect a configuration without running it, and --override to change values from the command line:

tud-lbm run examples/config_simple.toml --dry-run
tud-lbm run examples/config_simple.toml --override tau=0.8 --override nt=5_000

List the available physics, lattice, and analysis operators with:

tud-lbm run --list-simulation-operators
tud-lbm run --list-simulation-analysis

Interactive CLI

Omit the configuration path to enter interactive mode:

tud-lbm run

Parameter sweeps and post-processing

List-valued sweepable fields in a TOML configuration expand into a parameter sweep. Use --max-workers to control parallel execution and --compare to create cross-run comparison plots.

tud-lbm run examples/config_parallel.toml --max-workers 4 --compare

Saved runs can be plotted or animated, and a directory of runs can be analysed:

tud-lbm visualise /path/to/run-directory --no-prompt
tud-lbm animate /path/to/run-directory
tud-lbm compare /path/to/sweep-results --no-prompt

See the examples for single-phase, multiphase, parallel, and von Karman configurations.

Reporting bugs and vulnerabilities

• Bugs, questions, and feature requests — search the issue tracker first, then open a new issue. All issues and responses are publicly archived there.
• Security vulnerabilities — do not open a public issue. Follow the private reporting process in SECURITY.md; we acknowledge reports within 14 days.

Contributing

If you want to contribute to the development of tud_lbm, have a look at the contribution guidelines. Notable changes are recorded in the changelog.

Credits

This package was created with Copier and the NLeSC/python-template.