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. The charts are live: hover for values, click a legend entry to hide a curve, and move the sliders where they appear.
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 |
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.
Combining this with $\mathrm{Re} = uN/\nu$, for a body $N$ nodes long and lattice speed $u$, gives $\tau - \tfrac12 = 3uN/\mathrm{Re}$. The chart below plots that formula, so it involves no simulation. Choose a grid size and see where the line crosses the solver's warning level at $\tau = 0.51$. At $u = 0.05$, reaching Re = 100,000 above that level would take about 6,700 nodes along the body.
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$.
The same physics in the project's Python
Streaming and collision from the NumPy reference solver, src/lbm/streaming.py and src/lbm/collision.py. The array non_eq is $f_i - f_i^{\mathrm{eq}}$, and omega_plus and omega_minus are TRT's two relaxation rates:
def pull_stream(lattice: VelocitySet, f_post, xp=np):
"""Return f_i(x) = f_post_i(x - c_i) with periodic wrap-around, as a new array."""
axes = tuple(range(lattice.d))
return xp.stack(
[xp.roll(f_post[i], shift=index_shift(c_i), axis=axes) for i, c_i in enumerate(lattice.c)]
)
delta_rho, u = pre_collision_moments(lattice, f, force)
non_eq = f - equilibrium(lattice, delta_rho, u, xp)
non_eq_opp = non_eq[list(lattice.opposite)]
post = (
f - (0.5 * omega_plus) * (non_eq + non_eq_opp) - (0.5 * omega_minus) * (non_eq - non_eq_opp)
)
if any(not _is_zero(f_a) for f_a in force):
post = post + guo_source(lattice, u, force, omega_plus, omega_minus, xp)
return post
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. These three problems have known answers, so they show what the smarter methods gain, and lower is better. In the 2D array the staircase error wanders with no clean trend, IBM falls at first order, and Bouzidi falls at second order, reaching about 0.001 % at radius 24. The dashed lines show an ideal second-order trend for comparison.
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.
The speed numbers come from benchmarks/bench_mlups.py. It times a run, converts that to million lattice updates per second (MLUPS), then converts that to the memory bandwidth used. Each update reads and writes q values, hence the factor of 2:
mlups = nodes * steps / seconds / 1e6
bandwidth = mlups * 1e6 * 2 * q * itemsize / 1e9
The three kernel bars come from the latest benchmark file. The NumPy and CuPy bars come from earlier runs, and kernel speeds differ by about 1 % between runs.
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.
Each validation case can plot its own comparison. This excerpt from src/lbm/cases/poiseuille.py draws the simulated channel profile against the exact one:
fig, (ax_profile, ax_error) = plt.subplots(1, 2, figsize=(10, 4))
first = next(iter(results.values()))
ax_profile.plot(first.u_exact / first.u_exact.max(), first.y, "k-", label="exact")
for label, r in results.items():
ax_profile.plot(r.u / r.u_exact.max(), r.y, "o", ms=4, label=label)
ax_error.semilogy(r.y, np.abs(r.u - r.u_exact) / r.u_exact.max() + 1e-17, label=label)
The live charts on this page plot stored results: benchmark CSV files, the measured tables in figures/make_figures.py and its cached flow fields. Nothing was re-run to draw them. The animated schematics are drawings, and are labelled as such.
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, $u_{\max}$ = 0.01875 | Drag $C_D$ | 5.589 | 5.57–5.59 |
| 2D-1, Re = 20, N = 40, $u_{\max}$ = 0.01875 | Lift $C_L$ | 0.01058 | 0.0104–0.0110 |
| 2D-2, Re = 100, N = 80, $u_{\max}$ = 0.025 | Peak drag | 3.238 | 3.22–3.24 |
| 2D-2, Re = 100, N = 80, $u_{\max}$ = 0.025 | Peak lift | 0.992 | 0.99–1.01 |
| 2D-2, Re = 100, N = 80, $u_{\max}$ = 0.025 | Strouhal number | 0.302 | 0.295–0.305 |
The chart below shows a coarser stored run, at N = 40 and $u_{\max}$ = 0.05. Drag peaks near 3.28, above the shaded interval, while lift stays close to its accepted peak. Drag oscillates twice as fast as lift, because each shed vortex pushes the cylinder to one side in turn but adds to its drag every time. Most of the drag excess at this speed is the compressibility error explained further down: the stored N = 80 run at the same speed still peaks at 3.28, while the in-interval result used N = 80 at half the speed. Drag the slider under the chart to zoom into a few cycles.
3D checks
Two 3D flows have exact solutions to compare against. In both, doubling the resolution cuts the error by four, which is what second-order theory predicts. The last figure in this section shows a sphere at Re = 100, as a slice through its centre.
Move the slider to read the same stored field along lines parallel to the axis. Close to the axis the velocity starts negative, which is the backward flow in the bubble, and first turns positive about 1.44 diameters from the sphere's centre on this coarse N = 16 grid. Further from the axis, the flow outside the wake runs slightly faster than the free stream.
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 \approx 5.58$ 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.