HydPy-W-Wag (extended version of the original Wageningen WALRUS model)

wland_wag is a slightly modified and extended version of the WALRUS model, specifically designed to simulate surface water fluxes in lowland catchments influenced by near-surface groundwater (Brauer et al., 2014). We implemented wland_wag on behalf of the German Federal Institute of Hydrology (BfG) in the context of optimising the control of the Kiel Canal (Nord-Ostsee-Kanal).

With identical parameter values, WALRUS and wland_wag yield very similar results for the tutorial data available within the WALRUS repository. We found that all of the relatively small discrepancies were due to using different numerical integration algorithms, not differences in the underlying differential equations (we discuss the only exception to this in the documentation on method Calc_CDG_V1). However, to keep our extensions consistent, we found it necessary to adjust a few variable names and some unit conversions related to the size of some subareas.

Most of our extensions focus on the hydrological processes that apply before precipitation reaches the vadose zone:

  1. We add some factors to correct or adapt the meteorological input data.

  2. We introduce simple storages for intercepted water and snow, implemented similarly as in lland_dd.

  3. We support the specification of hydrological response units for these processes, making wland_wag a semi-distributed model (but we model the vadose zone in agreement with WALRUS still in a lumped manner).

  4. We define the land-use type SEALED, which has no vadose zone and directly routes all water reaching the soil surface into the quickflow reservoir.

  5. We allow specifying subbasins consisting of surface water areas or combinations of surface water and sealed areas only, not possessing any to “vadose zone area” (however, we do not allow specifying subbasins without any surface water area).

Another notable extension is the ability for a “bidirectional” coupling with models like dam_pump or sw1d_storage, which conceptionally makes models share the same surface water storage for the sake of modelling backwater effects. This functionality allows, for example, to estimate the effect of an increase in the target water level at a pumping station on evapotranspiration due to decreased drainage of agricultural areas or even to reversed flow from the adjacent channels to the shallow groundwater (influent flow conditions).

Last but not least, wland_wag allows the inclusion of so-called “elevated regions”. The original WALRUS model focuses on extremely flat areas like those frequently encountered in the Netherlands and hence does not consider any topographic influences. We realised this model concept strictness to be a limitation when applying it to areas where highly flat lowlands neighbour mildly elevated terrain, which is typical for the northern, coastal parts of Germany (Marsch and Geest). Hence, we added the possibility to define some hydrological response units as “elevated”. Here, the terrain is so high that the groundwater level is too deep for the bidirectional interactions between soil water and groundwater typical for lowlands. Hence, elevated regions are pure groundwater source areas that route their deep groundwater to the shallow groundwater of the lowland regions,where groundwater depletion can prevail. Therefore, adding elevated regions to a catchment model results in a (more or less substantial) general increase in groundwater availability in the lowland region. If the elevated region is sufficiently large and the groundwater travel time sufficiently long, this can significantly reduce summerly drought periods.

The following figure shows the general structure of wland_wag. Note that, besides surface water areas and sealed surfaces, all land-use types rely on the same set of process equations:

_images/HydPy-W-Wag.png

The WALRUS model defines some discontinuous differential equations, which complicate numerical integration (Brauer et al., 2014). We applied the regularisation techniques provided by the modules smoothutils and smoothtools to remove these discontinuities. As shown for each equation (for example, in the documentation on method Calc_RH_V1), this smoothing is optional. Set the related parameters SH and ST to zero to disable smoothing so that the original WALRUS relationships apply. The larger their values, the faster and more robust the performance of the numerical integration algorithm, but the larger the discrepancies to the discontinuous relationships. Our advice is to set small values like 1 mm or 1 °C (as in the following example calculations), respectively, which means that there is no sharp transition from one behaviour to another at a certain threshold but a smooth transition that mainly takes place in an interval of about 2 mm or 2 °C around the threshold. As a consequence, a negative value for the amount of water stored in the interception storage is acceptable, as the threshold of 0 mm does not mean that the storage is completely empty but that two domains (the storage is empty and the storage is not empty) are equally true (similar as in fuzzy logic).

Integration tests

Note

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

We perform all simulation runs over the same period of two months with a daily simulation step size:

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

wland_wag usually reads its temperature and precipitation input data from files and receives its potential evaporation and evapotranspiration input data from a submodel (petmodel), making the definition of the relevant Element object straightforward:

>>> from hydpy.models.wland_wag import *
>>> parameterstep("1d")
>>> land = Element("land", outlets="outlet")
>>> land.model = model

Our virtual test catchment has 10 km²:

>>> at(10.0)

We divide the land area into four hydrological response units of type FIELD, CONIFER, SEALED and WATER (note that the first three land-related units are optional, but the last water-related unit is required, as it corresponds to the surface water storage, which is an integral component of the WALRUS concept):

>>> nu(4)
>>> lt(FIELD, CONIFER, SEALED, WATER)

In the first examples, we consider the catchment completely flat and hence define no hydrological response unit as “elevated”:

>>> er(False)

With the following setting, the water area is 0.2 km², so the total land area is 9.8 km². Of this, 0.98 km² are sealed, which makes the size of the (non-sealed) vadose zone 8.82 km²:

>>> aur(0.6 * 0.98, 0.3 * 0.98, 0.1 * 0.98, 0.02)

The lowland’s ground surface level is 1.5 m above sea level, and the channel bottom level is exactly at sea level, making a channel depth of 1.5 m:

>>> gl(1.5)
>>> bl(0.0)

The following parameter values lead to good results in a small catchment near the Kiel Canal (northern part of Germany). For the parameter LAI, which provides land use-specific values, we define only those values relevant for FIELD, CONIFER, and SEALED. We adopt the default values for the “physical” soil parameters (B, PsiAE, and ThetaS):

>>> cp(0.8)
>>> lai.sealed = 10.0
>>> lai.conifer = 11.0
>>> lai.field = 0.4, 0.4, 0.3, 0.7, 3.0, 5.2, 4.6, 3.1, 1.3, 0.2, 0.0, 0.0
>>> ih(0.2)
>>> tt(0.0)
>>> ti(4.0)
>>> ddf(5.0)
>>> ddt(0.0)
>>> cw(400.0)
>>> cv(0.2)
>>> cg(200000.0)
>>> cgf(1.0)
>>> cq(0.5)
>>> b(soil=SANDY_LOAM)
>>> psiae(soil=SANDY_LOAM)
>>> thetas(soil=SANDY_LOAM)
>>> zeta1(0.02)
>>> zeta2(400.0)

The elevated region parameters are not required for now, and we can set their values to nan:

>>> cwe(nan)
>>> cge(nan)
>>> ac(nan)

We set both regularisation parameters to one (in agreement with the discussion above):

>>> sh(1.0)
>>> st(1.0)

In agreement with the original WALRUS model, we disable the RG option (the documentation on method Calc_FGS_V1 explains the stabilising functionalities of the restrictions RG is connected to) and the DGC option (we enable it in the groundwater connect example):

>>> rg(False)
>>> dgc(False)

wland_wag requires a submodel for calculating the potential evapotranspiration of land units and the potential evaporation of the sole water unit. We apply evap_ret_io to smuggle in the underlying reference evapotranspiration. evap_pet_mlc adjusts the given reference evapotranspiration to the month- and land cover-specific potential evapotranspiration values:

>>> with model.add_petmodel_v1("evap_pet_mlc"):
...     landmonthfactor.sealed = 0.7
...     landmonthfactor.conifer = 1.3
...     landmonthfactor.field[1:4] = 0.73, 0.77, 0.95
...     landmonthfactor.water[1:4] = 1.22, 1.26, 1.28
...     dampingfactor(1.0)
...     with model.add_retmodel_v1("evap_ret_io"):
...         evapotranspirationfactor(0.9)

Additionally, wland_wag requires a submodel for calculating the discharge out of the surface water storage (the same as the discharge at a catchment’s outlet. Here, we use wq_walrus, which implements the default approach of the original WALRUS model:

>>> with model.add_dischargemodel_v2("wq_walrus"):
...     crestheight(0.0)
...     bankfulldischarge(8.0)
...     dischargeexponent(1.5)

Next, we initialise a test function object that prepares and runs the following tests and prints and plots their results:

>>> test = IntegrationTest(land)

All simulation runs start from dry conditions. The groundwater depth (DG, 1.6 m), which is nearly in equilibrium with the water deficit in the vadose zone (DV, 0.14 m, see method Calc_DVEq_V1), lies below the channel depth (CD, 1.5 m). The interception height (IC), the snowpack (SP), and the surface water level (HS) are intentionally negative to make sure even the regularised equations consider the related storages as (almost) empty:

>>> test.inits = (
...     (states.ic, (-3.0, -3.0, -3.0, 0.0)),
...     (states.sp, (-3.0, -3.0, -3.0, 0.0)),
...     (states.dve, 140.0),
...     (states.dv, 140.0),
...     (states.hge, 900.0),
...     (states.dg, 1600.0),
...     (states.hq, 0.0),
...     (states.hs, -2.0),
...     (model.petmodel.sequences.logs.loggedpotentialevapotranspiration, 0.0),
... )

The following real data shows a shift from winter to spring conditions in the form of a rise in temperature and potential evapo(transpi)ration and includes two heavy rainfall events:

>>> inputs.t.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.p.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)
>>> model.petmodel.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)

wland_wag allows for defining additional supply and extraction series. We will discuss them later and set both to zero for now.

>>> inputs.fxg.series = 0.0
>>> inputs.fxs.series = 0.0

As we want to use method check_waterbalance() to prove that wland_wag keeps the water balance in each example run, we need to store the defined (initial) conditions before performing the first simulation run:

>>> test.reset_inits()
>>> conditions = model.conditions

base scenario

In our base scenario, we do not modify any of the settings described above. Initially, there is no exchange between groundwater and surface water due to the empty channel and the groundwater level below the channel bottom. The rainfall events increase both the groundwater level (via infiltration and percolation) and the surface water level (via quickflow generated on the sealed surfaces and on the saturated fraction of the vadose zone). Due to the faster rise of the surface water level, water first moves from the channel into groundwater (more concretely, it enters the vadose zone), but this inverses after the channel has discharged most of its content some days after the rainfall events.

>>> test("wland_wag_base_scenario",
...      axis1=(fluxes.pc, fluxes.fqs, fluxes.fgs, fluxes.rh),
...      axis2=(states.dg, states.hs))
Click to see the table
Click to see the graph

There is no indication of an error in the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

seepage

wland_wag allows modelling external seepage or extraction into or from the vadose zone. We define an extreme value of 10 mm/d, which applies for the whole two months, to show how wland_wag reacts in case of strong large-scale ponding (this is a critical aspect of the WALRUS concept; see the documentation on method Calc_FGS_V1 for a more in-depth discussion):

>>> inputs.fxg.series = 10.0

The integration algorithm implemented by ELSModel solves the differential equations of wland_wag stable; the results look as expected. Within the first few days, the groundwater table rises fast and finally exceeds the soil surface (large-scale ponding, indicated by negative values). The highest flow from groundwater to surface water occurs directly after ponding and before the surface water level reaches its steady state. At the end of the simulation run, the groundwater level is always slightly higher than the surface water level, which assures the necessary gradient to discharge the seepage water into the stream:

>>> test("wland_wag_seepage",
...      axis1=(fluxes.pc, fluxes.fqs, fluxes.fgs, fluxes.rh),
...      axis2=(states.dg, states.hs))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

groundwater connect

We set the DGC parameter to True to demonstrate the effects of the increased responsiveness of the groundwater level to the more direct groundwater connection to internal and external forcings explained in the documentation on method Calc_CDG_V1:

>>> dgc(True)

>>> test("wland_wag_groundwater_connect",
...      axis1=(fluxes.pc, fluxes.fqs, fluxes.fgs, fluxes.rh),
...      axis2=(states.dg, states.hs))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

>>> dgc(False)

surface water supply

We now repeat the seepage example but use the input sequence FXS instead of FXG to feed the water into the surface water reservoir instead of the vadose zone reservoir:

>>> inputs.fxg.series =  0.0
>>> inputs.fxs.series = 10.0

Overall, the following results look similar to the ones of the seepage example. However, it takes longer until the groundwater and surface water levels approach their final values because of the faster surface runoff response. The steady-state surface water level is higher than the groundwater level, but to a much lesser extent, as the vadose zone can absorb only as much water as it can release via evapotranspiration:

>>> test("wland_wag_surface_water_supply",
...      axis1=(fluxes.pc, fluxes.fqs, fluxes.fgs, fluxes.rh),
...      axis2=(states.dg, states.hs))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

elevated regions

This test demonstrates the initially explained elevated region add-on of wland_wag by setting the coniferous hydrological response unit’s ER flag to True:

>>> inputs.fxs.series = 0.0
>>> er(conifer=True, default=False)

The elevated region-specific parameters AC, CWE, and CGE now require values:

>>> ac(100.0)
>>> cwe(400.0)
>>> cge(200000.0)

The elevated region’s initial groundwater level is 1 m above the lowland’s. Hence, there is a permanent flux from the elevated to the lowland region, and the lowland’s groundwater depth decreases by 0.4 m during the simulation period instead of less than 0.2 m in the base scenario example:

>>> test("wland_wag_elevated_regions",
...      axis1=(fluxes.pc, fluxes.fgse, fluxes.fgs),
...      axis2=(states.hge, states.dg))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

snowfall

This example shows the functionality of the simple, day-degree-based snow module. We activate the snow processes by making the entire time series 8 °C colder:

>>> er(False)
>>> inputs.t.series -= 8.0

The following results show how the snow layer builds up throughout most of the simulation period and then suddenly melts due to relatively warm temperatures around the beginning of April. The differences between the three hydrological response units’ snow accumulation stem from differences in their interception parameterisations. At the end of the melting period, the values of SP quickly drop to around -1 mm. The regularisation of the day-degree threshold still allows further melting, but by such a small amount, SP does not decrease in a relevant manner anymore:

>>> test("wland_wag_snowfall", axis1=(fluxes.pc, states.sp), axis2=(inputs.t,))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

backwater effects

To model backwater effects as mentioned above, one must “disable” the unidirectional calculation of the runoff height by not setting or removing an existing discharge submodel:

>>> del model.dischargemodel

Next, we must add a submodel that complies with the WaterLevelModel_V1 interface. We apply exch_waterlevel, which makes the downstream water level available via a remote node:

>>> with model.add_waterlevelmodel_v1("exch_waterlevel"):
...     pass

We create such a node and build the required connections:

>>> from hydpy import Node
>>> waterlevel = Node("waterlevel", variable="WaterLevel")
>>> land = Element("land", outlets="outlet", receivers=waterlevel)
>>> land.model.connect()
>>> test.hydpy.update_devices(nodes=("outlet", waterlevel), elements=land)

Usually, the remote node would receive its data from a downstream model like dam_pump or sw1d_storage. Here, we simplify things by directly defining the downstream location’s water level time series by reusing the tabulated results of the snowfall example:

>>> waterlevel.prepare_simseries()
>>> waterlevel.deploymode = "oldsim"
>>> waterlevel.sequences.sim.series = [
...     -1.955539, -1.593272, -1.554112, -1.514237, -1.474332, -1.434671, -1.237946,
...     2.127124, 1.721998, 3.728419, 18.207013, 25.802253, 71.102022, 99.231277,
...     90.580027, 87.096102, 104.142108, 247.067521, 291.608204, 251.76909,
...     213.036118, 180.529412, 163.8984, 149.153668, 131.288692, 115.204072,
...     102.991454, 98.139161, 87.168564, 77.587424, 69.085831, 62.643619, 60.153237,
...     56.181454, 122.382442, 155.691919, 147.940892, 148.543172, 321.621321,
...     368.151976, 308.494631, 253.669569, 211.316972, 178.790605, 153.349539,
...     133.098674, 153.5539, 254.793577, 673.736602, 1281.108691, 1200.030141,
...     859.04159, 626.665696, 481.755443, 387.029438, 320.183349, 271.859287,
...     234.668462, 205.397587]

We need to convert the unit from mm (used by wland_wag) to m (specified by the WaterLevelModel_V1 interface):

>>> waterlevel.sequences.sim.series /= 1000.0

Despite inserting the water levels taken from the result table of the snowfall example, some relevant deviations in the other properties arise because the (externally defined) surface water level is kept constant within each simulation step. So, these deviations indicate numerical inaccuracy and could be reduced by setting a smaller simulation step size. Also, note that sequence DHS now contains all externally defined water level changes, which is a measure for these inaccuracies and helps keep track of the water balance:

>>> test("wland_wag_backwater_effects",
...      axis1=(fluxes.pc, states.sp), axis2=(inputs.t,))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

We return wland_wag to the standard “unidirectional” mode by removing the water level submodel and reintroducing the same discharge submodel:

>>> del model.waterlevelmodel
>>> with model.add_dischargemodel_v2("wq_walrus"):
...     crestheight(0.0)
...     bankfulldischarge(8.0)
...     dischargeexponent(1.5)

no vadose zone

This example demonstrates that wland_wag works well with completely sealed land surfaces. We enforce this by assigning the land-use type SEALED to all three land-related hydrological response units:

>>> lt(SEALED, SEALED, SEALED, WATER)
>>> assert lt.value[0] != model.petmodel.parameters.control.hrutype.values[0]  # ToDo
>>> model.petmodel.prepare_zonetypes(lt.values)

The results show the expected sharp runoff response of the catchment. Note that for a missing vadose zone, neither its water deficit (DV) nor its groundwater depth (DG) is definable. We set their values to nan. In contrast, we set the related flux FGS and the change in the groundwater level (CDG) to zero:

>>> test("wland_wag_no_vadose_zone",
...      axis1=(fluxes.pc, fluxes.fqs, fluxes.fgs, fluxes.rh),
...      axis2=(states.dg, states.hs))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

no land area

wland_wag also works for “catchments” consisting of surface water areas only. This setting somehow contradicts the original WALRUS concept. However, it may help to set up wland_wag with small “raster sub-catchments” in water basins with large lakes. Besides setting the number of hydrological response units (NU) to one, we need to reset the values of some parameters which lose their information when their shape changes:

>>> nu(1)
>>> aur(1.0)
>>> lt(WATER)
>>> er(False)
>>> model.update_parameters()
>>> model.petmodel.parameters.control.dampingfactor(1.0)
>>> model.petmodel.retmodel.parameters.control.evapotranspirationfactor(0.9)

Assigning a new value to parameter NU also changes the shape of the state sequences IC and SP. Hence, we must again query the relevant initial conditions for applying method check_waterbalance() after simulation:

>>> test.inits.ic = 0.0
>>> test.inits.sp = 0.0
>>> test.reset_inits()
>>> conditions = model.conditions

In contrast to the no vadose zone example, the generated runoff (RH) nearly vanishes due to the little rise in the water level, even for the two heavy precipitation events. Our “catchment” now works like a lake, and nearly all stored precipitation water evaporates sooner or later:

>>> test("wland_wag_no_land_area",
...      axis1=(fluxes.pc, fluxes.et, fluxes.rh), axis2=(states.hs,))
Click to see the table
Click to see the graph

There is no violation of the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0
class hydpy.models.wland_wag.Model[source]

Bases: BaseModel, Main_PETModel_V1, Main_PETModel_V2, Main_DischargeModel_V2, Main_WaterLevelModel_V1, Sub_TempModel_V1, Sub_PrecipModel_V1, Sub_SnowCoverModel_V1

HydPy-W-Wag (extended version of the original Wageningen WALRUS model).

The following “receiver update methods” are called in the given sequence before performing a simulation step:
The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:

  • Calc_PE_PET_V1 Let a submodel that complies with the PETModel_V1 or PETModel_V2 interface calculate the potential evapotranspiration of the land areas and the potential evaporation of the surface water storage.

  • Calc_FR_V1 Determine the fraction between rainfall and total precipitation.

  • Calc_PM_V1 Calculate the potential snowmelt of the land areas.

The following methods define the relevant components of a system of ODE equations (e.g. direct runoff):

  • Calc_FXS_V1 Query the current surface water supply/extraction.

  • Calc_FXG_V1 Query the current seepage/extraction.

  • Calc_PC_V1 Calculate the corrected precipitation.

  • Calc_TF_V1 Calculate the total amount of throughfall of the land areas.

  • Calc_EI_V1 Calculate the interception evaporation of the land areas.

  • Calc_RF_V1 Calculate the liquid amount of throughfall (rainfall) of the land areas.

  • Calc_SF_V1 Calculate the frozen amount of throughfall (snowfall) of the land areas.

  • Calc_AM_V1 Calculate the actual snowmelt of the land areas.

  • Calc_PS_V1 Calculate the precipitation entering the surface water reservoir.

  • Calc_WE_W_V1 Calculate the wetness index for the elevated and the lowland regions.

  • Calc_PVE_PV_V1 Calculate the rainfall (and snowmelt) entering the vadose zone in the elevated and lowland regions.

  • Calc_PQ_V1 Calculate the rainfall (and snowmelt) entering the quickflow reservoir.

  • Calc_BetaE_Beta_V1 Calculate the evapotranspiration reduction factor for the elevated and lowland regions.

  • Calc_ETVE_ETV_V1 Calculate the actual evapotranspiration from the elevated and lowland regions’ vadose zone.

  • Calc_ES_V1 Calculate the actual evaporation from the surface water reservoir.

  • Calc_FQS_V1 Calculate the quickflow.

  • Calc_GR_V1 Calculate the elevated region’s groundwater recharge.

  • Calc_FGSE_V1 Calculate the groundwater flow between the elevated and the lowland regions.

  • Calc_FGS_V1 Calculate the groundwater drainage or surface water infiltration.

  • Calc_RH_V1 Let a submodel that complies with the DischargeModel_V2 interface calculate the runoff height or, if no such submodel is available, equate it with all other flows in and out of the surface water storage.

  • Calc_DVEq_V1 Calculate the equilibrium storage deficit of the vadose zone.

  • Calc_CDG_V1 Calculate the change in the groundwater depth due to percolation and capillary rise.

The following methods define the complete equations of an ODE system (e.g. change in storage of fast water due to effective precipitation and direct runoff):
The following “outlet update methods” are called in the given sequence at the end of each simulation step:

  • Calc_ET_V1 Calculate the total actual evapotranspiration.

  • Calc_R_V1 Calculate the runoff in m³/s.

  • Pass_R_V1 Update the outlet link sequence.

The following interface methods are available to main models using the defined model as a submodel:

  • Get_Temperature_V1 Get the current subbasin-wide air temperature value (that applies to all hydrological response units so that the given index does not matter).

  • Get_MeanTemperature_V1 Get the current subbasin-wide air temperature value.

  • Get_Precipitation_V1 Get the current subbasin-wide precipitation value (that applies to all hydrological response units so that the given index does not matter).

  • Get_SnowCover_V1 Get the selected response unit’s current snow cover degree.

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:

  • Calc_PE_PET_PETModel_V1 Let a submodel that complies with the PETModel_V1 interface calculate the potential evapotranspiration of the land areas and the potential evaporation of the surface water storage.

  • Calc_PE_PET_PETModel_V2 Let a submodel that complies with the PETModel_V2 interface calculate the potential interception evaporation and potential vadose zone evapotranspiration of the land areas and the potential evaporation of the surface water storage.

Users can hook submodels into the defined main model if they satisfy one of the following interfaces:

  • PETModel_V1 Simple interface for calculating all potential evapotranspiration values in one step.

  • PETModel_V2 Interface for calculating separate potential interception, soil, and water evapotranspiration values.

  • DischargeModel_V2 Simple interface for calculating discharge in mm/T based on the current water depth.

  • WaterLevelModel_V1 Pure getter interface for querying the current water level.

DOCNAME: DocName = ('W-Wag', 'extended version of the original Wageningen WALRUS model')
petmodel: modeltools.SubmodelProperty

Required submodel that complies with one of the following interfaces: PETModel_V1 or PETModel_V2.

dischargemodel: modeltools.SubmodelProperty

Required submodel that complies with the following interface: DischargeModel_V2.

waterlevelmodel: modeltools.SubmodelProperty

Required submodel that complies with the following interface: WaterLevelModel_V1.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
numconsts: NumConstsELS
numvars: NumVarsELS
cymodel: CyModelProtocol | None
parameters: parametertools.Parameters
sequences: sequencetools.Sequences
masks: masktools.Masks
class hydpy.models.wland_wag.AideSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: AideSequences

Aide sequences of model wland_wag.

The following classes are selected:

  • FR() Fraction rainfall / total precipitation [-].

  • WE() Wetness index in the elevated region [-].

  • W() Wetness index in the lowland region [-].

  • BetaE() Evapotranspiration reduction factor in the elevated region [-].

  • Beta() Evapotranspiration reduction factor in the lowland region [-].

  • DVEq() Equilibrium storage deficit of the vadose zone for the actual groundwater depth [mm].

class hydpy.models.wland_wag.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Control parameters of model wland_wag.

The following classes are selected:

  • AT() Total area [km²].

  • NU() Number of hydrological response units [-].

  • LT() Landuse type [-].

  • ER() Elevated region [-].

  • AUR() Relative area of each hydrological response unit [-].

  • GL() The lowland region’s average ground level [m].

  • BL() Channel bottom level [m].

  • CP() Factor for correcting precipitation [-].

  • LAI() Leaf area index [-].

  • IH() Interception capacity with respect to the leaf surface area [mm].

  • TT() Threshold temperature for snow/rain [°C].

  • TI() Temperature interval with a mixture of snow and rain [°C].

  • DDF() Day degree factor [mm/°C/T].

  • DDT() Day degree threshold temperature [°C].

  • CWE() Wetness index parameter for the elevated region [mm].

  • CW() Wetness index parameter for the lowland region [mm].

  • CV() Vadose zone relaxation time constant for the lowland region [T].

  • CGE() Groundwater reservoir constant for the elevated region [mm T].

  • CG() Groundwater reservoir constant for the lowland region [mm T].

  • RG() Groundwater reservoir restriction [-].

  • CGF() Groundwater reservoir flood factor [1/mm].

  • DGC() Direct groundwater connect [-].

  • CQ() Quickflow reservoir relaxation time [T].

  • B() Pore size distribution parameter [-].

  • PsiAE() Air entry pressure [mm].

  • ThetaS() Soil moisture content at saturation [-].

  • AC() Air capacity for the elevated region [mm].

  • Zeta1() Curvature parameter of the evapotranspiration reduction function [-].

  • Zeta2() Inflection point of the evapotranspiration reduction function [mm].

  • SH() General smoothing parameter related to the height of water columns [mm].

  • ST() General smoothing parameter related to temperature [°C].

class hydpy.models.wland_wag.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model wland_wag.

The following classes are selected:

  • MOY() References the “global” month of the year index array [-].

  • NUL() Number of land-related hydrological response units [-].

  • NUGE() Number of groundwater-affected hydrological response units in the elevated region [-].

  • NUG() Number of groundwater-affected hydrological response units in the lowland region [-].

  • ALR() Relative land area [-].

  • ASR() Relative surface water area fraction [-].

  • AGRE() Relative groundwater area in the elevated region [-].

  • AGR() Relative groundwater area in the lowland region [-].

  • QF() Factor for converting mm/T to m³/s [T m³ / mm s].

  • CD() Channel depth [mm].

  • RH1() Regularisation parameter related to the height of water columns used when applying regularisation function smooth_logistic1() [mm].

  • RH2() Regularisation parameter related to the height of water columns used when applying regularisation function smooth_logistic2() [mm].

  • RT2() Regularisation parameter related to temperature for applying regularisation function smooth_logistic2()) [°C].

class hydpy.models.wland_wag.FactorSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FactorSequences

Factor sequences of model wland_wag.

The following classes are selected:

  • DHS() External change of the surface water depth [mm/T].

class hydpy.models.wland_wag.FixedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Fixed parameters of model wland_wag.

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

Bases: FluxSequences

Flux sequences of model wland_wag.

The following classes are selected:

  • PC() Corrected precipitation [mm/T].

  • PE() Potential evaporation from the interception and the surface water storage [mm/T].

  • PET() Potential evapotranspiration from the vadose zone [mm/T].

  • TF() Total amount of throughfall [mm/T].

  • EI() Interception evaporation [mm/T].

  • RF() Rainfall (or, more concrete, the liquid amount of throughfall) [mm/T].

  • SF() Snowfall (or, more concrete, the frozen amount of throughfall) [mm/T].

  • PM() Potential snowmelt [mm/T].

  • AM() Actual snowmelt [mm/T].

  • PS() Precipitation that enters the surface water reservoir [mm/T].

  • PVE() Rainfall (and snowmelt) entering the vadose zone in the elevated region [mm/T].

  • PV() Rainfall (and snowmelt) entering the vadose zone in the lowland region [mm/T].

  • PQ() Rainfall (and snowmelt) entering the quickflow reservoir [mm/T].

  • ETVE() Actual evapotranspiration from the vadose zone in the elevated region [mm/T].

  • ETV() Actual evapotranspiration from the vadose zone in the lowland region [mm/T].

  • ES() Actual evaporation from the surface water [mm/T].

  • ET() Total actual evapotranspiration [mm/T].

  • GR() Groundwater recharge in the elevated region [mm/T].

  • FXS() Surface water supply/extraction (normalised to ASR) [mm/T].

  • FXG() Seepage/extraction (normalised to ALR) [mm/T].

  • CDG() Change in the groundwater depth due to percolation and capillary rise [mm/T].

  • FGSE() Groundwater flow between the elevated and the lowland region [mm/T].

  • FGS() Groundwater drainage/surface water infiltration [mm/T].

  • FQS() Quickflow [mm/T].

  • RH() Runoff height [mm/T].

  • R() Runoff [m³/s].

class hydpy.models.wland_wag.InputSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: InputSequences

Input sequences of model wland_wag.

The following classes are selected:

  • T() Air temperature [°C].

  • P() Precipitation [mm/T].

  • FXG() Seepage/extraction (normalised to AT) [mm/T].

  • FXS() Surface water supply/extraction (normalised to AT) [mm/T].

class hydpy.models.wland_wag.OutletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: OutletSequences

Outlet sequences of model wland_wag.

The following classes are selected:

  • Q() Discharge [m³/s].

class hydpy.models.wland_wag.SolverParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Solver parameters of model wland_wag.

The following classes are selected:

  • AbsErrorMax() Absolute numerical error tolerance [mm/T].

  • RelErrorMax() Relative numerical error tolerance [-].

  • RelDTMin() Smallest relative integration time step size allowed [-].

  • RelDTMax() Largest relative integration time step size allowed [-].

class hydpy.models.wland_wag.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: StateSequences

State sequences of model wland_wag.

The following classes are selected:

  • IC() Interception storage [mm].

  • SP() Snow pack [mm].

  • DVE() Storage deficit of the vadose zone in the elevated region [mm].

  • DV() Storage deficit of the vadose zone in the lowland region [mm].

  • HGE() Groundwater level in the elevated region [mm].

  • DG() Groundwater depth in the lowland region [mm].

  • HQ() Level of the quickflow reservoir [mm].

  • HS() Surface water level [mm].