HydPy-H (base model)

The H-Land model is the core of the HydPy implementation of the the frequently applied HBV96 model. It consists of some routines for the preparation of meteorological input, and some process routines related to interception, snow, soil moisture, upper groundwater, lower groundwater (including lakes), and runoff concentration.

Method Features

class hydpy.models.hland.hland_model.Model[source]

Bases: AdHocModel

HydPy-H (base model).

The following “run methods” are called in the given sequence during each simulation step:
  • Calc_TC_V1 Adjust the measured air temperature to the altitude of the individual zones.

  • Calc_FracRain_V1 Determine the temperature-dependent fraction of (liquid) rainfall and (total) precipitation.

  • Calc_RFC_SFC_V1 Calculate the corrected fractions of rainfall/snowfall and total precipitation.

  • Calc_PC_V1 Apply the precipitation correction factors and adjust precipitation to the altitude of the individual zones.

  • Calc_TF_Ic_V1 Calculate throughfall and update the interception storage accordingly.

  • Calc_EI_Ic_V1 Let a submodel that follows the AETModel_V1 submodel interface calculate interception evaporation and adjust the amount of intercepted water.

  • Calc_SP_WC_V1 Add throughfall to the snow layer.

  • Calc_SPL_WCL_SP_WC_V1 Calculate the subbasin-internal redistribution losses of the snow layer.

  • Calc_SPG_WCG_SP_WC_V1 Calculate the subbasin-internal redistribution gains of the snow layer.

  • Calc_CFAct_V1 Adjust the day degree factor for snow to the current day of the year.

  • Calc_Melt_SP_WC_V1 Calculate the melting of the ice content within the snow layer and update both the snow layers’ ice and the water content.

  • Calc_Refr_SP_WC_V1 Calculate refreezing of the water content within the snow layer and update both the snow layers’ ice and the water content.

  • Calc_In_WC_V1 Calculate the actual water release from the snow layer due to the exceedance of the snow layers’ capacity for (liquid) water.

  • Calc_SWE_V1 Calculate the total snow water equivalent.

  • Calc_SR_V1 Calculate the sealed surface runoff.

  • Calc_GAct_V1 Adjust the day degree factor for glacier ice to the current day of the year.

  • Calc_GlMelt_In_V1 Calculate the melting of non-snow-covered glaciers and add it to the water release of the snow module.

  • Calc_R_SM_V1 Calculate effective precipitation and update the soil moisture.

  • Calc_CF_SM_V1 Calculate capillary flow and update the soil moisture.

  • Calc_EA_SM_V1 Let a submodel that follows the AETModel_V1 submodel interface calculate soil evapotranspiration and adjust the soil water content.

  • Calc_InUZ_V1 Accumulate the total inflow into the upper zone layer.

  • Calc_SUZ_V1 Add the effective precipitation to the upper storage reservoir.

  • Calc_ContriArea_V1 Determine the relative size of the contributing area of the whole subbasin.

  • Calc_Q0_Perc_UZ_V1 Calculate the percolation and direct runoff leaving the upper zone storage and update it accordingly.

  • Calc_DP_SUZ_V1 Calculate the deep percolation and remove it from the upper storage reservoir.

  • Calc_QAb1_QVs1_BW1_V1 Calculate the flow and the percolation from the surface flow reservoir and update it.

  • Calc_QAb2_QVs2_BW2_V1 Calculate the flow and the percolation from the interflow reservoir and update it.

  • Calc_RS_RI_SUZ_V1 Calculate the surface runoff and the interflow and remove them from the upper storage reservoir.

  • Calc_LZ_V1 Add percolation from the upper zone layera and lake precipitation to the lower zone storage.

  • Calc_LZ_V2 Add percolation from the interflow reservoir and lake precipitation to the lower zone storage.

  • Calc_GR1_V1 Calculate the recharge to the fast response groundwater reservoir.

  • Calc_RG1_SG1_V1 Calculate the discharge from the fast response groundwater reservoir and subtract it.

  • Calc_GR2_GR3_V1 Calculate the recharge of the first-order and the second-order slow response groundwater reservoir.

  • Calc_RG2_SG2_V1 Calculate the discharge from the first-order slow response groundwater reservoir and subtract it.

  • Calc_RG3_SG3_V1 Calculate the discharge from the second-order slow response groundwater reservoir and subtract it.

  • Calc_EL_SG2_SG3_V1 Let a submodel that follows the AETModel_V1 submodel interface calculate interception evaporation, soil evapotranspiration, and open water evaporation, and adjust the related interception, soil water, and slow response groundwater storages accordingly.

  • Calc_EL_LZ_V1 Let a submodel that follows the AETModel_V1 submodel interface calculate lake evaporation and adjust the lower zone’s water content.

  • Calc_Q1_LZ_V1 Calculate the slow response of the lower zone layer.

  • Calc_InRC_V1 Calculate the input of the runoff concentration submodel.

  • Calc_InRC_V3 Calculate the input of the runoff concentration submodel.

  • Calc_OutRC_V1 If the model has a submodel that follows the RConcModel_V1 submodel interface, calculate runoff concentration. If not, set the output equal to the input.

  • Calc_InRC_V2 Calculate the input of the runoff concentration submodel.

  • Calc_RT_V1 Calculate the total discharge in mm.

  • Calc_RT_V2 Calculate the total discharge in mm.

  • Calc_QT_V1 Calculate the total discharge in m³/s.

The following “outlet update methods” are called in the given sequence at the end of 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.

  • RConcModel_V1 Simple interface for calculating runoff concentration processes.

DOCNAME: DocName = ('H', 'base model')
aetmodel

Required submodel that complies with the following interface: AETModel_V1.

aetmodel_is_mainmodel
aetmodel_typeid
rconcmodel

Required submodel that complies with the following interface: RConcModel_V1.

rconcmodel_is_mainmodel
rconcmodel_typeid
REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Calc_TC_V1[source]

Bases: Method

Adjust the measured air temperature to the altitude of the individual zones.

Requires the control parameters:

NmbZones TCorr TCAlt ZoneZ

Requires the derived parameter:

Z

Requires the input sequence:

T

Calculates the factor sequence:

TC

Basic equation:

\(TC = T + TCorr - TCAlt \cdot (ZoneZ - Z)\)

Examples:

Prepare two zones, the first lying at the reference height and the second 200 meters above:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(2)
>>> zonez(2.0, 4.0)
>>> derived.z(2.0)

Applying the usual temperature lapse rate of 0.6°C/100m does not affect the first zone but reduces the temperature of the second zone by 1.2°C:

>>> tcorr(1.0)
>>> tcalt(0.6)
>>> inputs.t = 5.0
>>> model.calc_tc_v1()
>>> factors.tc
tc(6.0, 4.8)
class hydpy.models.hland.hland_model.Calc_FracRain_V1[source]

Bases: Method

Determine the temperature-dependent fraction of (liquid) rainfall and (total) precipitation.

Requires the control parameters:

NmbZones TT TTInt

Requires the factor sequence:

TC

Calculates the factor sequence:

FracRain

Basic equation:

\(FracRain = \frac{TC-(TT-\frac{TTInt}{2})}{TTInt}\)

Restriction:

\(0 \leq FracRain \leq 1\)

Examples:

The threshold temperature of seven zones is 0°C, and the corresponding temperature interval of mixed precipitation 2°C:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> tt(0.0)
>>> ttint(2.0)

The fraction of rainfall is zero below -1°C, is one above 1°C, and increases linearly in between:

>>> factors.tc = -10.0, -1.0, -0.5, 0.0, 0.5, 1.0, 10.0
>>> model.calc_fracrain_v1()
>>> factors.fracrain
fracrain(0.0, 0.0, 0.25, 0.5, 0.75, 1.0, 1.0)

Note the particular case of a zero temperature interval. With an actual temperature being equal to the threshold temperature, the rainfall fraction is one:

>>> ttint(0.0)
>>> model.calc_fracrain_v1()
>>> factors.fracrain
fracrain(0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0)
class hydpy.models.hland.hland_model.Calc_RFC_SFC_V1[source]

Bases: Method

Calculate the corrected fractions of rainfall/snowfall and total precipitation.

Requires the control parameters:

NmbZones RfCF SfCF

Requires the factor sequence:

FracRain

Calculates the factor sequences:

RfC SfC

Basic equations:

\(RfC = RfCF \cdot FracRain\)

\(SfC = SfCF \cdot (1 - FracRain)\)

Examples:

Assume five zones with different temperatures and hence different fractions of rainfall and total precipitation:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> factors.fracrain = 0.0, 0.25, 0.5, 0.75, 1.0

With no rainfall and no snowfall correction (due to the respective factors being one), the corrected fraction related to rain is identical to the original fraction, while the corrected fraction related to snow behaves the opposite:

>>> rfcf(1.0)
>>> sfcf(1.0)
>>> model.calc_rfc_sfc_v1()
>>> factors.rfc
rfc(0.0, 0.25, 0.5, 0.75, 1.0)
>>> factors.sfc
sfc(1.0, 0.75, 0.5, 0.25, 0.0)

With a rainfall reduction of 20% and a snowfall increase of 20 %, the corrected fractions are as follows:

>>> rfcf(0.8)
>>> sfcf(1.2)
>>> model.calc_rfc_sfc_v1()
>>> factors.rfc
rfc(0.0, 0.2, 0.4, 0.6, 0.8)
>>> factors.sfc
sfc(1.2, 0.9, 0.6, 0.3, 0.0)
class hydpy.models.hland.hland_model.Calc_PC_V1[source]

Bases: Method

Apply the precipitation correction factors and adjust precipitation to the altitude of the individual zones.

Requires the control parameters:

NmbZones PCAlt ZoneZ PCorr

Requires the derived parameter:

Z

Requires the input sequence:

P

Requires the factor sequences:

RfC SfC

Calculates the flux sequence:

PC

Basic equation:

\(PC = P \cdot PCorr \cdot (1 + PCAlt \cdot (ZoneZ - Z)) \cdot (RfC + SfC)\)

Examples:

Five zones are at an elevation of 200 m. A precipitation value of 5 mm has been measured at a gauge at an elevation of 300 m:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonez(3.0)
>>> inputs.p = 5.0
>>> derived.z(2.0)

The first four zones illustrate the individual precipitation corrections due to the general (PCorr, first zone), the altitude (PCAlt, second zone), the rainfall (RfC, third zone), and the snowfall adjustment (SfC, fourth zone). The fifth zone illustrates the interaction between all corrections:

>>> pcorr(1.3, 1.0, 1.0, 1.0, 1.3)
>>> pcalt(0.0, 0.1, 0.0, 0.0, 0.1)
>>> factors.rfc = 0.5, 0.5, 0.4, 0.5, 0.4
>>> factors.sfc = 0.5, 0.5, 0.5, 0.7, 0.7
>>> model.calc_pc_v1()
>>> fluxes.pc
pc(6.5, 5.5, 4.5, 6.0, 7.865)

Usually, one would set zero or positive values for parameter PCAlt. But it is also allowed to assign negative values to reflect possible negative relationships between precipitation and altitude. Method Calc_PC_V1 performs the required truncations to prevent negative precipitation values:

>>> pcalt(-1.0)
>>> model.calc_pc_v1()
>>> fluxes.pc
pc(0.0, 0.0, 0.0, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_TF_Ic_V1[source]

Bases: Method

Calculate throughfall and update the interception storage accordingly.

Requires the control parameters:

NmbZones ZoneType IcMax

Requires the flux sequence:

PC

Updates the state sequence:

Ic

Calculates the flux sequence:

TF

Basic equation:
\[\begin{split}TF = \begin{cases} PC &|\ Ic = IcMax \\ 0 &|\ Ic < IcMax \end{cases}\end{split}\]

Examples:

Initialise seven zones of different types. Assume a general interception capacity of 2 mm. All zones receive a precipitation input of 0.5 mm:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> zonetype(GLACIER, ILAKE, FIELD, FOREST, SEALED, SEALED, SEALED)
>>> icmax(2.0)
>>> fluxes.pc = 0.5
>>> states.ic = 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 2.0
>>> model.calc_tf_ic_v1()

The interception routine does not apply to glaciers (first zone) and internal lakes (second zone). Hence, all precipitation becomes throughfall. For fields, forests, and sealed areas, the interception routine works identical, so the results of zone three to five are equal. The last three zones demonstrate that all precipitation is stored until the intercepted water reaches the available capacity; afterwards, all precipitation becomes throughfall. Initial storage reduces the effective capacity of the respective simulation step:

>>> states.ic
ic(0.0, 0.0, 0.5, 0.5, 0.5, 1.5, 2.0)
>>> fluxes.tf
tf(0.5, 0.5, 0.0, 0.0, 0.0, 0.0, 0.5)

A zero precipitation example:

>>> fluxes.pc = 0.0
>>> states.ic = 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 2.0
>>> model.calc_tf_ic_v1()
>>> states.ic
ic(0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 2.0)
>>> fluxes.tf
tf(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)

A high precipitation example:

>>> fluxes.pc = 5.0
>>> states.ic = 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 2.0
>>> model.calc_tf_ic_v1()
>>> states.ic
ic(0.0, 0.0, 2.0, 2.0, 2.0, 2.0, 2.0)
>>> fluxes.tf
tf(5.0, 5.0, 3.0, 3.0, 3.0, 4.0, 5.0)
class hydpy.models.hland.hland_model.Calc_EI_Ic_AETModel_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate interception evaporation and adjust the amount of intercepted water.

Required by the method:

Calc_EI_Ic_V1

Requires the control parameters:

NmbZones ZoneType

Updates the state sequence:

Ic

Calculates the flux sequence:

EI

Basic equation:

\(\frac{dIc_i}{dt} = -EI_i\)

Examples:

We build an example based on evap_aet_hbv96 for calculating interception evaporation, which uses evap_ret_io for querying potential evapotranspiration:

>>> from hydpy.models.hland_96 import *
>>> parameterstep("1h")
>>> nmbzones(5)
>>> zonetype(GLACIER, SEALED, FIELD, FOREST, ILAKE)
>>> area(1.0)
>>> zonearea(0.05, 0.1, 0.2, 0.3, 0.35)
>>> zonez(5.0)
>>> icmax(3.0)
>>> fc(50.0)
>>> fluxes.tf = 0.5
>>> with model.add_aetmodel_v1("evap_aet_hbv96"):
...     with model.add_petmodel_v1("evap_ret_io"):
...         evapotranspirationfactor(0.6, 0.8, 1.0, 1.2, 1.4)
...         inputs.referenceevapotranspiration = 1.0

Calc_EI_Ic_AETModel_V1 uses the flux returned by the submodel to adjust Ic:

>>> states.ic = 2.0
>>> model.calc_ei_ic_v1()
>>> fluxes.ei
ei(0.0, 0.8, 1.0, 1.2, 0.0)
>>> states.ic
ic(0.0, 1.2, 1.0, 0.8, 0.0)
>>> fluxes.tf
tf(0.5, 0.5, 0.5, 0.5, 0.5)

Calc_EI_Ic_AETModel_V1 eventually reduces EI so that Ic does not become negative:

>>> model.aetmodel.petmodel.sequences.inputs.referenceevapotranspiration = 5.0
>>> states.ic = 2.0
>>> model.calc_ei_ic_v1()
>>> fluxes.ei
ei(0.0, 2.0, 2.0, 2.0, 0.0)
>>> states.ic
ic(0.0, 0.0, 0.0, 0.0, 0.0)
>>> fluxes.tf
tf(0.5, 0.5, 0.5, 0.5, 0.5)

In contrast, Calc_EI_Ic_AETModel_V1 does not reduce negative EI values (condensation) that cause an overshoot of the interception storage capacity:

>>> model.aetmodel.petmodel.sequences.inputs.referenceevapotranspiration = -3.0
>>> states.ic = 2.0
>>> model.calc_ei_ic_v1()
>>> fluxes.ei
ei(0.0, -2.4, -3.0, -3.6, 0.0)
>>> states.ic
ic(0.0, 4.4, 5.0, 5.6, 0.0)
>>> fluxes.tf
tf(0.5, 0.5, 0.5, 0.5, 0.5)
class hydpy.models.hland.hland_model.Calc_EI_Ic_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate interception evaporation and adjust the amount of intercepted water.

Required submethod:

Calc_EI_Ic_AETModel_V1

Requires the control parameters:

NmbZones ZoneType

Updates the state sequence:

Ic

Calculates the flux sequence:

EI

class hydpy.models.hland.hland_model.Calc_SP_WC_V1[source]

Bases: Method

Add throughfall to the snow layer.

Requires the control parameters:

NmbZones SClass ZoneType SFDist

Requires the factor sequences:

RfC SfC

Requires the flux sequence:

TF

Updates the state sequences:

WC SP

Basic equations:

\(\frac{dSP}{dt} = SFDist \cdot TF \cdot \frac{SfC}{SfC + RfC}\)

\(\frac{dWC}{dt} = SFDist \cdot TF \cdot \frac{RfC}{SfC + RfC}\)

Examples:

Consider the following setting, in which nine zones of different types receive a throughfall of 10 mm:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(9)
>>> sclass(1)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED, FIELD, FIELD, FIELD, FIELD)
>>> sfdist(0.2)
>>> fluxes.tf = 10.0
>>> factors.sfc = 0.5, 0.5, 0.5, 0.5, 0.5, 0.2, 0.8, 1.0, 4.0
>>> factors.rfc = 0.5, 0.5, 0.5, 0.5, 0.5, 0.8, 0.2, 4.0, 1.0
>>> states.sp = 2.0
>>> states.wc = 1.0
>>> model.calc_sp_wc_v1()
>>> states.sp
sp(0.0, 7.0, 7.0, 7.0, 7.0, 4.0, 10.0, 4.0, 10.0)
>>> states.wc
wc(0.0, 6.0, 6.0, 6.0, 6.0, 9.0, 3.0, 9.0, 3.0)

The snow routine does not apply to internal lakes, which is why both the ice storage and the water storage of the first zone remain unchanged. The snow routine is identical for fields, forests, sealed areas, and glaciers (besides the additional glacier melt), which is why the results zone three to five are equal. The last four zones illustrate that method Calc_SP_WC_V1 applies the corrected snowfall and rainfall fractions “relatively”, considering that the throughfall is already corrected.

When both factors are zero, neither the water nor the ice content of the snow layer changes:

>>> factors.sfc = 0.0
>>> factors.rfc = 0.0
>>> states.sp = 2.0
>>> states.wc = 1.0
>>> model.calc_sp_wc_v1()
>>> states.sp
sp(0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0)
>>> states.wc
wc(0.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0)

In the above examples, we did not divide the zones into snow classes. If we do so, method Calc_SP_WC_V1 adds different amounts of snow and rainfall to the individual snow classes based on the current values of parameter SFDist:

>>> sclass(2)
>>> sfdist(0.0, 2.0)
>>> factors.sfc = 0.5, 0.5, 0.5, 0.5, 0.5, 0.2, 0.8, 1.0, 4.0
>>> factors.rfc = 0.5, 0.5, 0.5, 0.5, 0.5, 0.8, 0.2, 4.0, 1.0
>>> states.sp = 2.0
>>> states.wc = 1.0
>>> model.calc_sp_wc_v1()
>>> states.sp
sp([[0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0],
    [0.0, 12.0, 12.0, 12.0, 12.0, 6.0, 18.0, 6.0, 18.0]])
>>> states.wc
wc([[0.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
    [0.0, 11.0, 11.0, 11.0, 11.0, 17.0, 5.0, 17.0, 5.0]])
class hydpy.models.hland.hland_model.Calc_SPL_WCL_SP_WC_V1[source]

Bases: Method

Calculate the subbasin-internal redistribution losses of the snow layer.

Requires the control parameters:

NmbZones SClass ZoneType SMax

Updates the state sequences:

WC SP

Calculates the flux sequences:

SPL WCL

Basic equations:

\(\frac{dSP}{dt} = -SPL\)

\(\frac{dWC}{dt} = -WCL\)

\(SPL = SP \cdot RelExcess\)

\(WCL = WC \cdot RelExcess\)

\(RelExcess = \frac{max(SP + WC - SMax, 0)}{SP + WC}\)

Examples:

We prepare eight zones. We use the first five to show the identical behaviour of the land-use types GLACIER, FIELD, FOREST, and SEALED and the unique behaviour of type ILAKE. Zones six to eight serve to demonstrate the effects of different initial states:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(8)
>>> sclass(1)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED, FIELD, FIELD, FIELD)
>>> smax(500.0)

Internal lakes do not possess a snow module and cannot redistribute any snow. Hence, Calc_SPL_WCL_SP_WC_V1 sets the loss (SPL and WCL) and state (SP and WC) sequences to zero. For all other zones, the total amount of snow redistribution depends on how much the total water equivalent exceeds the threshold parameter SMax (consistently set to 500 m). The fraction between the liquid (WCL) and frozen (SPL) loss depends on the fraction between the actual storage of liquid (WC) and frozen (SP) water in the snow layer:

>>> states.sp = 600.0, 600.0, 600.0, 600.0, 600.0, 60.0, 800.0, 0.0
>>> states.wc = 200.0, 200.0, 200.0, 200.0, 200.0, 20.0, 0.0, 800.0
>>> model.calc_spl_wcl_sp_wc_v1()
>>> fluxes.spl
spl(0.0, 225.0, 225.0, 225.0, 225.0, 0.0, 300.0, 0.0)
>>> fluxes.wcl
wcl(0.0, 75.0, 75.0, 75.0, 75.0, 0.0, 0.0, 300.0)
>>> states.sp
sp(0.0, 375.0, 375.0, 375.0, 375.0, 60.0, 500.0, 0.0)
>>> states.wc
wc(0.0, 125.0, 125.0, 125.0, 125.0, 20.0, 0.0, 500.0)

The above example deals with a single snow class. Here, we add a second snow class to illustrate that the total snow loss of each zone does not depend on its average snow storage but the degree of exceedance of SMax within its individual snow classes:

>>> sclass(2)
>>> states.sp = [[600.0, 600.0, 600.0, 600.0, 600.0, 60.0, 800.0, 0.0],
...              [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]]
>>> states.wc = [[200.0, 200.0, 200.0, 200.0, 200.0, 20.0, 0.0, 800.0],
...              [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]]
>>> model.calc_spl_wcl_sp_wc_v1()
>>> fluxes.spl
spl(0.0, 112.5, 112.5, 112.5, 112.5, 0.0, 150.0, 0.0)
>>> fluxes.wcl
wcl(0.0, 37.5, 37.5, 37.5, 37.5, 0.0, 0.0, 150.0)
>>> states.sp
sp([[0.0, 375.0, 375.0, 375.0, 375.0, 60.0, 500.0, 0.0],
    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
>>> states.wc
wc([[0.0, 125.0, 125.0, 125.0, 125.0, 20.0, 0.0, 500.0],
    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
class hydpy.models.hland.hland_model.Calc_SPG_WCG_SP_WC_V1[source]

Bases: Method

Calculate the subbasin-internal redistribution gains of the snow layer.

Requires the control parameters:

NmbZones SClass ZoneType SFDist SMax SRed

Requires the derived parameters:

RelLandArea RelZoneAreas ZoneAreaRatios IndicesZoneZ SRedNumber SRedOrder SRedEnd

Requires the flux sequences:

SPL WCL

Updates the state sequences:

WC SP

Calculates the flux sequences:

SPG WCG

Calculates the aide sequences:

SPE WCE

Basic equations:

\(\frac{dSP}{dt} = -SPG\)

\(\frac{dWC}{dt} = -WCG\)

Examples:

We prepare an example consisting of seven zones, sorted by (non-strictly) descending elevation. For now, there is a single snow class per zone, and the zones’ areas are identical (1.0 km²). The last zone is of type ILAKE and does not participate in snow redistribution. We use the same configuration for SMax (the maximum snow storage) and SRed (defining the redistribution paths) throughout all examples:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> area(7.0)
>>> nmbzones(7)
>>> sclass(1)
>>> zonetype(GLACIER, FIELD, FOREST, SEALED, FOREST, FIELD, ILAKE)
>>> zonez(30.0, 25.0, 20.0, 15.0, 10.0, 10.0, 5.0)
>>> zonearea(1.0)
>>> psi(1.0)
>>> sfdist(1.0)
>>> smax(500.0)
>>> sred([[0.0, 0.2, 0.2, 0.2, 0.2, 0.2, 0.0],
...       [0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.5, 0.5, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])

For convenience, we prepare a function that updates all relevant derived parameters:

>>> def update():
...     derived.rellandarea.update()
...     derived.relzoneareas.update()
...     derived.rellowerzonearea.update()
...     derived.zonearearatios.update()
...     derived.indiceszonez.update()
...     derived.sredorder.update()
...     derived.srednumber.update()
...     derived.sredend.update()
>>> update()

In the first example, the total snow water equivalent (300 mm) is way below SRed (500 mm). Hence, all frozen (SPL) and liquid (WCL) water released deposits completely in the target zones:

>>> states.sp = 200.0
>>> states.wc = 100.0
>>> fluxes.spl = 20.0, 20.0, 20.0, 20.0, 0.0, 0.0, 0.0
>>> fluxes.wcl = 10.0, 10.0, 10.0, 10.0, 0.0, 0.0, 0.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(0.0, 4.0, 24.0, 24.0, 14.0, 14.0, 0.0)
>>> fluxes.wcg
wcg(0.0, 2.0, 12.0, 12.0, 7.0, 7.0, 0.0)
>>> states.sp
sp(200.0, 204.0, 224.0, 224.0, 214.0, 214.0, 0.0)
>>> states.wc
wc(100.0, 102.0, 112.0, 112.0, 107.0, 107.0, 0.0)

The following test function checks that method Calc_SPG_WCG_SP_WC_V1 does not introduce any water balance errors:

>>> from hydpy import repr_
>>> def check(sp_old, wc_old):
...     def check_vector(deltas):
...         return numpy.max(numpy.abs(numpy.sum(deltas, axis=0)))
...     sp_new = states.sp.average_values()
...     sp_delta_l = fluxes.spl.average_values()
...     sp_delta_g = fluxes.spg.average_values()
...     sp_old_array = numpy.array(6 * [sp_old] + [0.0])
...     wc_new = states.wc.average_values()
...     wc_delta_l = fluxes.wcl.average_values()
...     wc_delta_g = fluxes.wcg.average_values()
...     wc_old_array = numpy.array(6 * [wc_old] + [0.0])
...     errors = [sp_old + sp_delta_l - sp_new,
...               sp_delta_l - sp_delta_g,
...               check_vector(sp_old_array + fluxes.spg - states.sp),
...               wc_old + wc_delta_l - wc_new,
...               wc_delta_l - wc_delta_g,
...               check_vector(wc_old_array + fluxes.wcg - states.wc)]
...     print(*(repr_(error) for error in errors), sep=", ")

The possible errors related to different aspects of the frozen and the liquid water content of the snow layer are all within the range of the given numerical precision:

>>> check(sp_old=200.0, wc_old=100.0)
0.0, 0.0, 0.0, 0.0, 0.0, 0.0

Next, we increase the size of the first area and decrease the size of the second area by the same amount. The different results for SPG and WCG reflect that the loss terms (SPL and WCL) relate to the sizes of the supplying zones while the gain terms (SPG and WCG) relate to the sizes of the receiving zones:

>>> zonearea(1.5, 0.5, 1.0, 1.0, 1.0, 1.0, 1.0)
>>> update()
>>> states.sp = 200.0
>>> states.wc = 100.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(0.0, 12.0, 16.0, 26.0, 16.0, 16.0, 0.0)
>>> fluxes.wcg
wcg(0.0, 6.0, 8.0, 13.0, 8.0, 8.0, 0.0)
>>> states.sp
sp(200.0, 212.0, 216.0, 226.0, 216.0, 216.0, 0.0)
>>> states.wc
wc(100.0, 106.0, 108.0, 113.0, 108.0, 108.0, 0.0)
>>> check(sp_old=200.0, wc_old=100.0)
0.0, 0.0, 0.0, 0.0, 0.0, 0.0

When modelling high mountain areas, even the lowest zones (the so-called “dead-ends”) can receive substantial amounts of redistributed snow. Therefore, the simple “from top to bottom” approach described so far can result in unrealistic snow towers for these dead-ends, especially if their size is small compared to the size of the snow-delivering area. To prevent such artefacts, method Calc_SPG_WCG_SP_WC_V1 takes the total snow amount of all dead-ends exceeding the SMax threshold and distributes it gradually to the other zones, starting from the lowest in the order defined by parameter IndicesZoneZ:

>>> zonearea(1.0)
>>> update()
>>> states.sp = 400.0
>>> states.wc = 75.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(0.0, 13.333333, 16.666667, 16.666667, 16.666667, 16.666667, 0.0)
>>> fluxes.wcg
wcg(0.0, 6.666667, 8.333333, 8.333333, 8.333333, 8.333333, 0.0)
>>> states.sp
sp(400.0, 413.333333, 416.666667, 416.666667, 416.666667, 416.666667,
   0.0)
>>> states.wc
wc(75.0, 81.666667, 83.333333, 83.333333, 83.333333, 83.333333, 0.0)
>>> check(sp_old=400.0, wc_old=75.0)
0.0, 0.0, 0.0, 0.0, 0.0, 0.0

If the total snow amount of all zone reaches SMax, Calc_SPG_WCG_SP_WC_V1 distributes all remaining excess evenly to all non-lake zones:

>>> states.sp = 400.0
>>> states.wc = 90.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(13.333333, 13.333333, 13.333333, 13.333333, 13.333333, 13.333333,
    0.0)
>>> fluxes.wcg
wcg(6.666667, 6.666667, 6.666667, 6.666667, 6.666667, 6.666667, 0.0)
>>> states.sp
sp(413.333333, 413.333333, 413.333333, 413.333333, 413.333333,
   413.333333, 0.0)
>>> states.wc
wc(96.666667, 96.666667, 96.666667, 96.666667, 96.666667, 96.666667, 0.0)
>>> check(sp_old=400.0, wc_old=90.0)
0.0, 0.0, 0.0, 0.0, 0.0, 0.0

Introducing multiple snow classes within each zone complicates things. We repeat some of the above examples with an increased number of snow classes:

>>> sclass(2)
>>> update()

The “normal” snow redistribution relies similarly on parameter SFDist as the snowfall accumulation does. We show this by repeating the first example with the most extreme configuration of SFDist, where the second snow class receives the entire amount of incoming snow:

>>> sfdist(0.0, 2.0)
>>> states.sp = 200.0
>>> states.wc = 100.0
>>> fluxes.spl = 20.0, 20.0, 20.0, 20.0, 0.0, 0.0, 0.0
>>> fluxes.wcl = 10.0, 10.0, 10.0, 10.0, 0.0, 0.0, 0.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(0.0, 4.0, 24.0, 24.0, 14.0, 14.0, 0.0)
>>> fluxes.wcg
wcg(0.0, 2.0, 12.0, 12.0, 7.0, 7.0, 0.0)
>>> states.sp
sp([[200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 0.0],
    [200.0, 208.0, 248.0, 248.0, 228.0, 228.0, 0.0]])
>>> states.wc
wc([[100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 0.0],
    [100.0, 104.0, 124.0, 124.0, 114.0, 114.0, 0.0]])

During the eventual “bottom to top” re-redistribution, on the other hand, the fractions between the gains of individual snow classes do not depend on SFDist but their remaining capacities:

>>> states.sp = 400.0
>>> states.wc = 75.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(0.0, 13.333333, 16.666667, 16.666667, 16.666667, 16.666667, 0.0)
>>> fluxes.wcg
wcg(0.0, 6.666667, 8.333333, 8.333333, 8.333333, 8.333333, 0.0)
>>> states.sp
sp([[400.0, 412.280702, 416.666667, 416.666667, 416.666667, 416.666667,
     0.0],
    [400.0, 414.385965, 416.666667, 416.666667, 416.666667, 416.666667,
     0.0]])
>>> states.wc
wc([[75.0, 81.140351, 83.333333, 83.333333, 83.333333, 83.333333, 0.0],
    [75.0, 82.192982, 83.333333, 83.333333, 83.333333, 83.333333, 0.0]])
>>> check(sp_old=400.0, wc_old=75.0)
0.0, 0.0, 0.0, 0.0, 0.0, 0.0

During a subbasin-wide excess of SMax, all snow classes of a specific zone handle the same total snow water equivalent:

>>> states.sp = 400.0
>>> states.wc = 90.0
>>> model.calc_spg_wcg_sp_wc_v1()
>>> fluxes.spg
spg(13.333333, 13.333333, 13.333333, 13.333333, 13.333333, 13.333333,
    0.0)
>>> fluxes.wcg
wcg(6.666667, 6.666667, 6.666667, 6.666667, 6.666667, 6.666667, 0.0)
>>> states.sp
sp([[413.333333, 413.333333, 413.333333, 413.333333, 413.333333,
     413.333333, 0.0],
    [413.333333, 413.333333, 413.333333, 413.333333, 413.333333,
     413.333333, 0.0]])
>>> states.wc
wc([[96.666667, 96.666667, 96.666667, 96.666667, 96.666667, 96.666667,
     0.0],
    [96.666667, 96.666667, 96.666667, 96.666667, 96.666667, 96.666667,
     0.0]])
>>> check(sp_old=400.0, wc_old=90.0)
0.0, 0.0, 0.0, 0.0, 0.0, 0.0
class hydpy.models.hland.hland_model.Calc_CFAct_V1[source]

Bases: Method

Adjust the day degree factor for snow to the current day of the year.

Requires the control parameters:

NmbZones ZoneType CFMax CFVar

Requires the derived parameter:

DOY

Requires the fixed parameter:

Pi

Calculates the factor sequence:

CFAct

Basic equations:

\(CFAct = max( CFMax + f \cdot CFVar, 0 )\)

\(f = sin(2 \cdot Pi \cdot (DOY + 1) / 366) / 2\)

Examples:

We initialise five zones of different types but the same values for CFMax and CFVar. For internal lakes, CFAct is always zero. In all other cases, results are identical and follow a sinusoid curve throughout the year (of which we show only selected points as the maximum around June 20 and the minimum around December 20):

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED)
>>> cfmax(4.0)
>>> cfvar(3.0)
>>> from hydpy import UnitTest
>>> test = UnitTest(model=model,
...                 method=model.calc_cfact_v1,
...                 last_example=10,
...                 parseqs=(derived.doy, factors.cfact))
>>> test.nexts.doy = 0, 1, 170, 171, 172, 353, 354, 355, 364, 365
>>> test()
| ex. |                     doy |                                       cfact |
-------------------------------------------------------------------------------
|   1 |   0    0    0    0    0 | 0.0  1.264648  1.264648  1.264648  1.264648 |
|   2 |   1    1    1    1    1 | 0.0  1.267289  1.267289  1.267289  1.267289 |
|   3 | 170  170  170  170  170 | 0.0  2.749762  2.749762  2.749762  2.749762 |
|   4 | 171  171  171  171  171 | 0.0  2.749976  2.749976  2.749976  2.749976 |
|   5 | 172  172  172  172  172 | 0.0  2.749969  2.749969  2.749969  2.749969 |
|   6 | 353  353  353  353  353 | 0.0  1.250238  1.250238  1.250238  1.250238 |
|   7 | 354  354  354  354  354 | 0.0  1.250024  1.250024  1.250024  1.250024 |
|   8 | 355  355  355  355  355 | 0.0  1.250031  1.250031  1.250031  1.250031 |
|   9 | 364  364  364  364  364 | 0.0  1.260018  1.260018  1.260018  1.260018 |
|  10 | 365  365  365  365  365 | 0.0  1.262224  1.262224  1.262224  1.262224 |

Now, we convert all zones to type FIELD and vary CFVar. If we set CFVar to zero, CFAct always equals CFMax (see zone one). If we change the sign of CFVar, the sinusoid curve shifts a half year to reflect the southern hemisphere’s annual cycle of radiation (compare zone two and three). Finally, Calc_CFAct_V1 prevents negative values of CFAct by setting them to zero (see zone four and five):

>>> zonetype(FIELD)
>>> cfvar(0.0, 3.0, -3.0, 10.0, -10.0)
>>> test()
| ex. |                     doy |                                       cfact |
-------------------------------------------------------------------------------
|   1 |   0    0    0    0    0 | 2.0  1.264648  2.735352       0.0  4.451173 |
|   2 |   1    1    1    1    1 | 2.0  1.267289  2.732711       0.0  4.442371 |
|   3 | 170  170  170  170  170 | 2.0  2.749762  1.250238  4.499206       0.0 |
|   4 | 171  171  171  171  171 | 2.0  2.749976  1.250024  4.499919       0.0 |
|   5 | 172  172  172  172  172 | 2.0  2.749969  1.250031  4.499896       0.0 |
|   6 | 353  353  353  353  353 | 2.0  1.250238  2.749762       0.0  4.499206 |
|   7 | 354  354  354  354  354 | 2.0  1.250024  2.749976       0.0  4.499919 |
|   8 | 355  355  355  355  355 | 2.0  1.250031  2.749969       0.0  4.499896 |
|   9 | 364  364  364  364  364 | 2.0  1.260018  2.739982       0.0  4.466606 |
|  10 | 365  365  365  365  365 | 2.0  1.262224  2.737776       0.0  4.459252 |
class hydpy.models.hland.hland_model.Calc_Melt_SP_WC_V1[source]

Bases: Method

Calculate the melting of the ice content within the snow layer and update both the snow layers’ ice and the water content.

Requires the control parameters:

NmbZones SClass ZoneType

Requires the derived parameter:

TTM

Requires the factor sequences:

TC CFAct

Updates the state sequences:

WC SP

Calculates the flux sequence:

Melt

Basic equations:

\(\frac{dSP}{dt} = - Melt\)

\(\frac{dWC}{dt} = + Melt\)

\(Melt = min(CFAct \cdot (TC - TTM), SP)\)

Examples:

We initialise seven zones with the same threshold temperature and degree-day factor but different zone types and initial ice contents:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> sclass(1)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED, SEALED, SEALED)
>>> derived.ttm = 2.0
>>> factors.cfact(2.0)
>>> states.sp = 0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0
>>> states.wc = 2.0

When the actual temperature equals the threshold temperature for melting and refreezing, no melting occurs, and the states remain unchanged:

>>> factors.tc = 2.0
>>> model.calc_melt_sp_wc_v1()
>>> fluxes.melt
melt(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sp
sp(0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0)
>>> states.wc
wc(0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0)

The same holds for an actual temperature lower than the threshold temperature:

>>> states.sp = 0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0
>>> states.wc = 2.0
>>> factors.tc = -1.0
>>> model.calc_melt_sp_wc_v1()
>>> fluxes.melt
melt(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sp
sp(0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0)
>>> states.wc
wc(0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0)

With an actual temperature of 3°C above the threshold temperature, melting can occur. The actual melting is consistent with potential melting, except for the first zone, an internal lake, and the last two zones, for which potential melting exceeds the available frozen water content of the snow layer:

>>> states.sp = 0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0
>>> states.wc = 2.0
>>> factors.tc = 5.0
>>> model.calc_melt_sp_wc_v1()
>>> fluxes.melt
melt(0.0, 6.0, 6.0, 6.0, 6.0, 5.0, 0.0)
>>> states.sp
sp(0.0, 4.0, 4.0, 4.0, 4.0, 0.0, 0.0)
>>> states.wc
wc(0.0, 8.0, 8.0, 8.0, 8.0, 7.0, 2.0)

In the above examples, we did not divide the zones into snow classes. If we do so, method Calc_Melt_SP_WC_V1 assumes a uniform distribution of the potential melting among the individual classes. This assumption implies that if a single snow class does not provide enough frozen water, the actual melting of the total zone must be smaller than its potential melt rate:

>>> sclass(2)
>>> states.sp = [[0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 0.0],
...              [0.0, 10.0, 10.0, 10.0, 10.0, 10.0, 0.0]]
>>> states.wc = [[0.0], [2.0]]
>>> model.calc_melt_sp_wc_v1()
>>> fluxes.melt
melt([[0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 0.0],
      [0.0, 6.0, 6.0, 6.0, 6.0, 6.0, 0.0]])
>>> states.sp
sp([[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
    [0.0, 4.0, 4.0, 4.0, 4.0, 4.0, 0.0]])
>>> states.wc
wc([[0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 0.0],
    [0.0, 8.0, 8.0, 8.0, 8.0, 8.0, 2.0]])
class hydpy.models.hland.hland_model.Calc_Refr_SP_WC_V1[source]

Bases: Method

Calculate refreezing of the water content within the snow layer and update both the snow layers’ ice and the water content.

Requires the control parameters:

NmbZones SClass ZoneType CFR CFMax

Requires the derived parameter:

TTM

Requires the factor sequence:

TC

Updates the state sequences:

WC SP

Calculates the flux sequence:

Refr

Basic equations:

\(\frac{dSP}{dt} = + Refr\)

\(\frac{dWC}{dt} = - Refr\)

\(Refr = min(cfr \cdot cfmax \cdot (TTM - TC), WC)\)

Examples:

We initialise seven zones with the same threshold temperature, degree-day factor and refreezing coefficient but different zone types and initial states:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> sclass(1)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED, SEALED, SEALED)
>>> cfmax(4.0)
>>> cfr(0.1)
>>> derived.ttm = 2.0
>>> states.sp = 2.0
>>> states.wc = 0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0

Note that the assumed length of the simulation step is half a day. Hence the effective value of the degree-day factor is not 4 but 2:

>>> cfmax
cfmax(4.0)
>>> from hydpy import round_
>>> round_(cfmax.values[0])
2.0

When the actual temperature equals the threshold temperature for melting and refreezing, no refreezing occurs, and the states remain unchanged:

>>> factors.tc = 2.0
>>> model.calc_refr_sp_wc_v1()
>>> fluxes.refr
refr(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sp
sp(0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0)
>>> states.wc
wc(0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0)

The same holds for an actual temperature higher than the threshold temperature:

>>> states.sp = 2.0
>>> states.wc = 0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0
>>> factors.tc = 2.0
>>> model.calc_refr_sp_wc_v1()
>>> fluxes.refr
refr(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sp
sp(0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0)
>>> states.wc
wc(0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0)

With an actual temperature of 3°C above the threshold temperature, there is no refreezing:

>>> states.sp = 2.0
>>> states.wc = 0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0
>>> factors.tc = 5.0
>>> model.calc_refr_sp_wc_v1()
>>> fluxes.refr
refr(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sp
sp(0.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0)
>>> states.wc
wc(0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0)

With an actual temperature of 3°C below the threshold temperature, refreezing can occur. Actual refreezing is consistent with potential refreezing, except for the first zone, an internal lake, and the last two zones, for which potential refreezing exceeds the available liquid water content of the snow layer:

>>> states.sp = 2.0
>>> states.wc = 0.0, 1.0, 1.0, 1.0, 1.0, 0.5, 0.0
>>> factors.tc = -1.0
>>> model.calc_refr_sp_wc_v1()
>>> fluxes.refr
refr(0.0, 0.6, 0.6, 0.6, 0.6, 0.5, 0.0)
>>> states.sp
sp(0.0, 2.6, 2.6, 2.6, 2.6, 2.5, 2.0)
>>> states.wc
wc(0.0, 0.4, 0.4, 0.4, 0.4, 0.0, 0.0)

In the above examples, we did not divide the zones into snow classes. If we do so, method Calc_Refr_SP_WC_V1 assumes a uniform distribution of the potential refreezing among the individual classes. This assumption implies that if a single snow class does not provide enough liquid water, the actual refreezing of the total zone must be smaller than its potential refreezing rate:

>>> sclass(2)
>>> states.sp = [[0.0], [2.0]]
>>> states.wc = [[0.0, 0.0, 0.1, 0.2, 0.3, 0.4, 0.0],
...              [0.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.0]]
>>> model.calc_refr_sp_wc_v1()
>>> fluxes.refr
refr([[0.0, 0.0, 0.1, 0.2, 0.3, 0.4, 0.0],
      [0.0, 0.6, 0.6, 0.6, 0.6, 0.6, 0.0]])
>>> states.sp
sp([[0.0, 0.0, 0.1, 0.2, 0.3, 0.4, 0.0],
    [0.0, 2.6, 2.6, 2.6, 2.6, 2.6, 2.0]])
>>> states.wc
wc([[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
    [0.0, 0.4, 0.4, 0.4, 0.4, 0.4, 0.0]])
class hydpy.models.hland.hland_model.Calc_In_WC_V1[source]

Bases: Method

Calculate the actual water release from the snow layer due to the exceedance of the snow layers’ capacity for (liquid) water.

Requires the control parameters:

NmbZones SClass ZoneType WHC

Requires the flux sequence:

TF

Requires the state sequence:

SP

Updates the state sequence:

WC

Calculates the flux sequence:

In_

Basic equations:

\(\frac{dWC}{dt} = -In\)

\(-In = max(WC - WHC \cdot SP, 0)\)

Examples:

We initialise seven zones of different types with different frozen water contents of the snow layer and set the relative water holding capacity to 20 %:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> sclass(1)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED, SEALED, SEALED)
>>> whc(0.2)
>>> states.sp = 0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0

Also, we set the actual value of stand precipitation to 5 mm/d:

>>> fluxes.tf = 5.0

When there is no (liquid) water content in the snow layer, no water can be released:

>>> states.wc = 0.0
>>> model.calc_in_wc_v1()
>>> fluxes.in_
in_(5.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.wc
wc(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)

When there is a (liquid) water content in the snow layer, the water release depends on the frozen water content. Note the special cases of the first zone being an internal lake, for which the snow routine does not apply, and of the last zone, which has no ice content and thus effectively is not a snow layer:

>>> states.wc = 5.0
>>> model.calc_in_wc_v1()
>>> fluxes.in_
in_(5.0, 3.0, 3.0, 3.0, 3.0, 4.0, 5.0)
>>> states.wc
wc(0.0, 2.0, 2.0, 2.0, 2.0, 1.0, 0.0)

For a relative water holding capacity of zero, the snow layer releases all liquid water immediately:

>>> whc(0.0)
>>> states.wc = 5.0
>>> model.calc_in_wc_v1()
>>> fluxes.in_
in_(5.0, 5.0, 5.0, 5.0, 5.0, 5.0, 5.0)
>>> states.wc
wc(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)

In the above examples, we did not divide the zones into snow classes. If we do so, method Calc_In_WC_V1 averages the water release of all snow classes of each zone:

>>> sclass(2)
>>> whc(0.0)
>>> states.sp = 0.0, 10.0, 10.0, 10.0, 10.0, 5.0, 0.0
>>> states.wc = [[2.0], [3.0]]
>>> model.calc_in_wc_v1()
>>> fluxes.in_
in_(5.0, 2.5, 2.5, 2.5, 2.5, 2.5, 2.5)
>>> states.wc
wc([[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])

For the single lake zone, method Calc_In_WC_V1 passed the stand precipitation directly to In_ in all examples.

class hydpy.models.hland.hland_model.Calc_SWE_V1[source]

Bases: Method

Calculate the total snow water equivalent.

Requires the control parameters:

NmbZones SClass ZoneType

Requires the state sequences:

SP WC

Calculates the factor sequence:

SWE

Basic equation:

\(SWE = SP + WC\)

Example:

We initialise five zones of different types, each one with two snow classes. For internal lakes, Calc_SWE_V1 generally sets the snow water equivalent to zero. For all others, the given basic equation applies:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(5)
>>> sclass(2)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED)
>>> states.wc = [[0.1, 0.2, 0.3, 0.4, 0.5], [0.6, 0.7, 0.8, 0.9, 1.0]]
>>> states.sp = [[1.0, 2.0, 3.0, 4.0, 5.0], [6.0, 7.0, 8.0, 9.0, 10.0]]
>>> model.calc_swe_v1()
>>> factors.swe
swe([[0.0, 2.2, 3.3, 4.4, 5.5],
     [0.0, 7.7, 8.8, 9.9, 11.0]])
class hydpy.models.hland.hland_model.Calc_SR_V1[source]

Bases: Method

Calculate the sealed surface runoff.

Requires the control parameters:

NmbZones ZoneType

Requires the flux sequence:

In_

Calculates the flux sequence:

SR

Basic equations:
\[\begin{split}SR = \begin{cases} In &|\ ZoneType_k = SEALED \\ 0 &|\ ZoneType_k \neq SEALED \end{cases}\end{split}\]

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(5)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED)
>>> fluxes.in_ = 1.0
>>> fluxes.sr = 2.0
>>> model.calc_sr_v1()
>>> fluxes.sr
sr(0.0, 0.0, 0.0, 0.0, 1.0)
class hydpy.models.hland.hland_model.Calc_GAct_V1[source]

Bases: Method

Adjust the day degree factor for glacier ice to the current day of the year.

Requires the control parameters:

NmbZones ZoneType GMelt GVar

Requires the derived parameter:

DOY

Requires the fixed parameter:

Pi

Calculates the factor sequence:

GAct

Basic equations:

\(GAct = max( GMelt + f \cdot GVar, 0 )\)

\(f = sin(2 \cdot Pi \cdot (DOY + 1) / 366) / 2\)

Examples:

The following examples agree with the ones Calc_CFAct_V1, except that method Calc_GAct_V1 applies the given basic equations only for zones of types GLACIER and sets GAct to zero for all other zone types:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(ILAKE, GLACIER, FIELD, FOREST, SEALED)
>>> gmelt(4.0)
>>> gvar(3.0)
>>> from hydpy import UnitTest
>>> test = UnitTest(model=model,
...                 method=model.calc_gact_v1,
...                 last_example=10,
...                 parseqs=(derived.doy, factors.gact))
>>> test.nexts.doy = 0, 1, 170, 171, 172, 353, 354, 355, 364, 365
>>> test()
| ex. |                     doy |                          gact |
-----------------------------------------------------------------
|   1 |   0    0    0    0    0 | 0.0  1.264648  0.0  0.0   0.0 |
|   2 |   1    1    1    1    1 | 0.0  1.267289  0.0  0.0   0.0 |
|   3 | 170  170  170  170  170 | 0.0  2.749762  0.0  0.0   0.0 |
|   4 | 171  171  171  171  171 | 0.0  2.749976  0.0  0.0   0.0 |
|   5 | 172  172  172  172  172 | 0.0  2.749969  0.0  0.0   0.0 |
|   6 | 353  353  353  353  353 | 0.0  1.250238  0.0  0.0   0.0 |
|   7 | 354  354  354  354  354 | 0.0  1.250024  0.0  0.0   0.0 |
|   8 | 355  355  355  355  355 | 0.0  1.250031  0.0  0.0   0.0 |
|   9 | 364  364  364  364  364 | 0.0  1.260018  0.0  0.0   0.0 |
|  10 | 365  365  365  365  365 | 0.0  1.262224  0.0  0.0   0.0 |
>>> zonetype(GLACIER)
>>> gvar(0.0, 3.0, -3.0, 10.0, -10.0)
>>> test()
| ex. |                     doy |                                        gact |
-------------------------------------------------------------------------------
|   1 |   0    0    0    0    0 | 2.0  1.264648  2.735352       0.0  4.451173 |
|   2 |   1    1    1    1    1 | 2.0  1.267289  2.732711       0.0  4.442371 |
|   3 | 170  170  170  170  170 | 2.0  2.749762  1.250238  4.499206       0.0 |
|   4 | 171  171  171  171  171 | 2.0  2.749976  1.250024  4.499919       0.0 |
|   5 | 172  172  172  172  172 | 2.0  2.749969  1.250031  4.499896       0.0 |
|   6 | 353  353  353  353  353 | 2.0  1.250238  2.749762       0.0  4.499206 |
|   7 | 354  354  354  354  354 | 2.0  1.250024  2.749976       0.0  4.499919 |
|   8 | 355  355  355  355  355 | 2.0  1.250031  2.749969       0.0  4.499896 |
|   9 | 364  364  364  364  364 | 2.0  1.260018  2.739982       0.0  4.466606 |
|  10 | 365  365  365  365  365 | 2.0  1.262224  2.737776       0.0  4.459252 |
class hydpy.models.hland.hland_model.Calc_GlMelt_In_V1[source]

Bases: Method

Calculate the melting of non-snow-covered glaciers and add it to the water release of the snow module.

Requires the control parameters:

NmbZones SClass ZoneType

Requires the derived parameter:

TTM

Requires the factor sequences:

TC GAct

Requires the state sequence:

SP

Updates the flux sequence:

In_

Calculates the flux sequence:

GlMelt

Basic equation:
\[\begin{split}GlMelt = \begin{cases} max(GMelt \cdot (TC - TTM), 0) &|\ SP = 0 \\ 0 &|\ SP > 0 \end{cases}\end{split}\]

Examples:

We prepare eight zones. The first four zones are no glaciers, a snow layer covers the sixth zone, and the last two zones actual temperature is not above the threshold temperature. Hence, glacier melting occurs only in the fifth zone:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(8)
>>> sclass(1)
>>> zonetype(FIELD, FOREST, ILAKE, SEALED, GLACIER, GLACIER, GLACIER, GLACIER)
>>> derived.ttm(2.0)
>>> factors.tc = 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 2.0, 1.0
>>> factors.gact = 2.0
>>> states.sp = 0.0, 0.0, 0.0, 0.0, 0.0, 0.1, 0.0, 0.0
>>> fluxes.in_ = 3.0
>>> model.calc_glmelt_in_v1()
>>> fluxes.glmelt
glmelt(0.0, 0.0, 0.0, 0.0, 2.0, 0.0, 0.0, 0.0)
>>> fluxes.in_
in_(3.0, 3.0, 3.0, 3.0, 5.0, 3.0, 3.0, 3.0)

In the above examples, we did not divide the zones into snow classes. If we do so, method Calc_GlMelt_In_V1 sums the glacier melt of all non-snow-covered snow classes of each glacier zone. This assumption implies that if there is a single snow-covered snow class, the actual glacier melting of the total zone must be smaller than its potential melt rate:

>>> sclass(2)
>>> factors.tc = 3.0
>>> fluxes.in_ = 3.0
>>> states.sp = [[0.0, 0.0, 0.1, 0.1, 0.0, 0.0, 0.1, 0.1],
...              [0.0, 0.1, 0.0, 0.1, 0.0, 0.1, 0.0, 0.1]]
>>> model.calc_glmelt_in_v1()
>>> fluxes.glmelt
glmelt(0.0, 0.0, 0.0, 0.0, 2.0, 1.0, 1.0, 0.0)
>>> fluxes.in_
in_(3.0, 3.0, 3.0, 3.0, 5.0, 4.0, 4.0, 3.0)
class hydpy.models.hland.hland_model.Calc_R_SM_V1[source]

Bases: Method

Calculate effective precipitation and update the soil moisture.

Requires the control parameters:

NmbZones ZoneType FC Beta

Requires the flux sequence:

In_

Updates the state sequence:

SM

Calculates the flux sequence:

R

Basic equations:

\(\frac{dSM}{dt} = IN - R\)

\(R = IN \cdot \left( \frac{SM}{FC} \right)^{Beta}\)

Examples:

We initialise seven zones of different types. The field capacity of all fields and forests is 200 mm, the input of each zone is 10 mm:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> zonetype(ILAKE, GLACIER, SEALED, FIELD, FIELD, FOREST, FOREST)
>>> fc(200.0)
>>> fluxes.in_ = 10.0

With the typical nonlinearity parameter value of 2, relative soil moisture of 50 % (zones five and six) results in a discharge coefficient of 25 %. For a completely dried (zone four) or saturated soil (zone seven), the discharge coefficient is generally 0 % and 100 %, respectively. Glaciers, internal lakes and sealed areas always route 100% of their input as effective precipitation:

>>> beta(2.0)
>>> states.sm = 0.0, 0.0, 0.0, 0.0, 100.0, 100.0, 200.0
>>> model.calc_r_sm_v1()
>>> fluxes.r
r(10.0, 10.0, 10.0, 0.0, 2.5, 2.5, 10.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 10.0, 107.5, 107.5, 200.0)

By decreasing the nonlinearity parameter, the discharge coefficient increases. A parameter value of zero leads to a discharge coefficient of 100 % for any soil moisture:

>>> beta(0.0)
>>> states.sm = 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0
>>> model.calc_r_sm_v1()
>>> fluxes.r
r(10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0)

Also, with a field capacity of zero, the discharge coefficient always equates to 100 %:

>>> fc(0.0)
>>> beta(2.0)
>>> states.sm = 0.0
>>> model.calc_r_sm_v1()
>>> fluxes.r
r(10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_CF_SM_V1[source]

Bases: Method

Calculate capillary flow and update the soil moisture.

Requires the control parameters:

NmbZones ZoneType FC CFlux

Requires the flux sequence:

R

Requires the state sequence:

UZ

Updates the state sequence:

SM

Calculates the flux sequence:

CF

Basic equations:

\(\frac{dSM}{dt} = CF\)

\(CF = CFLUX \cdot (1 - \frac{SM}{FC})\)

Examples:

We initialise seven zones of different types. For all fields and forests, the field capacity is 200 mm and the maximum capillary flow rate is 4 mm/d:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> zonetype(ILAKE, GLACIER, SEALED, FIELD, FOREST, FOREST, FOREST)
>>> fc(200.0)
>>> cflux(4.0)

Note that the assumed length of the simulation step is only half a day. Hence the maximum capillary flow per simulation step is 2 instead of 4:

>>> cflux
cflux(4.0)
>>> from hydpy import round_
>>> round_(cflux.values[0])
2.0

For fields and forests, the actual capillary return flow depends only on the relative soil moisture deficit, provided that the upper zone layer stores enough water or that enough “routable” effective precipitation is available:

>>> fluxes.r = 0.0
>>> states.sm = 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0
>>> states.uz = 20.0
>>> model.calc_cf_sm_v1()
>>> fluxes.cf
cf(0.0, 0.0, 0.0, 1.0, 1.0, 2.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 101.0, 101.0, 2.0, 200.0)
>>> states.sm = 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0
>>> states.uz = 0.0
>>> model.calc_cf_sm_v1()
>>> fluxes.cf
cf(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0)

If the upper zone layer is empty and no effective precipitation is available, capillary flow is zero:

>>> fluxes.r = 0.0
>>> states.sm = 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0
>>> states.uz = 0.0
>>> model.calc_cf_sm_v1()
>>> fluxes.cf
cf(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0)

In the following example, both the upper zone layer and effective precipitation provide water for the capillary flow but less than the maximum flow rate times the relative soil moisture:

>>> fluxes.r = 0.1
>>> states.sm = 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0
>>> states.uz = 0.2
>>> model.calc_cf_sm_v1()
>>> fluxes.cf
cf(0.0, 0.0, 0.0, 0.3, 0.3, 0.3, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 100.3, 100.3, 0.3, 200.0)

Even unrealistic high maximum capillary flow rates do not result in overfilled soils:

>>> cflux(1000.0)
>>> fluxes.r = 200.0
>>> states.sm = 0.0, 0.0, 0.0, 100.0, 100.0, 0.0, 200.0
>>> states.uz = 200.0
>>> model.calc_cf_sm_v1()
>>> fluxes.cf
cf(0.0, 0.0, 0.0, 100.0, 100.0, 200.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 200.0, 200.0, 200.0, 200.0)

For soils with zero field capacity, capillary flow is always zero:

>>> fc(0.0)
>>> states.sm = 0.0
>>> model.calc_cf_sm_v1()
>>> fluxes.cf
cf(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_EA_SM_AETModel_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate soil evapotranspiration and adjust the soil water content.

Required by the method:

Calc_EA_SM_V1

Requires the control parameters:

NmbZones ZoneType FC

Updates the flux sequence:

R

Updates the state sequence:

SM

Calculates the flux sequence:

EA

Basic equation:

\(\frac{dSM_i}{dt} = -EA_i\)

Examples:

We build an example based on evap_aet_hbv96 for calculating soil evapotranspiration:

>>> from hydpy.models.hland_96 import *
>>> parameterstep("1h")
>>> nmbzones(5)
>>> zonetype(GLACIER, SEALED, FIELD, FOREST, ILAKE)
>>> area(1.0)
>>> zonearea(0.05, 0.1, 0.2, 0.3, 0.35)
>>> zonez(5.0)
>>> fc(50.0)
>>> fluxes.r = 0.5
>>> with model.add_aetmodel_v1("evap_aet_hbv96"):
...     soilmoisturelimit(0.0)
...     excessreduction(field=0.5, forest=0.0)

Calc_EA_SM_AETModel_V1 uses the flux returned by the submodel to adjust SM:

>>> model.aetmodel.sequences.fluxes.potentialinterceptionevaporation = 1.0
>>> model.aetmodel.sequences.fluxes.potentialsoilevapotranspiration = 1.0
>>> model.aetmodel.sequences.fluxes.interceptionevaporation = 1.0
>>> states.sm = 3.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, 0.5, 1.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 2.5, 2.0, 0.0)
>>> fluxes.r
r(0.5, 0.5, 0.5, 0.5, 0.5)

Calc_EA_SM_AETModel_V1 eventually reduces EA so that SM does not become negative:

>>> model.aetmodel.sequences.fluxes.potentialinterceptionevaporation = 5.0
>>> model.aetmodel.sequences.fluxes.potentialsoilevapotranspiration = 5.0
>>> model.aetmodel.sequences.fluxes.interceptionevaporation = 5.0
>>> states.sm = 3.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, 2.5, 3.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.5, 0.0, 0.0)
>>> fluxes.r
r(0.5, 0.5, 0.5, 0.5, 0.5)

Calc_EA_SM_AETModel_V1 converts any amounts of condensation (negative EA) that would cause soil water to exceed field capacity to the effective soil response (R):

>>> model.aetmodel.sequences.fluxes.potentialinterceptionevaporation = -5.0
>>> model.aetmodel.sequences.fluxes.potentialsoilevapotranspiration = -5.0
>>> model.aetmodel.sequences.fluxes.interceptionevaporation = -5.0
>>> states.sm = 47.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, -2.5, -5.0, 0.0)
>>> states.sm
sm(0.0, 0.0, 49.5, 50.0, 0.0)
>>> fluxes.r
r(0.5, 0.5, 0.5, 2.5, 0.5)
class hydpy.models.hland.hland_model.Calc_EA_SM_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate soil evapotranspiration and adjust the soil water content.

Required submethod:

Calc_EA_SM_AETModel_V1

Requires the control parameters:

NmbZones ZoneType FC

Updates the flux sequence:

R

Updates the state sequence:

SM

Calculates the flux sequence:

EA

class hydpy.models.hland.hland_model.Calc_InUZ_V1[source]

Bases: Method

Accumulate the total inflow into the upper zone layer.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelUpperZoneArea

Requires the flux sequences:

R CF

Calculates the flux sequence:

InUZ

Basic equation:
\[\begin{split}InUZ = \sum_{k=1}^{NmbZones} \frac{RelZoneAreas_k}{RelUpperZoneArea} \cdot \begin{cases} R-CF &|\ ZoneType_k \in \{FIELD, FOREST, GLACIER \} \\ 0 &|\ ZoneType_k \notin \{FIELD, FOREST, GLACIER \} \end{cases}\end{split}\]

Examples:

We initialise five zones of different land-use types and sizes. Method Calc_InUZ_V1 takes only those of type FIELD, FOREST, and GLACIER into account:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, ILAKE, GLACIER, SEALED)
>>> derived.relzoneareas = 0.25, 0.2, 0.4, 0.05, 0.1
>>> derived.relupperzonearea = 0.5
>>> fluxes.r = 2.0, 4.0, 1.0, 6.0, 1.0
>>> fluxes.cf = 1.0, 2.0, 0.5, 3.0, 0.5
>>> model.calc_inuz_v1()
>>> fluxes.inuz
inuz(1.6)

Internal lakes and sealed areas do not contribute to the upper zone layer. Hence, for a subbasin consisting only of such zones, InUZ is zero:

>>> zonetype(ILAKE, ILAKE, ILAKE, SEALED, SEALED)
>>> model.calc_inuz_v1()
>>> fluxes.inuz
inuz(0.0)
class hydpy.models.hland.hland_model.Calc_SUZ_V1[source]

Bases: Method

Add the effective precipitation to the upper storage reservoir.

Requires the control parameters:

NmbZones ZoneType

Requires the flux sequence:

R

Updates the state sequence:

SUZ

Basic equation:

\(\frac{SUZ}{dt} = R\)

Example:

For internal lakes and sealed areas, method Calc_SUZ_V1 always sets SUZ to zero:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep()
>>> nmbzones(4)
>>> zonetype(FIELD, ILAKE, GLACIER, SEALED)
>>> states.suz = 1.0, 0.0, 2.0, 0.0
>>> fluxes.r = 2.0
>>> model.calc_suz_v1()
>>> states.suz
suz(3.0, 0.0, 4.0, 0.0)
class hydpy.models.hland.hland_model.Calc_ContriArea_V1[source]

Bases: Method

Determine the relative size of the contributing area of the whole subbasin.

Requires the control parameters:

RespArea NmbZones ZoneType FC Beta

Requires the derived parameters:

RelZoneAreas RelSoilArea

Requires the state sequence:

SM

Calculates the factor sequence:

ContriArea

Basic equation:

\(ContriArea = \left( \frac{SM}{FC} \right)^{Beta}\)

Examples:

We initialise five zones. Method Calc_ContriArea_V1 takes only the first two zones of type field and forest into account (even though glaciers also contribute to the inflow of the upper zone layer):

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> beta(2.0)
>>> fc(200.0)
>>> resparea(True)
>>> derived.relzoneareas(1.0/6.0, 2.0/6.0, 1.0/6.0, 1.0/6.0, 1.0/6.0)
>>> derived.relsoilarea(0.5)

With relative soil moisture of 100 % in the whole subbasin, the contributing area is also 100 %:

>>> states.sm = 200.0
>>> model.calc_contriarea_v1()
>>> factors.contriarea
contriarea(1.0)

Relative soil moistures of 0 % result in a contributing area of 0 %:

>>> states.sm = 0.0
>>> model.calc_contriarea_v1()
>>> factors.contriarea
contriarea(0.0)

For the given value 2 of the nonlinearity parameter Beta, soil moisture of 50 % corresponds to contributing area of 25 %:

>>> states.sm = 100.0
>>> model.calc_contriarea_v1()
>>> factors.contriarea
contriarea(0.25)

Setting the RespArea option to False, the soil area (total area of all field and forest zones in the subbasin) to zero, or all field capacities to zero, results in contributing area values of 100 %:

>>> resparea(False)
>>> model.calc_contriarea_v1()
>>> factors.contriarea
contriarea(1.0)
>>> resparea(True)
>>> derived.relsoilarea(0.0)
>>> model.calc_contriarea_v1()
>>> factors.contriarea
contriarea(1.0)
>>> derived.relsoilarea(0.5)
>>> fc(0.0)
>>> states.sm = 0.0
>>> model.calc_contriarea_v1()
>>> factors.contriarea
contriarea(1.0)
class hydpy.models.hland.hland_model.Calc_Q0_Perc_UZ_V1[source]

Bases: Method

Calculate the percolation and direct runoff leaving the upper zone storage and update it accordingly.

Requires the control parameters:

RecStep PercMax K Alpha

Requires the derived parameter:

DT

Requires the factor sequence:

ContriArea

Requires the flux sequence:

InUZ

Updates the state sequence:

UZ

Calculates the flux sequences:

Perc Q0

Basic equations:

\(\frac{dUZ}{dt} = InUZ - Perc - Q0\)

\(Perc = PercMax \cdot ContriArea\)

\(Q0 = K \cdot \left( \frac{UZ}{ContriArea} \right)^{1+Alpha}\)

Note that the system behaviour of this method depends strongly on the specifications of the options RespArea and RecStep.

Examples:

First, we prepare a small helper function for checking if method Calc_Q0_Perc_UZ_V1 always complies with the water balance equation, assuming an initial content of the upper zone storage of 1 mm:

>>> from hydpy import round_
>>> def check():
...     error = 1.0 + fluxes.inuz - fluxes.perc - fluxes.q0 - states.uz
...     assert round(error, 12) == 0

The upper zone layer routine is an exception compared to the other subroutines of hland regarding numerical accuracy. Method Calc_Q0_Perc_UZ_V1 divides each simulation step into substeps and solves each substep with the explicit Euler method. The more substeps involved, the more precise the numerical integration of the underlying ordinary differential equations. In the first example, we omit this option by setting the RecStep parameter, which defines the number of substeps, to one:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> recstep(2)
>>> derived.dt = 1/recstep
>>> percmax(2.0)
>>> alpha(1.0)
>>> k(2.0)
>>> factors.contriarea = 1.0
>>> fluxes.inuz = 0.0
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(1.0)
>>> fluxes.q0
q0(0.0)
>>> states.uz
uz(0.0)
>>> check()

Due to the sequential calculation of the upper zone routine, the upper zone storage drains completely through percolation, and no water remains for fast discharge response. By dividing the simulation step into 100 substeps, method Calc_Q0_Perc_UZ_V1 also calculates a considerable amount of direct runoff:

>>> recstep(200)
>>> derived.dt = 1.0/recstep
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.786934)
>>> fluxes.q0
q0(0.213066)
>>> states.uz
uz(0.0)
>>> check()

Note that the assumed length of the simulation step is half a day. Hence the effective values of the maximum percolation rate and the storage coefficient are not 2 but 1:

>>> percmax
percmax(2.0)
>>> k
k(2.0)
>>> percmax.value
1.0
>>> k.value
1.0

By decreasing the contributing area, one reduces percolation but increases the fast discharge response:

>>> factors.contriarea = 0.5
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.434108)
>>> fluxes.q0
q0(0.565892)
>>> states.uz
uz(0.0)
>>> check()

Without any contributing area, the complete amount of water stored in the upper zone layer is released as direct discharge immediately:

>>> factors.contriarea = 0.0
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.0)
>>> fluxes.q0
q0(1.0)
>>> states.uz
uz(0.0)
>>> check()

Resetting RecStep leads to more transparent results. Note that direct discharge drains the rest of the upper zone storage due to the storage coefficient’s large value and the numerical approximation’s low accuracy:

>>> recstep(2)
>>> factors.contriarea = 0.5
>>> derived.dt = 1.0/recstep
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.5)
>>> fluxes.q0
q0(0.5)
>>> states.uz
uz(0.0)
>>> check()

Applying a more reasonable storage coefficient leads to the following results:

>>> k(0.5)
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.5)
>>> fluxes.q0
q0(0.25)
>>> states.uz
uz(0.25)
>>> check()

Adding an input of 0.3 mm results in the same percolation value (which here is determined by the maximum percolation rate only) but increases the direct response (which always depends on the actual upper zone storage):

>>> fluxes.inuz = 0.3
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.5)
>>> fluxes.q0
q0(0.64)
>>> states.uz
uz(0.16)
>>> check()

Due to the same reasons, another increase in numerical accuracy has no impact on percolation but decreases the direct response:

>>> recstep(200)
>>> derived.dt = 1.0/recstep
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.5)
>>> fluxes.q0
q0(0.421708)
>>> states.uz
uz(0.378292)
>>> check()

If phases of capillary rise, InUZ is negative and constant throughout the complete simulation interval. However, if UZ runs dry during the simulation interval, it can no contribute to the capillary rise. To always comply with the water balance equation, method Calc_Q0_Perc_UZ_V1 reduces both Perc and Q0 by the same factor in such situations. Reducing InUZ would be more reasonable but would also require modifying CF and SM (and others?), which is way too much effort given the minor impact of this manipulation on the general simulation results. The following two examples show how the manipulation works if the capillary rise requires all (first example) or half (second example) of the available water.

>>> fluxes.inuz = -1.0
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.0)
>>> fluxes.q0
q0(0.0)
>>> states.uz
uz(0.0)
>>> check()
>>> fluxes.inuz = -0.5
>>> states.uz = 1.0
>>> model.calc_q0_perc_uz_v1()
>>> fluxes.perc
perc(0.323912)
>>> fluxes.q0
q0(0.176088)
>>> states.uz
uz(0.0)
>>> check()
class hydpy.models.hland.hland_model.Calc_DP_SUZ_V1[source]

Bases: Method

Calculate the deep percolation and remove it from the upper storage reservoir.

Requires the control parameters:

NmbZones ZoneType PercMax

Updates the state sequence:

SUZ

Calculates the flux sequence:

DP

Basic equation:

\(DP = min(PERCMax, SUZ)\)

\(\frac{SUZ}{dt} = -DP\)

\(\frac{SUZ}{dt} = -RS -RI\)

Example:

For internal lakes and sealed areas, method Calc_DP_SUZ_V1 always sets the values of DP and SUZ to zero:

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> nmbzones(9)
>>> zonetype(FIELD, FIELD, FIELD, FIELD, FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> percmax(4.8)
>>> states.suz = 0.0, 0.1, 0.2, 0.3, 0.4, 0.4, 0.4, 0.4, 0.4
>>> model.calc_dp_suz_v1()
>>> fluxes.dp
dp(0.0, 0.1, 0.2, 0.2, 0.2, 0.2, 0.2, 0.0, 0.0)
>>> states.suz
suz(0.0, 0.0, 0.0, 0.1, 0.2, 0.2, 0.2, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_QAb_QVs_BW_V1[source]

Bases: Method

Calculate the flow and the percolation from a two-outlet reservoir and update it.

Required by the methods:

Calc_QAb1_QVs1_BW1_V1 Calc_QAb2_QVs2_BW2_V1

Method Calc_QAb_QVs_BW_V1 is an “additional method” used by the “run methods” Calc_QAb1_QVs1_BW1_V1 and Calc_QAb2_QVs2_BW2_V1 for calculating the flow and the percolation from the surface water reservoir and the interflow reservoir, respectively. See the documentation on method Calc_QAb1_QVs1_BW1_V1 for further information.

class hydpy.models.hland.hland_model.Calc_QAb1_QVs1_BW1_V1[source]

Bases: Method

Calculate the flow and the percolation from the surface flow reservoir and update it.

Required submethod:

Calc_QAb_QVs_BW_V1

Requires the control parameters:

NmbZones ZoneType H1 TAb1 TVs1

Requires the flux sequence:

R

Updates the state sequence:

BW1

Calculates the flux sequences:

QAb1 QVs1

Basic equations:

\(\frac{dBW1}{dt} = R - QAb1 - QVs1\)

\(QAb1 = \frac{max(BW1 - H1, 0)}{TAb1}\)

\(QVs1 = \frac{BW1}{TVs1}\)

We follow the new COSERO implementation described in Kling et al. (2005) and Kling (2006) and solve the given ordinary differential equation under the assumption of constant inflow (R). Despite the simple appearance of the short equation, its solution is quite complicated due to the threshold H1 used (Kling et al. (2005) and Kling (2006) explain the math in some detail). Additionally, we allow setting either TAb1 or TVs1 to inf or zero, allowing for disabling certain surface flow reservoir functionalities. Consequently, our source code includes many branches, and extensive testing is required to get some confidence in its robustness. We verified each of the following tests with numerical integration results. You can find this independent test code in issue 68. Please tell us if you encounter a plausible combination of parameter values not adequately covered by our tests or source code.

Examples:

We prepare eight zones with identical values for the control parameters H1, TAb1, and TVs1. We only vary the inflow (R) and the initial state (BW1). For the first and the second zone, BW1 changes but remains permanently below H1. Hence, all water leaving the storage leaves via percolation. For the third and the fourth zone, BW1 also changes but is permanently above H1. Hence, there is a continuous generation of percolation and surface runoff. For the fifth and sixth zone, BW1 starts below and ends above H1 and the other way round. For the seventh and the eighth zone, inflow and outflow are balanced:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(8)
>>> zonetype(FIELD)
>>> h1(4.0)
>>> tab1(1.0)
>>> tvs1(2.0)
>>> fluxes.r = 0.0, 2.0, 0.0, 2.0, 5.0, 0.1, 0.5, 2.5
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 1.561119, 1.956437, 0.246114, 0.181758, 0.0, 1.0)
>>> fluxes.qvs1
qvs1(0.442398, 0.672805, 1.780559, 1.978219, 1.007586, 1.086805, 0.5,
     1.5)
>>> states.bw1
bw1(1.557602, 3.327195, 5.658322, 7.065344, 5.7463, 3.831437, 2.0, 6.0)

In the following examples, we keep the general configuration but set either TAb1 or TVs1 to inf or zero (you can replace inf with a high value and zero with a low value to confirm the correct “direction” of our handling of these special cases):

>>> infinity = inf
>>> zero = 0.0

Setting TAb1 to inf disables the surface runoff:

>>> tab1(infinity)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> fluxes.qvs1
qvs1(0.442398, 0.672805, 1.990793, 2.221199, 1.018414, 1.117516, 0.5,
     1.615203)
>>> states.bw1
bw1(1.557602, 3.327195, 7.009207, 8.778801, 5.981586, 3.982484, 2.0,
    6.884797)

Setting TAb1 to zero enforces that all water exceeding H1 becomes surface runoff immediately:

>>> tab1(zero)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 5.0, 6.0, 2.115471, 1.0, 0.0, 3.5)
>>> fluxes.qvs1
qvs1(0.442398, 0.672805, 0.884797, 1.0, 0.884529, 0.896317, 0.5, 1.0)
>>> states.bw1
bw1(1.557602, 3.327195, 3.115203, 4.0, 4.0, 3.203683, 2.0, 4.0)

Setting TVs1 to inf disables the percolation:

>>> tab1(1.0)
>>> tvs1(infinity)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 1.967347, 2.393469, 0.408182, 0.414775, 0.0, 1.319592)
>>> fluxes.qvs1
qvs1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.bw1
bw1(2.0, 4.0, 7.032653, 8.606531, 6.591818, 4.685225, 2.5, 7.180408)

Setting TAb1 to zero ensures that all availalbe water becomes percolation immediately:

>>> tvs1(zero)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> fluxes.qvs1
qvs1(2.0, 4.0, 9.0, 11.0, 7.0, 5.1, 2.5, 8.5)
>>> states.bw1
bw1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)

The following examples repeat the ones above for the edge case where the threshold value H1 is zero:

>>> h1(0.0)
>>> tvs1(2.0)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.703511, 1.09883, 3.165801, 3.561119, 1.691807, 1.778544,
     0.802341, 2.604682)
>>> fluxes.qvs1
qvs1(0.351756, 0.549415, 1.5829, 1.780559, 0.845904, 0.889272, 0.40117,
     1.302341)
>>> states.bw1
bw1(0.944733, 2.351756, 4.251299, 5.658322, 4.462289, 2.432184,
    1.296489, 4.592977)
>>> tab1(infinity)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> fluxes.qvs1
qvs1(0.442398, 0.672805, 1.990793, 2.221199, 1.018414, 1.117516, 0.5,
     1.615203)
>>> states.bw1
bw1(1.557602, 3.327195, 7.009207, 8.778801, 5.981586, 3.982484, 2.0,
    6.884797)
>>> tab1(zero)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(2.0, 4.0, 9.0, 11.0, 7.0, 5.1, 2.5, 8.5)
>>> fluxes.qvs1
qvs1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.bw1
bw1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> tab1(1.0)
>>> tvs1(infinity)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.786939, 1.213061, 3.541224, 3.967347, 1.852245, 1.988653,
     0.893469, 2.893469)
>>> fluxes.qvs1
qvs1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> states.bw1
bw1(1.213061, 2.786939, 5.458776, 7.032653, 5.147755, 3.111347,
    1.606531, 5.606531)
>>> tvs1(zero)
>>> states.bw1 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> fluxes.qvs1
qvs1(2.0, 4.0, 9.0, 11.0, 7.0, 5.1, 2.5, 8.5)
>>> states.bw1
bw1(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)

Calc_QAb1_QVs1_BW1_V1 processes forest and glacier zones like field zones but sets the values of QAb1, QVs1, and BW1 to zero for internal lakes and sealed areas:

>>> zonetype(FOREST, GLACIER, ILAKE, SEALED, FOREST, GLACIER, ILAKE, SEALED)
>>> h1(4.0)
>>> tab1(1.0)
>>> tvs1(2.0)
>>> fluxes.r = 2.0, 2.0, 2.0, 2.0, 2.5, 2.5, 2.5, 2.5
>>> states.bw1 = 2.0, 2.0, 2.0, 2.0, 6.0, 6.0, 6.0, 6.0
>>> model.calc_qab1_qvs1_bw1_v1()
>>> fluxes.qab1
qab1(0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0)
>>> fluxes.qvs1
qvs1(0.672805, 0.672805, 0.0, 0.0, 1.5, 1.5, 0.0, 0.0)
>>> states.bw1
bw1(3.327195, 3.327195, 0.0, 0.0, 6.0, 6.0, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_QAb2_QVs2_BW2_V1[source]

Bases: Method

Calculate the flow and the percolation from the interflow reservoir and update it.

Required submethod:

Calc_QAb_QVs_BW_V1

Requires the control parameters:

NmbZones ZoneType H2 TAb2 TVs2

Requires the flux sequence:

QVs1

Updates the state sequence:

BW2

Calculates the flux sequences:

QAb2 QVs2

Basic equations:

\(\frac{dBW2}{dt} = QVs1 - QAb2 - QVs2\)

\(QAb2 = \frac{max(BW2 - H2, 0)}{TAb2}\)

\(QVs2 = \frac{BW2}{TVs2}\)

Method Calc_QAb2_QVs2_BW2_V1 is functionally identical with method Calc_QAb1_QVs1_BW1_V1 and also relies on the “additional method” Calc_QAb_QVs_BW_V1. Please see the documentation on method Calc_QAb1_QVs1_BW1_V1, which provides more information and exhaustive example calculations.

Example:

We only repeat the first and the last example of the documentation on method Calc_QAb1_QVs1_BW1_V1 to verify that method Calc_QAb2_QVs2_BW2_V1 calls method Calc_QAb_QVs_BW_V1 correctly:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(8)
>>> zonetype(FIELD)
>>> h2(4.0)
>>> tab2(1.0)
>>> tvs2(2.0)
>>> fluxes.qvs1 = 0.0, 2.0, 0.0, 2.0, 5.0, 0.1, 0.5, 2.5
>>> states.bw2 = 2.0, 2.0, 9.0, 9.0, 2.0, 5.0, 2.0, 6.0
>>> model.calc_qab2_qvs2_bw2_v1()
>>> fluxes.qab2
qab2(0.0, 0.0, 1.561119, 1.956437, 0.246114, 0.181758, 0.0, 1.0)
>>> fluxes.qvs2
qvs2(0.442398, 0.672805, 1.780559, 1.978219, 1.007586, 1.086805, 0.5,
     1.5)
>>> states.bw2
bw2(1.557602, 3.327195, 5.658322, 7.065344, 5.7463, 3.831437, 2.0, 6.0)

Calc_QAb2_QVs2_BW2_V1 processes forest and glacier zones like field zones but sets the values of QAb2, QVs2, and BW2 to zero for internal lakes and sealed areas:

>>> zonetype(FOREST, GLACIER, ILAKE, SEALED, FOREST, GLACIER, ILAKE, SEALED)
>>> fluxes.qvs1 = 2.0, 2.0, 2.0, 2.0, 2.5, 2.5, 2.5, 2.5
>>> states.bw2 = 2.0, 2.0, 2.0, 2.0, 6.0, 6.0, 6.0, 6.0
>>> model.calc_qab2_qvs2_bw2_v1()
>>> fluxes.qab2
qab2(0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0)
>>> fluxes.qvs2
qvs2(0.672805, 0.672805, 0.0, 0.0, 1.5, 1.5, 0.0, 0.0)
>>> states.bw2
bw2(3.327195, 3.327195, 0.0, 0.0, 6.0, 6.0, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_RS_RI_SUZ_V1[source]

Bases: Method

Calculate the surface runoff and the interflow and remove them from the upper storage reservoir.

Requires the control parameters:

NmbZones ZoneType SGR

Requires the derived parameters:

W0 W1

Updates the state sequence:

SUZ

Calculates the flux sequences:

RS RI

Basic equation:

\(RS = (SUZ - SGR) \cdot (1 - W0)\)

\(RI = SUZ \cdot (1 - W1)\)

\(\frac{SUZ}{dt} = -(RS + RI)\)

Examples:

For internal lakes and sealed areas, method Calc_RS_RI_SUZ_V1 always sets the values of RS, RI, and SUZ to zero:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep()
>>> nmbzones(9)
>>> zonetype(FIELD, FIELD, FIELD, FIELD, FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> sgr(10.0)
>>> derived.w0 = 0.4
>>> derived.w1 = 0.8
>>> states.suz = 0.0, 5.0, 10.0, 15.0, 20.0, 20.0, 20.0, 20.0, 20.0
>>> model.calc_rs_ri_suz_v1()
>>> fluxes.rs
rs(0.0, 0.0, 0.0, 3.0, 6.0, 6.0, 6.0, 0.0, 0.0)
>>> fluxes.ri
ri(0.0, 1.0, 2.0, 3.0, 4.0, 4.0, 4.0, 0.0, 0.0)
>>> states.suz
suz(0.0, 4.0, 8.0, 9.0, 10.0, 10.0, 10.0, 0.0, 0.0)

Theoretically, the parallel calculation of RS and RI can result in negative values of SUZ. The checks implemented for the parameter classes K0 and K1 should prevent this problem. However, to be definitely on the safe side, method Calc_RS_RI_SUZ_V1 also checks if the final state of SUZ is negative and, when necessary, resets it to zero and reduces RS and RI accordingly (with the same fraction):

>>> derived.w0 = 0.1
>>> derived.w1 = 0.2
>>> states.suz = 0.0, 5.0, 10.0, 15.0, 20.0, 20.0, 20.0, 20.0, 20.0
>>> model.calc_rs_ri_suz_v1()
>>> fluxes.rs
rs(0.0, 0.0, 0.0, 4.909091, 10.8, 10.8, 10.8, 0.0, 0.0)
>>> fluxes.ri
ri(0.0, 4.0, 8.0, 13.090909, 19.2, 19.2, 19.2, 0.0, 0.0)
>>> states.suz
suz(0.0, 1.0, 2.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_LZ_V1[source]

Bases: Method

Add percolation from the upper zone layera and lake precipitation to the lower zone storage.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelUpperZoneArea RelLowerZoneArea RelZoneAreas

Requires the flux sequences:

Perc PC

Updates the state sequence:

LZ

Basic equation:
\[\begin{split}\frac{dLZ}{dt} = \frac{RelUpperZoneArea}{RelLowerZoneArea} \cdot Perc + \sum_{k=1}^{NmbZones} \frac{RelZoneAreas_k}{RelLowerZoneArea} \cdot \begin{cases} Pc_k &|\ ZoneType_k = ILAKE \\ 0 &|\ ZoneType_k \neq ILAKE \end{cases}\end{split}\]

Examples:

We define a subbasin with five zones of different land-use types and sizes:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> area(100.0)
>>> zonearea(10.0, 20.0, 30.0, 15.0, 25.0)
>>> psi(1.0)

To ensure the consistency of the values of the relevant derived parameters, we apply their update() methods:

>>> derived.relzoneareas.update()
>>> derived.relupperzonearea.update()
>>> derived.rellowerzonearea.update()

First, we set the precipitation intensity (PC) to 30 mm and the percolation intensity (Perc) to zero. Only the internal lake zone passes its value for PC directly to the lower zone layer. The fraction between its size (15 km²) and the extent of the lower zone layer (75 km²) is 1/5. Hence, the single zone’s input of 30 mm increases the lower zone layer’s water content by 6 mm:

>>> fluxes.pc = 30.0
>>> fluxes.perc = 0.0
>>> states.lz = 10.0
>>> model.calc_lz_v1()
>>> states.lz
lz(16.0)

Second, we set PC to zero and the percolation intensity to 5 mm. The fraction between the extents of the upper zone layer (60 km²) and the lower zone layer (75 km³) is 4/5. Hence, percolation released by the upper zone layer increases the content of the lower zone layer by 4 mm:

>>> fluxes.pc = 0.0
>>> fluxes.perc = 5.0
>>> model.calc_lz_v1()
>>> states.lz
lz(20.0)

In case the extent of the lower zone area is zero (which is possible for completely sealed subbasins only) method Calc_LZ_V1 sets LZ to zero:

>>> derived.rellowerzonearea(0.0)
>>> model.calc_lz_v1()
>>> states.lz
lz(0.0)
class hydpy.models.hland.hland_model.Calc_LZ_V2[source]

Bases: Method

Add percolation from the interflow reservoir and lake precipitation to the lower zone storage.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Requires the flux sequences:

QVs2 PC

Updates the state sequence:

LZ

Basic equation:
\[\begin{split}\frac{dLZ}{dt} = \sum_{k=1}^{NmbZones} \frac{RelZoneAreas_k}{RelLowerZoneArea} \cdot \begin{cases} QVs2_k &|\ ZoneType_k \in \{ FIELD, FOREST, GLACIER \} \\ Pc_k &|\ ZoneType_k = ILAKE \\ 0 &|\ ZoneType_k = SEALED \end{cases}\end{split}\]

Example:

The first three zones of type FIELD, FOREST, and GLACIER contribute via deep percolation to the lower zone reservoir. For the fourth zone of type ILAKE, precipitation contributes directly to the lower zone storage. The fifth zone of type SEALED does not contribute to the lower zone storage at all:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas = 0.24, 0.18, 0.12, 0.06, 0.4
>>> derived.rellowerzonearea = 0.6
>>> fluxes.qvs2 = 1.0, 2.0, 3.0, nan, nan
>>> fluxes.pc = nan, nan, nan, 14.0, nan
>>> states.lz = 5.0
>>> model.calc_lz_v2()
>>> states.lz
lz(8.0)
class hydpy.models.hland.hland_model.Calc_GR1_V1[source]

Bases: Method

Calculate the recharge to the fast response groundwater reservoir.

Requires the control parameters:

NmbZones ZoneType SG1Max K2

Requires the flux sequence:

DP

Updates the state sequence:

SG1

Calculates the flux sequence:

GR1

Basic equation:

\(GR1 = min \left(DP, \frac{SG1Max - SG1}{K2} \right)\)

Examples:

For internal lakes and sealed areas, method Calc_GR1_V1 always sets the values of GR1 and SG1 to zero:

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> nmbzones(9)
>>> zonetype(FIELD, FIELD, FIELD, FIELD, FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> sg1max(10.0)
>>> k2(10.0/24.0)
>>> from hydpy import round_
>>> round_(k2.values[0])
10.0
>>> fluxes.dp = 0.5
>>> states.sg1 = 0.0, 5.0, 9.0, 9.9, 10.0, 5.0, 5.0, 5.0, 5.0
>>> model.calc_gr1_v1()
>>> fluxes.gr1
gr1(0.5, 0.5, 0.1, 0.01, 0.0, 0.5, 0.5, 0.0, 0.0)

For unreasonably low values of parameter K2, the sum of SG1 and GR1 could theoretically become larger than SG1Max. We let method Calc_GR1_V1 reduce GR1 when necessary to ensure this does not happen:

>>> k2.values = 0.5
>>> states.sg1 = 0.0, 5.0, 9.0, 9.9, 10.0, 5.0, 5.0, 5.0, 5.0
>>> model.calc_gr1_v1()
>>> fluxes.gr1
gr1(0.5, 0.5, 0.5, 0.1, 0.0, 0.5, 0.5, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_RG1_SG1_V1[source]

Bases: Method

Calculate the discharge from the fast response groundwater reservoir and subtract it.

Requires the control parameters:

NmbZones ZoneType K2

Requires the derived parameter:

W2

Requires the flux sequence:

GR1

Updates the state sequence:

SG1

Calculates the flux sequence:

RG1

Basic equation:

\(SG1_{new} = W2 \cdot SG1_{old} + (1 - W2) \cdot K2 \cdot GR1\)

\(RG1 = SG1_{old} + GR1 - SG1_{new}\)

Example:

For internal lakes and sealed areas, method Calc_RG1_SG1_V1 always sets the values of GR1 and SG1 to zero:

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> zonetype(FIELD, FIELD, FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> k2(1.0/24, 10.0/24, 100.0/24, 100.0/24, 100.0/24, 100.0/24, 100.0/24)
>>> from hydpy import round_
>>> round_(k2.values)
1.442695, 10.0, 100.0, 100.0, 100.0, 100.0, 100.0
>>> derived.w2.update()
>>> fluxes.gr1 = 2.0
>>> states.sg1 = 5.0
>>> model.calc_rg1_sg1_v1()
>>> fluxes.rg1
rg1(3.057305, 0.572561, 0.059718, 0.059718, 0.059718, 0.0, 0.0)
>>> states.sg1
sg1(3.942695, 6.427439, 6.940282, 6.940282, 6.940282, 0.0, 0.0)
class hydpy.models.hland.hland_model.Calc_GR2_GR3_V1[source]

Bases: Method

Calculate the recharge of the first-order and the second-order slow response groundwater reservoir.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Requires the fixed parameter:

FSG

Requires the flux sequences:

PC DP GR1

Calculates the flux sequences:

GR2 GR3

Basic equations:
\[\begin{split}GRT = \sum_{k=1}^{NmbZones} \frac{RelZoneAreas_k}{RelLowerZoneArea} \cdot \begin{cases} DP_k - GR1_k &|\ ZoneType_k \in \{ FIELD, FOREST, GLACIER \} \\ Pc_k &|\ ZoneType_k = ILAKE \\ 0 &|\ ZoneType_k = SEALED \end{cases}\end{split}\]

\(GR2 = FSG \cdot GRT\)

\(GR3 = (1 - FSG) \cdot GRT\)

Example:

Method Calc_GR2_GR3_V1 aggregates the given input (term “GRT” in the given basic equations) divides it between GR2 and GR3:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas(0.24, 0.18, 0.12, 0.06, 0.4)
>>> derived.rellowerzonearea(0.6)
>>> fluxes.gr1 = 1.0, 2.0, 3.0, nan, nan
>>> fluxes.dp = 4.0, 6.0, 8.0, nan, nan
>>> fluxes.pc = nan, nan, nan, 11.0, nan
>>> model.calc_gr2_gr3_v1()
>>> fluxes.gr2
gr2(4.0)
>>> fluxes.gr3
gr3(0.5)
class hydpy.models.hland.hland_model.Calc_EL_SG2_SG3_AETModel_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate lake evaporation and adjust the slow response groundwater reservoirs.

Required by the method:

Calc_EL_SG2_SG3_V1

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Requires the fixed parameter:

FSG

Updates the state sequences:

SG2 SG3

Calculates the flux sequence:

EL

Basic equations:

\(\frac{dSG2_i}{dt} = -FSG \cdot \frac{RelZoneAreas_i}{RelLowerZoneArea} \cdot EL_i\)

\(\frac{dSG3_i}{dt} = -(1 - FSG) \cdot \frac{RelZoneAreas_i}{RelLowerZoneArea} \cdot EL_i\)

Examples:

We build an example based on evap_aet_hbv96 for calculating lake evaporation:

>>> from hydpy.models.hland_96p import *
>>> parameterstep("1h")
>>> nmbzones(5)
>>> zonetype(GLACIER, SEALED, FIELD, FOREST, ILAKE)
>>> area(0.9)
>>> zonearea(0.2, 0.1, 0.1, 0.1, 0.4)
>>> psi(1.0)
>>> zonez(5.0)
>>> fc(50.0)
>>> derived.relzoneareas.update()
>>> derived.rellowerzonearea.update()
>>> factors.tc = 10.0
>>> with model.add_aetmodel_v1("evap_aet_hbv96"):
...     temperaturethresholdice(0.0)

Calc_EL_SG2_SG3_AETModel_V1 uses the flux returned by the submodel to adjust SG2 and SG3, considering the total extent of the groundwater-affected subarea and the fraction between the spatial extents of the first-order and the second-order slow response groundwater reservoir:

>>> model.aetmodel.sequences.fluxes.potentialwaterevaporation = 2.25
>>> states.sg2 = 3.0
>>> states.sg3 = 0.3
>>> model.calc_el_sg2_sg3_v1()
>>> fluxes.el
el(0.0, 0.0, 0.0, 0.0, 2.25)
>>> states.sg2
sg2(2.0)
>>> states.sg3
sg3(0.175)

Zones of type ILAKE are assumed to have an open water surface, so evaporation is always possible. Therefore, applying Calc_EL_SG2_SG3_AETModel_V1 can result in negative SG2 and SG3 values:

>>> model.aetmodel.sequences.fluxes.potentialwaterevaporation = 4.5
>>> states.sg2 = 1.0
>>> states.sg3 = 0.1
>>> model.calc_el_sg2_sg3_v1()
>>> fluxes.el
el(0.0, 0.0, 0.0, 0.0, 4.5)
>>> states.sg2
sg2(-1.0)
>>> states.sg3
sg3(-0.15)
class hydpy.models.hland.hland_model.Calc_EL_SG2_SG3_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate interception evaporation, soil evapotranspiration, and open water evaporation, and adjust the related interception, soil water, and slow response groundwater storages accordingly.

Required submethod:

Calc_EL_SG2_SG3_AETModel_V1

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Requires the fixed parameter:

FSG

Updates the state sequences:

SG2 SG3

Calculates the flux sequence:

EL

class hydpy.models.hland.hland_model.Calc_RG2_SG2_V1[source]

Bases: Method

Calculate the discharge from the first-order slow response groundwater reservoir and subtract it.

Requires the control parameter:

K3

Requires the derived parameter:

W3

Requires the flux sequence:

GR2

Updates the state sequence:

SG2

Calculates the flux sequence:

RG2

Basic equation:

\(SG2_{new} = W3 \cdot SG2_{old} + (1 - W3) \cdot K3 \cdot GR2\)

\(RG2 = SG2_{old} + GR2 - SG2_{new}\)

Examples:

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> k3(2.0/24)
>>> from hydpy import round_
>>> round_(k3.values)
2.0
>>> derived.w3.update()
>>> fluxes.gr2 = 2.0

For non-negative SG2 values, method Calc_RG2_SG2_V1 strictly follows the given base equation:

>>> states.sg2 = 5.0
>>> model.calc_rg2_sg2_v1()
>>> fluxes.rg2
rg2(2.393469)
>>> states.sg2
sg2(4.606531)

For negative SG2 values, it uses RG2 to fill the groundwater storage so that no discharge occurs:

>>> states.sg2 = -3.0
>>> model.calc_rg2_sg2_v1()
>>> fluxes.rg2
rg2(0.0)
>>> states.sg2
sg2(-1.0)
>>> states.sg2 = -2.0
>>> model.calc_rg2_sg2_v1()
>>> fluxes.rg2
rg2(0.0)
>>> states.sg2
sg2(0.0)

If the sum of SG2 and RG2 is positive, recharge first fills the deficit. In the remaining time, Calc_RG2_SG2_V1 handles the remaining recharge as implied by the basic equations (with parameters K3 and W3 adapted to the remaining time interval):

>>> states.sg2 = -1.0
>>> model.calc_rg2_sg2_v1()
>>> fluxes.rg2
rg2(0.115203)
>>> states.sg2
sg2(0.884797)
class hydpy.models.hland.hland_model.Calc_RG3_SG3_V1[source]

Bases: Method

Calculate the discharge from the second-order slow response groundwater reservoir and subtract it.

Requires the derived parameters:

K4 W4

Requires the flux sequence:

GR3

Updates the state sequence:

SG3

Calculates the flux sequence:

RG3

Basic equation:

\(SG3_{new} = W4 \cdot SG3_{old} + (1 - W4) \cdot K4 \cdot GR3\)

\(RG3 = SG3_{old} + GR3 - SG3_{new}\)

Examples:

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> derived.k4(1.0/24)
>>> from hydpy import round_
>>> round_(derived.k4.values)
1.0
>>> derived.w4.update()
>>> fluxes.gr3 = 2.0

For non-negative SG3 values, method Calc_RG3_SG3_V1 strictly follows the given base equation:

>>> states.sg3 = 5.0
>>> model.calc_rg3_sg3_v1()
>>> fluxes.rg3
rg3(3.896362)
>>> states.sg3
sg3(3.103638)

For negative SG3 values, it uses RG3 to fill the groundwater storage so that no discharge occurs:

>>> states.sg3 = -3.0
>>> model.calc_rg3_sg3_v1()
>>> fluxes.rg3
rg3(0.0)
>>> states.sg3
sg3(-1.0)
>>> states.sg3 = -2.0
>>> model.calc_rg3_sg3_v1()
>>> fluxes.rg3
rg3(0.0)
>>> states.sg3
sg3(0.0)

If the sum of SG3 and RG3 is positive, recharge first fills the deficit. In the remaining time, Calc_RG3_SG3_V1 handles the remaining recharge as implied by the basic equations (with parameters K4 and W4 adapted to the remaining time interval):

>>> states.sg3 = -1.0
>>> model.calc_rg3_sg3_v1()
>>> fluxes.rg3
rg3(0.213061)
>>> states.sg3
sg3(0.786939)
class hydpy.models.hland.hland_model.Calc_EL_LZ_AETModel_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate lake evaporation and adjust the lower zone’s water content.

Required by the method:

Calc_EL_LZ_V1

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Updates the state sequence:

LZ

Calculates the flux sequence:

EL

Basic equation:

\(\frac{dLZ_i}{dt} = -\frac{RelZoneAreas_i}{RelLowerZoneArea} \cdot EL_i\)

Examples:

We build an example based on evap_aet_hbv96 for calculating lake evaporation:

>>> from hydpy.models.hland_96 import *
>>> parameterstep("1h")
>>> nmbzones(5)
>>> zonetype(GLACIER, SEALED, FIELD, FOREST, ILAKE)
>>> area(0.9)
>>> zonearea(0.2, 0.1, 0.1, 0.1, 0.4)
>>> psi(1.0)
>>> zonez(5.0)
>>> fc(50.0)
>>> derived.relzoneareas.update()
>>> derived.rellowerzonearea.update()
>>> factors.tc = 10.0
>>> with model.add_aetmodel_v1("evap_aet_hbv96"):
...     temperaturethresholdice(0.0)

Calc_EL_LZ_AETModel_V1 uses the flux returned by the submodel to adjust LZ, considering the extent of the groundwater-affected subarea:

>>> model.aetmodel.sequences.fluxes.potentialwaterevaporation = 2.0
>>> states.lz = 3.0
>>> model.calc_el_lz_v1()
>>> fluxes.el
el(0.0, 0.0, 0.0, 0.0, 2.0)
>>> states.lz
lz(2.0)

Zones of type ILAKE are assumed to have an open water surface, so evaporation is always possible. Therefore, applying Calc_EL_LZ_AETModel_V1 can result in negative LZ values:

>>> model.aetmodel.sequences.fluxes.potentialwaterevaporation = 6.0
>>> states.lz = 1.0
>>> model.calc_el_lz_v1()
>>> fluxes.el
el(0.0, 0.0, 0.0, 0.0, 6.0)
>>> states.lz
lz(-2.0)
class hydpy.models.hland.hland_model.Calc_EL_LZ_V1[source]

Bases: Method

Let a submodel that follows the AETModel_V1 submodel interface calculate lake evaporation and adjust the lower zone’s water content.

Required submethod:

Calc_EL_LZ_AETModel_V1

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Updates the state sequence:

LZ

Calculates the flux sequence:

EL

class hydpy.models.hland.hland_model.Calc_Q1_LZ_V1[source]

Bases: Method

Calculate the slow response of the lower zone layer.

Requires the control parameters:

K4 Gamma

Updates the state sequence:

LZ

Calculates the flux sequence:

Q1

Basic equations:
\[\begin{split}Q1 = \begin{cases} K4 \cdot LZ^{1 + Gamma} &|\ LZ > 0 \\ 0 &|\ LZ \leq 0 \end{cases}\end{split}\]

\(\frac{dLZ}{dt} = -Q1\)

Examples:

As long as the lower zone storage is negative or zero, there is no slow discharge response:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> k4(0.2)
>>> gamma(0.0)
>>> states.lz = -2.0
>>> model.calc_q1_lz_v1()
>>> fluxes.q1
q1(0.0)
>>> states.lz
lz(-2.0)
>>> states.lz = 0.0
>>> model.calc_q1_lz_v1()
>>> fluxes.q1
q1(0.0)
>>> states.lz
lz(0.0)

For storage values above zero the linear or nonlinear storage routing equation applies:

>>> states.lz = 2.0
>>> model.calc_q1_lz_v1()
>>> fluxes.q1
q1(0.2)
>>> states.lz
lz(1.8)
>>> gamma(1.0)
>>> states.lz = 2.0
>>> model.calc_q1_lz_v1()
>>> fluxes.q1
q1(0.4)
>>> states.lz
lz(1.6)

Note that the assumed length of the simulation step is half a day. Hence the effective value of the storage coefficient is not 0.2 but 0.1:

>>> k4
k4(0.2)
>>> k4.value
0.1
class hydpy.models.hland.hland_model.Calc_InRC_V1[source]

Bases: Method

Calculate the input of the runoff concentration submodel.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelUpperZoneArea RelLowerZoneArea

Requires the flux sequences:

R Q0 Q1

Calculates the flux sequence:

InRC

Basic equation:
\[\begin{split}InRC = A_U \cdot Q0 + A_L \cdot Q1 + \sum_{k=1}^{N} A_Z^k \cdot \begin{cases} R &|\ T_Z^k = S \\ 0 &|\ T_Z^k \neq S \end{cases} \\ \\ N = NmbZones \\ A_U = RelUpperZoneArea \\ A_L = RelLowerZoneArea \\ A_Z = RelZoneAreas \\ T_Z = ZoneType \\ S = SEALED\end{split}\]

Example:

We define a subbasin with five zones of different land-use types and sizes:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> area(100.0)
>>> zonearea(10.0, 20.0, 30.0, 15.0, 25.0)
>>> psi(1.0)

To ensure the consistency of the values of the relevant derived parameters, we apply their update() methods:

>>> derived.relzoneareas.update()
>>> derived.relupperzonearea.update()
>>> derived.rellowerzonearea.update()

The runoff concentration submodel receives freshly generated runoff (R) directly from the sealed zone (0.5 mm), direct runoff (Q0) indirectly from the field, forest, and glacier zones (0.6 mm) and base flow (Q1) indirectly from the field, forest, glacier and internal lake zones (3.0 mm):

>>> fluxes.r = 2.0
>>> fluxes.q0 = 1.0
>>> fluxes.q1 = 4.0
>>> model.calc_inrc_v1()
>>> fluxes.inrc
inrc(4.1)
class hydpy.models.hland.hland_model.Calc_InRC_V2[source]

Bases: Method

Calculate the input of the runoff concentration submodel.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Requires the flux sequences:

R RS RI RG1 RG2 RG3

Calculates the flux sequence:

InRC

Basic equation:
\[\begin{split}InRC = A_L \cdot (RG2 + RG3) + \sum_{k=1}^{N} \begin{cases} RS + RI + RG1 &|\ T_Z^k \in \{FI, FO, G \} \\ R &|\ T_Z^k = S \\ 0 &|\ T_Z^k = L \end{cases} \\ \\ N = NmbZones \\ A_L = RelLowerZoneArea \\ Z_T = ZoneType \\ FI = FIELD \\ FO = FOREST \\ G = GLACIER \\ S = SEALED \\ L = ILAKE\end{split}\]

Example:

Besides adding all components, method Calc_InRC_V2 needs to aggregate the HRU level values of RS, RI, RG1, and R to the subbasin level:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas(0.35, 0.25, 0.15, 0.05, 0.2)
>>> derived.rellowerzonearea(0.8)
>>> fluxes.rs = 0.1, 0.2, 0.3, nan, nan
>>> fluxes.ri = 0.4, 0.6, 0.8, nan, nan
>>> fluxes.rg1 = 1.1, 1.4, 1.7, nan, nan
>>> fluxes.r = nan, nan, nan, nan, 2.0
>>> fluxes.rg2 = 3.0
>>> fluxes.rg3 = 4.0
>>> model.calc_inrc_v2()
>>> fluxes.inrc
inrc(7.53)
class hydpy.models.hland.hland_model.Calc_InRC_V3[source]

Bases: Method

Calculate the input of the runoff concentration submodel.

Requires the control parameters:

NmbZones ZoneType

Requires the derived parameters:

RelZoneAreas RelLandArea

Requires the flux sequences:

R QAb1 QAb2

Calculates the flux sequence:

InRC

Basic equation:
\[\begin{split}InRC = \sum_{k=1}^{N} \frac{A_Z^k}{A_L} \cdot \begin{cases} QAb1 + QAb2 &|\ T_Z^k \in \{FI, FO, G \} \\ R &|\ T_Z^k = S \\ 0 &|\ T_Z^k = L \end{cases} \\ \\ N = NmbZones \\ A_Z = RelZoneAreas \\ A_L = RelLandArea \\ T_Z = ZoneType \\ FI = FIELD \\ FO = FOREST \\ G = GLACIER \\ S = SEALED \\ L = ILAKE\end{split}\]

Example:

The runoff concentration submodel receives surface flow (QAb1 and QAb2) from the first three zones of type FIELD, FOREST, and GLACIER, receives directly generated runoff from the fifth zone of type SEALED, and receives nothing from the fourth zone of type ILAKE:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas = 0.35, 0.25, 0.15, 0.2, 0.05
>>> derived.rellandarea(0.8)
>>> fluxes.qab1 = 1.0, 2.0, 3.0, nan, nan
>>> fluxes.qab2 = 3.0, 6.0, 9.0, nan, nan
>>> fluxes.r = nan, nan, nan, nan, 8.0
>>> model.calc_inrc_v3()
>>> fluxes.inrc
inrc(7.0)
class hydpy.models.hland.hland_model.Calc_OutRC_RConcModel_V1[source]

Bases: Method

Let a submodel that follows the RConcModel_V1 submodel interface calculate runoff concentration.

Required by the method:

Calc_OutRC_V1

Requires the flux sequence:

InRC

Calculates the flux sequence:

OutRC

class hydpy.models.hland.hland_model.Calc_OutRC_V1[source]

Bases: Method

If the model has a submodel that follows the RConcModel_V1 submodel interface, calculate runoff concentration. If not, set the output equal to the input.

Required submethod:

Calc_OutRC_RConcModel_V1

Requires the flux sequence:

InRC

Calculates the flux sequence:

OutRC

Examples:

A model without a submodel for runoff concentration directs the input directly to the output:

>>> from hydpy.models.hland_96 import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> fluxes.inrc = 1.0
>>> model.calc_outrc_v1()
>>> fluxes.outrc
outrc(1.0)

If a submodel for runoff concentration is added (in this case, a unit hydrograph with three ordinates), the output for the first time step corresponds to the portion of the input specified by the first ordinate (since the initial conditions of the logging sequence QUH were set to zero, and thus no additional runoff portions from previous time steps are included):

>>> with model.add_rconcmodel_v1("rconc_uh"):
...     uh([0.3,0.4,0.3])
...     logs.quh = 0.0, 0.0, 0.0
>>> model.calc_outrc_v1()
>>> fluxes.outrc
outrc(0.3)
class hydpy.models.hland.hland_model.Calc_RT_V1[source]

Bases: Method

Calculate the total discharge in mm.

Requires the flux sequence:

OutRC

Calculates the flux sequence:

RT

Basic equation:

\(RT = OutRC\)

Examples:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> fluxes.outrc = 3.0
>>> model.calc_rt_v1()
>>> fluxes.rt
rt(3.0)
class hydpy.models.hland.hland_model.Calc_RT_V2[source]

Bases: Method

Calculate the total discharge in mm.

Requires the derived parameters:

RelLandArea RelLowerZoneArea

Requires the flux sequences:

OutRC Q1

Calculates the flux sequence:

RT

Basic equation:

\(RT = RelUpperZoneArea \cdot OutRC + RelLowerZoneArea \cdot Q1\)

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> derived.rellandarea(0.8)
>>> derived.rellowerzonearea(0.6)
>>> fluxes.outrc = 2.5
>>> fluxes.q1 = 1.0
>>> model.calc_rt_v2()
>>> fluxes.rt
rt(2.6)
class hydpy.models.hland.hland_model.Calc_QT_V1[source]

Bases: Method

Calculate the total discharge in m³/s.

Requires the derived parameter:

QFactor

Requires the flux sequence:

RT

Calculates the flux sequence:

QT

Basic equation:

\(QT = QFactor \cdot RT\)

Example:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> derived.qfactor(0.5)
>>> fluxes.rt = 2.0
>>> model.calc_qt_v1()
>>> fluxes.qt
qt(1.0)
class hydpy.models.hland.hland_model.Pass_Q_V1[source]

Bases: Method

Update the outlet link sequence.

Requires the flux sequence:

QT

Calculates the outlet sequence:

Q

class hydpy.models.hland.hland_model.Get_Temperature_V1[source]

Bases: Method

Get the selected zone’s current temperature.

Requires the factor sequence:

TC

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(2)
>>> factors.tc = 2.0, 4.0
>>> from hydpy import round_
>>> round_(model.get_temperature_v1(0))
2.0
>>> round_(model.get_temperature_v1(1))
4.0
class hydpy.models.hland.hland_model.Get_MeanTemperature_V1[source]

Bases: Method

Get the basin’s current mean temperature.

Requires the input sequence:

T

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> inputs.t = 2.0
>>> from hydpy import round_
>>> round_(model.get_meantemperature_v1())
2.0
class hydpy.models.hland.hland_model.Get_Precipitation_V1[source]

Bases: Method

Get the current precipitation from the selected zone.

Requires the flux sequence:

PC

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(2)
>>> fluxes.pc = 2.0, 4.0
>>> from hydpy import round_
>>> round_(model.get_precipitation_v1(0))
2.0
>>> round_(model.get_precipitation_v1(1))
4.0
class hydpy.models.hland.hland_model.Get_InterceptedWater_V1[source]

Bases: Method

Get the selected zone’s current amount of intercepted water.

Requires the state sequence:

Ic

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(2)
>>> states.ic = 2.0, 4.0
>>> from hydpy import round_
>>> round_(model.get_interceptedwater_v1(0))
2.0
>>> round_(model.get_interceptedwater_v1(1))
4.0
class hydpy.models.hland.hland_model.Get_SoilWater_V1[source]

Bases: Method

Get the selected zone’s current soil water content.

Requires the state sequence:

SM

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(2)
>>> states.sm = 2.0, 4.0
>>> from hydpy import round_
>>> round_(model.get_soilwater_v1(0))
2.0
>>> round_(model.get_soilwater_v1(1))
4.0
class hydpy.models.hland.hland_model.Get_SnowCover_V1[source]

Bases: Method

Get the selected zone’s current snow cover degree.

Requires the control parameter:

SClass

Requires the state sequence:

SP

Example:

Each snow class with a non-zero amount of snow counts as completely covered:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(3)
>>> sclass(2)
>>> states.sp = [[0.0, 0.0, 1.0], [0.0, 1.0, 1.0]]
>>> from hydpy import round_
>>> round_(model.get_snowcover_v1(0))
0.0
>>> round_(model.get_snowcover_v1(1))
0.5
>>> round_(model.get_snowcover_v1(2))
1.0
class hydpy.models.hland.hland_model.Main_AETModel_V1[source]

Bases: AdHocModel

Base class for HydPy-H models that use submodels that comply with the AETModel_V1 interface.

aetmodel: SubmodelProperty
aetmodel_is_mainmodel
aetmodel_typeid
add_aetmodel_v1

Initialise the given submodel that follows the AETModel_V1 interface and is responsible for calculating the different kinds of actual evapotranspiration.

>>> from hydpy.models.hland_96 import *
>>> parameterstep()
>>> nmbzones(5)
>>> area(10.0)
>>> zonetype(FIELD, FOREST, ILAKE, GLACIER, SEALED)
>>> zonearea(2.0)
>>> zonez(3.0)
>>> fc(200.0)
>>> with model.add_aetmodel_v1("evap_aet_hbv96"):
...     nmbhru
...     water
...     interception
...     soil
...     excessreduction(field=1.0, forest=0.5, default=nan)
...     for method, arguments in model.preparemethod2arguments.items():
...         print(method, arguments[0][0], sep=": ")
nmbhru(5)
water(field=False, forest=False, glacier=False, ilake=True,
      sealed=False)
interception(field=True, forest=True, glacier=False, ilake=False,
             sealed=True)
soil(field=True, forest=True, glacier=False, ilake=False, sealed=False)
prepare_nmbzones: 5
prepare_zonetypes: [1 2 4 3 5]
prepare_subareas: [2. 2. 2. 2. 2.]
prepare_elevations: [300. 300. 300. 300. 300.]
prepare_maxsoilwater: [200. 200. 200. 200. 200.]
prepare_water: [False False  True False False]
prepare_interception: [ True  True False False False]
prepare_plant: [ True  True False False False]
prepare_soil: [ True  True False False False]
>>> ered = model.aetmodel.parameters.control.excessreduction
>>> ered
excessreduction(field=1.0, forest=0.5)
>>> zonetype(FOREST, FIELD, ILAKE, GLACIER, SEALED)
>>> ered
excessreduction(field=0.5, forest=1.0)
>>> from hydpy import round_
>>> round_(ered.average_values())
0.75
REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Main_RConcModel_V1[source]

Bases: AdHocModel

Base class for HydPy-H models that use submodels that comply with the RConcModel_V1 interface.

rconcmodel: SubmodelProperty
rconcmodel_is_mainmodel
rconcmodel_typeid
add_rconcmodel_v1

Initialise the given submodel that follows the RConcModel_V1 interface and is responsible for calculating the runoff concentration.

>>> from hydpy.models.hland_96 import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> with model.add_rconcmodel_v1("rconc_uh"):
...     uh([0.3, 0.5, 0.2])
...     logs.quh.shape = 3
...     logs.quh = 1.0, 3.0, 0.0
>>> model.sequences.fluxes.inrc = 0.0
>>> model.calc_outrc_v1()
>>> fluxes.outrc
outrc(1.0)
REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Sub_TempModel_V1[source]

Bases: AdHocModel, TempModel_V1

Base class for HydPy-H models that comply with the TempModel_V1 submodel interface.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Sub_PrecipModel_V1[source]

Bases: AdHocModel, PrecipModel_V1

Base class for HydPy-H models that comply with the PrecipModel_V1 submodel interface.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Sub_IntercModel_V1[source]

Bases: AdHocModel, IntercModel_V1

Base class for HydPy-H models that comply with the IntercModel_V1 submodel interface.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Sub_SoilWaterModel_V1[source]

Bases: AdHocModel, SoilWaterModel_V1

Base class for HydPy-H models that comply with the SoilWaterModel_V1 submodel interface.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.hland.hland_model.Sub_SnowCoverModel_V1[source]

Bases: AdHocModel, SnowCoverModel_V1

Base class for HydPy-H models that comply with the SnowCoverModel_V1 submodel interface.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()

Parameter Features

Parameter tools

class hydpy.models.hland.hland_parameters.ParameterBase(subvars: SubParameters)[source]

Bases: ZipParameter

Base class for 1-dimensional parameters.

constants: dict[str, int] = {'FIELD': 1, 'FOREST': 2, 'GLACIER': 3, 'ILAKE': 4, 'SEALED': 5}

Mapping of the constants’ names and values.

property refweights

Reference to the associated instance of RelZoneAreas for calculating areal mean values.

name: str = 'parameterbase'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterComplete(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for all types of zones.

ParameterComplete applies the features of class ZipParameter on the land use types FIELD, FOREST, GLACIER, ILAKE, and SEALED and considers them all as relevant (e.g., for calculating weighted averages).

We use parameter PCorr as an example, which is a subclass of ParameterComplete. After preparing the parameter ZoneType, PCorr allows setting its values using the relevant land-use types as keywords:

>>> from hydpy import print_vector, round_
>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(6)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD, SEALED)
>>> pcorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0, sealed=5.0)
>>> pcorr
pcorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0, sealed=5.0)
>>> print_vector(pcorr.values)
2.0, 1.0, 4.0, 3.0, 2.0, 5.0

Parameter ZoneArea serves for calculating areal means (see the documentation on property refweights):

>>> zonearea.values = 0.0, 1.0, 2.0, 3.0, 4.0, 5.0
>>> round_(pcorr.average_values())
3.4

Alternatively, pass other masks defined in module hland_masks to take only certain types of zones into account:

>>> round_(pcorr.average_values(model.masks.field))
2.0
>>> round_(pcorr.average_values("soil"))
1.8
>>> round_(pcorr.average_values(model.masks.field, "forest"))
1.8

All other masks (for example, Soil, being used by ParameterSoil subclasses as IcMax) are subsets of mask Complete:

>>> icmax.mask in pcorr.mask
True
>>> pcorr.mask in icmax.mask
False
mask: masktools.IndexMask
name: str = 'parametercomplete'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterLand(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for FIELD, FOREST, GLACIER, and SEALED zones.

ParameterLand works similarly to ParameterComplete. Some examples based on the parameter WHC:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
>>> whc(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
>>> whc
whc(field=2.0, forest=1.0, glacier=4.0)
>>> whc(field=2.0, default=9.0)
>>> whc
whc(field=2.0, forest=9.0, glacier=9.0)
>>> zonearea.values = 1.0, 1.0, 1.0, nan, 1.0
>>> from hydpy import round_
>>> round_(whc.average_values())
5.5
mask: masktools.IndexMask
name: str = 'parameterland'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterInterception(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for FIELD, FOREST, and SEALED zones.

ParameterInterception works similarly to ParameterComplete. Some examples based on the parameter IcMax:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> icmax(field=2.0, forest=1.0, glacier=4.0, ilake=5.0, sealed=3.0)
>>> icmax
icmax(field=2.0, forest=1.0, sealed=3.0)
>>> icmax(field=2.0, default=8.0, sealed=3.0)
>>> icmax
icmax(field=2.0, forest=8.0, sealed=3.0)
>>> zonearea.values = 1.0, 2.0, nan, nan, 3.0
>>> from hydpy import round_
>>> round_(icmax.average_values())
4.5
mask: masktools.IndexMask
name: str = 'parameterinterception'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterSoil(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for FIELD and FOREST zones.

ParameterSoil works similarly to ParameterComplete. Some examples based on the parameter IcMax:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
>>> icmax(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
>>> icmax
icmax(field=2.0, forest=1.0)
>>> icmax(field=2.0, default=9.0)
>>> icmax
icmax(field=2.0, forest=9.0)
>>> zonearea.values = 0.0, 1.0, nan, nan, 3.0
>>> from hydpy import round_
>>> round_(icmax.average_values())
3.75
mask: masktools.IndexMask
name: str = 'parametersoil'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterUpperZone(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for FIELD, FOREST, and GLACIER zones.

ParameterLand works similarly to ParameterComplete. Some examples based on parameter H1:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(6)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD, SEALED)
>>> h1(field=2.0, forest=1.0, glacier=4.0, ilake=3.0, sealed=5.0)
>>> h1
h1(field=2.0, forest=1.0, glacier=4.0)
>>> h1(field=2.0, default=9.0)
>>> h1
h1(field=2.0, forest=9.0, glacier=9.0)
>>> zonearea.values = 1.0, 1.0, 1.0, nan, 1.0, nan
>>> from hydpy import round_
>>> round_(h1.average_values())
5.5
mask: masktools.IndexMask
name: str = 'parameterupperzone'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterGlacier(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for GLACIER zones.

ParameterGlacier works similarly to ParameterComplete. Some examples based on the parameter GMelt:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> simulationstep("1d")
>>> nmbzones(5)
>>> zonetype(GLACIER, FOREST, ILAKE, GLACIER, FIELD)
>>> gmelt(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
>>> gmelt
gmelt(4.0)
>>> gmelt(field=2.0, forest=9.0, default=8.0)
>>> gmelt
gmelt(8.0)
>>> zonearea.values = 1.0, nan, nan, 1.0, nan
>>> from hydpy import round_
>>> round_(gmelt.average_values())
8.0
mask: masktools.IndexMask
name: str = 'parameterglacier'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_parameters.ParameterNoGlacier(subvars: SubParameters)[source]

Bases: ParameterBase

Base class for 1-dimensional parameters relevant for FIELD, FOREST, and ILAKE zones.

ParameterNoGlacier works similarly to ParameterComplete. Some examples based on the parameter TCorr:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
>>> tcorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
>>> tcorr
tcorr(field=2.0, forest=1.0, ilake=3.0)
>>> tcorr(field=2.0, default=9.0)
>>> tcorr
tcorr(field=2.0, forest=9.0, ilake=9.0)
>>> zonearea.values = 1.0, 1.0, nan, 1.0, 1.0
>>> from hydpy import round_
>>> round_(tcorr.average_values())
5.5
mask: masktools.IndexMask
name: str = 'parameternoglacier'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

Constants

Base model hland allows dividing subbasins into zones (hydrological response units). It applies the equations related to some processes (for example, interception) separately for each zone. Consequently, parameters such as the interception capacity IcMax and sequences such as the actual interception storage Ic are 1-dimensional. Each entry represents the value of a different zone.

In contrast to the original HBV96 model, hland allows defining individual parameter values for each zone, which provides flexibility but might be a little overwhelming in many use cases. Hence, we also support the original HBV96-distinction into the zone types “field”, “forest”, “glacier”, and “ilake” (internal lake). In addition, we allow the designation of the type “sealed” (sealed area). Parameter “ZoneType” specifies the type of each response unit via one of the integer constants FIELD, FOREST, GLACIER, ILAKE, and SEALED. By performing a wildcard import, these constants become available in your local namespace:

>>> from hydpy.models.hland import *
>>> FIELD, FOREST, GLACIER, ILAKE, SEALED
(1, 2, 3, 4, 5)
hydpy.models.hland.hland_constants.FIELD = 1

Constant for the zone type field.

hydpy.models.hland.hland_constants.FOREST = 2

Constant for the zone type forest.

hydpy.models.hland.hland_constants.GLACIER = 3

Constant for the zone type glacier.

hydpy.models.hland.hland_constants.ILAKE = 4

Constant for the zone type internal lake.

hydpy.models.hland.hland_constants.SEALED = 5

Constant for the zone type sealed surface.

Control parameters

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

Bases: SubParameters

Control parameters of model hland.

The following classes are selected:
  • Area() Subbasin area [km²].

  • NmbZones() Number of zones (hydrological response units) in a subbasin [-].

  • SClass() Number of snow classes in each zone [-].

  • ZoneType() Type of each zone [-].

  • ZoneArea() Zone area [km²].

  • Psi() Fraction of the actual sealing of zones classified as SEALED [-].

  • ZoneZ() Zone elevation [100m].

  • PCorr() General precipitation correction factor [-].

  • PCAlt() Elevation correction factor for precipitation [1/100m].

  • RfCF() Rainfall correction factor [-].

  • SfCF() Snowfall correction factor [-].

  • TCorr() General temperature correction addend [-].

  • TCAlt() Elevation correction factor for temperature [-1°C/100m].

  • IcMax() Maximum interception storage [mm].

  • SFDist() Distribution of snowfall [-].

  • SMax() Maximum snow water equivalent [mm].

  • SRed() Snow redistribution paths [-].

  • TT() Temperature threshold for snow/rain [°C].

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

  • DTTM() Difference between TTM and TT [°C].

  • CFMax() Average degree day factor for snow (on glaciers or not) [mm/°C/T].

  • CFVar() Annual variability of CFMax [mm/°C/T].

  • GMelt() Degree day factor for glacial ice [mm/°C/T].

  • GVar() Annual variability of GMelt [mm/°C/T].

  • CFR() Refreezing factor for water stored within the snow layer [-].

  • WHC() Relative water holding capacity of the snow layer [-].

  • FC() Maximum soil moisture content (field capacity) [mm].

  • Beta() Nonlinearity parameter of the soil routine [-].

  • PercMax() Maximum percolation rate [mm/T].

  • CFlux() Capacity (maximum) of the capillary return flux [mm/T].

  • RespArea() Flag to enable the contributing area approach [-].

  • RecStep() Number of internal computation steps per simulation time step [-].

  • Alpha() Nonlinearity parameter of the upper zone layer [-].

  • K() Recession coefficient of the upper zone layer [1/T/mm^alpha].

  • SGR() Threshold content of SUZ for the generation of surface runoff [mm].

  • K0() Storage time for surface runoff [T].

  • H1() Outlet level of the reservoir for simulating surface flow [mm].

  • TAb1() Recession coefficient for simulating surface flow [T].

  • TVs1() Recession coefficient for simulating percolation from the surface flow module [T].

  • K1() Storage time for interflow [T].

  • SG1Max() Maximum content of the fast response groundwater reservoir SG1 [mm].

  • H2() Outlet level of the reservoir for simulating interflow [mm].

  • TAb2() Recession coefficient for simulating interflow [T].

  • TVs2() Recession coefficient for simulating percolation from the interflow module [T].

  • K4() Recession coefficient of the lower zone layer [1/T].

  • K2() Storage time for quick response baseflow [T].

  • K3() Storage time for delayed baseflow [T].

  • Gamma() Nonlinearity parameter of the lower zone layer [-].

class hydpy.models.hland.hland_control.Area(subvars: SubParameters)[source]

Bases: Parameter

Subbasin area [km²].

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (1e-10, None)
name: str = 'area'

Name of the variable in lowercase letters.

unit: str = 'km²'

Unit of the variable.

class hydpy.models.hland.hland_control.NmbZones(subvars: SubParameters)[source]

Bases: Parameter

Number of zones (hydrological response units) in a subbasin [-].

Required by the methods:

Calc_CFAct_V1 Calc_CF_SM_V1 Calc_ContriArea_V1 Calc_DP_SUZ_V1 Calc_EA_SM_AETModel_V1 Calc_EA_SM_V1 Calc_EI_Ic_AETModel_V1 Calc_EI_Ic_V1 Calc_EL_LZ_AETModel_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_FracRain_V1 Calc_GAct_V1 Calc_GR1_V1 Calc_GR2_GR3_V1 Calc_GlMelt_In_V1 Calc_InRC_V1 Calc_InRC_V2 Calc_InRC_V3 Calc_InUZ_V1 Calc_In_WC_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_Melt_SP_WC_V1 Calc_PC_V1 Calc_QAb1_QVs1_BW1_V1 Calc_QAb2_QVs2_BW2_V1 Calc_RFC_SFC_V1 Calc_RG1_SG1_V1 Calc_RS_RI_SUZ_V1 Calc_R_SM_V1 Calc_Refr_SP_WC_V1 Calc_SPG_WCG_SP_WC_V1 Calc_SPL_WCL_SP_WC_V1 Calc_SP_WC_V1 Calc_SR_V1 Calc_SUZ_V1 Calc_SWE_V1 Calc_TC_V1 Calc_TF_Ic_V1

NmbZones determines the length of most 1-dimensional parameters and sequences. Usually, you should first prepare NmbZones and define the values of all 1-dimensional parameters and sequences afterwards:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(5)
>>> icmax.shape
(5,)
>>> states.ic.shape
(5,)

Changing the value of NmbZones later reshapes the affected parameters and sequences and makes it necessary the reset their values:

>>> icmax(2.0)
>>> icmax
icmax(2.0)
>>> nmbzones(3)
>>> icmax
icmax(?)

Re-defining the same value does not delete the already available data:

>>> icmax(2.0)
>>> nmbzones(3)
>>> icmax
icmax(2.0)

The length of both axes of the 2-dimensional sequence SRed agree with NmbZones:

>>> sred.shape
(3, 3)

Some 2-dimensional sequences reflect differences in snow accumulation within each zone. NmbZones prepares their shapes also, but therefore requires parameter SClass to provide the number of snow classes within each zone:

>>> states.sp
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: Shape information for variable `sp` can only be retrieved after it has been defined.
>>> sclass.value = 2
>>> nmbzones(4)
>>> states.sp.shape
(2, 4)
NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (1, None)
name: str = 'nmbzones'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.SClass(subvars: SubParameters)[source]

Bases: Parameter

Number of snow classes in each zone [-].

Required by the methods:

Calc_GlMelt_In_V1 Calc_In_WC_V1 Calc_Melt_SP_WC_V1 Calc_Refr_SP_WC_V1 Calc_SPG_WCG_SP_WC_V1 Calc_SPL_WCL_SP_WC_V1 Calc_SP_WC_V1 Calc_SWE_V1 Get_SnowCover_V1

SClass determines the length of the first axis of those 2-dimensional sequences reflecting differences in snow accumulation within each zone. Therefore, it requires parameter NmbZones to provide the number of zones within the subbasin:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> sclass(1)
>>> states.sp
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: Shape information for variable `sp` can only be retrieved after it has been defined.
>>> nmbzones.value = 2
>>> sclass(3)
>>> states.sp.shape
(3, 2)

Changing the value of SClass later reshapes the affected sequences and makes it necessary to reset their values:

>>> states.sp = 2.0
>>> states.sp
sp([[2.0, 2.0],
    [2.0, 2.0],
    [2.0, 2.0]])
>>> sclass(2)
>>> states.sp
sp([[nan, nan],
    [nan, nan]])

Re-defining the same value does not delete the already available data:

>>> states.sp = 2.0
>>> sclass(2)
>>> states.sp
sp([[2.0, 2.0],
    [2.0, 2.0]])

Additionally, SClass determines the shape of the control parameter SFDist:

>>> sfdist.shape
(2,)
NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (1, None)
INIT: int | float | bool | None = 1
name: str = 'sclass'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.ZoneType(subvars: SubParameters)[source]

Bases: NameParameter

Type of each zone [-].

Required by the methods:

Calc_CFAct_V1 Calc_CF_SM_V1 Calc_ContriArea_V1 Calc_DP_SUZ_V1 Calc_EA_SM_AETModel_V1 Calc_EA_SM_V1 Calc_EI_Ic_AETModel_V1 Calc_EI_Ic_V1 Calc_EL_LZ_AETModel_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_GAct_V1 Calc_GR1_V1 Calc_GR2_GR3_V1 Calc_GlMelt_In_V1 Calc_InRC_V1 Calc_InRC_V2 Calc_InRC_V3 Calc_InUZ_V1 Calc_In_WC_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_Melt_SP_WC_V1 Calc_QAb1_QVs1_BW1_V1 Calc_QAb2_QVs2_BW2_V1 Calc_RG1_SG1_V1 Calc_RS_RI_SUZ_V1 Calc_R_SM_V1 Calc_Refr_SP_WC_V1 Calc_SPG_WCG_SP_WC_V1 Calc_SPL_WCL_SP_WC_V1 Calc_SP_WC_V1 Calc_SR_V1 Calc_SUZ_V1 Calc_SWE_V1 Calc_TF_Ic_V1

Parameter ZoneType relies on the integer constants defined in module hland_constants for representing zone types:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(6)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, ILAKE, FIELD)
>>> from hydpy import print_vector
>>> print_vector(zonetype.values)
1, 2, 3, 4, 4, 1
>>> zonetype
zonetype(FIELD, FOREST, GLACIER, ILAKE, ILAKE, FIELD)
constants: Constants = {'FIELD': 1, 'FOREST': 2, 'GLACIER': 3, 'ILAKE': 4, 'SEALED': 5}
name: str = 'zonetype'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.ZoneArea(subvars: SubParameters)[source]

Bases: ParameterComplete

Zone area [km²].

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
trim(lower=None, upper=None) bool[source]

Trim ZoneArea so that \(\Sigma ZoneArea = Area\) holds and each zone area is non-negative.

Our example basin is 6 km² large and consists of three zones:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> area(6.0)
>>> nmbzones(3)
>>> zonetype(FIELD)

First, an example with correct data:

>>> zonearea(1.0, 2.0, 3.0)
>>> zonearea
zonearea(1.0, 2.0, 3.0)

Second, an example with a single zone with a negative area:

>>> zonearea(-1.0, 2.0, 4.0)
>>> zonearea
zonearea(0.0, 2.0, 4.0)

Third, an example with too low zone areas:

>>> zonearea(0.5, 1.0, 1.5)
>>> zonearea
zonearea(1.0, 2.0, 3.0)

Fourth, an example with too high zone areas:

>>> zonearea(2.0, 4.0, 6.0)
>>> zonearea
zonearea(1.0, 2.0, 3.0)

Fifth, a combined example:

>>> zonearea(-1.0, 1.0, 2.0)
>>> zonearea
zonearea(0.0, 2.0, 4.0)
name: str = 'zonearea'

Name of the variable in lowercase letters.

unit: str = 'km²'

Unit of the variable.

class hydpy.models.hland.hland_control.Psi(subvars: SubParameters)[source]

Bases: Parameter

Fraction of the actual sealing of zones classified as SEALED [-].

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.01, 1.0)
INIT: int | float | bool | None = 1.0
name: str = 'psi'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.ZoneZ(subvars: SubParameters)[source]

Bases: ParameterComplete

Zone elevation [100m].

Required by the methods:

Calc_PC_V1 Calc_TC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'zonez'

Name of the variable in lowercase letters.

unit: str = '100m'

Unit of the variable.

class hydpy.models.hland.hland_control.PCorr(subvars: SubParameters)[source]

Bases: ParameterComplete

General precipitation correction factor [-].

Required by the method:

Calc_PC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.0
name: str = 'pcorr'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.PCAlt(subvars: SubParameters)[source]

Bases: ParameterComplete

Elevation correction factor for precipitation [1/100m].

Required by the method:

Calc_PC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.1
name: str = 'pcalt'

Name of the variable in lowercase letters.

unit: str = '1/100m'

Unit of the variable.

class hydpy.models.hland.hland_control.RfCF(subvars: SubParameters)[source]

Bases: ParameterComplete

Rainfall correction factor [-].

Required by the method:

Calc_RFC_SFC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.0
name: str = 'rfcf'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.SfCF(subvars: SubParameters)[source]

Bases: ParameterComplete

Snowfall correction factor [-].

Required by the method:

Calc_RFC_SFC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.0
name: str = 'sfcf'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.TCorr(subvars: SubParameters)[source]

Bases: ParameterNoGlacier

General temperature correction addend [-].

Required by the method:

Calc_TC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.0
name: str = 'tcorr'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.TCAlt(subvars: SubParameters)[source]

Bases: ParameterComplete

Elevation correction factor for temperature [-1°C/100m].

Required by the method:

Calc_TC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.6
name: str = 'tcalt'

Name of the variable in lowercase letters.

unit: str = '-1°C/100m'

Unit of the variable.

class hydpy.models.hland.hland_control.IcMax(subvars: SubParameters)[source]

Bases: ParameterInterception

Maximum interception storage [mm].

Required by the method:

Calc_TF_Ic_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'icmax'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.SFDist(subvars: SubParameters)[source]

Bases: Parameter

Distribution of snowfall [-].

Required by the methods:

Calc_SPG_WCG_SP_WC_V1 Calc_SP_WC_V1

Parameter SFDist handles multiple adjustment factors for snowfall, one for each snow class, to introduce spatial heterogeneity to the snow depth within each zone. If we, for example, define three snow classes per zone but assign the neutral value 1.0 to SFDist, all snow classes will receive the same amount of liquid and frozen snowfall (everything else will also be identical, so defining three snow classes instead of one is just a waste of computation time):

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> sclass(3)
>>> sfdist(1.0)
>>> sfdist
sfdist(1.0)

SFDist norms the given values. If we assign 0.1, 0.2, and 0.3, the snow classes receive 50 %, 100 %, and 150 % of the average snowfall of their respective zone:

>>> sfdist(0.1, 0.2, 0.3)
>>> sfdist
sfdist(0.5, 1.0, 1.5)

SFDist provides two convenient alternatives for defining multiple factors with single keyword arguments. To illustrate how they work, we first define a test function that accepts a keyword argument, passes it to a SFDist instance for the cases of one to five snow classes, and prints the respective snow class-specific factors:

>>> from hydpy import print_vector
>>> def test(**kwargs):
...     for nmb in range(1, 6):
...         sclass(nmb)
...         sfdist(**kwargs)
...         print_vector(sfdist.values)

The first available keyword is linear. Using it, SFDist calculates its factors in agreement with the original HBV96 implementation. For the lowest possible value, 0.0, all adjustment factors are one:

>>> test(linear=0.0)
1.0
1.0, 1.0
1.0, 1.0, 1.0
1.0, 1.0, 1.0, 1.0
1.0, 1.0, 1.0, 1.0, 1.0

For the highest possible value, 1.0, the first snow class receives no snowfall, while the last snow receives twice the zone’s average snowfall. SFDist interpolates the factors of the other snow classes linearly:

>>> test(linear=1.0)
1.0
0.0, 2.0
0.0, 1.0, 2.0
0.0, 0.666667, 1.333333, 2.0
0.0, 0.5, 1.0, 1.5, 2.0

For a value of 0.5, the first and the last snow class receive 50 % and 150 % of the zone’s average snowfall:

>>> test(linear=0.5)
1.0
0.5, 1.5
0.5, 1.0, 1.5
0.5, 0.833333, 1.166667, 1.5
0.5, 0.75, 1.0, 1.25, 1.5

The first available keyword is lognormal. Here, SFDist calculates factors resulting in a lognormal distribution of snowfall, similarly as implemented in the COSERO model (Frey and Holzmann, 2015). Again, the lowest possible value, 0.0, results in uniform snow distributions:

>>> test(lognormal=0.0)
1.0
1.0, 1.0
1.0, 1.0, 1.0
1.0, 1.0, 1.0, 1.0
1.0, 1.0, 1.0, 1.0, 1.0

In the following examples, we increase the scale factor from 0.01 to 0.1 to 1.0. The higher the scale factor, the more snow concentrates in the last snow class:

>>> test(lognormal=0.01)
1.0
0.992021, 1.007979
0.989116, 0.999953, 1.010931
0.987332, 0.996711, 1.003204, 1.012754
0.986061, 0.994647, 0.999951, 1.005284, 1.014057
>>> test(lognormal=0.1)
1.0
0.920344, 1.079656
0.893412, 0.995313, 1.111276
0.877282, 0.963406, 1.028038, 1.131273
0.865966, 0.943604, 0.995118, 1.049519, 1.145792
>>> test(lognormal=1.0)
1.0
0.317311, 1.682689
0.228763, 0.624994, 2.146243
0.188069, 0.446552, 0.854969, 2.51041
0.163826, 0.361372, 0.612984, 1.047213, 2.814604

Theoretically, higher scale factors are allowed. However, 1.0 results in highly heterogeneous snow distributions already.

Wrong usage results in the usual error messages:

>>> sfdist(normal=1.0)
Traceback (most recent call last):
...
NotImplementedError: The value(s) of parameter `sfdist` of element `?` could not be set based on the given keyword arguments.
>>> sfdist(linear=1.0, lognormal=1.0)
Traceback (most recent call last):
...
NotImplementedError: The value(s) of parameter `sfdist` of element `?` could not be set based on the given keyword arguments.
>>> sfdist(1.0, lognormal=1.0)
Traceback (most recent call last):
...
ValueError: For parameter `sfdist` of element `?` both positional and keyword arguments are given, which is ambiguous.
NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.0
name: str = 'sfdist'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.SMax(subvars: SubParameters)[source]

Bases: ParameterLand

Maximum snow water equivalent [mm].

Required by the methods:

Calc_SPG_WCG_SP_WC_V1 Calc_SPL_WCL_SP_WC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = inf
name: str = 'smax'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.SRed(subvars)[source]

Bases: Parameter

Snow redistribution paths [-].

Required by the method:

Calc_SPG_WCG_SP_WC_V1

SRed is a 2-dimensional parameter that handles weighting factors for all possible zone connections. The source zones vary on the rows and the target zones on the columns. In the following example, zone one sends all snow available for redistribution to zone three. Zone two sends 50 % to zone four and 50 % to zone five. Zone six sends 40 % to zone two, 40 % to zone three, and 20 % to zone four:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(6)
>>> zonetype(FIELD)
>>> sred([[0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.5, 0.5, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.4, 0.4, 0.2, 0.0, 0.0]])
>>> sred
sred([[0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.5, 0.5, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.4, 0.4, 0.2, 0.0, 0.0]])

A zone can either redistribute no snow at all (we then call it a “dead end”) or needs to send 100 % of the snow available for redistribution. Hence, the sums of the individual rows must be either 0.0 or 1.0. Method verify() checks for possible violations of this requirement (by calling method verify_sums()):

>>> sred([[0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.5, 0.5],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.4, 0.5],
...       [0.0, 0.1, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.4, 0.4, 0.2, 0.0, 0.0]])
>>> sred.verify()
Traceback (most recent call last):
...
RuntimeError: The sum(s) of the following row(s) of parameter `sred` of element `?` are neither 0.0 nor 1.0: 3 and 4.

Zones of type ILAKE possess no snow module. Hence, they never release any snow for redistribution and method verify() checks for possible unused weighting factors in the relevant rows (by calling method verify_lakes()):

>>> zonetype(FIELD, FIELD, FIELD, ILAKE, FIELD, ILAKE)
>>> sred([[0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
>>> sred.verify()
Traceback (most recent call last):
...
RuntimeError: Internal lake zones cannot be involved in snow redistribution, so the sums of all rows of parameter `sred` of element `?` corresponding to internal lake zones must be zero, which is not the case for the row(s): 3.

For the same reason, internal lakes cannot receive and accumulate any redistributed snow. Therefore, method verify() additionally checks for possible problematic weighting factors in the relevant columns (by calling method verify_lakes()):

>>> sred([[0.0, 0.5, 0.0, 0.0, 0.0, 0.5],
...       [0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
>>> sred.verify()
Traceback (most recent call last):
...
RuntimeError: Internal lake zones cannot be involved in snow redistribution, so the sums of all columns of parameter `sred` of element `?` corresponding to internal lake zones must be zero, which is not the case for the column(s): 3 and 5.

The snow redistribution routine of hland does not allow for any cycles. Method verify() checks for possible cycles by calling method verify_order():

>>> zonetype(FIELD)
>>> sred([[0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.5, 0.5],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.5, 0.5],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.4, 0.4, 0.2, 0.0, 0.0]])
>>> sred.verify()
Traceback (most recent call last):
...
RuntimeError: The weighting factors of parameter `sred` of element `?` define at least one cycle: (1, 5) and (5, 1).

Note that method verify_order() relies on the update() method of parameter SRedOrder but resets its values afterwards:

>>> derived.sredorder.shape = (1, 2)
>>> derived.sredorder.values = [[0, 1]]
>>> old_values = derived.sredorder.values.copy()
>>> sred.values[1, -2:] = 1.0, 0.0
>>> sred.verify_order()
Traceback (most recent call last):
...
RuntimeError: The weighting factors of parameter `sred` of element `?` define at least one cycle: (3, 5) and (5, 3).
>>> derived.sredorder
sredorder(0, 1)

Parameter SRed provides two options to define the weighting factors with little effort. The first option works by specifying the number of target zones. If we set the number of target zones to one, SRed determines the next lower target for each zone that is not a dead-end:

>>> zonetype(GLACIER, FIELD, FOREST, SEALED, ILAKE, FOREST)
>>> zonez(6.0, 5.0, 4.0, 3.0, 2.0, 1.0)
>>> zonearea.values = 1.0
>>> sred(n_zones=1)

For brevity, parameter SRed returns string representations based on these options when possible:

>>> sred
sred(n_zones=1)

Clear the contents of the KeywordArguments object returned by property keywordarguments to see the actual parameter values:

>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])

For two target zones (and identical zone areas), the weights of the next two lower zones are 0.5:

>>> sred(n_zones=2)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.5, 0.5, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.5, 0.5, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.5, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])

You can specify an arbitrarily high numbes of target zones. Parameter SRed adjusts the given value to the number of actually available target zones:

>>> sred(n_zones=999)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.25, 0.25, 0.25, 0.0, 0.25],
      [0.0, 0.0, 0.333333, 0.333333, 0.0, 0.333333],
      [0.0, 0.0, 0.0, 0.5, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])

After defining the same elevation for the second and the third zone, the first zone redistributes the same snow amount to both of them. Additionally, both zones redistribute their own snow to the fourth zone:

>>> zonez(6.0, 5.0, 5.0, 3.0, 2.0, 1.0)
>>> sred(n_zones=1)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.5, 0.5, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
>>> sred(n_zones=2)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.5, 0.5, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.5, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.5, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
>>> sred(n_zones=999)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.25, 0.25, 0.25, 0.0, 0.25],
      [0.0, 0.0, 0.0, 0.5, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.5, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])

For all zones lying on the same elevation, no redistribution occurs:

>>> zonez(1.0)
>>> sred(n_zones=1)
>>> sred.keywordarguments.clear()
>>> sred
sred(0.0)
>>> sred(n_zones=2)
>>> sred.keywordarguments.clear()
>>> sred
sred(0.0)
>>> sred(n_zones=999)
>>> sred.keywordarguments.clear()
>>> sred
sred(0.0)

The following examples demonstrate that the weights’ calculation works well for unsorted elevations:

>>> zonetype(FIELD, FOREST, FOREST, ILAKE, GLACIER, SEALED)
>>> zonez(5.0, 4.0, 1.0, 2.0, 6.0, 3.0)
>>> sred(n_zones=1)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [1.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])
>>> sred(n_zones=2)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.5, 0.0, 0.0, 0.0, 0.5],
      [0.0, 0.0, 0.5, 0.0, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.5, 0.5, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])
>>> sred(n_zones=999)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.333333, 0.333333, 0.0, 0.0, 0.333333],
      [0.0, 0.0, 0.5, 0.0, 0.0, 0.5],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.25, 0.25, 0.25, 0.0, 0.0, 0.25],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])

For unequal zone areas, the calculated weights reflect the relations between the respective source and target zones. The idea is that larger target zones have larger contact surfaces with their source zones than smaller ones. This approach prevents building extreme snow towers in small target zones:

>>> zonearea.values = 1.0, 2.0, 3.0, 4.0, 5.0, 6.0
>>> sred(n_zones=1)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [1.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])
>>> sred(n_zones=2)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.25, 0.0, 0.0, 0.0, 0.75],
      [0.0, 0.0, 0.333333, 0.0, 0.0, 0.666667],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.333333, 0.666667, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])
>>> sred(n_zones=999)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.181818, 0.272727, 0.0, 0.0, 0.545455],
      [0.0, 0.0, 0.333333, 0.0, 0.0, 0.666667],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.083333, 0.166667, 0.25, 0.0, 0.0, 0.5],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])

Instead of supplying the number of target zones directly, on can define the maximum height of redistribution. For a source zone at an elevation x, parameter SRed searches for zones that lie within the interval \([x - d\_height, x)\). If it does not find one, it selects at least the next lower target zone(s), if existing:

>>> zonez(5.0, 5.0, 1.0, 2.0, 6.0, 3.0)
>>> sred(d_height=0.0)
>>> sred
sred(d_height=0.0)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.333333, 0.666667, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])
>>> sred(d_height=2.0)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.333333, 0.666667, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])
>>> sred(d_height=10.0)
>>> sred.keywordarguments.clear()
>>> sred
sred([[0.0, 0.0, 0.333333, 0.0, 0.0, 0.666667],
      [0.0, 0.0, 0.333333, 0.0, 0.0, 0.666667],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      [0.083333, 0.166667, 0.25, 0.0, 0.0, 0.5],
      [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]])

Passing multiple keyword arguments or a positional and a keyword argument at once results in the following error messages:

>>> sred(n_zones=1, d_height=0.0)
Traceback (most recent call last):
...
ValueError: Parameter `sred` of element `?` accepts at most a single keyword argument but 2 are given.
>>> sred(0.0, d_height=0.0)
Traceback (most recent call last):
...
ValueError: For parameter `sred` of element `?` both positional and keyword arguments are given, which is ambiguous.
NDIM: int = 2
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.0
verify() None[source]

Perform the usual parameter value verifications (implemented in method verify()) and call methods verify_sums(), verify_lakes(), and verify_order() for additional checks.

See the main documentation on class SRed for further information.

verify_sums() None[source]

Check if the sums of all rows are either 0.0 (for dead-end zones) or 1.0 (for redistributing zones).

See the main documentation on class SRed for further information.

verify_order() None[source]

Check if the weighting factors define any cycles.

See the main documentation on class SRed for further information.

verify_lakes() None[source]

Check if any internal lake seems to be involved in snow redistribution.

See the main documentation on class SRed for further information.

property keywordarguments: KeywordArguments[float]

A KeywordArguments object, providing the currently valid keyword argument.

We reuse one of the example configurations of the main documentation on class SRed:

>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(6)
>>> zonetype(GLACIER, FIELD, FOREST, SEALED, ILAKE, FOREST)
>>> zonez(6.0, 5.0, 4.0, 3.0, 2.0, 1.0)
>>> zonearea.values = 1.0

After defining the values of parameter SRed via option n_zones or d_height, the returned KeywordArguments object contains the given name-value pair and indicates its validity by its True valid attribute:

>>> sred(n_zones=1)
>>> sred.keywordarguments
KeywordArguments(n_zones=1)
>>> sred.keywordarguments.valid
True

Property keywordarguments checks if the last passed option still results in the currently defined parameter values and sets the valid flag to False if this is not the case. We show this by modifying the zone heights specified by parameter ZoneZ:

>>> zonez(4.0, 5.0, 4.0, 3.0, 2.0, 1.0)
>>> sred.keywordarguments
KeywordArguments(n_zones=1)
>>> sred.keywordarguments.valid
False

After resetting the original values of ZoneZ, the valid flag of the returned KeywordArguments object is True again:

>>> zonez(6.0, 5.0, 4.0, 3.0, 2.0, 1.0)
>>> sred.keywordarguments
KeywordArguments(n_zones=1)
>>> sred.keywordarguments.valid
True

After defining the parameter values directly, the KeywordArguments object is always empty and invalid:

>>> sred(sred.values)
>>> sred.keywordarguments
KeywordArguments()
>>> sred.keywordarguments.valid
False

The same holds for erroneous keyword arguments:

>>> sred(n_zones=None)
Traceback (most recent call last):
...
TypeError: '>=' not supported between instances of 'int' and 'NoneType'
>>> sred.keywordarguments
KeywordArguments()
>>> sred.keywordarguments.valid
False
name: str = 'sred'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.TT(subvars: SubParameters)[source]

Bases: ParameterComplete

Temperature threshold for snow/rain [°C].

Required by the method:

Calc_FracRain_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.0
name: str = 'tt'

Name of the variable in lowercase letters.

unit: str = '°C'

Unit of the variable.

class hydpy.models.hland.hland_control.TTInt(subvars: SubParameters)[source]

Bases: ParameterComplete

Temperature interval with a mixture of snow and rain [°C].

Required by the method:

Calc_FracRain_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.0
name: str = 'ttint'

Name of the variable in lowercase letters.

unit: str = '°C'

Unit of the variable.

class hydpy.models.hland.hland_control.DTTM(subvars: SubParameters)[source]

Bases: ParameterLand

Difference between TTM and TT [°C].

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.0
name: str = 'dttm'

Name of the variable in lowercase letters.

unit: str = '°C'

Unit of the variable.

class hydpy.models.hland.hland_control.CFMax(subvars: SubParameters)[source]

Bases: ParameterLand

Average degree day factor for snow (on glaciers or not) [mm/°C/T].

Required by the methods:

Calc_CFAct_V1 Calc_Refr_SP_WC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 3.5
name: str = 'cfmax'

Name of the variable in lowercase letters.

unit: str = 'mm/°C/T'

Unit of the variable.

class hydpy.models.hland.hland_control.CFVar(subvars: SubParameters)[source]

Bases: ParameterLand

Annual variability of CFMax [mm/°C/T].

Required by the method:

Calc_CFAct_V1

Use positive values for the northern and negative values for the southern hemisphere.

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.0
name: str = 'cfvar'

Name of the variable in lowercase letters.

unit: str = 'mm/°C/T'

Unit of the variable.

class hydpy.models.hland.hland_control.GMelt(subvars: SubParameters)[source]

Bases: ParameterGlacier

Degree day factor for glacial ice [mm/°C/T].

Required by the method:

Calc_GAct_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 3.5
name: str = 'gmelt'

Name of the variable in lowercase letters.

unit: str = 'mm/°C/T'

Unit of the variable.

class hydpy.models.hland.hland_control.GVar(subvars: SubParameters)[source]

Bases: ParameterGlacier

Annual variability of GMelt [mm/°C/T].

Required by the method:

Calc_GAct_V1

Use positive values for the northern and negative values for the southern hemisphere.

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
INIT: int | float | bool | None = 0.0
name: str = 'gvar'

Name of the variable in lowercase letters.

unit: str = 'mm/°C/T'

Unit of the variable.

class hydpy.models.hland.hland_control.CFR(subvars: SubParameters)[source]

Bases: ParameterLand

Refreezing factor for water stored within the snow layer [-].

Required by the method:

Calc_Refr_SP_WC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.05
name: str = 'cfr'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.WHC(subvars: SubParameters)[source]

Bases: ParameterLand

Relative water holding capacity of the snow layer [-].

Required by the method:

Calc_In_WC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.1
name: str = 'whc'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.FC(subvars: SubParameters)[source]

Bases: ParameterSoil

Maximum soil moisture content (field capacity) [mm].

Required by the methods:

Calc_CF_SM_V1 Calc_ContriArea_V1 Calc_EA_SM_AETModel_V1 Calc_EA_SM_V1 Calc_R_SM_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 200
name: str = 'fc'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.Beta(subvars: SubParameters)[source]

Bases: ParameterSoil

Nonlinearity parameter of the soil routine [-].

Required by the methods:

Calc_ContriArea_V1 Calc_R_SM_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 2.0
name: str = 'beta'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.PercMax(subvars: SubParameters)[source]

Bases: Parameter

Maximum percolation rate [mm/T].

Required by the methods:

Calc_DP_SUZ_V1 Calc_Q0_Perc_UZ_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'percmax'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_control.CFlux(subvars: SubParameters)[source]

Bases: ParameterSoil

Capacity (maximum) of the capillary return flux [mm/T].

Required by the method:

Calc_CF_SM_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.0
name: str = 'cflux'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_control.RespArea(subvars: SubParameters)[source]

Bases: Parameter

Flag to enable the contributing area approach [-].

Required by the method:

Calc_ContriArea_V1

NDIM: int = 0
TYPE

alias of bool

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'resparea'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.RecStep(subvars: SubParameters)[source]

Bases: Parameter

Number of internal computation steps per simulation time step [-].

Required by the method:

Calc_Q0_Perc_UZ_V1

The default value of 1440 internal computation steps per day corresponds to 1 computation step per minute.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> recstep(4.2)
>>> recstep
recstep(4.0)
NDIM: int = 0
TYPE

alias of int

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (1, None)
INIT: int | float | bool | None = 1440
name: str = 'recstep'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.Alpha(subvars: SubParameters)[source]

Bases: Parameter

Nonlinearity parameter of the upper zone layer [-].

Required by the method:

Calc_Q0_Perc_UZ_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.0
name: str = 'alpha'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.K(subvars: SubParameters)[source]

Bases: Parameter

Recession coefficient of the upper zone layer [1/T/mm^alpha].

Required by the method:

Calc_Q0_Perc_UZ_V1

In addition to the Parameter call method, it is possible to set the value of parameter K in accordance to the keyword arguments khq, hq and (optionally) alpha:

Parameter K allows defining its value via the keyword arguments khq, hq and (optionally) alpha:

\(K = \frac{HQ}{(HQ/KHQ)^{1+Alpha}}\)

Examples:

When directly setting the value of parameter K, one should be be aware of its time dependence:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> k(2.0)
>>> k
k(2.0)
>>> k.value
1.0

Alternatively, one can specify the mentioned three keyword arguments:

>>> k(hq=10.0, khq=2.0, alpha=1.0)
>>> k
k(0.4)
>>> k.value
0.2

If a value for keyword argument alpha is missing, parameter K tries to query it from parameter Alpha.

>>> alpha(2.0)
>>> k(hq=10.0, khq=2.0)
>>> k
k(0.08)
>>> k.value
0.04

The following exceptions occur for wrong combinations of keyword arguments or when Alpha is not ready (still has the value nan):

>>> k(wrong=1)
Traceback (most recent call last):
...
ValueError: For parameter `k` of element `?` a value can be set directly or indirectly by using the keyword arguments `khq` and `hq`.
>>> k(hq=10.0)
Traceback (most recent call last):
...
ValueError: For the alternative calculation of parameter `k` of element `?`, at least the keywords arguments `khq` and `hq` must be given.
>>> import numpy
>>> alpha(numpy.nan)
>>> k(hq=10.0, khq=2.0)
Traceback (most recent call last):
...
RuntimeError: For the alternative calculation of parameter `k` of element `?`, either the keyword argument `alpha` must be given or the value of parameter `alpha` must be defined beforehand.

The default value for k of 0.009633 results from the default values for alpha, hq and khq given in HBV96:

>>> k(hq=3.0, khq=0.17, alpha=1.0)
>>> k
k(0.009633)
NDIM: int = 0
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.009633
name: str = 'k'

Name of the variable in lowercase letters.

unit: str = '1/T/mm^alpha'

Unit of the variable.

class hydpy.models.hland.hland_control.SGR(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Threshold content of SUZ for the generation of surface runoff [mm].

Required by the method:

Calc_RS_RI_SUZ_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'sgr'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.K0(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Storage time for surface runoff [T].

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
trim(lower=None, upper=None) bool[source]

Trim K0 following \(K^* \leq K0 \leq K1\) with \(K^* = -1/ln \left( 1 - e^{-1 / k1} \right)\).

The additional restriction \(K^*\) serves to prevent the storage SUZ from taking on negative values (see issue 67).

>>> from hydpy.models.hland import *
>>> simulationstep("1d")
>>> parameterstep("1h")
>>> nmbzones(5)
>>> zonetype(FIELD)
>>> k1(48.0, 48.0, 48.0, 48.0, nan)
>>> k0(24.0, 36.0, 48.0, 72.0, 72.0)
>>> k0
k0(25.730308, 36.0, 48.0, 48.0, 72.0)
name: str = 'k0'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.H1(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Outlet level of the reservoir for simulating surface flow [mm].

Required by the method:

Calc_QAb1_QVs1_BW1_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'h1'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.TAb1(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Recession coefficient for simulating surface flow [T].

Required by the method:

Calc_QAb1_QVs1_BW1_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'tab1'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.TVs1(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Recession coefficient for simulating percolation from the surface flow module [T].

Required by the method:

Calc_QAb1_QVs1_BW1_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'tvs1'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.K1(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Storage time for interflow [T].

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
trim(lower=None, upper=None) bool[source]

Trim K1 following \(max (K0, K^*) \leq K1 \leq K2\) with \(K^* = max \left( -1/ln \left( 1 - e^{-1 / k0} \right), K1L \right)\).

The additional restriction \(K^*\) serves to prevent the storage SUZ from taking on negative values (see issue 67).

>>> from hydpy.models.hland import *
>>> simulationstep("1d")
>>> parameterstep("1h")
>>> nmbzones(9)
>>> zonetype(FIELD)
>>> k1(24.0, 24.0, 72.0, 120.0, 24.0, 24.0, 120.0, nan, nan)
>>> k1
k1(34.624681, 34.624681, 72.0, 120.0, 34.624681, 34.624681, 120.0, nan,
   nan)
>>> k1.values = nan
>>> k0(48.0, 24.0, 24.0, 24.0, nan, 24.0, nan, 24.0, nan)
>>> k2(96.0, 96.0, 96.0, 96.0, nan, nan, 96.0, 96.0, nan)
>>> k1(24.0, 24.0, 72.0, 120.0, 24.0, 24.0, 120.0, nan, nan)
>>> k1
k1(48.0, 52.324614, 72.0, 96.0, 34.624681, 52.324614, 96.0, nan, nan)
name: str = 'k1'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.SG1Max(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Maximum content of the fast response groundwater reservoir SG1 [mm].

Required by the method:

Calc_GR1_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'sg1max'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.H2(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Outlet level of the reservoir for simulating interflow [mm].

Required by the method:

Calc_QAb2_QVs2_BW2_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'h2'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_control.TAb2(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Recession coefficient for simulating interflow [T].

Required by the method:

Calc_QAb2_QVs2_BW2_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'tab2'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.TVs2(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Recession coefficient for simulating percolation from the interflow module [T].

Required by the method:

Calc_QAb2_QVs2_BW2_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'tvs2'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.K4(subvars: SubParameters)[source]

Bases: Parameter

Recession coefficient of the lower zone layer [1/T].

Required by the method:

Calc_Q1_LZ_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = True
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.01
name: str = 'k4'

Name of the variable in lowercase letters.

unit: str = '1/T'

Unit of the variable.

class hydpy.models.hland.hland_control.K2(subvars: SubParameters)[source]

Bases: ParameterUpperZone

Storage time for quick response baseflow [T].

Required by the methods:

Calc_GR1_V1 Calc_RG1_SG1_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
trim(lower=None, upper=None) bool[source]

Trim K2 following \(max(K1, K1L) \leq K2 \leq K3\).

>>> from hydpy.models.hland import *
>>> simulationstep("1d")
>>> parameterstep("1h")
>>> nmbzones(6)
>>> zonetype(FIELD)
>>> k2(12.0, 12.0, 12.0, nan, 96.0, 120.0)
>>> k2
k2(34.624681, 34.624681, 34.624681, nan, 96.0, 120.0)
>>> k2.values = nan
>>> k1(24.0, 72.0, nan, nan, nan, 72.0)
>>> k3(96.0)
>>> k2(12.0, 12.0, 12.0, nan, 96.0, 120.0)
>>> k2
k2(34.624681, 72.0, 34.624681, nan, 96.0, 96.0)
name: str = 'k2'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.K3(subvars: SubParameters)[source]

Bases: Parameter

Storage time for delayed baseflow [T].

Required by the method:

Calc_RG2_SG2_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (1.0, None)
trim(lower=None, upper=None) bool[source]

Trim K3 in accordance with \(max(K2, K1L) \leq K3\).

>>> from hydpy.models.hland import *
>>> simulationstep("1d")
>>> parameterstep("1h")
>>> nmbzones(3)
>>> k3(12.0)
>>> k3
k3(34.624681)
>>> k3.values = nan
>>> k2(36.0, 36.0, nan)
>>> k2.value[0] /= 3.0
>>> k3(12.0)
>>> k3
k3(36.0)
>>> k2.values[1] /= 3.0
>>> k3(12.0)
>>> k3
k3(34.624681)
name: str = 'k3'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_control.Gamma(subvars: SubParameters)[source]

Bases: Parameter

Nonlinearity parameter of the lower zone layer [-].

Required by the method:

Calc_Q1_LZ_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'gamma'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_control.MaxBaz(subvars: SubParameters)[source]

Bases: Parameter

Base length of the triangle unit hydrograph [T].

NDIM: int = 0
TYPE

alias of float

name: str = 'maxbaz'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

Derived parameters

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

Bases: SubParameters

Derived parameters of model hland.

The following classes are selected:
  • DOY() References the dayofyear index array provided by the instance of class Indexer available in module pub [-].

  • RelZoneAreas() Relative area of all zones [-].

  • RelSoilArea() Relative area of all FIELD and FOREST zones [-].

  • RelLandArea() Relative area of all FIELD, FOREST, GLACIER, and SEALED zones [-].

  • RelUpperZoneArea() Relative area of all FIELD, FOREST, and GLACIER zones [-].

  • RelLowerZoneArea() Relative area of all FIELD, FOREST, GLACIER, and ILAKE zones [-].

  • ZoneAreaRatios() Ratios of all zone combinations [-].

  • IndicesZoneZ() Indices of the zones sorted by altitude [-].

  • Z() Average (reference) subbasin elevation [100m].

  • SRedOrder() Processing order for the snow redistribution routine [-].

  • SRedEnd() Flags that indicate the “dead ends” of snow redistribution within a subbasin.

  • SRedNumber() The total number of snow redistribution paths [-].

  • TTM() Threshold temperature for snow melting and refreezing [°C].

  • DT() Relative time step length for the upper zone layer calculations [-].

  • W0() Weight for calculating surface runoff [-].

  • W1() Weight for calculating interflow [-].

  • W2() Weight for calculating the quick response base flow [-].

  • W3() Weight for calculating the response of the first-order groundwater reservoir [-].

  • K4() Storage time for very delayed baseflow [T].

  • W4() Weight for calculating the response of the second-order groundwater reservoir [-].

  • QFactor() Factor for converting mm/stepsize to m³/s.

class hydpy.models.hland.hland_derived.DOY(subvars: SubParameters)[source]

Bases: DOYParameter

References the dayofyear index array provided by the instance of class Indexer available in module pub [-].

Required by the methods:

Calc_CFAct_V1 Calc_GAct_V1

name: str = 'doy'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.RelZoneAreas(subvars: SubParameters)[source]

Bases: ParameterComplete

Relative area of all zones [-].

Required by the methods:

Calc_ContriArea_V1 Calc_EL_LZ_AETModel_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_GR2_GR3_V1 Calc_InRC_V1 Calc_InRC_V2 Calc_InRC_V3 Calc_InUZ_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_SPG_WCG_SP_WC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
strict_valuehandling: bool = False
update() None[source]

Update the relative area based on the parameters ZoneArea, ZoneType, and Psi.

In the simplest case, RelZoneAreas provides the fractions of the zone areas available via the control parameter ZoneArea:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> area(100.0)
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea(10.0, 40.0, 20.0, 25.0, 5.0)
>>> psi(1.0)
>>> derived.relzoneareas.update()
>>> derived.relzoneareas
relzoneareas(field=0.1, forest=0.4, glacier=0.2, ilake=0.25,
             sealed=0.05)

hland assumes complete sealing for zones classified as land-use type SEALED. Hence, besides interception losses, their runoff coefficient is always one. When deriving zone types from available land-use classifications, we are likely to identify zones as SEALED that actually have lower runoff coefficients due to incomplete sealing, infiltration of sealed surface runoff on adjacent unsealed areas, retention of surface runoff in sewage treatment plants, and many other issues. Parameter Psi allows decreasing the effective relative area of zones of type SEALED. Method update() divides the remaining “uneffective” sealed area to all zones of different land-use types (proportionally to their sizes), except those of type GLACIER:

>>> psi(0.6)
>>> derived.relzoneareas.update()
>>> derived.relzoneareas
relzoneareas(field=0.102667, forest=0.410667, glacier=0.2,
             ilake=0.256667, sealed=0.03)

For subbasins without SEALED zones, the value of Psi is irrelevant:

>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, ILAKE)
>>> derived.relzoneareas.update()
>>> derived.relzoneareas
relzoneareas(0.1, 0.4, 0.2, 0.25, 0.05)

The same holds for subbasins consisting only of SEALED and GLACIER zones:

>>> zonetype(SEALED)
>>> derived.relzoneareas.update()
>>> derived.relzoneareas
relzoneareas(0.1, 0.4, 0.2, 0.25, 0.05)
>>> zonetype(GLACIER, GLACIER, SEALED, SEALED, SEALED)
>>> derived.relzoneareas.update()
>>> derived.relzoneareas
relzoneareas(0.1, 0.4, 0.2, 0.25, 0.05)

The last example demonstrates that the underlying algorithm also works when multiple SEALED or GLACIER zones are involved:

>>> zonetype(FIELD, GLACIER, GLACIER, SEALED, SEALED)
>>> derived.relzoneareas.update()
>>> derived.relzoneareas
relzoneareas(0.22, 0.4, 0.2, 0.15, 0.03)
name: str = 'relzoneareas'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.RelSoilArea(subvars: SubParameters)[source]

Bases: Parameter

Relative area of all FIELD and FOREST zones [-].

Required by the method:

Calc_ContriArea_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update RelSoilArea based on RelZoneAreas and ZoneType.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas(0.1, 0.2, 0.15, 0.25, 0.3)
>>> derived.relsoilarea.update()
>>> derived.relsoilarea
relsoilarea(0.3)
name: str = 'relsoilarea'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.RelLandArea(subvars: SubParameters)[source]

Bases: Parameter

Relative area of all FIELD, FOREST, GLACIER, and SEALED zones [-].

Required by the methods:

Calc_InRC_V3 Calc_RT_V2 Calc_SPG_WCG_SP_WC_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update RelLandArea based on RelZoneAreas and ZoneType.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas(0.1, 0.2, 0.3, 0.15, 0.25)
>>> derived.rellandarea.update()
>>> derived.rellandarea
rellandarea(0.85)
name: str = 'rellandarea'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.RelUpperZoneArea(subvars: SubParameters)[source]

Bases: Parameter

Relative area of all FIELD, FOREST, and GLACIER zones [-].

Required by the methods:

Calc_InRC_V1 Calc_InUZ_V1 Calc_LZ_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update RelUpperZoneArea based on RelZoneAreas and ZoneType.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas(0.1, 0.2, 0.3, 0.15, 0.25)
>>> derived.relupperzonearea.update()
>>> derived.relupperzonearea
relupperzonearea(0.6)
name: str = 'relupperzonearea'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.RelLowerZoneArea(subvars: SubParameters)[source]

Bases: Parameter

Relative area of all FIELD, FOREST, GLACIER, and ILAKE zones [-].

Required by the methods:

Calc_EL_LZ_AETModel_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_GR2_GR3_V1 Calc_InRC_V1 Calc_InRC_V2 Calc_LZ_V1 Calc_LZ_V2 Calc_RT_V2

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update RelLowerZoneArea based on RelZoneAreas and ZoneType.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> derived.relzoneareas(0.1, 0.2, 0.3, 0.15, 0.25)
>>> derived.rellowerzonearea.update()
>>> derived.rellowerzonearea
rellowerzonearea(0.75)
name: str = 'rellowerzonearea'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.ZoneAreaRatios(subvars: SubParameters)[source]

Bases: Parameter

Ratios of all zone combinations [-].

Required by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 2
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
update() None[source]

Update the zone area ratios based on the parameter ZoneArea.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> derived.relzoneareas(0.0625, 0.3125, 0.625)
>>> derived.zonearearatios.update()
>>> derived.zonearearatios
zonearearatios([[1.0, 0.2, 0.1],
                [5.0, 1.0, 0.5],
                [10.0, 2.0, 1.0]])
name: str = 'zonearearatios'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.IndicesZoneZ(subvars: SubParameters)[source]

Bases: Parameter

Indices of the zones sorted by altitude [-].

Required by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 1
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)
update() None[source]

Update the indices based on the order of the values of parameter ZoneZ.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonez(3.0, 4.0, 2.0, 5.0, 3.0)
>>> derived.indiceszonez.update()
>>> derived.indiceszonez
indiceszonez(2, 0, 4, 1, 3)
name: str = 'indiceszonez'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.Z(subvars: SubParameters)[source]

Bases: Parameter

Average (reference) subbasin elevation [100m].

Required by the methods:

Calc_PC_V1 Calc_TC_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
update() None[source]

Average the individual zone elevations.

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(3)
>>> area(10.0)
>>> zonearea(5.0, 3.0, 2.0)
>>> zonez(1.0, 3.0, 8.0)
>>> derived.z.update()
>>> derived.z
z(3.0)
name: str = 'z'

Name of the variable in lowercase letters.

unit: str = '100m'

Unit of the variable.

class hydpy.models.hland.hland_derived.SRedOrder(subvars: SubParameters)[source]

Bases: Parameter

Processing order for the snow redistribution routine [-].

Required by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 2
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)
update() None[source]

Update the processing order based on the weighting factors defined by parameter SRed.

An example for well-sorted data:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(6)
>>> zonetype(FIELD)
>>> sred([[0.0, 0.2, 0.2, 0.2, 0.2, 0.2],
...       [0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.5, 0.5],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]])
>>> derived.sredorder.update()
>>> derived.sredorder
sredorder([[0, 1],
           [0, 2],
           [0, 3],
           [0, 4],
           [0, 5],
           [1, 2],
           [2, 3],
           [3, 4],
           [3, 5]])

An erroneous example, including a cycle:

>>> sred([[0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
...       [0.0, 0.4, 0.4, 0.2, 0.0, 0.0]])
>>> derived.sredorder.update()
Traceback (most recent call last):
...
RuntimeError: The weighting factors of parameter `sred` of element `?` define at least one cycle: (1, 4), (4, 5), and (5, 1).

A “no redistribution” example:

>>> sred(0.0)
>>> derived.sredorder.update()
>>> derived.sredorder
sredorder([[]])

An example or unsorted data:

>>> nmbzones(5)
>>> zonetype(FIELD)
>>> sred([[0.0, 0.5, 0.0, 0.5, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0],
...       [0.0, 0.0, 0.0, 0.0, 1.0],
...       [0.0, 0.0, 0.0, 0.0, 0.0],
...       [1.0, 0.0, 0.0, 0.0, 0.0]])
>>> derived.sredorder.update()
>>> derived.sredorder
sredorder([[2, 4],
           [4, 0],
           [0, 1],
           [0, 3]])
name: str = 'sredorder'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.SRedEnd(subvars: SubParameters)[source]

Bases: Parameter

Flags that indicate the “dead ends” of snow redistribution within a subbasin.

Required by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 1
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (False, True)
update() None[source]

Update the dead-end flags based on parameter SRedOrder.

>>> from hydpy.models.hland_96 import *
>>> parameterstep("1d")
>>> nmbzones(6)
>>> derived.sredorder.shape = 9, 2
>>> derived.sredorder([[0, 1],
...                    [0, 2],
...                    [1, 2],
...                    [0, 3],
...                    [2, 3],
...                    [0, 4],
...                    [3, 4],
...                    [0, 5],
...                    [3, 5]])
>>> derived.sredend.update()
>>> derived.sredend
sredend(0, 0, 0, 0, 1, 1)
name: str = 'sredend'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_derived.SRedNumber(subvars: SubParameters)[source]

Bases: Parameter

The total number of snow redistribution paths [-].

Required by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)
update() None[source]

Update the number of redistribution paths based on the parameter SRedOrder.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> derived.sredorder.shape = 8, 3
>>> derived.srednumber.update()
>>> derived.srednumber
srednumber(8)
name: str = 'srednumber'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.TTM(subvars: SubParameters)[source]

Bases: ParameterLand

Threshold temperature for snow melting and refreezing [°C].

Required by the methods:

Calc_GlMelt_In_V1 Calc_Melt_SP_WC_V1 Calc_Refr_SP_WC_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
update()[source]

Update TTM based on \(TTM = TT + DTTM\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(1)
>>> zonetype(FIELD)
>>> tt(1.0)
>>> dttm(-2.0)
>>> derived.ttm.update()
>>> derived.ttm
ttm(-1.0)
name: str = 'ttm'

Name of the variable in lowercase letters.

unit: str = '°C'

Unit of the variable.

class hydpy.models.hland.hland_derived.DT(subvars: SubParameters)[source]

Bases: Parameter

Relative time step length for the upper zone layer calculations [-].

Required by the method:

Calc_Q0_Perc_UZ_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update DT based on \(DT = \frac{1}{RecStep}\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> recstep(2.0)
>>> derived.dt.update()
>>> derived.dt
dt(1.0)
>>> recstep(10.0)
>>> derived.dt.update()
>>> derived.dt
dt(0.2)

Note that the value assigned to parameter RecStep depends on the current parameter step size (one day). Due to the current simulation step size (one hour), the applied RecStep value is five:

>>> recstep.value
5
name: str = 'dt'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.W0(subvars: SubParameters)[source]

Bases: Parameter

Weight for calculating surface runoff [-].

Required by the method:

Calc_RS_RI_SUZ_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update W0 based on \(W0 = e^{-1/K0}\).

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> nmbzones(5)
>>> k0(0.0, 0.05, 0.5, 5.0, inf)
>>> from hydpy import round_
>>> round_(k0.values)
0.0, 1.2, 12.0, 120.0, inf
>>> derived.w0.update()
>>> derived.w0
w0(0.0, 0.434598, 0.920044, 0.991701, 1.0)
name: str = 'w0'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.W1(subvars: SubParameters)[source]

Bases: Parameter

Weight for calculating interflow [-].

Required by the method:

Calc_RS_RI_SUZ_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update W1 based on \(W1 = e^{-1/K1}\).

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> nmbzones(4)
>>> k1(0.05, 0.5, 5.0, inf)
>>> from hydpy import round_
>>> round_(k1.values)
1.442695, 12.0, 120.0, inf
>>> derived.w1.update()
>>> derived.w1
w1(0.5, 0.920044, 0.991701, 1.0)
name: str = 'w1'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.W2(subvars: SubParameters)[source]

Bases: Parameter

Weight for calculating the quick response base flow [-].

Required by the method:

Calc_RG1_SG1_V1

NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update W2 based on \(W2 = e^{-1/K2}\).

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> nmbzones(4)
>>> k2(0.05, 0.5, 5.0, inf)
>>> from hydpy import round_
>>> round_(k2.values)
1.442695, 12.0, 120.0, inf
>>> derived.w2.update()
>>> derived.w2
w2(0.5, 0.920044, 0.991701, 1.0)
name: str = 'w2'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.W3(subvars: SubParameters)[source]

Bases: Parameter

Weight for calculating the response of the first-order groundwater reservoir [-].

Required by the method:

Calc_RG2_SG2_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update W3 based on \(W3 = e^{-1/K3}\).

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> k3(5.0)
>>> from hydpy import round_
>>> round_(k3.value)
120.0
>>> derived.w3.update()
>>> derived.w3
w3(0.991701)
name: str = 'w3'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.K4(subvars: SubParameters)[source]

Bases: Parameter

Storage time for very delayed baseflow [T].

Required by the method:

Calc_RG3_SG3_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
update()[source]

Update K4 based on \(K4 = 9 \cdot K3\).

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> k3(1.0)
>>> from hydpy import round_
>>> round_(k3.value)
24.0
>>> derived.k4.update()
>>> derived.k4
k4(9.0)
>>> round_(derived.k4.value)
216.0
name: str = 'k4'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.hland.hland_derived.W4(subvars: SubParameters)[source]

Bases: Parameter

Weight for calculating the response of the second-order groundwater reservoir [-].

Required by the method:

Calc_RG3_SG3_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)
update()[source]

Update W4 based on \(W4 = e^{-1/K4}\).

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> derived.k4(5.0)
>>> from hydpy import round_
>>> round_(derived.k4.value)
120.0
>>> derived.w4.update()
>>> derived.w4
w4(0.991701)
name: str = 'w4'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_derived.QFactor(subvars: SubParameters)[source]

Bases: Parameter

Factor for converting mm/stepsize to m³/s.

Required by the method:

Calc_QT_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
update()[source]

Update QFactor based on Area and the current simulation step size.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> area(50.0)
>>> derived.qfactor.update()
>>> derived.qfactor
qfactor(1.157407)
name: str = 'qfactor'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

Fixed parameters

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

Bases: SubParameters

Fixed parameters of model hland.

The following classes are selected:
  • Pi() π [-].

  • FSG() Fraction between the spatial extents of the first-order and the second-order slow response groundwater reservoir [-].

  • K1L() Lowest possible lower boundary value for the parameters K1, K2, and K3 [-].

class hydpy.models.hland.hland_fixed.Pi(subvars: SubParameters)[source]

Bases: FixedParameter

π [-].

Required by the methods:

Calc_CFAct_V1 Calc_GAct_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool = 3.141592653589793
name: str = 'pi'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_fixed.FSG(subvars: SubParameters)[source]

Bases: FixedParameter

Fraction between the spatial extents of the first-order and the second-order slow response groundwater reservoir [-].

Required by the methods:

Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_GR2_GR3_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool = 0.8888888888888888
name: str = 'fsg'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_fixed.K1L(subvars: SubParameters)[source]

Bases: FixedParameter

Lowest possible lower boundary value for the parameters K1, K2, and K3 [-].

To prevent SUZ from taking on negative values, we must ensure that \(\left( 1 - e^{-1/K0} \right) + \left( 1 - e^{-1/K1} \right) < 1\) holds. Also, we need to follow the restriction \(K0 \leq K1 \leq K2 \leq K3\). K1L defines the lowest value meeting both constraints:

>>> from hydpy.models.hland import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> from numpy import exp
>>> from hydpy import round_
>>> round_(2.0 * (1.0 - exp(-1.0/fixed.k1l)))
1.0
NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool = 1.4426950408889632
name: str = 'k1l'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

Sequence Features

Sequence tools

class hydpy.models.hland.hland_sequences.Factor1DSequence(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FactorSequence

Base class for 1-dimensional factor subclasses that support aggregation with respect to ZoneArea.

All Factor1DSequence subclasses must implement fitting mask objects individually.

The following example shows how the subclass TC works:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea.values = 10.0, 20.0, 30.0, 35.0, 5.0
>>> factors.tc(5.0, 2.0, 4.0, 1.0, 6.0)
>>> from hydpy import round_
>>> round_(factors.tc.average_values())
2.75
NDIM: int = 1
NUMERIC: bool = False
property refweights

Alias for the associated instance of ZoneArea for calculating areal values.

name: str = 'factor1dsequence'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_sequences.Factor2DSequence(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FactorSequence

Base class for 2-dimensional factor subclasses that support aggregation with respect to ZoneArea.

All Factor2DSequence subclasses must implement fitting mask objects individually.

The following example shows how subclass SWE works, which implements mask Land:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbzones(5)
>>> sclass(2)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 60.0
>>> factors.swe = [[40.0, 10.0, 30.0, nan, 0.0],
...                [60.0, 30.0, 50.0, nan, 20.0]]
>>> from hydpy import round_
>>> round_(factors.swe.average_values())
22.5
NDIM: int = 2
NUMERIC: bool = False
property refweights

Alias for the associated instance of ZoneArea for calculating areal values.

property valuevector: ndarray[Any, dtype[float64]]

Values of the individual zones; each entry is the average of the values of all snow classes of a specific zone.

We take subclass SWE as an example:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> sclass(2)
>>> zonetype(FIELD)
>>> zonearea.values = 1.0, 1.0, 1.0
>>> factors.swe = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
>>> from hydpy import print_vector
>>> print_vector(factors.swe.valuevector)
2.5, 3.5, 4.5

The definition of valuevector of Factor2DSequence allows applying method average_values() like for the 1-dimensional zone-related sequences of hland:

>>> print_vector([factors.swe.average_values()])
3.5
property seriesmatrix: ndarray[Any, dtype[float64]]

Time series of the values of the individual zones; each entry is the average of the values of all snow classes of a specific zone.

We take subclass Melt as an example:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2000-01-05", "1d"
>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> sclass(2)
>>> zonetype(FIELD)
>>> zonearea.values = 1.0, 1.0, 1.0
>>> factors.swe.prepare_series()
>>> factors.swe.series = [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
...                     [[2.0, 3.0, 4.0], [5.0, 6.0, 7.0]],
...                     [[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]],
...                     [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]]
>>> from hydpy import print_vector
>>> for values in factors.swe.seriesmatrix:
...     print_vector(values)
2.5, 3.5, 4.5
3.5, 4.5, 5.5
4.5, 5.5, 6.5
5.5, 6.5, 7.5

The definition of seriesmatrix of Factor2DSequence allows applying method average_series() like for the 1-dimensional zone-related sequences of hland:

>>> print_vector(factors.swe.average_series())
3.5, 4.5, 5.5, 6.5
name: str = 'factor2dsequence'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_sequences.Flux1DSequence(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Base class for 1-dimensional flux subclasses that support aggregation with respect to ZoneArea.

All Flux1DSequence subclasses must implement fitting mask objects individually.

The following example shows how the subclass PC works:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea.values = 10.0, 20.0, 30.0, 35.0, 5.0
>>> fluxes.pc(5.0, 2.0, 4.0, 1.0, 6.0)
>>> from hydpy import round_
>>> round_(fluxes.pc.average_values())
2.75
NDIM: int = 1
NUMERIC: bool = False
property refweights

Alias for the associated instance of ZoneArea for calculating areal values.

name: str = 'flux1dsequence'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_sequences.Flux2DSequence(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Base class for 2-dimensional flux subclasses that support aggregation with respect to ZoneArea.

All Flux2DSequence subclasses must implement fitting mask objects individually.

The following example shows how subclass Melt works, which implements mask Snow:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> sclass(2)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 60.0
>>> fluxes.melt = [[40.0, 10.0, 30.0, nan, 0.0],
...                [60.0, 30.0, 50.0, nan, 20.0]]
>>> from hydpy import round_
>>> round_(fluxes.melt.average_values())
22.5
NDIM: int = 2
NUMERIC: bool = False
property refweights

Alias for the associated instance of ZoneArea for calculating areal values.

property valuevector: ndarray[Any, dtype[float64]]

Values of the individual zones; each entry is the average of the values of all snow classes of a specific zone.

We take subclass Melt as an example:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> sclass(2)
>>> zonetype(FIELD)
>>> zonearea.values = 1.0, 1.0, 1.0
>>> fluxes.melt = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
>>> from hydpy import print_vector
>>> print_vector(fluxes.melt.valuevector)
2.5, 3.5, 4.5

The definition of valuevector of Flux2DSequence allows applying method average_values() like for the 1-dimensional zone-related sequences of hland:

>>> print_vector([fluxes.melt.average_values()])
3.5
property seriesmatrix: ndarray[Any, dtype[float64]]

Time series of the values of the individual zones; each entry is the average of the values of all snow classes of a specific zone.

We take subclass Melt as an example:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2000-01-05", "1d"
>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> sclass(2)
>>> zonetype(FIELD)
>>> zonearea.values = 1.0, 1.0, 1.0
>>> fluxes.melt.prepare_series()
>>> fluxes.melt.series = [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
...                     [[2.0, 3.0, 4.0], [5.0, 6.0, 7.0]],
...                     [[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]],
...                     [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]]
>>> from hydpy import print_vector
>>> for values in fluxes.melt.seriesmatrix:
...     print_vector(values)
2.5, 3.5, 4.5
3.5, 4.5, 5.5
4.5, 5.5, 6.5
5.5, 6.5, 7.5

The definition of seriesmatrix of Flux2DSequence allows applying method average_series() like for the 1-dimensional zone-related sequences of hland:

>>> print_vector(fluxes.melt.average_series())
3.5, 4.5, 5.5, 6.5
name: str = 'flux2dsequence'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_sequences.State1DSequence(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Base class for 1-dimensional state subclasses that support aggregation with respect to ZoneArea.

All State1DSequence subclasses must implement fitting mask objects individually.

The following example shows how subclass SM works, which implements mask Soil:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 50.0
>>> fc(100.0)
>>> states.sm = 50.0, 20.0, 40.0, 10.0, nan
>>> from hydpy import round_
>>> round_(states.sm.average_values())
30.0
NDIM: int = 1
NUMERIC: bool = False
property refweights

Alias for the associated instance of ZoneArea for calculating areal values.

name: str = 'state1dsequence'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.hland.hland_sequences.State2DSequence(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Base class for 2-dimensional state subclasses that support aggregation with respect to ZoneArea.

All State2DSequence subclasses must implement fitting mask objects individually.

The following example shows how subclass SP works, which implements mask Snow:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> sclass(2)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
>>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 60.0
>>> states.sp = [[40.0, 10.0, 30.0, nan, 0.0],
...              [60.0, 30.0, 50.0, nan, 20.0]]
>>> from hydpy import round_
>>> round_(states.sp.average_values())
22.5
NDIM: int = 2
NUMERIC: bool = False
property refweights

Alias for the associated instance of ZoneArea for calculating areal values.

property valuevector: ndarray[Any, dtype[float64]]

Values of the individual zones; each entry is the average of the values of all snow classes of a specific zone.

We take subclass SP as an example:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> sclass(2)
>>> zonetype(FIELD)
>>> zonearea.values = 1.0, 1.0, 1.0
>>> states.sp = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
>>> from hydpy import print_vector
>>> print_vector(states.sp.valuevector)
2.5, 3.5, 4.5

The definition of valuevector of State2DSequence allows applying method average_values() like for the 1-dimensional zone-related sequences of hland:

>>> print_vector([states.sp.average_values()])
3.5
property seriesmatrix: ndarray[Any, dtype[float64]]

Time series of the values of the individual zones; each entry is the average of the values of all snow classes of a specific zone.

We take subclass SP as an example:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2000-01-05", "1d"
>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(3)
>>> sclass(2)
>>> zonetype(FIELD)
>>> zonearea.values = 1.0, 1.0, 1.0
>>> states.sp.prepare_series()
>>> states.sp.series = [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
...                     [[2.0, 3.0, 4.0], [5.0, 6.0, 7.0]],
...                     [[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]],
...                     [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]]
>>> from hydpy import print_vector
>>> for values in states.sp.seriesmatrix:
...     print_vector(values)
2.5, 3.5, 4.5
3.5, 4.5, 5.5
4.5, 5.5, 6.5
5.5, 6.5, 7.5

The definition of seriesmatrix of State2DSequence allows applying method average_series() like for the 1-dimensional zone-related sequences of hland:

>>> print_vector(states.sp.average_series())
3.5, 4.5, 5.5, 6.5
name: str = 'state2dsequence'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

Input sequences

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

Bases: InputSequences

Input sequences of model hland.

The following classes are selected:
  • P() Precipitation [mm].

  • T() Temperature [°C].

class hydpy.models.hland.hland_inputs.P(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: InputSequence

Precipitation [mm].

Required by the method:

Calc_PC_V1

NDIM: int = 0
NUMERIC: bool = False
STANDARD_NAME: ClassVar[StandardInputNames] = 'precipitation'
name: str = 'p'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_inputs.T(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: InputSequence

Temperature [°C].

Required by the methods:

Calc_TC_V1 Get_MeanTemperature_V1

NDIM: int = 0
NUMERIC: bool = False
STANDARD_NAME: ClassVar[StandardInputNames] = 'air_temperature'
name: str = 't'

Name of the variable in lowercase letters.

unit: str = '°C'

Unit of the variable.

Factor sequences

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

Bases: FactorSequences

Factor sequences of model hland.

The following classes are selected:
  • TC() Corrected temperature [°C].

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

  • RfC() Actual precipitation correction related to liquid precipitation [-].

  • SfC() Actual precipitation correction related to frozen precipitation [-].

  • CFAct() Actual degree day factor for snow (on glaciers or not) [mm/°C/T].

  • SWE() Snow water equivalent [mm].

  • GAct() Actual degree day factor for glacier ice [mm/°C/T].

  • ContriArea() Fraction of the “soil area” contributing to runoff generation [-].

class hydpy.models.hland.hland_factors.TC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor1DSequence

Corrected temperature [°C].

Calculated by the method:

Calc_TC_V1

Required by the methods:

Calc_FracRain_V1 Calc_GlMelt_In_V1 Calc_Melt_SP_WC_V1 Calc_Refr_SP_WC_V1 Get_Temperature_V1

mask
name: str = 'tc'

Name of the variable in lowercase letters.

unit: str = '°C'

Unit of the variable.

class hydpy.models.hland.hland_factors.FracRain(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor1DSequence

Fraction rainfall / total precipitation [-].

Calculated by the method:

Calc_FracRain_V1

Required by the method:

Calc_RFC_SFC_V1

mask
name: str = 'fracrain'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_factors.RfC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor1DSequence

Actual precipitation correction related to liquid precipitation [-].

Calculated by the method:

Calc_RFC_SFC_V1

Required by the methods:

Calc_PC_V1 Calc_SP_WC_V1

mask
name: str = 'rfc'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_factors.SfC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor1DSequence

Actual precipitation correction related to frozen precipitation [-].

Calculated by the method:

Calc_RFC_SFC_V1

Required by the methods:

Calc_PC_V1 Calc_SP_WC_V1

mask
name: str = 'sfc'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hland.hland_factors.CFAct(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor1DSequence

Actual degree day factor for snow (on glaciers or not) [mm/°C/T].

Calculated by the method:

Calc_CFAct_V1

Required by the method:

Calc_Melt_SP_WC_V1

mask
name: str = 'cfact'

Name of the variable in lowercase letters.

unit: str = 'mm/°C/T'

Unit of the variable.

class hydpy.models.hland.hland_factors.SWE(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor2DSequence

Snow water equivalent [mm].

Calculated by the method:

Calc_SWE_V1

mask
name: str = 'swe'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_factors.GAct(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Factor1DSequence

Actual degree day factor for glacier ice [mm/°C/T].

Calculated by the method:

Calc_GAct_V1

Required by the method:

Calc_GlMelt_In_V1

mask
name: str = 'gact'

Name of the variable in lowercase letters.

unit: str = 'mm/°C/T'

Unit of the variable.

class hydpy.models.hland.hland_factors.ContriArea(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FactorSequence

Fraction of the “soil area” contributing to runoff generation [-].

Calculated by the method:

Calc_ContriArea_V1

Required by the method:

Calc_Q0_Perc_UZ_V1

NDIM: int = 0
name: str = 'contriarea'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

Flux sequences

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

Bases: FluxSequences

Flux sequences of model hland.

The following classes are selected:
  • PC() Corrected precipitation [mm/T].

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

  • TF() Throughfall [mm/T].

  • SPL() Subbasin-internal redistribution loss of the snow’s ice content [mm/T].

  • WCL() Subbasin-internal redistribution loss of the snow’s water content [mm/T].

  • SPG() Subbasin-internal redistribution gain of the snow’s ice content [mm/T].

  • WCG() Subbasin-internal redistribution gain of the snow’s water content [mm/T].

  • GlMelt() Glacier melt [mm/T].

  • Melt() Actual melting of frozen water stored in the snow layer [mm/T].

  • Refr() Actual (re)freezing of liquid water stored in the snow layer [mm/T].

  • In_() Snow module release/soil module inflow [mm/T].

  • R() Effective soil response [mm/T].

  • SR() Sealed surface runoff [mm/T].

  • EA() Actual soil evaporation [mm/T].

  • CF() Actual capillary flow [mm/T].

  • InUZ() Inflow to the upper zone layer [mm/T].

  • Perc() Percolation from the upper to the lower zone layer [mm/T].

  • DP() Deep percolation rate [mm/T].

  • Q0() Outflow from the upper zone layer [mm/T].

  • QVs1() Percolation from the surface flow reservoir [mm/T].

  • QAb1() Surface flow [mm/T].

  • QVs2() Percolation from the interflow reservoir [mm/T].

  • QAb2() Interflow [mm/T].

  • EL() Actual lake evaporation [mm/T].

  • Q1() Outflow from the lower zone layer [mm/T].

  • RS() Surface runoff [mm/T].

  • RI() Interflow [mm/T].

  • GR1() Recharge into the fast response groundwater reservoir [mm/T].

  • RG1() Discharge from the fast response groundwater reservoir [mm/T].

  • GR2() Recharge into the first-order slow response groundwater reservoir [mm/T].

  • RG2() Discharge from the first-order slow response groundwater reservoir [mm/T].

  • GR3() Recharge into the second-order slow response groundwater reservoir [mm/T].

  • RG3() Discharge from the second-order slow response groundwater reservoir [mm/T].

  • InRC() Input of the runoff concentration submodel [mm/T].

  • OutRC() Output of the runoff concentration submodel [mm/T].

  • RT() Total model outflow [mm/T].

  • QT() Total model outflow [m³/s].

class hydpy.models.hland.hland_fluxes.PC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Corrected precipitation [mm/T].

Calculated by the method:

Calc_PC_V1

Required by the methods:

Calc_GR2_GR3_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_TF_Ic_V1 Get_Precipitation_V1

mask
name: str = 'pc'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.EI(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Interception evaporation [mm/T].

Calculated by the methods:

Calc_EI_Ic_AETModel_V1 Calc_EI_Ic_V1

mask
name: str = 'ei'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.TF(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Throughfall [mm/T].

Calculated by the method:

Calc_TF_Ic_V1

Required by the methods:

Calc_In_WC_V1 Calc_SP_WC_V1

mask
name: str = 'tf'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.SPL(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Subbasin-internal redistribution loss of the snow’s ice content [mm/T].

Calculated by the method:

Calc_SPL_WCL_SP_WC_V1

Required by the method:

Calc_SPG_WCG_SP_WC_V1

mask
name: str = 'spl'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.WCL(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Subbasin-internal redistribution loss of the snow’s water content [mm/T].

Calculated by the method:

Calc_SPL_WCL_SP_WC_V1

Required by the method:

Calc_SPG_WCG_SP_WC_V1

mask
name: str = 'wcl'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.SPG(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Subbasin-internal redistribution gain of the snow’s ice content [mm/T].

Calculated by the method:

Calc_SPG_WCG_SP_WC_V1

mask
name: str = 'spg'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.WCG(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Subbasin-internal redistribution gain of the snow’s water content [mm/T].

Calculated by the method:

Calc_SPG_WCG_SP_WC_V1

mask
name: str = 'wcg'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.GlMelt(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Glacier melt [mm/T].

Calculated by the method:

Calc_GlMelt_In_V1

mask
name: str = 'glmelt'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.Melt(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux2DSequence

Actual melting of frozen water stored in the snow layer [mm/T].

Calculated by the method:

Calc_Melt_SP_WC_V1

mask
name: str = 'melt'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.Refr(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux2DSequence

Actual (re)freezing of liquid water stored in the snow layer [mm/T].

Calculated by the method:

Calc_Refr_SP_WC_V1

mask
name: str = 'refr'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.In_(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Snow module release/soil module inflow [mm/T].

Calculated by the method:

Calc_In_WC_V1

Updated by the method:

Calc_GlMelt_In_V1

Required by the methods:

Calc_R_SM_V1 Calc_SR_V1

mask
name: str = 'in_'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.R(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Effective soil response [mm/T].

Calculated by the method:

Calc_R_SM_V1

Updated by the methods:

Calc_EA_SM_AETModel_V1 Calc_EA_SM_V1

Required by the methods:

Calc_CF_SM_V1 Calc_InRC_V1 Calc_InRC_V2 Calc_InRC_V3 Calc_InUZ_V1 Calc_QAb1_QVs1_BW1_V1 Calc_SUZ_V1

Note that PREVAH uses the abbreviation DSUZ instead of the HBV96 abbreviation R.

mask
name: str = 'r'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.SR(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Sealed surface runoff [mm/T].

Calculated by the method:

Calc_SR_V1

mask
name: str = 'sr'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.EA(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Actual soil evaporation [mm/T].

Calculated by the methods:

Calc_EA_SM_AETModel_V1 Calc_EA_SM_V1

mask
name: str = 'ea'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.CFPot(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Potential capillary flow [mm/T].

mask
name: str = 'cfpot'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.CF(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Actual capillary flow [mm/T].

Calculated by the method:

Calc_CF_SM_V1

Required by the method:

Calc_InUZ_V1

mask
name: str = 'cf'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.InUZ(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Inflow to the upper zone layer [mm/T].

Calculated by the method:

Calc_InUZ_V1

Required by the method:

Calc_Q0_Perc_UZ_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'inuz'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.Perc(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Percolation from the upper to the lower zone layer [mm/T].

Calculated by the method:

Calc_Q0_Perc_UZ_V1

Required by the method:

Calc_LZ_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'perc'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.DP(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Deep percolation rate [mm/T].

Calculated by the method:

Calc_DP_SUZ_V1

Required by the methods:

Calc_GR1_V1 Calc_GR2_GR3_V1

Note that PREVAH uses the abbreviation Perc, which is also the abbreviation used by HBV96. However, Perc is 0-dimensional while DP is 1-dimensional, which is why we need to define separate sequence classes with different names.

mask
name: str = 'dp'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.Q0(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Outflow from the upper zone layer [mm/T].

Calculated by the method:

Calc_Q0_Perc_UZ_V1

Required by the method:

Calc_InRC_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'q0'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.QVs1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Percolation from the surface flow reservoir [mm/T].

Calculated by the method:

Calc_QAb1_QVs1_BW1_V1

Required by the method:

Calc_QAb2_QVs2_BW2_V1

Note that COSERO uses the abbreviation QVS1ZON instead.

mask
name: str = 'qvs1'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.QAb1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Surface flow [mm/T].

Calculated by the method:

Calc_QAb1_QVs1_BW1_V1

Required by the method:

Calc_InRC_V3

Note that COSERO uses the abbreviation QAB1ZON instead.

mask
name: str = 'qab1'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.QVs2(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Percolation from the interflow reservoir [mm/T].

Calculated by the method:

Calc_QAb2_QVs2_BW2_V1

Required by the method:

Calc_LZ_V2

Note that COSERO uses the abbreviation QVS2ZON instead.

mask
name: str = 'qvs2'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.QAb2(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Interflow [mm/T].

Calculated by the method:

Calc_QAb2_QVs2_BW2_V1

Required by the method:

Calc_InRC_V3

Note that COSERO uses the abbreviation QAB2ZON instead.

mask
name: str = 'qab2'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.EL(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Actual lake evaporation [mm/T].

Calculated by the methods:

Calc_EL_LZ_AETModel_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1

mask
name: str = 'el'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.Q1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Outflow from the lower zone layer [mm/T].

Calculated by the method:

Calc_Q1_LZ_V1

Required by the methods:

Calc_InRC_V1 Calc_RT_V2

NDIM: int = 0
NUMERIC: bool = False
name: str = 'q1'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RS(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Surface runoff [mm/T].

Calculated by the method:

Calc_RS_RI_SUZ_V1

Required by the method:

Calc_InRC_V2

mask
name: str = 'rs'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RI(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Interflow [mm/T].

Calculated by the method:

Calc_RS_RI_SUZ_V1

Required by the method:

Calc_InRC_V2

mask
name: str = 'ri'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.GR1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Recharge into the fast response groundwater reservoir [mm/T].

Calculated by the method:

Calc_GR1_V1

Required by the methods:

Calc_GR2_GR3_V1 Calc_RG1_SG1_V1

mask
name: str = 'gr1'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RG1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: Flux1DSequence

Discharge from the fast response groundwater reservoir [mm/T].

Calculated by the method:

Calc_RG1_SG1_V1

Required by the method:

Calc_InRC_V2

mask
name: str = 'rg1'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.GR2(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Recharge into the first-order slow response groundwater reservoir [mm/T].

Calculated by the method:

Calc_GR2_GR3_V1

Required by the method:

Calc_RG2_SG2_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'gr2'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RG2(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Discharge from the first-order slow response groundwater reservoir [mm/T].

Calculated by the method:

Calc_RG2_SG2_V1

Required by the method:

Calc_InRC_V2

NDIM: int = 0
NUMERIC: bool = False
name: str = 'rg2'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.GR3(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Recharge into the second-order slow response groundwater reservoir [mm/T].

Calculated by the method:

Calc_GR2_GR3_V1

Required by the method:

Calc_RG3_SG3_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'gr3'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RG3(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Discharge from the second-order slow response groundwater reservoir [mm/T].

Calculated by the method:

Calc_RG3_SG3_V1

Required by the method:

Calc_InRC_V2

NDIM: int = 0
NUMERIC: bool = False
name: str = 'rg3'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.InRC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Input of the runoff concentration submodel [mm/T].

Calculated by the methods:

Calc_InRC_V1 Calc_InRC_V2 Calc_InRC_V3

Required by the methods:

Calc_OutRC_RConcModel_V1 Calc_OutRC_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'inrc'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.OutRC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Output of the runoff concentration submodel [mm/T].

Calculated by the methods:

Calc_OutRC_RConcModel_V1 Calc_OutRC_V1

Required by the methods:

Calc_RT_V1 Calc_RT_V2

NDIM: int = 0
NUMERIC: bool = False
name: str = 'outrc'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RO(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Sum of all flow components [mm/T].

NDIM: int = 0
NUMERIC: bool = False
name: str = 'ro'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RA(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Actual abstraction from runoff [mm/T].

NDIM: int = 0
NUMERIC: bool = False
name: str = 'ra'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.RT(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Total model outflow [mm/T].

Calculated by the methods:

Calc_RT_V1 Calc_RT_V2

Required by the method:

Calc_QT_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'rt'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_fluxes.QT(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Total model outflow [m³/s].

Calculated by the method:

Calc_QT_V1

Required by the method:

Pass_Q_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'qt'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

State sequences

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

Bases: StateSequences

State sequences of model hland.

The following classes are selected:
  • Ic() Interception storage [mm].

  • SP() Frozen water stored in the snow layer [mm].

  • WC() Liquid water content of the snow layer [mm].

  • SM() Soil moisture [mm].

  • UZ() Storage in the upper zone layer [mm].

  • SUZ() Upper storage reservoir [mm].

  • BW1() Water stored in the surface flow reservoir [mm].

  • BW2() Water stored in the interflow reservoir [mm].

  • LZ() Storage in the lower zone layer [mm].

  • SG1() Fast response groundwater reservoir [mm].

  • SG2() First-order slow response groundwater reservoir [mm].

  • SG3() Second-order slow response groundwater reservoir [mm].

class hydpy.models.hland.hland_states.Ic(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State1DSequence

Interception storage [mm].

Updated by the methods:

Calc_EI_Ic_AETModel_V1 Calc_EI_Ic_V1 Calc_TF_Ic_V1

Required by the method:

Get_InterceptedWater_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
mask
name: str = 'ic'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SP(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State2DSequence

Frozen water stored in the snow layer [mm].

Updated by the methods:

Calc_Melt_SP_WC_V1 Calc_Refr_SP_WC_V1 Calc_SPG_WCG_SP_WC_V1 Calc_SPL_WCL_SP_WC_V1 Calc_SP_WC_V1

Required by the methods:

Calc_GlMelt_In_V1 Calc_In_WC_V1 Calc_SWE_V1 Get_SnowCover_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
mask
trim(lower=None, upper=None) bool[source]

Trim SP following \(WC \leq WHC \cdot SP\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(7)
>>> sclass(2)
>>> whc(0.1)
>>> states.sp([[-1.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0],
...            [-2.0, 0.0, 0.0, 6.0, 6.0, 6.0, 6.0]])
>>> states.sp
sp([[0.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0],
    [0.0, 0.0, 0.0, 6.0, 6.0, 6.0, 6.0]])
>>> states.wc.values = [[-1.0, 0.0, 1.0, -1.0, 0.0, 0.5, 1.0],
...                     [-1.0, 0.0, 1.0, -1.0, 0.0, 0.5, 1.0]]
>>> states.sp([[-1.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0],
...            [-2.0, 0.0, 0.0, 6.0, 6.0, 6.0, 6.0]])
>>> states.sp
sp([[0.0, 0.0, 10.0, 5.0, 5.0, 5.0, 10.0],
    [0.0, 0.0, 10.0, 6.0, 6.0, 6.0, 10.0]])
>>> whc(0.0)
>>> states.wc.values = 0.0
>>> states.sp([[-1.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0],
...            [-2.0, 0.0, 0.0, 6.0, 6.0, 6.0, 6.0]])
>>> states.sp
sp([[0.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0],
    [0.0, 0.0, 0.0, 6.0, 6.0, 6.0, 6.0]])
name: str = 'sp'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.WC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State2DSequence

Liquid water content of the snow layer [mm].

Updated by the methods:

Calc_In_WC_V1 Calc_Melt_SP_WC_V1 Calc_Refr_SP_WC_V1 Calc_SPG_WCG_SP_WC_V1 Calc_SPL_WCL_SP_WC_V1 Calc_SP_WC_V1

Required by the method:

Calc_SWE_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
mask
trim(lower=None, upper=None) bool[source]

Trim WC following \(WC \leq WHC \cdot SP\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(7)
>>> sclass(2)
>>> whc(0.1)
>>> states.sp = [[0.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0],
...              [0.0, 0.0, 0.0, 5.0, 5.0, 5.0, 5.0]]
>>> states.wc([[-1.0, 0.0, 1.0, -1.0, 0.0, 0.5, 1.0],
...            [-0.2, 0.0, 0.2, -0.2, 0.0, 0.1, 0.2]])
>>> states.wc
wc([[0.0, 0.0, 0.0, 0.0, 0.0, 0.5, 0.5],
    [0.0, 0.0, 0.0, 0.0, 0.0, 0.1, 0.2]])
name: str = 'wc'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SM(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State1DSequence

Soil moisture [mm].

Updated by the methods:

Calc_CF_SM_V1 Calc_EA_SM_AETModel_V1 Calc_EA_SM_V1 Calc_R_SM_V1

Required by the methods:

Calc_ContriArea_V1 Get_SoilWater_V1

Note that PREVAH uses the abbreviation SSM, and COSERO uses the abbreviation BW0ZON instead of the HBV96 abbreviation SM.

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
mask
trim(lower=None, upper=None) bool[source]

Trim SM following \(0 \leq SM \leq FC\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> fc(200.0)
>>> states.sm(-100.0, 0.0, 100.0, 200.0, 300.0)
>>> states.sm
sm(0.0, 0.0, 100.0, 200.0, 200.0)
name: str = 'sm'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.UZ(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Storage in the upper zone layer [mm].

Updated by the method:

Calc_Q0_Perc_UZ_V1

Required by the method:

Calc_CF_SM_V1

NDIM: int = 0
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'uz'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SUZ(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State1DSequence

Upper storage reservoir [mm].

Updated by the methods:

Calc_DP_SUZ_V1 Calc_RS_RI_SUZ_V1 Calc_SUZ_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'suz'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.BW1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State1DSequence

Water stored in the surface flow reservoir [mm].

Updated by the method:

Calc_QAb1_QVs1_BW1_V1

Note that COSERO uses the abbreviation BW1ZON instead.

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
mask
name: str = 'bw1'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.BW2(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State1DSequence

Water stored in the interflow reservoir [mm].

Updated by the method:

Calc_QAb2_QVs2_BW2_V1

Note that COSERO uses the abbreviation BW2ZON instead.

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
mask
name: str = 'bw2'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.LZ(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Storage in the lower zone layer [mm].

Updated by the methods:

Calc_EL_LZ_AETModel_V1 Calc_EL_LZ_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_Q1_LZ_V1

Note that COSERO uses the abbreviation BW3Geb instead of the HBV96 abbreviation LZ.

NDIM: int = 0
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
trim(lower=None, upper=None) bool[source]

Trim negative values if the actual subbasin does not contain an internal lake.

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(2)
>>> zonetype(FIELD, ILAKE)
>>> states.lz(-1.0)
>>> states.lz
lz(-1.0)
>>> zonetype(FIELD, FOREST)
>>> states.lz(-1.0)
>>> states.lz
lz(0.0)
>>> states.lz(1.0)
>>> states.lz
lz(1.0)
name: str = 'lz'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SG1(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: State1DSequence

Fast response groundwater reservoir [mm].

Updated by the methods:

Calc_GR1_V1 Calc_RG1_SG1_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
mask
trim(lower=None, upper=None) bool[source]

Trim SG1 following \(0 \leq SG1 \leq SG1Max\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> sg1max(100.0)
>>> states.sg1(-50.0, 0.0, 50.0, 100.0, 150.0)
>>> states.sg1
sg1(0.0, 0.0, 50.0, 100.0, 100.0)
name: str = 'sg1'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SG2(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

First-order slow response groundwater reservoir [mm].

Updated by the methods:

Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_RG2_SG2_V1

NDIM: int = 0
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'sg2'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SG3(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Second-order slow response groundwater reservoir [mm].

Updated by the methods:

Calc_EL_SG2_SG3_AETModel_V1 Calc_EL_SG2_SG3_V1 Calc_RG3_SG3_V1

NDIM: int = 0
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'sg3'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

class hydpy.models.hland.hland_states.SC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Storage cascade for runoff concentration [mm].

NDIM: int = 1
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'sc'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

Outlet sequences

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

Bases: OutletSequences

Outlet sequences of model hland.

The following classes are selected:
  • Q() Runoff [m³/s].

class hydpy.models.hland.hland_outlets.Q(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: OutletSequence

Runoff [m³/s].

Calculated by the method:

Pass_Q_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'q'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

Aide sequences

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

Bases: AideSequences

Aide sequences of model hland.

The following classes are selected:
  • SPE() Subbasin-internal redistribution excess of the snow’s ice content [mm/T].

  • WCE() Subbasin-internal redistribution excess of the snow’s water content [mm/T].

class hydpy.models.hland.hland_aides.SPE(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: AideSequence

Subbasin-internal redistribution excess of the snow’s ice content [mm/T].

Calculated by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 1
NUMERIC: bool = False
name: str = 'spe'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.hland.hland_aides.WCE(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: AideSequence

Subbasin-internal redistribution excess of the snow’s water content [mm/T].

Calculated by the method:

Calc_SPG_WCG_SP_WC_V1

NDIM: int = 1
NUMERIC: bool = False
name: str = 'wce'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

Auxiliary Features

Masks

class hydpy.models.hland.Masks[source]

Bases: Masks

Masks of base model hland.

The following classes are selected:
class hydpy.models.hland.hland_masks.HLandBaseMask(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: IndexMask

To be overridden.

static get_refindices(variable)[source]

Reference to the associated instance of ZoneType.

name: str = 'hlandbasemask'
class hydpy.models.hland.hland_masks.Complete(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including all types of zones.

relevant: tuple[int, ...] = (1, 2, 4, 3, 5)

The integer values that are relevant to the referenced index parameter.

name: str = 'complete'
class hydpy.models.hland.hland_masks.Land(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including zones of type FIELD, FOREST, GLACIER, and SEALED.

relevant: tuple[int, ...] = (1, 2, 3, 5)

The integer values that are relevant to the referenced index parameter.

name: str = 'land'
class hydpy.models.hland.hland_masks.Interception(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including zones of type FIELD, FOREST, and SEALED.

relevant: tuple[int, ...] = (1, 2, 5)

The integer values that are relevant to the referenced index parameter.

name: str = 'interception'
class hydpy.models.hland.hland_masks.Snow(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including zones of type FIELD, FOREST, GLACIER, and SEALED.

relevant: tuple[int, ...] = (1, 2, 3, 5)

The integer values that are relevant to the referenced index parameter.

name: str = 'snow'
class hydpy.models.hland.hland_masks.Soil(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including zones of type FIELD and FOREST.

relevant: tuple[int, ...] = (1, 2)

The integer values that are relevant to the referenced index parameter.

name: str = 'soil'
class hydpy.models.hland.hland_masks.UpperZone(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including zones of type FIELD, FOREST, and GLACIER.

relevant: tuple[int, ...] = (1, 2, 3)

The integer values that are relevant to the referenced index parameter.

name: str = 'upperzone'
class hydpy.models.hland.hland_masks.Field(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask for zone type FIELD.

relevant: tuple[int, ...] = (1,)

The integer values that are relevant to the referenced index parameter.

name: str = 'field'
class hydpy.models.hland.hland_masks.Forest(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask for zone type FOREST.

relevant: tuple[int, ...] = (2,)

The integer values that are relevant to the referenced index parameter.

name: str = 'forest'
class hydpy.models.hland.hland_masks.ILake(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask for zone type ILAKE.

relevant: tuple[int, ...] = (4,)

The integer values that are relevant to the referenced index parameter.

name: str = 'ilake'
class hydpy.models.hland.hland_masks.Glacier(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask for zone type GLACIER.

relevant: tuple[int, ...] = (3,)

The integer values that are relevant to the referenced index parameter.

name: str = 'glacier'
class hydpy.models.hland.hland_masks.Sealed(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask for zone type SEALED.

relevant: tuple[int, ...] = (5,)

The integer values that are relevant to the referenced index parameter.

name: str = 'sealed'
class hydpy.models.hland.hland_masks.NoGlacier(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: HLandBaseMask

Mask including zones of type FIELD, FOREST, and ILAKE.

relevant: tuple[int, ...] = (1, 2, 4, 5)

The integer values that are relevant to the referenced index parameter.

name: str = 'noglacier'
class hydpy.models.hland.AideSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: AideSequences

Aide sequences of model hland.

The following classes are selected:
  • SPE() Subbasin-internal redistribution excess of the snow’s ice content [mm/T].

  • WCE() Subbasin-internal redistribution excess of the snow’s water content [mm/T].

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

Bases: SubParameters

Control parameters of model hland.

The following classes are selected:
  • Area() Subbasin area [km²].

  • NmbZones() Number of zones (hydrological response units) in a subbasin [-].

  • SClass() Number of snow classes in each zone [-].

  • ZoneType() Type of each zone [-].

  • ZoneArea() Zone area [km²].

  • Psi() Fraction of the actual sealing of zones classified as SEALED [-].

  • ZoneZ() Zone elevation [100m].

  • PCorr() General precipitation correction factor [-].

  • PCAlt() Elevation correction factor for precipitation [1/100m].

  • RfCF() Rainfall correction factor [-].

  • SfCF() Snowfall correction factor [-].

  • TCorr() General temperature correction addend [-].

  • TCAlt() Elevation correction factor for temperature [-1°C/100m].

  • IcMax() Maximum interception storage [mm].

  • SFDist() Distribution of snowfall [-].

  • SMax() Maximum snow water equivalent [mm].

  • SRed() Snow redistribution paths [-].

  • TT() Temperature threshold for snow/rain [°C].

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

  • DTTM() Difference between TTM and TT [°C].

  • CFMax() Average degree day factor for snow (on glaciers or not) [mm/°C/T].

  • CFVar() Annual variability of CFMax [mm/°C/T].

  • GMelt() Degree day factor for glacial ice [mm/°C/T].

  • GVar() Annual variability of GMelt [mm/°C/T].

  • CFR() Refreezing factor for water stored within the snow layer [-].

  • WHC() Relative water holding capacity of the snow layer [-].

  • FC() Maximum soil moisture content (field capacity) [mm].

  • Beta() Nonlinearity parameter of the soil routine [-].

  • PercMax() Maximum percolation rate [mm/T].

  • CFlux() Capacity (maximum) of the capillary return flux [mm/T].

  • RespArea() Flag to enable the contributing area approach [-].

  • RecStep() Number of internal computation steps per simulation time step [-].

  • Alpha() Nonlinearity parameter of the upper zone layer [-].

  • K() Recession coefficient of the upper zone layer [1/T/mm^alpha].

  • SGR() Threshold content of SUZ for the generation of surface runoff [mm].

  • K0() Storage time for surface runoff [T].

  • H1() Outlet level of the reservoir for simulating surface flow [mm].

  • TAb1() Recession coefficient for simulating surface flow [T].

  • TVs1() Recession coefficient for simulating percolation from the surface flow module [T].

  • K1() Storage time for interflow [T].

  • SG1Max() Maximum content of the fast response groundwater reservoir SG1 [mm].

  • H2() Outlet level of the reservoir for simulating interflow [mm].

  • TAb2() Recession coefficient for simulating interflow [T].

  • TVs2() Recession coefficient for simulating percolation from the interflow module [T].

  • K4() Recession coefficient of the lower zone layer [1/T].

  • K2() Storage time for quick response baseflow [T].

  • K3() Storage time for delayed baseflow [T].

  • Gamma() Nonlinearity parameter of the lower zone layer [-].

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

Bases: SubParameters

Derived parameters of model hland.

The following classes are selected:
  • DOY() References the dayofyear index array provided by the instance of class Indexer available in module pub [-].

  • RelZoneAreas() Relative area of all zones [-].

  • RelSoilArea() Relative area of all FIELD and FOREST zones [-].

  • RelLandArea() Relative area of all FIELD, FOREST, GLACIER, and SEALED zones [-].

  • RelUpperZoneArea() Relative area of all FIELD, FOREST, and GLACIER zones [-].

  • RelLowerZoneArea() Relative area of all FIELD, FOREST, GLACIER, and ILAKE zones [-].

  • ZoneAreaRatios() Ratios of all zone combinations [-].

  • IndicesZoneZ() Indices of the zones sorted by altitude [-].

  • Z() Average (reference) subbasin elevation [100m].

  • SRedOrder() Processing order for the snow redistribution routine [-].

  • SRedEnd() Flags that indicate the “dead ends” of snow redistribution within a subbasin.

  • SRedNumber() The total number of snow redistribution paths [-].

  • TTM() Threshold temperature for snow melting and refreezing [°C].

  • DT() Relative time step length for the upper zone layer calculations [-].

  • W0() Weight for calculating surface runoff [-].

  • W1() Weight for calculating interflow [-].

  • W2() Weight for calculating the quick response base flow [-].

  • W3() Weight for calculating the response of the first-order groundwater reservoir [-].

  • K4() Storage time for very delayed baseflow [T].

  • W4() Weight for calculating the response of the second-order groundwater reservoir [-].

  • QFactor() Factor for converting mm/stepsize to m³/s.

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

Bases: FactorSequences

Factor sequences of model hland.

The following classes are selected:
  • TC() Corrected temperature [°C].

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

  • RfC() Actual precipitation correction related to liquid precipitation [-].

  • SfC() Actual precipitation correction related to frozen precipitation [-].

  • CFAct() Actual degree day factor for snow (on glaciers or not) [mm/°C/T].

  • SWE() Snow water equivalent [mm].

  • GAct() Actual degree day factor for glacier ice [mm/°C/T].

  • ContriArea() Fraction of the “soil area” contributing to runoff generation [-].

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

Bases: SubParameters

Fixed parameters of model hland.

The following classes are selected:
  • Pi() π [-].

  • FSG() Fraction between the spatial extents of the first-order and the second-order slow response groundwater reservoir [-].

  • K1L() Lowest possible lower boundary value for the parameters K1, K2, and K3 [-].

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

Bases: FluxSequences

Flux sequences of model hland.

The following classes are selected:
  • PC() Corrected precipitation [mm/T].

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

  • TF() Throughfall [mm/T].

  • SPL() Subbasin-internal redistribution loss of the snow’s ice content [mm/T].

  • WCL() Subbasin-internal redistribution loss of the snow’s water content [mm/T].

  • SPG() Subbasin-internal redistribution gain of the snow’s ice content [mm/T].

  • WCG() Subbasin-internal redistribution gain of the snow’s water content [mm/T].

  • GlMelt() Glacier melt [mm/T].

  • Melt() Actual melting of frozen water stored in the snow layer [mm/T].

  • Refr() Actual (re)freezing of liquid water stored in the snow layer [mm/T].

  • In_() Snow module release/soil module inflow [mm/T].

  • R() Effective soil response [mm/T].

  • SR() Sealed surface runoff [mm/T].

  • EA() Actual soil evaporation [mm/T].

  • CF() Actual capillary flow [mm/T].

  • InUZ() Inflow to the upper zone layer [mm/T].

  • Perc() Percolation from the upper to the lower zone layer [mm/T].

  • DP() Deep percolation rate [mm/T].

  • Q0() Outflow from the upper zone layer [mm/T].

  • QVs1() Percolation from the surface flow reservoir [mm/T].

  • QAb1() Surface flow [mm/T].

  • QVs2() Percolation from the interflow reservoir [mm/T].

  • QAb2() Interflow [mm/T].

  • EL() Actual lake evaporation [mm/T].

  • Q1() Outflow from the lower zone layer [mm/T].

  • RS() Surface runoff [mm/T].

  • RI() Interflow [mm/T].

  • GR1() Recharge into the fast response groundwater reservoir [mm/T].

  • RG1() Discharge from the fast response groundwater reservoir [mm/T].

  • GR2() Recharge into the first-order slow response groundwater reservoir [mm/T].

  • RG2() Discharge from the first-order slow response groundwater reservoir [mm/T].

  • GR3() Recharge into the second-order slow response groundwater reservoir [mm/T].

  • RG3() Discharge from the second-order slow response groundwater reservoir [mm/T].

  • InRC() Input of the runoff concentration submodel [mm/T].

  • OutRC() Output of the runoff concentration submodel [mm/T].

  • RT() Total model outflow [mm/T].

  • QT() Total model outflow [m³/s].

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

Bases: InputSequences

Input sequences of model hland.

The following classes are selected:
  • P() Precipitation [mm].

  • T() Temperature [°C].

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

Bases: OutletSequences

Outlet sequences of model hland.

The following classes are selected:
  • Q() Runoff [m³/s].

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

Bases: StateSequences

State sequences of model hland.

The following classes are selected:
  • Ic() Interception storage [mm].

  • SP() Frozen water stored in the snow layer [mm].

  • WC() Liquid water content of the snow layer [mm].

  • SM() Soil moisture [mm].

  • UZ() Storage in the upper zone layer [mm].

  • SUZ() Upper storage reservoir [mm].

  • BW1() Water stored in the surface flow reservoir [mm].

  • BW2() Water stored in the interflow reservoir [mm].

  • LZ() Storage in the lower zone layer [mm].

  • SG1() Fast response groundwater reservoir [mm].

  • SG2() First-order slow response groundwater reservoir [mm].

  • SG3() Second-order slow response groundwater reservoir [mm].