diff --git a/docs/source/inputs/index.rst b/docs/source/inputs/index.rst index 5770f9d6d..4e0ce457e 100644 --- a/docs/source/inputs/index.rst +++ b/docs/source/inputs/index.rst @@ -22,6 +22,7 @@ SUEWS supports two formats for providing input parameters: :maxdepth: 1 :caption: Tools and Utilities + surface-data-preparation converter transition_guide yaml/validation @@ -31,4 +32,3 @@ SUEWS supports two formats for providing input parameters: :caption: Table-based Input Format (Legacy - Deprecated) tables/index - diff --git a/docs/source/inputs/surface-data-preparation.rst b/docs/source/inputs/surface-data-preparation.rst new file mode 100644 index 000000000..ef0256591 --- /dev/null +++ b/docs/source/inputs/surface-data-preparation.rst @@ -0,0 +1,301 @@ +.. _surface_data_preparation: + +Preparing Surface Characteristics Data +====================================== + +This guide explains how to move from a real study area to site-specific SUEWS +surface parameters. It complements the :doc:`/inputs/yaml/index` guide, which +explains configuration structure and validation. + +Use this page when you know *which* parameters are needed, but need practical +advice on where to obtain data and how to derive values. + +Recommended Workflow +-------------------- + +1. Delineate the site footprint used for the SUEWS grid. +2. Compile geospatial layers (land cover, elevation, buildings, vegetation). +3. Derive surface fractions and morphology from the same footprint. +4. Derive seasonal biophysical parameters (albedo, LAI, phenology). +5. Fill the YAML configuration and run ``suews-validate``. +6. Compare against local observations and refine sensitive parameters. + +For broader setup context, see :doc:`/workflow`. + +Land Cover Fractions +-------------------- + +Physical meaning +~~~~~~~~~~~~~~~~ +Fraction of grid area occupied by each of the seven SUEWS surface types. + +YAML configuration path +~~~~~~~~~~~~~~~~~~~~~~~ + +Set one fraction for each surface type: + +- ``sites..properties.land_cover.paved.sfr`` +- ``sites..properties.land_cover.bldgs.sfr`` +- ``sites..properties.land_cover.evetr.sfr`` +- ``sites..properties.land_cover.dectr.sfr`` +- ``sites..properties.land_cover.grass.sfr`` +- ``sites..properties.land_cover.bsoil.sfr`` +- ``sites..properties.land_cover.water.sfr`` + +Fractions should sum to 1.0 (the validator can correct small rounding errors). + +Data sources +~~~~~~~~~~~~ + +- `UMEP`_ (QGIS tools for land cover fractions from raster/vector inputs) +- `CORINE Land Cover`_ (Europe) +- `NLCD`_ (United States) +- `OpenStreetMap`_ (global vector features) + +Derivation method +~~~~~~~~~~~~~~~~~ + +1. Reproject all datasets to a metric CRS. +2. Clip to the SUEWS site footprint. +3. Map source classes to the seven SUEWS surface types. +4. Compute area fractions by class and normalise to 1.0. +5. Check consistency with local imagery. + +Parameter reference +~~~~~~~~~~~~~~~~~~~ + +See :doc:`/inputs/yaml/config-reference/index` for full parameter definitions. + +Albedo +------ + +Physical meaning +~~~~~~~~~~~~~~~~ +Shortwave reflectance controlling net radiation partitioning at the surface. + +YAML configuration path +~~~~~~~~~~~~~~~~~~~~~~~ + +- Non-vegetated surfaces (single albedo): + + - ``sites..properties.land_cover.paved.alb`` + - ``sites..properties.land_cover.bldgs.alb`` + - ``sites..properties.land_cover.bsoil.alb`` + - ``sites..properties.land_cover.water.alb`` + +- Vegetated surfaces (seasonal range): + + - ``sites..properties.land_cover.evetr.alb_min`` and ``alb_max`` + - ``sites..properties.land_cover.dectr.alb_min`` and ``alb_max`` + - ``sites..properties.land_cover.grass.alb_min`` and ``alb_max`` + +Data sources +~~~~~~~~~~~~ + +- `MODIS MCD43A3`_ (broadband albedo) +- `Landsat Collection 2 Surface Reflectance`_ +- Field measurements (radiometers) + +Derivation method +~~~~~~~~~~~~~~~~~ + +1. Extract albedo for the study footprint and quality-filter cloud/snow pixels. +2. Compute representative statistics for the simulation period. +3. Use a single representative ``alb`` for non-vegetated surfaces. +4. Use seasonal low/high values for ``alb_min`` and ``alb_max`` on vegetation. + +Parameter reference +~~~~~~~~~~~~~~~~~~~ + +See :doc:`/inputs/yaml/config-reference/index`. + +Urban Morphology +---------------- + +Physical meaning +~~~~~~~~~~~~~~~~ +Building and vegetation structure controlling roughness, turbulence, and radiation. + +YAML configuration path +~~~~~~~~~~~~~~~~~~~~~~~ + +- ``sites..properties.land_cover.bldgs.bldgh`` +- ``sites..properties.land_cover.bldgs.faibldg`` +- ``sites..properties.land_cover.evetr.evetreeh`` +- ``sites..properties.land_cover.dectr.dectreeh`` + +Data sources +~~~~~~~~~~~~ + +- Airborne or national `LiDAR`_ products +- `OpenStreetMap`_ building footprints/attributes +- `UMEP`_ Morphometric Calculator tools +- `Global Human Settlement Layer (GHSL)`_ products + +Derivation method +~~~~~~~~~~~~~~~~~ + +1. Build a DSM/DTM or equivalent elevation model. +2. Derive mean building height within the site. +3. Estimate frontal area index from geometry and wind-direction context. +4. Derive representative tree heights from canopy products or field surveys. + +Parameter reference +~~~~~~~~~~~~~~~~~~~ + +See :doc:`/inputs/yaml/config-reference/index`. + +Leaf Area Index (LAI) and Phenology +----------------------------------- + +Physical meaning +~~~~~~~~~~~~~~~~ +Seasonal vegetation state controlling transpiration, interception, and radiation. + +YAML configuration path +~~~~~~~~~~~~~~~~~~~~~~~ + +For each vegetated surface (``evetr``, ``dectr``, ``grass``): + +- ``sites..properties.land_cover..lai.laimin`` +- ``sites..properties.land_cover..lai.laimax`` +- ``sites..properties.land_cover..lai.gddfull`` +- ``sites..properties.land_cover..lai.sddfull`` + +Data sources +~~~~~~~~~~~~ + +- `MODIS LAI`_ products +- `Copernicus LAI`_ products +- Field LAI measurements (e.g., LAI-2200, hemispherical photography) + +Derivation method +~~~~~~~~~~~~~~~~~ + +1. Extract multi-year seasonal LAI trajectories for the footprint. +2. Set ``laimin`` from dormant-season values and ``laimax`` from peak values. +3. Estimate phenology thresholds (``gddfull``, ``sddfull``) from local climate + and observed green-up/senescence timing. +4. Check that values are physically consistent for local vegetation types. + +Parameter reference +~~~~~~~~~~~~~~~~~~~ + +See :doc:`/inputs/yaml/config-reference/index`. + +OHM Coefficients +---------------- + +Physical meaning +~~~~~~~~~~~~~~~~ +Coefficients ``a1``, ``a2``, and ``a3`` for storage heat flux parameterisation. + +YAML configuration path +~~~~~~~~~~~~~~~~~~~~~~~ + +For each surface, coefficients are set by season and wetness state, for example: + +- ``sites..properties.land_cover..ohm_coef.summer_wet.a1`` +- ``sites..properties.land_cover..ohm_coef.summer_wet.a2`` +- ``sites..properties.land_cover..ohm_coef.summer_wet.a3`` + +The same pattern applies for ``summer_dry``, ``winter_wet``, and ``winter_dry``. + +Data sources +~~~~~~~~~~~~ + +- Site-specific flux and radiation measurements (if available) +- Published coefficient sets in the SUEWS documentation/literature + +Derivation method +~~~~~~~~~~~~~~~~~ + +If you have suitable observations, derive coefficients using +``supy.util.derive_ohm_coef()`` as shown in +:doc:`/inputs/tables/SUEWS_SiteInfo/SUEWS_OHMCoefficients`. + +If you do not have local flux data, start from literature/default sets and +prioritise sensitivity testing before introducing custom coefficients. + +Parameter reference +~~~~~~~~~~~~~~~~~~~ + +See :doc:`/inputs/yaml/config-reference/index` and +:doc:`/inputs/tables/SUEWS_SiteInfo/SUEWS_OHMCoefficients`. + +Surface Conductance +------------------- + +Physical meaning +~~~~~~~~~~~~~~~~ +Parameters controlling potential and realised stomatal/surface conductance. + +YAML configuration path +~~~~~~~~~~~~~~~~~~~~~~~ + +- Site-level conductance parameter: + + - ``sites..properties.conductance.g_max`` + +- Vegetation surface conductance limits: + + - ``sites..properties.land_cover.evetr.maxconductance`` + - ``sites..properties.land_cover.dectr.maxconductance`` + - ``sites..properties.land_cover.grass.maxconductance`` + +Data sources +~~~~~~~~~~~~ + +- Eddy covariance inversions +- Leaf- or canopy-level gas exchange observations +- Published parameter sets for similar vegetation and climate regimes + +Derivation method +~~~~~~~~~~~~~~~~~ + +Direct local estimation is data-intensive. In most applications, begin with +published values for similar sites, then calibrate within physically realistic +ranges against local fluxes where available. + +Parameter reference +~~~~~~~~~~~~~~~~~~~ + +See :doc:`/inputs/yaml/config-reference/index`. + +SUEWS-database (Under Development) +---------------------------------- + +A dedicated repository for curated SUEWS surface parameter datasets is under +active development: + +- `UMEP-dev/SUEWS-database`_ + +Use it as a starting point where relevant, but still verify representativeness +for your site and period. + +References and Tools +-------------------- + +The following resources are commonly used when preparing SUEWS surface data: + +- `UMEP`_ (QGIS pre-processing tools) +- `CORINE Land Cover`_ +- `NLCD`_ +- `OpenStreetMap`_ +- `MODIS MCD43A3`_ (albedo) +- `MODIS LAI`_ and `Copernicus LAI`_ +- `Landsat Collection 2 Surface Reflectance`_ +- `Global Human Settlement Layer (GHSL)`_ +- `UMEP-dev/SUEWS-database`_ + +.. _UMEP: https://umep-docs.readthedocs.io/en/latest/ +.. _CORINE Land Cover: https://land.copernicus.eu/en/products/corine-land-cover +.. _NLCD: https://www.usgs.gov/centers/eros/science/national-land-cover-database +.. _OpenStreetMap: https://www.openstreetmap.org/ +.. _MODIS MCD43A3: https://lpdaac.usgs.gov/products/mcd43a3v061/ +.. _MODIS LAI: https://lpdaac.usgs.gov/products/mcd15a3hv061/ +.. _Copernicus LAI: https://land.copernicus.eu/global/products/lai +.. _Landsat Collection 2 Surface Reflectance: https://www.usgs.gov/landsat-missions/landsat-collection-2-surface-reflectance +.. _LiDAR: https://www.usgs.gov/programs/3d-elevation-program +.. _Global Human Settlement Layer (GHSL): https://ghsl.jrc.ec.europa.eu/ +.. _UMEP-dev/SUEWS-database: https://github.com/UMEP-dev/SUEWS-database diff --git a/docs/source/inputs/tables/SUEWS_SiteInfo/Typical_Values.rst b/docs/source/inputs/tables/SUEWS_SiteInfo/Typical_Values.rst index 8a554a6c3..9917d0291 100644 --- a/docs/source/inputs/tables/SUEWS_SiteInfo/Typical_Values.rst +++ b/docs/source/inputs/tables/SUEWS_SiteInfo/Typical_Values.rst @@ -5,6 +5,11 @@ Typical Values ############## +.. note:: + + For guidance on deriving site-specific values from real-world data sources, + see :doc:`/inputs/surface-data-preparation`. + Other values to add - please let us know Generic Properties @@ -32,4 +37,3 @@ Storage Heat Flux Related :header-rows: 1 :stub-columns: 1 - diff --git a/docs/source/tutorials/tutorial_02_setup_own_site.py b/docs/source/tutorials/tutorial_02_setup_own_site.py index 32ad70ca3..a89bdcc89 100644 --- a/docs/source/tutorials/tutorial_02_setup_own_site.py +++ b/docs/source/tutorials/tutorial_02_setup_own_site.py @@ -18,6 +18,11 @@ **API approach**: This tutorial uses the :class:`~supy.SUEWSSimulation` OOP interface with :meth:`~supy.SUEWSSimulation.update_config` for parameter modification. This approach provides a clean separation between configuration and execution. + +.. seealso:: + + For guidance on sourcing and deriving site parameters from real-world data, + see :doc:`/inputs/surface-data-preparation`. """ from pathlib import Path diff --git a/docs/source/workflow.rst b/docs/source/workflow.rst index 027e079fc..3140e983a 100644 --- a/docs/source/workflow.rst +++ b/docs/source/workflow.rst @@ -362,6 +362,9 @@ Data Requirements and Quality **Data Sources**: Use the `UMEP`_ plugin for QGIS to derive land cover fractions from satellite imagery or local spatial datasets. +For detailed guidance on obtaining and preparing surface characteristics data, +see :doc:`/inputs/surface-data-preparation`. + Part III: Advanced Applications and Research --------------------------------------------- @@ -646,4 +649,4 @@ See `Recent Publications `__ for the latest research using The SUEWS community regularly organises training workshops and webinars. Check the mailing list for announcements of upcoming events. -.. _`UMEP`: http://umep-docs.readthedocs.io/en/latest/index.html \ No newline at end of file +.. _`UMEP`: http://umep-docs.readthedocs.io/en/latest/index.html