A GPU fluid simulator, explained

How a laptop graphics card simulates flowing fluid at the speed limit of its own memory
Abstract

This project is a lattice Boltzmann fluid solver for 2D and 3D flow, written in Python and CUDA C++. On a laptop RTX 3050 it performs about 2,130 million lattice updates per second, roughly 98.5 % of what the card's memory can deliver. Its results are checked against exact solutions and published benchmarks. This page explains the physics, the GPU engineering, the evidence and the limits, and it says plainly who did what.

Output from this solver: a Schäfer–Turek benchmark cylinder at Reynolds number 100. Red and blue show fluid spinning in opposite directions.

The project at a glance

ResultValueCompared with
2D speedabout 2,130 million updates/sabout 2,170 million/s, the memory limit
3D speedabout 1,000 million updates/sabout 1,030 million/s, the memory limit
Speedup from a fused kernel37×the same algorithm as ordinary GPU array code
Cylinder shedding frequencySt = 0.302published interval 0.295–0.305
Accuracy as the grid gets finererror falls by 4× per doublingsecond order, as theory predicts
GPU vs CPU referenceagree to about 1e-17 in float64independent NumPy implementation

Who did what

How this project was built

The project was built with Claude Code, Anthropic's AI coding tool, mostly between October 21 and 27, 2026.

Shaurya Attreya set the goal of a validated GPU solver, chose Python and CuPy's RawKernel route for the GPU, set the scope of each stage, chose to restructure the engine before going further, pushed the work toward arbitrary shapes and 3D, and approved each stage.

Claude wrote the physics code, the CUDA kernels and the tests. It also ran the validation and benchmarks, produced the figures, and wrote this page.

The evidence below does not rest on anyone's word. Each result is compared with an exact solution or a published benchmark, and the code is public.

Why simulate fluid this way?

Air and water are described by the Navier–Stokes equations. Most classic solvers treat water or slow air as incompressible, so a push anywhere is felt everywhere at once. Each time step then needs a pressure equation solved across the whole domain, and every part of the grid has to communicate with every other part. Graphics cards are poor at that kind of global work.

The lattice Boltzmann method (LBM) takes a different route. Rather than tracking velocity and pressure directly, it tracks groups of fictional particles moving on a grid. Each grid point only needs data from its immediate neighbours, so thousands of GPU threads can update the grid independently.

The trade-off is that LBM is slightly compressible. Its pressure comes directly from density, which removes the global solve, but this adds an error that grows with the square of the Mach number. That error turns up later on this page.

The physics in four ideas

1. Fluid as populations on a lattice

Each grid point stores a set of numbers $f_i$, called populations. Each one is the amount of fluid moving in one allowed direction $\mathbf{c}_i$. In 2D the solver uses D2Q9, meaning two dimensions and nine directions: one at rest, four along the axes and four diagonal. In 3D it uses D3Q19, with nineteen directions.

c₁c₂c₃c₄c₅c₆c₇c₈ c₀
D2Q9: rest (weight 4/9), axis directions in blue (1/9 each), diagonals in orange (1/36 each).

The ordinary fluid properties are just sums over these populations:

$$\rho = \sum_i f_i, \qquad \rho\,\mathbf{u} = \sum_i \mathbf{c}_i f_i$$

2. Streaming: particles move

In each time step, every population moves one grid point along its direction.

$$f_i(\mathbf{x} + \mathbf{c}_i,\ t + 1) = f_i^{*}(\mathbf{x},\ t)$$

3. Collision: particles relax

At each point, populations then collide and move toward a local equilibrium that has the same density and momentum:

$$f_i^{\mathrm{eq}} = w_i\,\rho\left[1 + 3\,\mathbf{c}_i\!\cdot\!\mathbf{u} + \tfrac{9}{2}(\mathbf{c}_i\!\cdot\!\mathbf{u})^2 - \tfrac{3}{2}|\mathbf{u}|^2\right]$$

$$f_i^{*} = f_i - \frac{1}{\tau}\left(f_i - f_i^{\mathrm{eq}}\right)$$

The relaxation time $\tau$ sets how quickly this happens. Collision conserves mass and momentum, which is why it produces real fluid behaviour.

4. From particles back to fluid

A mathematical expansion, the Chapman–Enskog analysis, shows that at low speed these two simple steps reproduce the Navier–Stokes equations. It also ties the relaxation time to viscosity:

$$\nu = \tfrac{1}{3}\left(\tau - \tfrac{1}{2}\right)$$

The formula also marks a stability limit. As $\tau$ approaches $\tfrac12$, viscosity approaches zero and the simple scheme becomes unstable. Fast, thin-boundary-layer flows need exactly that regime, which is why high Reynolds numbers remain unfinished work here.

This solver's default collision is TRT (two relaxation times). It relaxes even and odd parts of the populations separately. With the particular combination $\Lambda = 3/16$, a straight wall sits exactly where it should for any viscosity. Without it, in the simpler BGK scheme, the wall's effective position shifts with $\tau$.

Walls, curved bodies and open ends

Populations that hit a solid need a rule for what happens next. This solver implements several, and it compares them directly.

ProblemMethodIdea
Straight wallHalfway bounce-backA population hitting a wall returns the way it came
Moving wallLadd correctionBounce-back plus a term that adds the wall's momentum
Curved bodyBouzidi interpolated bounce-backUses how far along each grid link the true surface sits
Curved bodyImmersed boundary method (IBM)Surface points push on the fluid with local forces
Inlet and outletZou–HeSolves for missing populations from a set velocity or pressure
Force on a bodyMomentum exchangeAdds up momentum transferred across each wall link

Plain bounce-back turns a circle into grid-shaped stairs. The figure below shows what the smarter methods gain. Its left panel has all three: the staircase error wanders with no clean trend, IBM falls at first order, and Bouzidi falls at second order, with error near 0.001 % at radius 24.

Log-log error plots for staircase, Bouzidi and immersed boundary walls in three test problems
Error against body size in three problems with known answers. Lower is better. Dotted lines show ideal first-order and second-order trends.

Making the GPU fast

Memory is the speed limit

LBM does little arithmetic per point but moves a lot of data. A 2D update in float32 reads nine numbers and writes nine: 72 bytes. A benchmark measured this card's memory at about 156 GB/s, which caps speed:

$$\frac{156\ \text{GB/s}}{72\ \text{bytes per update}} \approx 2{,}170\ \text{million updates per second}$$

So the engineering question is how close the code gets to that ceiling. Faster arithmetic can't help once memory is the bottleneck.

A fused kernel

Written as ordinary GPU array code, one time step launches about 100 small GPU programs. A fused kernel combines streaming, walls and collision into one program that handles each point in a single pass. That change alone gave a 37× speedup.

Here is the core of the two-lattice kernel. One thread runs this for each grid point:

real_t f[Q];
#pragma unroll
for (int i = 0; i < Q; ++i) {
    const size_t src = neighbour<-1>(i, n, nx, ny, nz);
    if (solid[src] == SOLID) {
        // Halfway bounce-back: the population that left this node towards the wall.
        f[i] = f_src[opp(i) * n_nodes + n.index] + wall_term(i, wall_u, src, n_nodes);
    } else {
        f[i] = f_src[i * n_nodes + src];
    }
}

collide_node(f, r);

#pragma unroll
for (int i = 0; i < Q; ++i) f_dst[i * n_nodes + n.index] = f[i];

Three designs, tested against each other

Three other choices matter:

A 3D update moves 152 bytes, so the same memory limit is about 1,030 million updates per second.

Is it correct?

Speed means nothing if the answers are wrong, so every case below is compared with an exact solution or a published reference.

TestWhat it checksResult
Poiseuille channel flowWalls and driving forceTRT matches the exact parabola to 3e-13
Taylor–Green vortexViscosity, grid accuracyConvergence order 2.00; decay-rate error 0.4 % at N = 32
Lid-driven cavity, Re = 1000Moving walls, stabilityWithin 0.9 % of Ghia et al. (1982)
3D ABC flow3D scheme vs exact solutionOrder 2.0 from 16³ to 128³
3D square ductWalls in two directionsOrder 2.0 vs Fourier series
Stokes cylinder arrayCurved wallsBouzidi −0.10 % at R = 8 vs Sangani–Acrivos
Pipe flow (3D)Curved wall in 3DBouzidi error 7–45× below staircase
Sphere, Re = 20 and 1003D body in open flow$C_D$ = 2.77 and 1.13 vs 2.74 and 1.09 (Clift et al.)
GPU vs NumPyImplementation correctnessAbout 1e-17 in 2D and 5e-18 in 3D, float64

There were also over 300 automated tests when the 3D engine stage finished.

Four panels: cavity flow, centreline velocity against Ghia data, Poiseuille error against relaxation time, and speed by backend
2D core results. Top: Re = 1000 cavity flow and its match to Ghia's data. Bottom left: TRT stays at round-off level for every τ, while BGK's wall error follows the theory curve. Bottom right: speed of each version.

The cylinder benchmark

The Schäfer–Turek benchmark is a standard test with intervals agreed by several research groups. It places a cylinder in a channel. At Re = 20 the flow settles, and at Re = 100 it sheds vortices in a repeating pattern.

CaseQuantityThis solverAccepted interval
2D-1, Re = 20, N = 40Drag $C_D$5.5895.57–5.59
2D-1, Re = 20, N = 40Lift $C_L$0.010580.0104–0.0110
2D-2, Re = 100, N = 80Peak drag3.2383.22–3.24
2D-2, Re = 100, N = 80Peak lift0.9920.99–1.01
2D-2, Re = 100, N = 80Strouhal number0.3020.295–0.305
Vortex street behind a cylinder with drag and lift over time
The Re = 100 case on a coarser grid (N = 40). Drag peaks near 3.28 here, above the accepted interval. The in-interval value of 3.238 in the table comes from the finer N = 80 grid.
Two log-log plots showing 3D error falling along second-order lines
3D validation. Doubling the resolution cuts the error by four, as second-order theory predicts.
Speed field around a sphere with a closed recirculation bubble behind it
A sphere at Re = 100 in 3D, showing a slice through its centre. The orange line outlines the region where flow runs backward.

Two errors that didn't announce themselves

The most useful results came from numbers that looked almost right.

A drag error that better resolution didn't fix. Cylinder drag came out about 2 % too high, and using a finer grid didn't help. That pointed away from grid error. Plotting drag against the square of the flow speed gave a straight line, so the cause was LBM's slight compressibility. The fix was running at a lower lattice velocity, and the line extrapolates to $C_D = 5.581$ at zero Mach number, inside the accepted interval.

Drag coefficient plotted against squared velocity, forming a straight line
Drag against squared lattice velocity at a fixed grid size. The straight line identifies the error as compressibility.

A blow-up 140,000 steps in. A run looked healthy, then its mass grew exponentially. The cause was inconsistent treatment of Zou–He inlet and outlet nodes at the channel corners. Giving those nodes the full Zou–He treatment fixed it.

What this project doesn't do yet

Run it yourself

Open the runnable notebook in Google Colab. It installs the package and runs small cases on the CPU reference solver, so it needs no GPU.

With an NVIDIA GPU and uv, the full kernels run locally:

git clone https://github.com/ShauryaAttreya37/High-Performance-LBM-On-GPU-.git
cd High-Performance-LBM-On-GPU-
uv sync --extra gpu
uv run python -m lbm.cases.lid_driven_cavity --re 1000 --n 256 --backend cuda-aa --dtype float32 --plot
uv run python benchmarks/bench_mlups.py --plot

References