crawLBM

A bare-bones 2D Lattice Boltzmann Method (LBM) fluid solver written in Python. The logic is simply: crawl before walking or running.

Features

• BGK (single-relaxation-time) collision operator
• D2Q9 lattice structure
• Periodic and halfway bounce-back boundary conditions (including moving walls)
• Taylor-Green Vortex and Couette Flow test problems
• Physical unit conversion (SI inputs → lattice units)

Installation

From PyPI

pip install crawLBM

From source

git clone https://github.com/biboyd/crawLBM.git
cd crawLBM
pip install .

For development (editable install):

pip install -e .

Usage

After installation, run the solver from the command line:

# Taylor-Green Vortex (default)
crawlbm --init TG-vortex --domain_resolution 64 --max_step 1000 --plot_dir ./output

# Couette Flow
crawlbm --init Couette --domain_resolution 32 --tau 0.8 --max_step 2000 --plot_dir ./output

Key options

Python API

from crawlbm import Grid, advance_sim
from crawlbm._cli import init_TG_vortex

grid = Grid(nx=64, ny=64)
init_TG_vortex(grid, Lx=1.0, Ly=1.0, U_0=0.01)
advance_sim(grid, tau=0.8, max_step=500, plot_int=100, plot_dir='./output')

Running tests

pip install pytest
pytest unit_tests/ -v

Dependencies

• Python >= 3.8
• NumPy

Matplotlib is an optional dependency used by the plotting scripts in plotfiles/ and test_problems/. Install it with:

pip install crawlbm[plot]

LLM Acknowledgement

Core functions and functionality were written by Brendan Boyd. Unit tests, convergence tests, and cleaning up the codebase to work as a python package was implemented via Claude Code.

Additionally, some bug fixes were found via Claude Code.