HydPy-WHMod-Urban (WHMod for urban regions)

whmod_urban is an extension of whmod_rural that considers water management measures relevant to urban areas. Its key additional feature is its ability to collect excess water from selected sealed (surface runoff) and not sealed areas (percolation) in cisterns and to use it for irrigation. We designed whmod_urban originally to develop and analyse Sponge City concepts for Munich, Germany.

Integration tests

The following test settings are identical to those of whmod_rural:

Note

When new to HydPy, consider reading section Integration Tests first.

>>> from hydpy import Element, pub, Timegrid
>>> pub.timegrids = "2017-02-10", "2017-04-10", "1d"

>>> element = Element("element")
>>> from hydpy.models.whmod_urban import *
>>> parameterstep("1d")
>>> element.model = model

>>> area(10.0)
>>> nmbzones(1)
>>> zonearea(10.0)
>>> landtype(GRASS)
>>> soiltype(SAND)
>>> interceptioncapacity.grass_feb = 0.4
>>> interceptioncapacity.grass_mar = 0.6
>>> interceptioncapacity.grass_apr = 0.8
>>> degreedayfactor(grass=4.5)
>>> availablefieldcapacity(sand=0.2)
>>> rootingdepth(0.5)
>>> groundwaterdepth(1.0)
>>> withcapillaryrise(True)
>>> capillarythreshold(0.8)
>>> capillarylimit(0.4)
>>> withexternalirrigation(False)
>>> irrigationtrigger(0.6)
>>> irrigationtarget(0.7)
>>> baseflowindex(0.8)
>>> rechargedelay(5.0)

>>> with model.add_aetmodel_v1("evap_aet_minhas") as aetmodel:
...     dissefactor(grass=4.0, deciduous=6.0, corn=3.0, conifer=6.0, springwheat=6.0,
...                 winterwheat=6.0)
...     with model.add_petmodel_v1("evap_pet_mlc") as petmodel:
...         landmonthfactor.grass = 1.0
...         dampingfactor(1.0)
...         with model.add_retmodel_v1("evap_ret_io") as retmodel:
...             evapotranspirationfactor(1.0)

>>> from hydpy import IntegrationTest
>>> IntegrationTest.plotting_options.axis1 = (
...     inputs.precipitation, fluxes.totalevapotranspiration
... )
>>> IntegrationTest.plotting_options.axis2 = (
...     fluxes.cisterninflow,
...     fluxes.cisternoverflow,
...     fluxes.cisterndemand,
...     fluxes.cisternextraction
... )
>>> test = IntegrationTest(element)
>>> test.dateformat = "%Y-%m-%d"

>>> test.inits = (
...     (states.interceptedwater, 0.0),
...     (states.snowpack, 0.0),
...     (states.soilmoisture, 0.0),
...     (states.deepwater, 0.0),
...     (petmodel.sequences.logs.loggedpotentialevapotranspiration, 0.0),
... )

>>> inputs.temperature.series = (
...     -2.8, -1.5, -0.9, -1.6, -1.3, 1.7, 4.4, 4.5, 3.4, 4.8, 6.7, 5.8, 6.5, 5.0, 3.0,
...     3.1, 7.1, 9.4, 4.6, 3.7, 4.7, 5.9, 7.7, 6.3, 3.7, 1.6, 4.0, 5.6, 5.8, 5.7, 4.6,
...     4.2, 7.4, 6.3, 8.7, 6.4, 5.2, 5.1, 8.7, 6.2, 5.9, 5.2, 5.2, 5.9, 6.7, 7.0, 8.3,
...     9.0, 12.4, 15.0, 11.8, 9.4, 8.1, 7.9, 7.5, 7.2, 8.1, 8.6, 10.5)
>>> inputs.precipitation.series = (
...     0.0, 0.4, 0.0, 0.0, 0.0, 0.0, 0.2, 4.5, 0.0, 3.2, 4.6, 2.3, 18.0, 19.2, 0.4,
...     8.3, 5.3, 0.7, 2.7, 1.6, 2.5, 0.6, 0.2, 1.7, 0.3, 0.0, 1.8, 8.9, 0.0, 0.0,
...     0.0, 0.9, 0.1, 0.0, 0.0, 3.9, 8.7, 26.4, 11.5, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0,
...     0.0, 0.0, 1.5, 0.3, 0.2, 4.5, 0.0, 0.0, 0.0, 0.4, 0.0, 0.0, 0.0, 0.0)
>>> retmodel.sequences.inputs.referenceevapotranspiration.series = (
...     0.6, 0.8, 0.7, 0.4, 0.4, 0.4, 0.4, 0.3, 0.3, 0.4, 0.3, 0.6, 0.8, 0.5, 0.8,
...     0.5, 0.4, 1.3, 0.9, 0.7, 0.7, 1.1, 1.0, 0.8, 0.6, 0.7, 0.7, 0.5, 0.8, 1.0,
...     1.2, 0.9, 0.9, 1.2, 1.4, 1.1, 1.1, 0.5, 0.6, 1.5, 2.0, 1.6, 1.6, 1.2, 1.3,
...     1.6, 1.9, 0.8, 1.5, 2.7, 1.5, 1.6, 2.0, 2.1, 1.7, 1.7, 0.8, 1.3, 2.5)

grassland

We first repeat the grassland example of whmod_rural.

The cistern has a capacity of 0.1 m³:

>>> cisterncapacity(0.1)

We set the boolean CisternSource parameter for the single considered zone to False so that the cistern cannot receive any inflow:

>>> cisternsource(False)

We also set the cistern’s initial water content to zero:

>>> test.inits.cisternwater = 0.0

Due to the effectively “turned off” cistern, the following results are identical to the grassland example of whmod_rural:

>>> conditions = test("whmod_urban_grassland", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> from hydpy import round_
>>> round_(model.check_waterbalance(conditions))
0.0

external irrigation

External irrigation works as discussed in the irrigation example of whmod_rural:

>>> withexternalirrigation(True)
>>> conditions = test("whmod_urban_external_irrigation", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> from hydpy import round_
>>> round_(model.check_waterbalance(conditions))
0.0

internal irrigation

We turn off external irrigation but activate internal irrigation by setting the boolean CisternSource parameter for the single grassland zone to True:

>>> withexternalirrigation(False)
>>> cisternsource(True)

In contrast to external irrigation, internal irrigation is limited to the water collected in the cistern. As the cistern is initially empty and can only receive water from the dry grassland zone, which is also initially dry, it cannot irrigate the same zone substantially:

>>> conditions = test("whmod_urban_internal_irrigation", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> from hydpy import round_
>>> round_(model.check_waterbalance(conditions))
0.0

combined irrigation

In this example, we turn on external irrigation and fill the cistern to show how both types of irrigation interact:

>>> withexternalirrigation(True)
>>> test.inits.cisternwater = 0.1

whmod_urban first takes as much irrigation water from the cistern as required or available and then uses the (unlimited) external source to satisfy the remaining demand:

>>> conditions = test("whmod_urban_combined_irrigation", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> from hydpy import round_
>>> round_(model.check_waterbalance(conditions))
0.0

water

Water areas do neither fill nor empty the cistern. We show this by setting the cistern’s initial water content to 0.05 m³, half its previously set capacity:

>>> landtype(WATER)
>>> soiltype(NONE)
>>> withexternalirrigation(False)
>>> test.inits.cisternwater = 0.05

The other settings are stem from the water example of whmod_rural. The cistern’s water content remains constant. Otherwise, the results are identical to those of the original example:

>>> landmonthfactor = petmodel.parameters.control.landmonthfactor
>>> landmonthfactor.water_feb = 1.217
>>> landmonthfactor.water_mar = 1.256
>>> landmonthfactor.water_apr = 1.283
>>> conditions = test("whmod_urban_water", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0

unused surface runoff

Zones with sealed surfaces are either connected or unconnected to the cistern. We first demonstrate the case of an unconnected zone:

>>> landtype(SEALED)
>>> cisternsource(False)

As typical for whmod_rural and demonstrated in the sealed example, all surface runoff leaves the considered system and is lost for irrigation:

>>> interceptioncapacity.sealed = 2.0
>>> landmonthfactor.sealed = 1.0
>>> conditions = test("whmod_urban_unused_surface_runoff", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0

collected surface runoff

However, connected sealed zones route all their surface runoff into the cistern, which means their complete precipitation input, besides interception evaporation losses, becomes available for irrigation:

>>> cisternsource(True)
>>> conditions = test("whmod_urban_collected_surface_runoff", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0

multiple zones

This example modifies the multiple zones example of whmod_rural by connecting the first (grassland) and last zone (sealed surface) to the cistern:

>>> name2value = {par.name: par.value for par in control}
>>> nmbzones(4)
>>> landtype(GRASS, CONIFER, WATER, SEALED)
>>> soiltype(SAND, SAND, NONE, NONE)
>>> cisternsource(True, False, False, True)
>>> zonearea(2.5)
>>> interceptioncapacity.conifer = 2.0
>>> landmonthfactor.conifer = 1.335

>>> for name, value in name2value.items():
...     if name not in ("nmbzones", "landtype", "soiltype", "cisternsource", "zonearea", "interceptioncapacity"):
...         control[name].value = value
>>> model.update_parameters()
>>> aetmodel.parameters.control.dissefactor(4.0)
>>> petmodel.parameters.control.dampingfactor(1.0)
>>> retmodel.parameters.control.evapotranspirationfactor(1.0)

The second zone (conifer forest) benefits from irrigation by a faster soil moisture increase. In contrast, the first zone’s soil water content increases slightly slower than in the original example. This behaviour is due to the assumption of an impermeable layer, which not only drains percolated water into the cistern but also prevents any capillary rise:

>>> conditions = test("whmod_urban_multiple_zones", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0

snow

All snow processes are modelled exactly as by whmod_rural and described in the snow example:

>>> cisternsource(False)
>>> test.inits.cisternwater = 0.0
>>> inputs.temperature.series -= 8.0
>>> conditions = test("whmod_urban_snow", get_conditions="2017-02-10")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0
class hydpy.models.whmod_urban.Model[source]

Bases: Main_AETModel_V1, Sub_TempModel_V1, Sub_PrecipModel_V1, Sub_IntercModel_V1, Sub_SoilWaterModel_V1, Sub_SnowCoverModel_V1

HydPy-WHMod-Urban (WHMod for urban regions).

The following “run methods” are called in the given sequence during each simulation step:
The following interface methods are available to main models using the defined model as a submodel:
The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:
Users can hook submodels into the defined main model if they satisfy one of the following interfaces:

  • AETModel_V1 Interface for calculating interception evaporation, evapotranspiration from soils, evaporation from water areas in separate steps.

DOCNAME: DocName = ('WHMod-Urban', 'WHMod for urban regions')
aetmodel: SubmodelProperty

Required submodel that complies with the following interface: AETModel_V1.

check_waterbalance(initial_conditions: dict[str, dict[str, dict[str, float | ndarray[tuple[int, ...], dtype[float64]]]]]) → float[source]

Determine the water balance error of the previous simulation run in mm.

Method check_waterbalance() calculates the balance error as follows:

\[\begin{split}Error = \Sigma In - \Sigma Out - \Delta Vol \\ \\ \Sigma In = \sum_{t=t_0}^{t_1} \left( P_t + \sum_{k=1}^{N} Z^k \cdot E_t^k \right) \\ \Sigma Out = \sum_{t=t_0}^{t_1} \left( T_t + O_t / A + \sum_{k=1}^{N} Z^k \cdot \left( B_t^k + R_t^k + \begin{cases} S_t^k &|\ \overline{C} \\ 0 &|\ C \end{cases} \right) \right) \\ \Delta Vol = f_{\Delta}\big(D\big) + f_{\Delta}\big(W\big) / A + \sum_{k=1}^{N} Z^k \cdot \Big( f_{\Delta} \big( I^k \big) + f_{\Delta} \big( P^k \big) + f_{\Delta} \big( M^k \big) \Big) \\ \\ f_{\Delta}(x) = x_{t1} - x_{t0} \\ \\ A = Area \cdot 1000\\ N = NmbZones \\ Z = ZoneRatio \\ C = CisternSource \\ P = Precipitation \\ T = TotalEvapotranspiration \\ S = SurfaceRunoff \\ O = CisternOverflow \\ B = Baseflow \\ R = DelayedRecharge \\ I = InterceptedWater \\ P = Snowpack \\ M = SoilMoisture \\ W = CisternWater \\ D = DeepWater\end{split}\]

The returned error should always be in scale with numerical precision so that it does not affect the simulation results in any relevant manner.

Pick the required initial conditions before starting the simulation run via property conditions. See the integration tests of the application model whmod_urban for some examples.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
cymodel: CyModelProtocol | None
parameters: parametertools.Parameters
sequences: sequencetools.Sequences
masks: masktools.Masks
class hydpy.models.whmod_urban.Masks[source]

Bases: Masks

Masks applicable to whmod_urban.

The following classes are selected:
class hydpy.models.whmod_urban.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Control parameters of model whmod_urban.

The following classes are selected:
class hydpy.models.whmod_urban.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model whmod_urban.

The following classes are selected:
class hydpy.models.whmod_urban.FactorSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FactorSequences

Factor sequences of model whmod_urban.

The following classes are selected:
class hydpy.models.whmod_urban.FluxSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model whmod_urban.

The following classes are selected:
class hydpy.models.whmod_urban.InputSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: InputSequences

Input sequences of model whmod_urban.

The following classes are selected:
class hydpy.models.whmod_urban.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: StateSequences

State sequences of model whmod_urban.

The following classes are selected: