A GPU fluid simulator, explained
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.
The project at a glance
| Result | Value | Compared with |
|---|---|---|
| 2D speed | about 2,130 million updates/s | about 2,170 million/s, the memory limit |
| 3D speed | about 1,000 million updates/s | about 1,030 million/s, the memory limit |
| Speedup from a fused kernel | 37× | the same algorithm as ordinary GPU array code |
| Cylinder shedding frequency | St = 0.302 | published interval 0.295–0.305 |
| Accuracy as the grid gets finer | error falls by 4× per doubling | second order, as theory predicts |
| GPU vs CPU reference | agree to about 1e-17 in float64 | independent 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.
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.
| Problem | Method | Idea |
|---|---|---|
| Straight wall | Halfway bounce-back | A population hitting a wall returns the way it came |
| Moving wall | Ladd correction | Bounce-back plus a term that adds the wall's momentum |
| Curved body | Bouzidi interpolated bounce-back | Uses how far along each grid link the true surface sits |
| Curved body | Immersed boundary method (IBM) | Surface points push on the fluid with local forces |
| Inlet and outlet | Zou–He | Solves for missing populations from a set velocity or pressure |
| Force on a body | Momentum exchange | Adds 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.
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
- Two-lattice: read from one copy of the grid and write to another. Simple and fastest, but it uses twice the memory.
- AA pattern: update a single grid in place, alternating two kinds of step. It uses half the memory and almost matches the two-lattice kernel, which matters on a 6 GB card.
- Tiled: copy neighbouring data through fast on-chip shared memory, a well-known optimisation from older GPUs. On this card it's slower, and the gap widens as the grid grows.
Three other choices matter:
- Registers, not memory. Per-thread arrays stay in registers, and every kernel uses 0 bytes of local memory.
- One source for 2D and 3D. A 2D grid compiles as a 3D grid with one layer, where the z terms are compile-time zeros. So 3D support didn't slow 2D down.
- float32 for production. This consumer GPU runs float64 at 1/64 of the float32 rate, which drops speed to about 280–310 million updates/s. Validation results match to four digits, so float32 is the default.
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.
| Test | What it checks | Result |
|---|---|---|
| Poiseuille channel flow | Walls and driving force | TRT matches the exact parabola to 3e-13 |
| Taylor–Green vortex | Viscosity, grid accuracy | Convergence order 2.00; decay-rate error 0.4 % at N = 32 |
| Lid-driven cavity, Re = 1000 | Moving walls, stability | Within 0.9 % of Ghia et al. (1982) |
| 3D ABC flow | 3D scheme vs exact solution | Order 2.0 from 16³ to 128³ |
| 3D square duct | Walls in two directions | Order 2.0 vs Fourier series |
| Stokes cylinder array | Curved walls | Bouzidi −0.10 % at R = 8 vs Sangani–Acrivos |
| Pipe flow (3D) | Curved wall in 3D | Bouzidi error 7–45× below staircase |
| Sphere, Re = 20 and 100 | 3D body in open flow | $C_D$ = 2.77 and 1.13 vs 2.74 and 1.09 (Clift et al.) |
| GPU vs NumPy | Implementation correctness | About 1e-17 in 2D and 5e-18 in 3D, float64 |
There were also over 300 automated tests when the 3D engine stage finished.
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.
| Case | Quantity | This solver | Accepted interval |
|---|---|---|---|
| 2D-1, Re = 20, N = 40 | Drag $C_D$ | 5.589 | 5.57–5.59 |
| 2D-1, Re = 20, N = 40 | Lift $C_L$ | 0.01058 | 0.0104–0.0110 |
| 2D-2, Re = 100, N = 80 | Peak drag | 3.238 | 3.22–3.24 |
| 2D-2, Re = 100, N = 80 | Peak lift | 0.992 | 0.99–1.01 |
| 2D-2, Re = 100, N = 80 | Strouhal number | 0.302 | 0.295–0.305 |
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.
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
- High Reynolds numbers. The long-term goal of drag predictions up to Re = 100,000 hasn't been reached. Tests here stop at Re = 1,000 and the required turbulence models aren't built.
- Wind-tunnel validation. Comparisons so far are against exact solutions, numerical benchmarks and published correlations, and no wind-tunnel sweep has been done.
- IBM speed. The immersed boundary step is still ordinary array code and costs two thirds of throughput.
- 3D open flow speed. A body with an inlet and outlet keeps 96 % of empty-domain speed in 2D, but 77–83 % in 3D.
- Sphere accuracy. Sphere drag sits 1–4 % above the reference correlation on these coarse grids.
- Planned stages. Real-time visualisation and automated CI are still on the roadmap, and everything so far has been measured on one GPU model.
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
- T. Krüger et al., The Lattice Boltzmann Method: Principles and Practice, Springer (2017).
- I. Ginzburg, F. Verhaeghe, D. d'Humières, Two-relaxation-time lattice Boltzmann scheme, Commun. Comput. Phys. 3 (2008) 427.
- Z. Guo, C. Zheng, B. Shi, Discrete lattice effects on the forcing term, Phys. Rev. E 65 (2002) 046308.
- A. J. C. Ladd, Numerical simulations of particulate suspensions, J. Fluid Mech. 271 (1994) 285.
- U. Ghia, K. N. Ghia, C. T. Shin, High-Re solutions for incompressible flow, J. Comput. Phys. 48 (1982) 387.
- M. Bouzidi, M. Firdaouss, P. Lallemand, Momentum transfer of a Boltzmann-lattice fluid with boundaries, Phys. Fluids 13 (2001) 3452.
- Q. Zou, X. He, On pressure and velocity boundary conditions, Phys. Fluids 9 (1997) 1591.
- M. Schäfer, S. Turek, Benchmark computations of laminar flow around a cylinder, Notes Numer. Fluid Mech. 52 (1996) 547.
- A. S. Sangani, A. Acrivos, Slow flow past periodic arrays of cylinders, Int. J. Multiphase Flow 8 (1982) 193.
- The README has the full list.