wland_v002

Version 2 of HydPy-W-Land is still under development and likely to change in the future.

When applying wland_v001 on the Kiel Catchment river basins, we realised some strengths and some limitations of the WALRUS concept. First, wland_v001 does not predict the high dynamics of the groundwater levels encountered at many groundwater gauges. We assume this shortcoming is connected with an observed tendency to underestimate streamflow peaks. Second, wland_v001 tends to run dry during summer conditions much too fast.

So far, wland_v002 offers a physically based approach that increases groundwater dynamics. See the documentation on method Calc_GF_V1 for an in-depth explanation. The second problem seems to be related to a lack of “groundwater recharge areas” where groundwater is less exposed to evapotranspiration. We will address this later.

The following integration tests are identical with the ones of wland_v001, except that we set the additional parameter ThetaR to 0.01. Compare the base scenario example of wland_v001 and with the base scenario example of wland_v002 to see how the differences between both models affect groundwater dynamics.

Integration tests

Note

When new to HydPy, consider reading section How to understand integration tests? first.

>>> from hydpy import IntegrationTest, Element, pub, round_
>>> pub.timegrids = "2017-02-10", "2017-04-10", "1d"
>>> from hydpy.models.wland_v002 import *
>>> parameterstep("1d")
>>> land = Element("land", outlets="outlet")
>>> land.model = model
>>> al(9.8)
>>> as_(0.2)
>>> nu(3)
>>> lt(FIELD, CONIFER, SEALED)
>>> aur(0.6, 0.3, 0.1)
>>> cp(0.8)
>>> cpet(0.9)
>>> cpetl.sealed = 0.7
>>> cpetl.conifer = 1.3
>>> cpetl.field = 0.73, 0.73, 0.77, 0.95, 1.19, 1.18, 1.19, 1.15, 0.97, 0.85, 0.78, 0.73
>>> cpes(jan=1.16, feb=1.22, mar=1.26, apr=1.28, may=1.28, jun=1.30,
...      jul=1.28, aug=1.28, sep=1.27, oct=1.23, nov=1.17, dec=1.14)
>>> 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)
>>> cd(1500.0)
>>> cs(8.0)
>>> hsmin(0.0)
>>> xs(1.5)
>>> b(soil=SANDY_LOAM)
>>> psiae(soil=SANDY_LOAM)
>>> thetas(soil=SANDY_LOAM)
>>> thetar(0.01)
>>> zeta1(0.02)
>>> zeta2(400.0)
>>> sh(1.0)
>>> st(1.0)
>>> test = IntegrationTest(land)
>>> test.inits = ((states.ic, -3.0),
...               (states.sp, -3.0),
...               (states.dv, 140.0),
...               (states.dg, 1600.0),
...               (states.hq, 0.0),
...               (states.hs, -2.0))
>>> 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)
>>> inputs.pet.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)
>>> inputs.fxg.series = 0.0
>>> inputs.fxs.series = 0.0
>>> test.reset_inits()
>>> conditions = sequences.conditions

base scenario

>>> test("wland_v002_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
>>> round_(model.check_waterbalance(conditions))
0.0

seepage

>>> inputs.fxg.series = 10.0

>>> test("wland_v002_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
>>> round_(model.check_waterbalance(conditions))
0.0

surface water supply

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

>>> test("wland_v002_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
>>> round_(model.check_waterbalance(conditions))
0.0

snowfall

>>> inputs.fxs.series =  0.0
>>> inputs.t.series -= 8.0

>>> test("wland_v002_snowfall",
...      axis1=(fluxes.pc, states.sp,),
...      axis2=(inputs.t,))
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0

No vadose zone

>>> lt(SEALED)

>>> test("wland_v002_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
>>> round_(model.check_waterbalance(conditions))
0.0

No land area

>>> nu(0)
>>> al(0.0)
>>> as_(10.0)
>>> test.reset_inits()
>>> conditions = sequences.conditions

>>> test("wland_v002_no_land_area",
...      axis1=(fluxes.pc, fluxes.et, fluxes.rh),
...      axis2=(states.hs,))
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0
class hydpy.models.wland_v002.Model[source]

Bases: ELSModel

The HydPy-W-Land model.

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

  • Calc_FR_V1 Determine the fraction between rainfall and total precipitation.

  • Calc_PM_V1 Calculate the potential snowmelt.

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_PETL_V1 Adjust the potential evapotranspiration of the land areas.

  • Calc_PES_V1 Adapt the potential evaporation for the surface water area.

  • Calc_TF_V1 Calculate the total amount of throughfall.

  • Calc_EI_V1 Calculate the interception evaporation.

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

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

  • Calc_AM_V1 Calculate the actual snowmelt.

  • Calc_PS_V1 Calculate the precipitation entering the surface water reservoir.

  • Calc_W_V1 Calculate the wetness index.

  • Calc_PV_V1 Calculate the rainfall (and snowmelt) entering the vadose zone.

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

  • Calc_Beta_V1 Calculate the evapotranspiration reduction factor.

  • Calc_ETV_V1 Calculate the actual evapotranspiration from the vadose zone.

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

  • Calc_FQS_V1 Calculate the quickflow.

  • Calc_FGS_V1 Calculate the groundwater drainage or surface water infiltration.

  • Calc_RH_V1 Calculate the runoff height.

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

  • Calc_DGEq_V1 Calculate the equilibrium groundwater depth.

  • Calc_GF_V1 Calculate the gain factor for changes in groundwater depth.

  • Calc_CDG_V2 Calculate the change in the vadose zone’s storage deficit due to percolation, capillary rise, macropore-infiltration, seepage, groundwater drainage, and channel water infiltration.

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 “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:

  • Return_DVH_V2 Return the storage deficit of the vadose zone at a specific height above the groundwater table.

  • Return_ErrorDV_V1 Calculate the difference between the equilibrium and the actual storage deficit of the vadose zone.

The following “submodels” might be called by one or more of the implemented methods or are meant to be directly called by the user:

  • PegasusDGEq Pegasus iterator for finding the equilibrium groundwater depth.

check_waterbalance(initial_conditions: Dict[str, Dict[str, ArrayFloat]]) → float[source]

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

Method check_waterbalance() calculates the balance error as follows:

\(\sum_{t=t0}^{t1} \big( PC_t + FXG_t + FXS_t - ET_t - RH_t \big) + ASR \cdot \big( HS_{t0} - HS_{t1}\big) + ALR \cdot \left( \big( HQ_{t0} - HQ_{t1} \big) - AGR \cdot \big( DV_{t0} - DV_{t1} \big) + \sum_{k=1}^{NU} AUR^k \cdot \big( IC_{t0}^k - IC_{t1}^k + SP_{t0}^k - SP_{t1}^k \big) \right)\)

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 wland_v001 for some examples.

class hydpy.models.wland_v002.AideSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: AideSequences

Aide sequences of model wland_v002.

The following classes are selected:

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

  • W() Wetness index [-].

  • Beta() Evapotranspiration reduction factor [-].

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

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

  • GF() Gain factor for changes in groundwater depth [-].

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

Bases: SubParameters

Control parameters of model wland_v002.

The following classes are selected:

  • AL() Land area [km²].

  • AS_() Surface water area [km²].

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

  • LT() Landuse type [-].

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

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

  • CPET() Factor for correcting potential evapotranspiration [-].

  • CPETL() Factor for converting general potential evapotranspiration (usually grass reference evapotranspiration) to land-use specific potential evapotranspiration [-].

  • CPES() Factor for converting general potential evapotranspiration (usually grass reference evapotranspiration) to potential evaporation from water areas [-].

  • 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].

  • CW() Wetness index parameter [mm].

  • CV() Vadose zone relaxation time constant [T].

  • CG() Groundwater reservoir constant [mm T].

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

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

  • CD() Channel depth [mm].

  • CS() Surface water parameter for bankfull discharge [mm/T].

  • HSMin() Surface water level where and below which discharge is zero [mm].

  • XS() Stage-discharge relation exponent [-].

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

  • PsiAE() Air entry pressure [mm].

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

  • ThetaR() Residual soil moisture deficit at tension saturation [-].

  • 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_v002.DerivedParameters(master: Parameters, cls_fastaccess: Type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model wland_v002.

The following classes are selected:

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

  • NUG() Number of groundwater affected hydrological response units [-].

  • AT() Total area [km²].

  • ALR() Relative land area [-].

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

  • AGR() Relative groundwater area [-].

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

  • 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_v002.FixedParameters(master: Parameters, cls_fastaccess: Type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Fixed parameters of model wland_v002.

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

Bases: FluxSequences

Flux sequences of model wland_v002.

The following classes are selected:

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

  • PETL() Adjusted potential evapotranspiration of the land areas [mm/T].

  • PES() Adjusted potential evaporation of the surface water area [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 entering the surface water reservoir [mm/T].

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

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

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

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

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

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

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

  • CDG() Change in the groundwater depth due to percolation and capillary rise [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_v002.InputSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: InputSequences

Input sequences of model wland_v002.

The following classes are selected:

  • T() Air temperature [°C].

  • P() Precipitation [mm/T].

  • PET() Potential evapotranspiration [mm/T].

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

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

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

Bases: OutletSequences

Outlet sequences of model wland_v002.

The following classes are selected:

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

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

Bases: SubParameters

Solver parameters of model wland_v002.

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_v002.StateSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: StateSequences

State sequences of model wland_v002.

The following classes are selected:

  • IC() Interception storage [mm].

  • SP() Snow pack [mm].

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

  • DG() Groundwater depth [mm].

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

  • HS() Surface water level [mm].