Choosing units and staying stable¶
English | Japanese
Every number on this page was measured in this repository. The source is stated in each section.
Lattice units without a conversion class¶
OpenRheo has no UnitConverter. It uses lattice units with dx = dt = 1, and each benchmark chooses u_lat (the characteristic velocity), N (the number of cells across the characteristic length) and Re directly. The viscosity is ν = c_s²(τ−1/2) with c_s² = 1/3, so there is only 1 governing relation:
τ = 3 · u_lat · N / Re + 0.5
This formula is written verbatim in the header of ghia_re1000.cpp, and you can check it against any case header. Once the physics has fixed Re, the currencies you can freely choose are the 2 of u_lat and N, and as a consequence they fix τ (stability) and Ma = u_lat·√3 (compressibility error). This page is about the safe ranges of those 2, and about the 3rd currency (the collision operator) for when neither can be moved.
The τ → 0.5 cliff — measured records¶
The stability limit of τ is 0.5. What happens as you approach it is on record in this repository.
- ghia_re1000 (Re=1000 cavity): as recorded in its header, plain BGK D3Q19 gave NaN at every resolution tried, n=16–64 (τ=0.519 at n=64). Even after switching every solve to regularized BGK, n≥48 is required, and n=16/32 still give NaN — because the boundary layer ~1/√Re ≈ 0.03 is less than half a coarse cell. The measured τ of the gallery runs is 0.5144 at n=48 and 0.5288 at fine n=96 (runs.json).
- powerlaw_poiseuille2d: because τ is recomputed from the shear rate in every cell at every step, the source clamps τ to the band [0.51, 2.0]. The lower bound 0.51 is the house-style number for "a safety margin from the cliff".
- This is what the cliff looks like in a log: the gallery run of channel3d-d3q19 (runs.json) prints τ0=0.51333 and then exits 1 with "FAIL NaN at warm-up step 1000". NaN does not arrive gradually; it arrives suddenly, as total collapse.
The 3rd currency — the ladder of collision operators¶
When neither the resolution nor u_lat can be moved, the remaining lever is the collision operator. kbc_cavity2d switches between bgk|mrt|kbc on the same lattice under the same conditions and prints either STABLE max|rho-1| or DIVERGED@step in its RESULT line — a case that treats stability itself as the measured quantity. The measured record (docs/design/kbc-entropic-design.md §11) is that BGK diverges at Re=1500 while KBC is stable up to Re=2000 (2 times, on the same n=64 lattice). ghia_re1000 runs every solve with regularized BGK because of the total-collapse record in the previous section, and cavity3d-d3q27 runs low-resolution Re=10⁴ stably with the D3Q27 cumulant. The ladder runs roughly bgk → reg/trt/mrt → central-moment/cumulant/kbc; which case uses what is in Models. We also quote the caveat from the same §11: KBC on D3Q19 effectively collapses to MRT (the benefit of KBC is on the D3Q27 side).
Mach — the upper limit on u_lat and local acceleration¶
Ma = u_lat·√3. The house default is u_lat ≈ 0.05, but it is not uniform: ghia_re1000 and kbc_cavity2d use 0.1, venturi3d uses 0.04 (because u speeds up by a factor of 1/β² in the throat, the inlet value is lowered to keep the peak Ma down). What to look at is not the inlet value but the printed peak Ma: cylinder2d has a peak Ma of 0.130 even with Ubar=0.05 (gallery run log), and the failure log of channel3d printed Ma_centre~0.40 before the NaN — a case of hitting the τ cliff and compressibility at the same time. Halving u_lat cuts the compressibility error to 1/4, but doubles the number of steps to the same physical time (Things to try in the cylinder2d note explains this with measurements).
The start-up pressure wave¶
Imposing an inflow condition impulsively on a fluid at rest sends a pressure wave through it. In the cylinder2d gallery run Cd at step 0 is 134.4, falling to 4.03 by t≈0.5 s — an artefact of the initial condition, not physics. That is why the plots clip the vertical axis to the 2–98 percentiles and the QoI are evaluated over the later, developed interval. Know that this is normal before you see the start-up spike and suspect a NaN or a bug.
Boundary-induced divergence — a measured fix for backflow¶
When an LES wake hits a fixed-pressure outflow as backflow, the instability starts there. Commit 000617a is the measured fix: it added 16 lines to forest_step.hpp that clamp the re-entering normal velocity to 0 at the forest pressure outflow (equivalent to inletOutlet) — a no-op for outgoing flow, and all gates still PASS after the change. If you see a NaN that starts near the outflow, first check whether this mechanism is present.
NaN checklist — starting from the log you have¶
- Read the log you already have. What was printed just before the NaN? In the channel3d example, τ0=0.51333 and Ma_centre~0.40 almost give the answer.
- Check τ: τ = 3·u_lat·N/Re + 0.5. If it is around 0.51 or below, it is one of 3–5 below.
- Check the peak Ma: if it is above 0.1, lower u_lat (the number of steps goes up).
- Move the collision operator up one rung: bgk → reg/mrt → cumulant/kbc.
- Raise the resolution: if the boundary layer 1/√Re is half a cell or less, changing the operator is not enough (the lesson of ghia's n≥48).
- Suspect the start-up: if the divergence is early, it is the impulsive initial condition (pressure wave). Ramp up, or discard an initial interval.
- Suspect backflow at the outflow: with a fixed-pressure outflow + LES, use the backflow clamp (commit 000617a).
- There is no Δt knob to turn. dx = dt = 1 — the only currencies you can move are the 3 of u_lat, N and the collision operator.