From 9de8f9275e8d491fb4e010eb2db738df7833c746 Mon Sep 17 00:00:00 2001 From: Ting Sun Date: Mon, 1 Dec 2025 12:47:42 +0000 Subject: [PATCH] docs: clarify forcing height requirements and inertial sublayer (#953) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update forcing-data.rst introduction to specify that meteorological data should be within the inertial sublayer (blended response above roughness elements) - Add new "Forcing Height" section explaining the urban boundary layer structure (UCL, RSL, ISL) and why forcing height matters - Include YAML configuration example for setting the z parameter - Improve z parameter description in site.py data model to explain the inertial sublayer requirement Closes #953 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/source/inputs/forcing-data.rst | 27 ++++++++++++++++++++++++++- src/supy/data_model/core/site.py | 2 +- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/source/inputs/forcing-data.rst b/docs/source/inputs/forcing-data.rst index 6d8148f1b..a0880f016 100644 --- a/docs/source/inputs/forcing-data.rst +++ b/docs/source/inputs/forcing-data.rst @@ -3,7 +3,32 @@ Meteorological Forcing Data ============================ -SUEWS requires continuous meteorological data to drive the urban energy and water balance calculations. This page describes the format and requirements for forcing data files. +SUEWS requires continuous meteorological data representative of the neighbourhood scale, within the inertial sublayer (i.e. a blended response above the roughness elements of buildings and trees), to drive the urban energy and water balance calculations. This page describes the format and requirements for forcing data files. + +.. important:: **Forcing Height** + + Forcing data must represent the urban neighbourhood as a whole, not individual buildings or trees. This requires measurements from within the inertial sublayer, where turbulent mixing produces spatially blended values. The forcing height (``z``) tells SUEWS where your data originate, enabling correct profile calculations between this reference level and the surface. In urban environments, the atmospheric boundary layer is divided into: + + - **Urban Canopy Layer (UCL)**: Within the urban canopy, among buildings and trees + - **Roughness Sublayer (RSL)**: Extends from the surface to approximately 2-5 times the mean building/tree height; flow is spatially heterogeneous + - **Inertial Sublayer (ISL)**: Above the RSL, where Monin-Obukhov Similarity Theory applies and fluxes are approximately constant with height + + **Guidance for choosing z:** + + - For in-situ measurements: use the actual measurement height (typically flux tower height) + - For reanalysis data (e.g., ERA5): check the reference height of the dataset + - For nested model output: use the height of the lowest model level above the surface + + Set the forcing height in your YAML configuration: + + .. code-block:: yaml + + sites: + - name: "MySite" + properties: + z: 50.0 # Forcing height in metres + + See :yaml:option:`z` for full documentation, and :ref:`rsl_mod` in :doc:`/parameterisations-and-sub-models` for details on profile calculations. Data Requirements ----------------- diff --git a/src/supy/data_model/core/site.py b/src/supy/data_model/core/site.py index 764c64b44..d481cc77d 100644 --- a/src/supy/data_model/core/site.py +++ b/src/supy/data_model/core/site.py @@ -2450,7 +2450,7 @@ class SiteProperties(BaseModel): ) z: FlexibleRefValue(float) = Field( gt=0, - description="Forcing height", + description="Height at which forcing data are specified, should be within the inertial sublayer above the blending height where values are spatially representative of the urban neighbourhood", json_schema_extra={ "unit": "m", "display_name": "Forcing height",