Water demand and allocation in sbm model concept

build/create_binaries/download_test_data.jl

@@ -51,3 +51,9 @@ instates_sbm_gw_path =
 lake_sh_1_path = testdata(v"0.2.1", "lake_sh_1.csv", "lake_sh_1.csv")
 lake_sh_2_path = testdata(v"0.2.1", "lake_sh_2.csv", "lake_sh_2.csv")
 lake_hq_2_path = testdata(v"0.2.1", "lake_hq_2.csv", "lake_hq_2.csv")
+forcing_calendar_noleap_path =
+    testdata(v"0.2.8", "forcing-calendar-noleap.nc", "forcing-calendar-noleap.nc")
+forcing_piave_path = testdata(v"0.2.9", "inmaps-era5-2010-piave.nc", "forcing-piave.nc")
+staticmaps_piave_path = testdata(v"0.2.9", "staticmaps-piave.nc", "staticmaps-piave.nc")
+instates_piave_path = testdata(v"0.2.9", "instates-piave.nc", "instates-piave.nc")
+instates_piave_gwf_path = testdata(v"0.2.9", "instates-piave-gwf.nc", "instates-piave-gwf.nc")

docs/src/changelog.md

@@ -70,8 +70,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   built-in operators is still allowed. This change in naming convention is now in effect and
   all invalid uses of non-ASCII characters have been replaced by ASCII equivalents.
 - Docs: 1) improved description of different model configurations in model-setup.md, also in
-  relation to hydromt_wflow in docs, 2) citing info related to wflow\_sbm publication in
+  relation to hydromt\_wflow in docs, 2) citing info related to wflow\_sbm publication in
   Geosci. Model Dev. (from in review to published).
+- Root water uptake reduction (Feddes): 1) extend critical pressure head parameters with
+  `h3_low` and `h3_high`, 2) all critical pressure head parameters can be set (values for
+  `h1`, `h2` and `h3` were fixed) and 3) the root water uptake reduction coefficient
+  ``\alpha`` can be set at 0 (default is 1) at critical pressure head `h1` (through the
+  model parameter `alpha_h1`).
+- For the actual transpiration computation in `SBM`, the potential transpiration is
+  partitioned over the soil layers with roots according to the model parameter
+  `rootfraction` (fraction of the total root length in a soil layer). Previously,
+  for each soil layer (from top to bottom) the actual transpiration was computed, and the
+  remaining potential transpiration was used in the next soil layer.
 
 ### Added
 - Total water storage as an export variable for `SBM` concept. This is the total water stored
@@ -84,6 +94,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the following sections: [The SBM soil water accounting scheme](@ref) and [Subsurface flow
   routing](@ref) for a short description.
 - Local inertial routing to `sbm_gwf` model type.
+- Water demand and allocation computations for model types `sbm` and `sbm_gwf`.
 
 ## v0.7.3 - 2024-01-12
 

docs/src/index.md

@@ -6,13 +6,14 @@ CurrentModule = Wflow
 
 Wflow is Deltares' solution for modelling hydrological processes, allowing users to account
 for precipitation, interception, snow accumulation and melt, evapotranspiration, soil water,
-surface water and groundwater recharge in a fully distributed environment. Successfully
-applied worldwide for analyzing flood hazards, drought, climate change impacts and land use
-changes, wflow is growing to be a leader in hydrology solutions. Wflow is conceived as a
-framework, within which multiple distributed model concepts are available, which maximizes
-the use of open earth observation data, making it the hydrological model of choice for data
-scarce environments. Based on gridded topography, soil, land use and climate data, wflow
-calculates all hydrological fluxes at any given grid cell in the model at a given time step.
+surface water, groundwater recharge, and water demand and allocation in a fully distributed
+environment. Successfully applied worldwide for analyzing flood hazards, drought, climate
+change impacts and land use changes, wflow is growing to be a leader in hydrology solutions.
+Wflow is conceived as a framework, within which multiple distributed model concepts are
+available, which maximizes the use of open earth observation data, making it the
+hydrological model of choice for data scarce environments. Based on gridded topography,
+soil, land use and climate data, wflow calculates all hydrological fluxes at any given grid
+cell in the model at a given time step.
 
 Wflow was born out of the creation of Deltares in 2008, when a strategic review identified
 the need for a distributed hydrological model to allow the simulation of flows at the

docs/src/model_docs/lateral/kinwave.md

@@ -54,6 +54,13 @@ External water (supply/abstraction) `inflow` [m``^3`` s``^{-1}``]  can be added
 kinematic wave for surface water routing, as a cyclic parameter or as part of forcing (see
 also [Input section](@ref)).
 
+## Abstractions (internal)
+Abstractions (internal) from the river are possible when water demand and allocation is
+computed through the variable `abstraction` [m``^3`` s``{-1}``], that is set from the water
+demand and allocation module each time step. The `abstraction` is divided by the length of
+the runoff pathway and subtracted from the lateral inflow of the kinematic wave routing
+scheme for river flow.
+
 ## Subsurface flow routing
 In the SBM model the kinematic wave approach is used to route subsurface flow laterally.
 Different vertical hydraulic conductivity depth profiles are possible as part of the

docs/src/model_docs/lateral/local-inertial.md

@@ -146,6 +146,12 @@ External water (supply/abstraction) `inflow` [m``^3`` s``^{-1}``]  can be added
 inertial model for river flow (1D) and river and overland flow combined (1D-2D), as a cyclic
 parameter or as part of forcing (see also [Input section](@ref)).
 
+## Abstractions (internal)
+Abstractions (internal) from the river are possible when water demand and allocation is
+computed through the variable `abstraction` [m``^3`` s``{-1}``], that is set from the water
+demand and allocation module each time step. Abstractions are subtracted as part of the
+continuity equation of the local inertial model.
+
 ## Multi-Threading
 The local inertial model for river flow (1D) and river and overland flow combined (1D-2D)
 can be executed in parallel using multiple threads.

docs/src/model_docs/model_configurations.md

@@ -13,6 +13,14 @@ for the vertical concept SBM of wflow\_sbm:
 - The unsaturated zone can be split-up in different layers
 - The addition of evapotranspiration losses
 - The addition of a capillary rise
+- The addition of [water demand and allocation](@ref sbm_demand_allocation)
+
+The water demand and allocation computations are supported by the wflow\_sbm model
+configurations:
+- [SBM + Kinematic wave](@ref config_sbm)
+- [SBM + Groundwater flow](@ref config_sbm_gwf)
+- [SBM + Local inertial river](@ref config_sbm_gwf_lie_river)
+- [SBM + Local inertial river (1D) and land (2D)](@ref config_sbm_gwf_lie_river_land)
 
 The vertical SBM concept is explained in more detail in the following section [SBM vertical
 concept](@ref vert_sbm).

docs/src/model_docs/params_lateral.md

@@ -22,7 +22,9 @@ internal model parameter `sl`, and is listed in the Table below between parenthe
 | `q_av`          | average discharge | m``^3`` s``^{-1}``| - |
 | `qlat`          | lateral inflow per unit length  | m``^2`` s``^{-1}``| - |
 | `inwater`       | lateral inflow | m``^3`` s``^{-1}``| - |
-| `inflow`        | external inflow (abstraction/supply/demand) | m``^3`` s``^{-1}``| 0.0 |
+| **`inflow`**    | external inflow (abstraction/supply/demand) | m``^3`` s``^{-1}``| 0.0 |
+| `inflow_wb`     | inflow waterbody (lake or reservoir model) from land part | m``^3`` s``^{-1}``| 0.0 |
+| `abstraction`   | abstraction (computed as part of water demand and allocation) | m``^3`` s``^{-1}``| 0.0 |
 | `volume`        | kinematic wave volume |m``^3``| - |
 | `h`             | water level | m | - |
 | `h_av`          | average water level | m | - |
@@ -38,6 +40,7 @@ internal model parameter `sl`, and is listed in the Table below between parenthe
 | `lake_index`   |  map cell to 0 (no lake) or i (pick lake i in lake field) | - | - |
 | `reservoir`    | an array of reservoir models `SimpleReservoir` | - | - |
 | `lake`         | an array of lake models `Lake` | - | - |
+| `waterallocation`| water allocation of type `WaterAllocationRiver` | - | - |
 | `kinwave_it`   | boolean for kinematic wave iterations | - | false |
 
 The Table below shows the parameters (fields) of struct `SurfaceFlowLand` used for overland
@@ -210,6 +213,7 @@ the `layered_exponential` profile `kv` is used and `z_exp` is required as part o
 | `ssfin` | inflow from upstream cells | m``^3`` d``{-1}``  | - |
 | `ssfmax` | maximum subsurface flow | m``^2`` d``{-1}``  | - |
 | `to_river` | part of subsurface flow that flows to the river | m``^3`` d``{-1}``  | - |
+| `volume` | subsurface volume | m``^3`` | - |
 
 ## Local inertial
 
@@ -270,7 +274,8 @@ model parameter `mannings_n`, and is listed in the Table below between parenthes
 | `volume`    | river volume | m``^3`` | - |
 | `error`    | error volume | m``^3`` | - |
 | `inwater`    | lateral inflow | m``^3`` s``^{-1}`` | - |
-| `inflow`        | external inflow (abstraction/supply/demand) | m``^3`` s``^{-1}``| 0.0 |
+| **`inflow`**  | external inflow (abstraction/supply/demand) | m``^3`` s``^{-1}``| 0.0 |
+| `abstraction` | abstraction (computed as part of water demand and allocation) | m``^3`` s``^{-1}``| 0.0 |
 | `inflow_wb`        | inflow waterbody (lake or reservoir model) from land part | m``^3`` s``^{-1}``| 0.0 |
 | `bankfull_volume`    | bankfull volume | m``^3`` | - |
 | **`bankfull_depth`**    | bankfull depth | m | - |
@@ -280,6 +285,7 @@ model parameter `mannings_n`, and is listed in the Table below between parenthes
 | `waterbody`   |  water body cells (reservoir or lake) | - | - |
 | `reservoir`    | an array of reservoir models `SimpleReservoir` | - | - |
 | `lake` | an array of lake models `Lake` | - | - |
+| `waterallocation`| optional water allocation of type `WaterAllocationRiver` | - | - |
 | `floodplain` | optional 1D floodplain routing `FloodPlain` | - | - |
 
 ### [1D floodplain](@id local-inertial_floodplain_params)
@@ -376,6 +382,18 @@ internal model parameter `z`, and is listed in the Table below between parenthes
 | `rivercells`  |  river cells| - | - |
 | `h_av` | average water depth| m | - |
 
+## Water allocation river
+The Table below shows the parameters (fields) of struct `WaterAllocationRiver`, used when
+water demand and allocation is computed (optional), including a description of these
+parameters, the unit, and default value if applicable.
+
+|  parameter  | description  	  | unit  | default |
+|:--------------- | ------------------| ----- | -------- |
+| `act_surfacewater_abst` |  actual surface water abstraction | mm Δt⁻¹ | - |
+| `act_surfacewater_abst_vol`| actual surface water abstraction | m``^3`` Δt⁻¹ | - |
+| `available_surfacewater`| available surface water | m``^3`` | - |
+| `nonirri_returnflow`| return flow from non-irrigation | mm Δt⁻¹ | - |
+
 ## Groundwater flow
 
 ### Confined aquifer

docs/src/model_docs/params_vertical.md

@@ -51,7 +51,7 @@ profile `kv` is used and `z_layered` is required as input.
 | **`f`** | scaling parameter (controls exponential decline of `kv_0`) | mm``^{-1}`` | 0.001  |
 | **`z_exp`** | Depth from soil surface for which exponential decline of `kv_0` is valid | mm | -  |
 | **`z_layered`** | Depth from soil surface for which layered profile (of `layered_exponential`) is valid | mm | -  |
-| **`hb`** | air entry pressure of soil (Brooks-Corey) | cm | 10.0  |
+| **`hb`** | air entry pressure of soil (Brooks-Corey) | cm | -10.0  |
 | **`soilthickness`** | soil thickness | mm | 2000.0  |
 | **`infiltcappath`** | infiltration capacity of the compacted areas  | mm Δt``^{-1}`` | 10.0 mm day``^{-1}`` |
 | **`infiltcapsoil`** | soil infiltration capacity | mm Δt``^{-1}`` | 100.0 mm day``^{-1}``|
@@ -61,6 +61,13 @@ profile `kv` is used and `z_layered` is required as input.
 | **`waterfrac`** | fraction of open water (excluding rivers) | - | 0.0  |
 | **`pathfrac`** | fraction of compacted area | - | 0.01  |
 | **`rootingdepth`** | rooting depth  | mm | 750.0  |
+| **`rootfraction`** | root fraction per soil layer (relative to the total root length) | - | - |
+| **`h1`** | soil water pressure head h1 of the root water uptake reduction function (Feddes) | cm | 0.0 cm |
+| **`h2`** | soil water pressure head h2 of the root water uptake reduction function (Feddes) | cm | -100.0 cm |
+| **`h3_high`** | soil water pressure head h3_high of the root water uptake reduction function (Feddes) | cm | -400.0 cm |
+| **`h3_low`** | soil water pressure head h3_low of the root water uptake reduction function (Feddes) | cm | -1000.0 cm |
+| **`h4`** | soil water pressure head h4 of the root water uptake reduction function (Feddes) | cm | -15849.0 cm |
+| **`alpha_h1`** |  root water uptake reduction at soil water pressure head h1 (0.0 or 1.0) | - | 1.0 |
 | **`rootdistpar`** | controls how roots are linked to water table | - | -500.0  |
 | **`cap_hmax`** | water depth beyond which capillary flux ceases | mm | 2000.0  |
 | **`cap_n`** | coefficient controlling capillary rise | - | 2.0  |
@@ -134,7 +141,12 @@ profile `kv` is used and `z_layered` is required as input.
 | `waterlevel_land` | water level land | mm | - |
 | `waterlevel_river` | water level river | mm | - |
 | `total_storage` | total water storage (excluding floodplains, lakes and reservoirs) | mm | - |
-
+| `paddy` | optional paddy (rice) fields of type `Paddy` (water demand and irrigation) | - | - |
+| `nonpaddy` | optional non-paddy fields of type `NonPaddy` (water demand and irrigation) | - | - |
+| `domestic` | optional domestic water demand of type `NonIrrigationDemand` | - | - |
+| `livestock` | optional livestock water demand of type `NonIrrigationDemand` | - | - |
+| `industry` | optional industry water demand of type `NonIrrigationDemand` | - | - |
+| `waterallocation` | optional water allocation of type `WaterAllocationLand` | - | - |
 
 ## [HBV](@id params_hbv)
 The Table below shows the parameters (fields) of struct `HBV`, including a description of
@@ -378,3 +390,82 @@ specific_leaf = "Sl"
 | `TCsand` | transport capacity of overland flow for particle class sand  | ton Δt``^{-1}`` | - |
 | `TCsagg` | transport capacity of overland flow for particle class small aggregates  | ton Δt``^{-1}`` | - |
 | `TClagg` | transport capacity of overland flow for particle class large aggregates  | ton Δt``^{-1}`` | - |
+
+## Water demand and allocation
+
+### Paddy
+The Table below shows the parameters (fields) of struct `Paddy`, including a description of
+these parameters, the unit, and default value if applicable. The parameters in bold
+represent model parameters that can be set through static and forcing input data (netCDF),
+and can be listed in the TOML configuration file under `[input.vertical.paddy]`, to map the
+internal model parameter to the external netCDF variable.
+
+|  parameter | description    | unit | default |
+|:---------------| --------------- | ---------------------- | ----- |
+| `demand_gross` | irrigation gross demand | mm Δt``^{-1}`` | - |
+| **`irrigation_efficiency`** | irrigation efficiency | - | - |
+| **`maximum_irrigation_depth`** | maximum irrigation depth | mm Δt``^{-1}`` | 25.0 |
+| **`irrigation_areas`** | irrigation areas | - | - |
+| **`irrigation_trigger`** | irrigation on or off | - | - |
+| **`h_min`** | minimum required water depth in the irrigated paddy fields | mm | 20.0 |
+| **`h_opt`** | optimal water depth in the irrigated paddy fields | mm | 50.0 |
+| **`h_max`** | water depth when paddy field starts spilling water (overflow) | mm | 80.0 |
+| `h` | actual water depth in paddy field | mm | - |
+
+### Non-paddy
+The Table below shows the parameters (fields) of struct `NonPaddy`, including a description
+of these parameters, the unit, and default value if applicable. The parameters in bold
+represent model parameters that can be set through static and forcing input data (netCDF),
+and can be listed in the TOML configuration file under `[input.vertical.nonpaddy]`, to map
+the internal model parameter to the external netCDF variable.
+
+|  parameter | description    | unit | default |
+|:---------------| --------------- | ---------------------- | ----- |
+| `demand_gross` | irrigation gross demand | mm Δt``^{-1}`` | - |
+| **`irrigation_efficiency`** | irrigation efficiency | - | - |
+| **`maximum_irrigation_depth`** | maximum irrigation depth | mm Δt``^{-1}`` | 25.0 |
+| **`irrigation_areas`** | irrigation areas | - | - |
+| **`irrigation_trigger`** | irrigation on or off | - | - |
+
+### Non-irrigation (industry, domestic and livestock)
+The Table below shows the parameters (fields) of struct `NonIrrigationDemand`, including a
+description of these parameters, the unit, and default value if applicable. The parameters
+in bold represent model parameters that can be set through static and forcing input data
+(netCDF). These parameters can be listed for the sectors industry, domestic and livestock,
+in the TOML configuration file under `[input.vertical.industry]`,
+`[input.vertical.domestic]` and `[input.vertical.livestock]`, to map the internal model
+parameter to the external netCDF variable.
+
+|  parameter | description    | unit | default |
+|:---------------| --------------- | ---------------------- | ----- |
+| **`demand_gross`** | gross industry water demand | mm Δt``^{-1}`` | 0.0 |
+| **`demand_net`** | net industry water demand | mm Δt``^{-1}`` | 0.0 |
+| `returnflow_fraction` | return flow fraction | - | - |
+| `returnflow` | return flow | mm Δt``^{-1}`` | - |
+
+### Water allocation land
+The Table below shows the parameters (fields) of struct `WaterAllocationLand`, including a
+description of these parameters, the unit, and default value if applicable. The parameters
+in bold represent model parameters that can be set through static and forcing input data
+(netCDF), and can be listed in the TOML configuration file under
+`[input.vertical.waterallocation]`, to map the internal model parameter to the external
+netCDF variable.
+
+|  parameter | description    | unit | default |
+|:---------------| --------------- | ---------------------- | ----- |
+| `irri_demand_gross` | irrigation gross demand | mm Δt``^{-1}`` | - |
+| `nonirri_demand_gross` | non-irrigation gross demand | mm Δt``^{-1}`` | - |
+| `total_gross_demand` | total gross demand | mm Δt``^{-1}`` | - |
+| **`frac_sw_used`** | fraction surface water used | - | 1.0 |
+| **`areas`** | allocation areas | - | 1 |
+| `surfacewater_demand` | demand from surface water | mm Δt``^{-1}`` | - |
+| `surfacewater_alloc` | allocation from surface water | mm Δt``^{-1}`` | - |
+| `act_groundwater_abst` | actual groundwater abstraction | mm Δt``^{-1}`` | - |
+| `act_groundwater_abst_vol` | actual groundwater abstraction | m``^3`` Δt``^{-1}`` | - |
+| `available_groundwater` | available groundwater | m``^3`` | - |
+| `groundwater_demand` | groundwater_demand |mm Δt``^{-1}`` | - |
+| `groundwater_alloc` | allocation from groundwater |mm Δt``^{-1}`` | - |
+| `irri_alloc` | allocated water for irrigation |mm Δt``^{-1}`` | - |
+| `nonirri_alloc` | allocated water for non-irrigation |mm Δt``^{-1}`` | - |
+| `total_alloc` | total allocated water |mm Δt``^{-1}`` | - |
+| `nonirri_returnflow` | return flow from non-irrigation |mm Δt``^{-1}`` | - |