IBSEB wall function: Louis (1979) stability factors on roofs (erf.ibseb.stability_scheme)

[hgopalan]

Summary

Based on ERF-Fire after the development sync (#428). The Obukhov seed reads the ground surface layer through upstream's per-face vector (m_SurfaceLayer[zlo], from erf-model#4025), and is now fetched only for the iterative scheme, since the Louis factors need no seed.

Adds the Louis (1979) stability factors as a second way to correct the building wall function on roofs, next to the iterated similarity functions.

• Input. erf.ibseb.stability_scheme = iterative | louis. It is a sub-option of the existing erf.ibseb.stability_correction and is read only when that switch is on. The default stays iterative, so every existing deck is unchanged.
• Aborts at start-up name the input to change. They fire for:
  • stability_scheme set without the correction;
  • an unknown scheme;
  • obukhov_seed or obukhov_relax together with louis.

The factors

The bulk Richardson number is taken between the skin and the fluid cell centre (half a cell, delta), with the effective wind that includes the convective velocity scale.

• Unstable: F = 1 - b Ri_b / (1 + C* a^2 b sqrt(|Ri_b| delta / z0)) with b = 9.4, C* = 7.4 (momentum) and 5.3 (heat).
• Stable: F_m = F_h = 1 / (1 + 4.7 Ri_b)^2.

The factors multiply the neutral coefficients: u* = kappa U sqrt(F_m) / ln(delta/z0) and u* theta* = kappa^2 U dtheta F_h / (ln(delta/z0) ln(delta/z0h)).

• Neutral limit. It is the wall function's two log laws. Louis' heat-to-momentum ratio R = 0.74 is not applied, because it stands in for a heat roughness below the momentum one, which erf.ibseb.z0h_wall already sets.
• No iteration or seed. The Obukhov length it stores is diagnosed from the resulting u* and theta*. Walls stay on the log law, as with the iterated scheme.
• Coefficients. They are the values usually cited for Louis (1979), BLM 17, 187-202. The paper itself was not accessible while writing this, so please check them against it.

How it compares

Offline roof flux at delta = 5 m, z0 = 0.01 m, z0h = 0.001 m, theta_air = 300 K (H in W/m2):

U [m/s]	skin - air [K]	iterative H	Louis H	Ri_b	Louis / iterative
0.5	5	29.0	39.7	-3.27	1.37
0.5	25	265.6	404.8	-16.4	1.52
1.0	25	312.4	436.1	-4.09	1.40
2.7	5	69.9	72.4	-0.11	1.04
2.7	25	479.0	552.5	-0.56	1.15
5.0	25	689.0	726.9	-0.16	1.06
2.7	-2	-14.9	-14.1	0.04	0.95
1.0	-2	~0 (collapsed)	-1.2	0.33	no critical Ri in Louis

In the WallFunction case (hot roof in calm air, convective scale on), the roof flux is 465 W/m2 with Louis and 436 W/m2 with the iterated functions.

Test plan

• Release build (MPI, FFT, fire, dust): no warnings; 669 unit tests pass, including the new IBSEBLouis suite (neutral, stable and unstable closed forms, monotone and continuous through neutral).
• Each unit test fails on a mutated header (heat C* changed, stable form changed).
• Exec/CanonicalTests/SEB/WallFunction: ALL PASS, including the new checks:
  • inputs_louis: roof u*, L and H follow the factors to about 1e-11 (tolerance 1e-6), and walls stay on the log law.
  • The same check run on the iterated scheme's dumps fails (u* 3 %, H 14 %), so it tells the schemes apart.
  • The three abort decks stop with their messages.
  • The Deardorff restart is exact.
• On 4 ranks, every line of the previous reference output is reproduced exactly, resid_max included: the neutral, deardorff, stability and bulkri variants and the restart. The README reference block now adds the Louis lines and the abort decks.
• Single-precision compile of ERF_IBFaceSet.cpp, ERF_IBSEB.cpp and the new test: clean.
• Sphinx: 0 warnings. Codespell, git diff --check, GPU lint (no hits) and the MSVC scan are clean.
• The new header's square root takes a clipped argument, so a speculatively evaluated unstable arm cannot trap.

🤖 Generated with Claude Code