{ "cells": [ { "cell_type": "markdown", "id": "bp-0001", "metadata": {}, "source": [ "# Best Practices and Pitfalls\n", "\n", "*Last updated: June 2026*\n", "\n", "This page collects known limitations, non-obvious configuration requirements, and\n", "recommendations gathered from experience with JAX-ALFA simulations. Read through\n", "these before setting up a new case — each item documents a real pitfall that is\n", "easy to overlook." ] }, { "cell_type": "markdown", "id": "bp-0002", "metadata": {}, "source": [ "---\n", "## 1. Surface Flux as Lower Boundary Condition for Stable Boundary Layers" ] }, { "cell_type": "raw", "id": "bp-0003", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ ".. warning::\n", "\n", " Do not use a prescribed surface heat flux as the lower thermal boundary condition\n", " for **stable** boundary layer simulations. Use a prescribed surface temperature\n", " (``optSurfBC = 2``) instead." ] }, { "cell_type": "markdown", "id": "bp-0004", "metadata": {}, "source": "The surface sensible heat flux (SHFX) exhibits a **dual nature** in stably stratified conditions: a single value of SHFX can correspond to two distinct stability states: weakly stable and very stable regimes. This fundamental property was first identified by Malhi (1995) and later elaborated by Basu et al. (2008).\n\nWhen SHFX is prescribed as the lower boundary condition, a PBL model (single-column or LES) can **only access the weakly stable solution**. The very stable regime — where turbulence is strongly suppressed — remains inaccessible under a flux prescription. To simulate both weakly stable and very stable conditions faithfully, the **surface temperature** must be prescribed instead.\n\nSet ``optSurfBC = 2`` in ``Config.py`` and ensure ``SurfaceBCFile`` points to a valid surface boundary condition file. This is also the approach adopted in all GABLS intercomparison studies.\n\n```python\noptSurfBC = 2\nSurfaceBCFile = 'input/SurfaceBC.npz' # generate with CreateSurfaceBC_*.py before running\n```\n\n**References:**\n\nMalhi, Y. S. (1995). The significance of the dual solutions for heat fluxes measured by the temperature fluctuations method in stable conditions. *Boundary-Layer Meteorology*, 74, 389–396.\n\nBasu, S., Holtslag, A. A. M., Van De Wiel, B. J. H., Moene, A. F., and Steeneveld, G.-J. (2008). An inconvenient \"truth\" about using sensible heat flux as a surface boundary condition in models under stably stratified regimes. *Acta Geophysica*, 56(1), 88–99. https://doi.org/10.2478/s11600-007-0038-y" }, { "cell_type": "markdown", "id": "bp-0005", "metadata": {}, "source": [ "---\n", "## 2. First Half-Model Level Height for High-Resolution Simulations" ] }, { "cell_type": "raw", "id": "bp-0006", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": ".. warning::\n\n For high-resolution simulations, ensure the height of the first half-model level\n satisfies :math:`z_1 > 50\\,z_{0m}`, where :math:`z_{0m}` is the aerodynamic roughness\n length. Violating this constraint invalidates the Monin–Obukhov similarity\n theory (MOST) boundary condition and corrupts the surface flux computation." }, { "cell_type": "markdown", "id": "bp-0007", "metadata": {}, "source": "### Physical basis\n\nMOST-based boundary conditions are valid only within the **inertial sublayer** (ISL), whose lower limit coincides with the top of the roughness sublayer (RSL) at height $z_* = 50 z_{0m}$. A number of recent high-resolution LES studies have placed $z_1$ **below** this limit and incorrectly invoked MOST, resulting in erroneous surface fluxes and artificial resolution sensitivity.\n\n### Practical check\n\nThe first half-model level sits at $z_1 = \\Delta z / 2$. In JAX-ALFA, verify the constraint before running:\n\n```python\nz1 = 0.5 * l_z / (nz - 1) # height of first half-model level (m)\nassert z1 > 50 * z0m, f\"z1={z1:.3f} m is not > 50*z0m={50*z0m:.3f} m\"\n```\n\nIf ``z0m`` and ``z0T`` differ, the momentum constraint ($z_1 > 50\\,z_{0m}$) is the binding one, but verify both for consistency.\n\nFor the GABLS1 case ($z_{0m} = 0.1$ m) this means $\\Delta z > 10$ m and $z_1 > 5$ m, which limits how far the grid can be refined before MOST breaks down.\n\n### Temporary workaround\n\nReduce ``z0m`` and ``z0T`` consistently in ``Config.py`` to restore the $z_1 > 50\\,z_{0m}$ constraint without changing the grid resolution. This is a **numerical fix, not a physical one** — document clearly that the roughness lengths no longer reflect the true surface.\n\n### Permanent solution\n\nAdopt a **roughness sublayer (RSL) parameterization** that replaces MOST at heights $z_1 < z_*$. Several formulations exist (e.g., Physick and Garratt 1995; Arnqvist and Bergström 2015), and their incorporation into LES codes is straightforward. RSL models are currently under development for JAX-ALFA.\n\n**Reference:**\nBasu, S., and Lacser, A. (2017). A cautionary note on the use of Monin–Obukhov similarity theory in very high-resolution large-eddy simulations. *Boundary-Layer Meteorology*, 163, 197–207.\nhttps://doi.org/10.1007/s10546-016-0225-y" }, { "cell_type": "markdown", "id": "bp-0008", "metadata": {}, "source": [ "---\n", "## 3. Filter-to-Grid Ratio (FGR) for LASDD-SM in Stable Boundary Layers" ] }, { "cell_type": "raw", "id": "bp-0009", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ ".. warning::\n", "\n", " When using the LASDD-SM SGS model (``optSgs = 1``) for stable boundary layer\n", " simulations, always set ``FGR = 2``. Using ``FGR = 1`` makes the model\n", " under-dissipative and can produce unreliable results." ] }, { "cell_type": "markdown", "id": "bp-0010", "metadata": {}, "source": "Set ``FGR = 2`` in ``Config.py``. This is the value used in the original LASDD-SM\npaper (Basu and Porté-Agel 2006), and it is required for LASDD-SM stable BL simulations.\n\n```python\nFGR = 2\n```\n\nWhen ``FGR = 2``, JAX-ALFA skips the 3/2-rule zero-padding step, making the\nsimulation slightly faster.\n\n**Reference:**\n\nBasu, S., and Porté-Agel, F. (2006). Large-eddy simulation of stably stratified\natmospheric boundary layer turbulence: A scale-dependent dynamic modeling approach.\n*Journal of the Atmospheric Sciences*, 63(8), 2074–2091.\nhttps://doi.org/10.1175/JAS3734.1" }, { "cell_type": "markdown", "id": "bp-0011", "metadata": {}, "source": [ "---\n", "## 4. Inapplicability of MOST for Free Convective Boundary Layers" ] }, { "cell_type": "raw", "id": "bp-0012", "metadata": {}, "source": [ ".. warning::\n", "\n", " For free convective simulations (zero geostrophic wind), do **not** use\n", " the homogeneous surface flux option (``optSurfFlux = 0``). Set\n", " ``optSurfFlux = 1`` (heterogeneous) instead." ] }, { "cell_type": "markdown", "id": "bp-0013", "metadata": {}, "source": [ "In free convection, the domain-averaged horizontal wind speed is essentially zero.\n", "Monin–Obukhov similarity theory (MOST) relates the surface momentum and scalar fluxes\n", "to the **mean** wind speed; when that mean vanishes, the friction velocity $u_*$ computed\n", "from the planar average goes to zero, and MOST becomes singular or severely inaccurate.\n", "\n", "The remedy is to apply MOST **locally** at each horizontal grid point, where\n", "instantaneous wind speeds remain non-zero even when the planar average is not.\n", "In JAX-ALFA this is controlled by ``optSurfFlux``:\n", "\n", "```python\n", "optSurfFlux = 0 # homogeneous — planar-averaged wind; breaks down in free convection\n", "optSurfFlux = 1 # heterogeneous — local wind at each (x, y) point; correct for free convection\n", "```\n", "\n", "The CBL_N91 benchmark uses ``optSurfFlux = 1`` for exactly this reason.\n", "All simulations with $U_g = V_g = 0$ (or near-zero geostrophic wind) should do the same." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "version": "3.8.0" } }, "nbformat": 4, "nbformat_minor": 5 }