thermal-cavity2d¶
English | Japanese
« Home · « Heat transfer and phase change
Thermal LBM -- 2D Boussinesq natural convection in a differentially-heated square cavity (de Vahl Davis 1983 benchmark). Driver ONLY: the physics lives in openrheo_amr/thermal_ddf.hpp (double-distribution-function thermal LBM, D2Q9 momentum + D2Q5 temperature, Guo buoyancy), which this file sets up, marches and reports. Migrated from an inlined implementation as the first benchmark of docs/design/module-architecture-design.md -- the same module backs tests/test_thermal_ddf (de Vahl Davis Nu) and tests/test_thermal_rayleigh_benard (the same stepper with the hot walls moved to the horizontal boundaries), so the physics now has one home instead of one copy per case.
Geometry¶

Animation¶
Fields¶
The fields this computation wrote at its last output step, plotted as they are. 3D cases show the mid-plane.


Results¶
The differentially side-heated square cavity of de Vahl Davis (1983), Ra = 1e4, Pr = 0.71, N = 128, buoyancy velocity U = 0.1. The mapping is ν = U·N·√(Pr/Ra) = 0.1 × 128 × √(7.1e-5) = 0.10785, α = ν/Pr = 0.15191, gβ = U²/(ΔT·N) = 0.01/128 = 7.813e-5, τ_f = 3ν + 1/2 = 0.8236, τ_g = 3α + 1/2 = 0.9557 — agreeing in every digit with the 1st line of the log. Wall-clock time 10.51 seconds.
- Convergence: Nu_hot overshoots to 2.373 during start-up (step 8000) and then undergoes a decaying oscillation; it satisfies dNu/Nu < 5e-7 at step 42000 and stops.
- Nusselt number: Nu_hot = Nu_cold = 2.244091 (heat-balance imbalance 0.00%). Against the de Vahl Davis benchmark value 2.243, (2.244091 − 2.243)/2.243 = +0.049%.
- Velocity extrema (U_ref = α/H scale): |u_max| = 16.187 (y/H = 0.176), |v_max| = 19.645 (x/H = 0.879). Against the literature values 16.178 (y = 0.823) and 19.617 (x = 0.119): 0.06% / 0.14%. The positions are 1 − 0.176 = 0.824 and 1 − 0.879 = 0.121, which match the literature positions apart from a mirror image in the direction of rotation.
🧩 About the module gate. This driver is only 148 lines long. The physics lives in
thermal_ddf.hpp (the DDF thermal LBM module), and ctest thermal_ddf keeps a permanent
golden gate at N = 64 with Nu = 2.2431 vs 2.243 (0.00%)
(docs/design/module-architecture-design.md). When migrating from the inline implementation,
the pass condition for the migration was that this RESULT line (Nu 2.244091, u_max −16.187181, v_max −19.645266,
converged at step 42000) be bit-identical.
During the module extraction a bug that dropped the H/ΔT factor of the Nusselt integral actually occurred,
and the gate caught it immediately — these numbers are not decoration but a regression net.
Governing equations¶
Natural convection in the Boussinesq approximation. Incompressible NS + buoyancy, and temperature advection–diffusion:
\[
\partial_t\boldsymbol{u}+\boldsymbol{u}\cdot\nabla\boldsymbol{u}
=-\nabla p+\nu\nabla^2\boldsymbol{u}+g\beta T\,\hat{\boldsymbol{y}},\qquad
\partial_t T+\boldsymbol{u}\cdot\nabla T=\alpha\nabla^2 T
\]
The governing groups are Ra = gβΔT H³/(να) and Pr = ν/α. The LBM uses a double distribution function (DDF): D2Q9 BGK carries momentum, D2Q5 BGK carries temperature, and buoyancy enters via Guo forcing (He–Chen–Doolen 1998 / Guo 2002). The lattice mapping fixes U = √(gβΔT H) at a small value to keep the Mach number low:
\[
\nu=UH\sqrt{Pr/Ra},\quad \alpha=\nu/Pr,\quad g\beta=U^2/(\Delta T\,H)
\]
All walls are no-slip (halfway bounce-back); for temperature, the left wall is T = +1/2 (hot) and the right wall T = −1/2, both anti-bounce-back Dirichlet, and the top and bottom are adiabatic.
Code walkthrough¶
Source (148 lines) and thermal_ddf.hpp.
%%{init: {'themeVariables': {'fontSize': '11px'}}}%%
flowchart LR
H["Left wall hot T=+1/2<br/>anti-BB Dirichlet<br/>no-slip"] --> C2["128×128 cavity<br/>D2Q9+D2Q5 DDF / Guo buoyancy<br/>top/bottom: adiabatic, no-slip"]
C2 --> C["Right wall cold T=−1/2<br/>anti-BB Dirichlet<br/>no-slip"]
- ThermalParams — only sets square(128), Ra, Pr and the wall types (left/right Dirichlet / top/bottom Adiabatic). The lattice, equilibrium and forcing are all on the module side.
- Initial field — starts from thermal_linear_profile (the linear conduction profile).
- March — runs the thermal step and monitors the relative drift of the hot-wall Nu every 2000 steps. Stops once it falls below 5e-7.
- Report — Nu_hot/Nu_cold (balance check), velocity extrema and their positions, RESULT line. With ORHEO_WIKI_DUMP enabled, the T and u fields go to the gallery.
Build & run¶
cmake -S native -B native/build && cmake --build native/build -j
./native/build/orheo-thermal-cavity2d
thermal_cavity2d [N] [Ra] [steps] [Pr] [out_prefix] [U]
Cost of the computation that made the figures on this page (Miyabi-G Grace CPU (72 cores, -stdpar=multicore)): 10.5 s wall.
Things to try¶
- Ra sweep:
thermal_cavity2d 128 1e5→ 1e6. Trace Nu(Ra) along the de Vahl Davis series. The boundary layers get thinner, so raise N as well. - N convergence: measure the grid convergence of Nu with N = 64/128/256 (ctest is already at 0.00% at N = 64, but the positions of the velocity extrema are more sensitive to resolution).
- Lower U: isolate the contribution of the compressibility error (Ma²) with U = 0.05. Does the 4th digit of Nu move?
- Compare with rayleigh_benard2d: just changing the wall settings of the same module gives a different classic problem — reading the diff of ThermalParams is the quickest way to see it.
Validation¶
| Tier | T1 — automatic gate |
| QoI | Nu, u_max |
| Reference | de Vahl Davis (1983) Int.J.Numer.Meth.Fluids 3:249 -- Nu, u_max |
| Gate | 🧩 module gate (thermal_ddf) |
| Measured | 2.244091 (rel. err +0.05%) — cross-code run (thermal_cavity) |
Source & run details¶
| Item | Value |
|---|---|
| Target | orheo-thermal-cavity2d |
| Source | native/benchmarks/thermal_cavity2d.cpp |
| Lattice | D2Q9 + D2Q5 (DDF) |
| GPU twin | no |
| Modules | thermal_ddf.hpp |
| Gallery run | 2026-07-27 @ 7628c0cf |
| Args | `` |
| Wall time | 10.51 s |
| CPU time | 370.34 s |
| Device | Miyabi-G Grace CPU (72 cores, -stdpar=multicore) |
Computation log¶
The actual output of this computation (head and tail).
thermal_cavity2d N=128 Ra=1e+04 Pr=0.710 U=0.100 nu=0.10785 alpha=0.15191 gbeta=7.813e-05 tau_f=0.8236 tau_g=0.9557
step 0: Nu_hot=1.00000 dNu/Nu=1.00e+09
step 2000: Nu_hot=1.11724 dNu/Nu=1.05e-01
step 4000: Nu_hot=1.82400 dNu/Nu=3.87e-01
step 6000: Nu_hot=2.36510 dNu/Nu=2.29e-01
step 8000: Nu_hot=2.37307 dNu/Nu=3.36e-03
step 10000: Nu_hot=2.26905 dNu/Nu=4.58e-02
step 12000: Nu_hot=2.22279 dNu/Nu=2.08e-02
step 14000: Nu_hot=2.22648 dNu/Nu=1.66e-03
step 16000: Nu_hot=2.24035 dNu/Nu=6.19e-03
step 18000: Nu_hot=2.24628 dNu/Nu=2.64e-03
step 20000: Nu_hot=2.24583 dNu/Nu=1.97e-04
step 22000: Nu_hot=2.24429 dNu/Nu=6.89e-04
step 24000: Nu_hot=2.24372 dNu/Nu=2.54e-04
...
step 34000: Nu_hot=2.24409 dNu/Nu=1.01e-05
step 36000: Nu_hot=2.24408 dNu/Nu=2.83e-06
step 38000: Nu_hot=2.24409 dNu/Nu=1.27e-06
step 40000: Nu_hot=2.24409 dNu/Nu=1.35e-06
step 42000: Nu_hot=2.24409 dNu/Nu=3.61e-07
converged (dNu/Nu < 5e-7) at step 42000
Nu_hot=2.2441 Nu_cold=2.2441 (imbalance 0.00%)
u_max=-16.187 (y/H=0.176) v_max=-19.645 (x/H=0.879) [U_ref=alpha/H]
RESULT Ra=10000 N=128 Nu_hot=2.244091 Nu_cold=2.244091 umax=-16.187181 vmax=-19.645266
References¶
- G. de Vahl Davis, Int. J. Numer. Methods Fluids 3 (1983) 249 — benchmark values Nu = 2.243, u_max = 16.178 (y = 0.823), v_max = 19.617 (x = 0.119) (Ra = 1e4).
- X. He, S. Chen & G. D. Doolen, J. Comput. Phys. 146 (1998) 282 — DDF thermal LBM.
- Z. Guo, C. Zheng & B. Shi, Phys. Rev. E 65 (2002) 046308 — forcing term.