One-equation k RANS: wall condition, closure fixes, terrain wall distance, Canonical_RANS regression cases

Docs/sphinx_doc/Inputs.rst

@@ -1617,8 +1617,37 @@ List of Parameters
 | **erf.max_geom_lscale**          | upper bound [m] on the geometric mixing length           | Real > 0           | 30.0             |
 |                                  | (per-level)                                              |                    |                  |
 +----------------------------------+----------------------------------------------------------+--------------------+------------------+
-| **erf.dirichlet_k**              | impose a Dirichlet condition on the turbulent kinetic    | Boolean            | false            |
-|                                  | energy at the wall (per-level)                           |                    |                  |
+| **erf.dirichlet_k**              | k-equation RANS under a surface layer: set the turbulent | Boolean            | false            |
+|                                  | kinetic energy of the first cell above the wall from u*  |                    |                  |
+|                                  | and t* (Axell & Liungman 2001, Eq. 16) and hold it       |                    |                  |
+|                                  | through the step (per-level)                             |                    |                  |
++----------------------------------+----------------------------------------------------------+--------------------+------------------+
+| **erf.tke_floor**                | runtime floor on the turbulent kinetic energy [m^2/s^2]  | Real >= 0          | 0 (machine       |
+|                                  | in the k-equation update and the RANS closure; distinct  |                    | epsilon on rho k)|
+|                                  | from ``erf.tke_min``, the initial value (per-level)      |                    |                  |
++----------------------------------+----------------------------------------------------------+--------------------+------------------+
+| **erf.implicit_tke_dissipation** | Deardorff or k-equation RANS: treat the TKE dissipation  | Boolean            | false            |
+|                                  | implicitly, eps = (C k_old^1/2 / L) k_new folded into    |                    |                  |
+|                                  | the update, which removes the dissipation time-step      |                    |                  |
+|                                  | limit near the wall (per-level)                          |                    |                  |
++----------------------------------+----------------------------------------------------------+--------------------+------------------+
+| **erf.rans_consistent_diffusivit-| k-equation RANS: horizontal heat, scalar and moisture    | Boolean            | false            |
+| ies**                            | diffusivities follow the scalar stability function       |                    |                  |
+|                                  | (Axell & Liungman Eq. 32) like the vertical heat         |                    |                  |
+|                                  | diffusivity, instead of Pr_t and Sc_t times the eddy     |                    |                  |
+|                                  | viscosity (per-level)                                    |                    |                  |
++----------------------------------+----------------------------------------------------------+--------------------+------------------+
+| **erf.rans_lscale_from_pblh**    | k-equation RANS: cap the geometric length at kappa times | Boolean            | false            |
+|                                  | 0.1 times the diagnosed PBL height (needs                |                    |                  |
+|                                  | ``erf.most.pblh_calc = MYNN25``), clamped to             |                    |                  |
+|                                  | [``erf.rans_lscale_min``, ``erf.max_geom_lscale``]       |                    |                  |
+|                                  | (per-level)                                              |                    |                  |
++----------------------------------+----------------------------------------------------------+--------------------+------------------+
+| **erf.rans_lscale_min**          | lower bound [m] of the PBL-height cap above (per-level)  | Real > 0           | 1.0              |
++----------------------------------+----------------------------------------------------------+--------------------+------------------+
+| **erf.wall_dist_type**           | wall distance for RANS on a terrain-fitted mesh:         | "poisson",         | "poisson"        |
+|                                  | Tucker (2003) Poisson distance, or the height above the  | "terrain_height"   |                  |
+|                                  | local surface projected on its normal (no linear solve)  |                    |                  |
 +----------------------------------+----------------------------------------------------------+--------------------+------------------+
 
 Note: in the equations for the evolution of momentum, potential temperature and advected scalars, the

Docs/sphinx_doc/RegressionTests.rst

@@ -539,6 +539,31 @@ Problem Location: ``Exec/CanonicalTests/DensityCurrent``
 
 .. _`Exec/CanonicalTests/DensityCurrent`: https://github.com/erf-model/ERF/tree/development/Exec/CanonicalTests/DensityCurrent
 
+Canonical RANS
+---------------------------
+Five cases exercise the one-equation :math:`k` RANS closure (see :ref:`RANS`)
+on flat ground (neutral, stable and convective boundary layers) and on
+terrain-fitted meshes (a 2D ridge and a 3D hill), each for 40 steps. Every
+entry then runs the case's Python check script, which reads the plotfile
+with a standard-library AMReX reader, averages or samples the fields, and
+compares numbers against stated targets with tolerances: wall distance
+against the exact distance to the terrain, length scale against its bounds,
+the wall value of :math:`k` against :math:`u_*^2 / (c_\mu^0)^2`, dissipation
+against AL01 Eq. 19, and, in the longer physics runs documented in each
+case's README, the log law, GABLS1 depths and jets, the convective heat
+budget and the hill-top speed-up. The script's exit code is the verdict; a
+clean exit alone never passes a test. The ``_Poisson`` variants run the
+terrain cases with the Poisson wall distance instead of the terrain height.
+
+Test names: ``RANS_Neutral_ABL_Flat``, ``RANS_Stable_ABL_Flat``,
+``RANS_Convective_ABL_Flat``, ``RANS_Neutral_Hill_2D`` (and ``_Poisson``),
+``RANS_Flat_Fitted_2D`` (and ``_Poisson``), ``RANS_Neutral_Hill_3D`` (and
+``_Poisson``); label ``rans``.
+
+Problem Location: `Exec/CanonicalTests/Canonical_RANS`_
+
+.. _`Exec/CanonicalTests/Canonical_RANS`: https://github.com/erf-model/ERF/tree/development/Exec/CanonicalTests/Canonical_RANS
+
 Ekman Spiral
 ---------------------------
 The Ekman spiral problem tests the computation of the stress term internally and at no-slip walls, as well as Coriolis and geostrophic forcing.

Docs/sphinx_doc/index.rst

@@ -60,6 +60,7 @@ In addition to this documentation, there is API documentation for ERF generated
    theory/Buoyancy.rst
    theory/Microphysics.rst
    theory/DNSvsLES.rst
+   theory/RANS.rst
    theory/PBLschemes.rst
    theory/Forcings.rst
    Particles.rst