hland_v1

Version 1 of the H-Land model is designed to agree with the HBV96 configuration of the HBV model used by the German Federal Institute of Hydrology (BfG) but offers more flexibility in some regards (e.g. in parameterization). It can briefly be summarized as follows:

  • Calculates the actual potential evapotranspiration from reference potential evaporation values.

  • Applies separate correction factors on the liquid and the frozen amount of precipitation.

  • Implements interception with simple “buckets”.

  • Uses the degree-day method for calculating snowmelt.

  • Considers both the melting of ice and the (re)freezing of water within the snow layer.

  • Assumes a linear relationship between soil evaporation and relative soil moisture (as long as a maximum evaporation value is not exceeded).

  • Assumes a saturation excess mechanism for the generation of direct runoff.

  • Provides an optional “response area” option, which modifies the usual calculation of direct runoff and percolation.

  • Distinguishes between an upper zone layer related to direct runoff and a lower zone layer related to base flow.

  • Allows for percolation from the upper to the lower zone layer and allows for a capillary rise from upper zone layer to the soils layer.

  • Considers water areas as “groundwater lakes” being connected with the lower zone layer.

  • In contrast to the original HBV96 implementation, both the upper and the lower zone layer can be handled as nonlinear storages.

  • Conceptualizes the melting of glacial ice with an additional application of the degree-day method.

The following figure shows the general structure of H-Land Version 1. Note that zones of type FIELD and FOREST are based on the same set of process equations:

_images/HydPy-H-Land_Version-1.png

Integration tests

Note

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

The following integration tests are based on the data used for testing application model lland_v2. Hopefully, this eases drawing comparisons between both models.

All integration tests are performed over a period of five days with a simulation step of one hour:

>>> from hydpy import pub
>>> pub.timegrids = "01.01.2000", "05.01.2000", "1h"

Prepare the model instance and build the connections to element land and node outlet:

>>> from hydpy.models.hland_v1 import *
>>> parameterstep("1h")
>>> from hydpy import Node, Element
>>> outlet = Node("outlet")
>>> land = Element("land", outlets=outlet)
>>> land.model = model

All tests shall be performed using a single zone with a size of one square kilometre at an altitude of 100 meter:

>>> nmbzones(1)
>>> area(1.0)
>>> zonearea(1.0)
>>> zonez(1.0)

The reference elevation levels for precipitation (ZRelP), temperature (ZRelT), and evaporation (ZRelE) are all set to 200 m:

>>> zrelp(2.0)
>>> zrelt(2.0)
>>> zrele(2.0)

Initialize a test function object, which prepares and runs the tests and prints their results for the given sequences:

>>> from hydpy import IntegrationTest
>>> IntegrationTest.plotting_options.axis1 = inputs.p, fluxes.outuh, fluxes.qt
>>> IntegrationTest.plotting_options.axis2 = inputs.t
>>> test = IntegrationTest(land)
>>> test.dateformat = "%d/%m %H:00"

field

In the first example, FIELD is selected as the only zone type (note that the results for type FOREST would be the same):

>>> zonetype(FIELD)

The following set of control parameter values tries to configure application model hland_v1 in a manner that allows to retrace the influence of the different implemented methods on the shown results:

>>> pcorr(1.2)
>>> pcalt(0.1)
>>> rfcf(1.1)
>>> sfcf(1.3)
>>> tcalt(0.6)
>>> ecorr(0.8)
>>> ecalt(-0.1)
>>> epf(0.1)
>>> etf(0.1)
>>> ered(0.5)
>>> icmax(2.0)
>>> tt(0.0)
>>> ttint(2.0)
>>> dttm(1.0)
>>> cfmax(0.5)
>>> gmelt(1.0)
>>> cfr(0.1)
>>> whc(0.4)
>>> fc(200.0)
>>> lp(0.8)
>>> beta(2.0)
>>> percmax(0.5)
>>> cflux(0.1)
>>> alpha(2.0)
>>> k(0.001)
>>> k4(0.005)
>>> gamma(0.0)
>>> maxbaz(3)
>>> abstr(0.003)

Initially, relative soil moisture is 50 % and the lower zone layer contains only 10 mm. All other storages are empty:

>>> test.inits = ((states.ic, 0.0),
...               (states.sp, 0.0),
...               (states.wc, 0.0),
...               (states.sm, 100.0),
...               (states.uz, 0.0),
...               (states.lz, 10.0),
...               (logs.quh, 0.05))

As mentioned above, the values of the input sequences P, T, and EPN are taken from here. For educational purposes, unrealistically high values of EPN are used again. For the sake of simplicity, the values of TN are assumed to be constantly 1 °C below the values of T:

>>> inputs.p.series = (
...     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.2, 0.0, 0.0, 1.3, 5.6, 2.9, 4.9, 10.6, 0.1, 0.7, 3.0,
...     2.1, 10.4, 3.5, 3.4, 1.2, 0.1, 0.0, 0.0, 0.4, 0.1, 3.6, 5.9, 1.1,
...     20.7, 37.9, 8.2, 3.6, 7.5, 18.5, 15.4, 6.3, 1.9, 4.9, 2.7, 0.5,
...     0.2, 0.5, 2.4, 0.4, 0.2, 0.0, 0.0, 0.3, 2.6, 0.7, 0.3, 0.3, 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.3, 0.0,
...     0.0, 0.0, 0.7, 0.4, 0.1, 0.4, 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)
>>> inputs.t.series = (
...     21.2, 19.4, 18.9, 18.3, 18.9, 22.5, 25.1, 28.3, 27.8, 31.4, 32.2,
...     35.2, 37.1, 31.2, 24.3, 25.4, 25.9, 23.7, 21.6, 21.2, 20.4, 19.8,
...     19.6, 19.2, 19.2, 19.2, 18.9, 18.7, 18.5, 18.3, 18.5, 18.8, 18.8,
...     19.0, 19.2, 19.3, 19.0, 18.8, 18.7, 17.8, 17.4, 17.3, 16.8, 16.5,
...     16.3, 16.2, 15.5, 14.6, 14.7, 14.6, 14.1, 14.3, 14.9, 15.7, 16.0,
...     16.7, 17.1, 16.2, 15.9, 16.3, 16.3, 16.4, 16.5, 18.4, 18.3, 18.1,
...     16.7, 15.2, 13.4, 12.4, 11.6, 11.0, 10.5, 11.7, 11.9, 11.2, 11.1,
...     11.9, 12.2, 11.8, 11.4, 11.6, 13.0, 17.1, 18.2, 22.4, 21.4, 21.8,
...     22.2, 20.1, 17.8, 15.2, 14.5, 12.4, 11.7, 11.9)
>>> inputs.tn.series = inputs.t.series-1.0
>>> inputs.epn.series = (
...     0.100707, 0.097801, 0.096981, 0.09599, 0.096981, 0.102761,
...     0.291908, 1.932875, 4.369536, 7.317556, 8.264362, 9.369867,
...     5.126178, 6.62503, 7.397619, 2.39151, 1.829834, 1.136569,
...     0.750986, 0.223895, 0.099425, 0.098454, 0.098128, 0.097474,
...     0.097474, 0.097474, 0.096981, 0.096652, 0.096321, 0.09599,
...     0.187298, 1.264612, 3.045538, 1.930758, 2.461001, 6.215945,
...     3.374783, 8.821555, 4.046025, 2.110757, 2.239257, 2.877848,
...     1.591452, 0.291604, 0.092622, 0.092451, 0.091248, 0.089683,
...     0.089858, 0.089683, 0.088805, 0.089157, 0.090207, 0.091593,
...     0.154861, 0.470369, 1.173726, 4.202296, 4.359715, 5.305753,
...     5.376027, 4.658915, 7.789594, 4.851567, 5.30692, 3.286036,
...     1.506216, 0.274762, 0.087565, 0.085771, 0.084317, 0.083215,
...     0.082289, 0.0845, 0.084864, 0.083584, 0.0834, 0.084864, 0.310229,
...     1.391958, 3.195876, 5.191651, 7.155036, 8.391432, 8.391286,
...     10.715238, 9.383394, 7.861915, 6.298329, 2.948416, 1.309232,
...     0.32955, 0.089508, 0.085771, 0.0845, 0.084864)

In the first example, the RespArea option is disabled and a relatively large value for the accuracy related parameter RecStep is set:

>>> resparea(False)
>>> recstep(100)

The following results show the response of application model hland_v1 to the given extreme precipitation event, which is strongly attenuated by the large evaporation values. One striking difference to other models like lland_v2 is the block-like appearance of percolation (Perc), which is one reason for the unusual transitions between event periods (with relevant amounts of both runoff components Q0 and Q1) and the subsequent pure base flow periods (with relevant amounts of Q1 only):

>>> test("hland_v1_field")
Click to see the table
Click to see the graph

contributing area

The functionality of hland_v1 can be changed substantially by enabling its RespArea option, which decreases Perc but increases Q0 in dry periods (regarding relative soil moisture). Hence the graph of Perc appears less blocky and reaches its maximum at the same time as the graph of SM, whereas Q0 shows more pronounced peaks in the initial subperiod when the soil is not saturated yet:

>>> resparea(True)
>>> test("hland_v1_resparea")
Click to see the table
Click to see the graph

low accuracy

The next example is supposed to demonstrate that one should be careful when reducing the value of RecStep in order to save computation times. Setting RecStep to one, which is the lowest possible value, results in low accuracies in the calculation of Q0. This can easily be seen when comparing the Q0 graph of the last example and the Q0 graph of this example. Obviously, the Q0 graph of this example is (much more) wrong, as its maximum peak is largely above the maximum peak of R, which is physically impossible:

>>> recstep(1)
>>> test("hland_v1_low_accuracy")
Click to see the table
Click to see the graph

internal lake

In the fourth example, the functionality of zones of type ILAKE is demonstrated. For these “internal lakes” only the lower zone storage (LZ) is relevant (all other storage values are zero). Precipitation (PC) is directly added to LZ and evaporation (EPC) is directly subtracted from LZ. The latter occurs even when LZ is completely empty, possibly resulting in negative storage values in drought periods. The only case for which lake evaporation (EL) is prevented is when the actual temperature (TC) is below the threshold temperature for the occurrence of lake ice (TTIce). In this example, the value of TTIce is set to the unrealistic value of 13°C, resulting in a deviation between the graphs of EPC and EL for the last day of the simulation period:

>>> recstep(100)
>>> zonetype(ILAKE)
>>> ttice(13.0)
>>> parameters.update()
>>> test("hland_v1_ilake")
Click to see the table
Click to see the graph

glacier

This example demonstrates the functionality of zones of type GLACIER. GLACIER zones are similar to zones of type FIELD or FOREST, but possess neither an interception storage nor a soil storage. Instead, all precipitation or melting water is passed to the upper zone storage (UZ) directly. The snow routines of GLACIER, FIELD, and FOREST zones are identical. Additional glacier melt can only occur if the glacier is not covered by any snow. In the following test run, the simulation time period can be distinguished into three subperiods. On the first two days (-20°C), the snow layer builds up. On the third day (+20°C and SP > 0), the snow melts and (with some time delay) the melted water is released. On the fourth day (+20°C and SP = 0), an increased amount of water is passed to UZ, as GMelt is set to a larger value than CFMax:

>>> zonetype(GLACIER)
>>> parameters.update()
>>> inputs.t.series[:48] = -20.0
>>> inputs.t.series[48:] = 20.0
>>> inputs.tn.series = inputs.t.series
>>> test("hland_v1_glacier")
Click to see the table
Click to see the graph
class hydpy.models.hland_v1.Model[source]

Bases: hydpy.core.modeltools.AdHocModel

HBV96 version of HydPy-H-Land (hland_v1).

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_TMean_V1 Calculate the areal mean temperature of the subbasin.

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

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

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

  • Calc_EP_V1 Adjust potential norm evaporation to the actual temperature.

  • Calc_EPC_V1 Apply the evaporation correction factors and adjust evaporation to the altitude of the individual zones.

  • Calc_TF_Ic_V1 Calculate throughfall and update the interception storage accordingly.

  • Calc_EI_Ic_V1 Calculate interception evaporation and update the interception storage accordingly.

  • Calc_SP_WC_V1 Add throughfall to the snow layer.

  • Calc_Melt_SP_WC_V1 Calculate 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_GlMelt_In_V1 Calculate melting from glaciers which are actually not covered by a snow layer and add it to the water release of the snow module.

  • Calc_R_SM_V1 Calculate effective precipitation and update soil moisture.

  • Calc_CF_SM_V1 Calculate capillary flow and update soil moisture.

  • Calc_EA_SM_V1 Calculate soil evaporation and update soil moisture.

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

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

  • Calc_Q0_Perc_UZ_V1 Perform the upper zone layer routine which determines percolation to the lower zone layer and the fast response of the hland model.

  • Calc_LZ_V1 Update the lower zone layer in accordance with percolation from upper groundwater to lower groundwater and/or in accordance with lake precipitation.

  • Calc_EL_LZ_V1 Calculate lake evaporation.

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

  • Calc_InUH_V1 Calculate the unit hydrograph input.

  • Calc_OutUH_QUH_V1 Calculate the unit hydrograph output (convolution).

  • Calc_QT_V1 Calculate the total discharge after possible abstractions.

The following “outlet update methods” are called in the given sequence at the end of each simulation step:
class hydpy.models.hland_v1.Masks[source]

Bases: hydpy.core.masktools.Masks

Masks applicable to hland_v1.

The following classes are selected:
class hydpy.models.hland_v1.ControlParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Control parameters of model hland_v1.

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

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

  • ZoneType() Type of each zone.

  • ZoneArea() Zone area [km²].

  • ZoneZ() Zone elevation [100m].

  • ZRelP() Subbasin-wide reference elevation level for precipitation [100m].

  • ZRelT() Subbasin-wide reference elevation level for temperature [100m].

  • ZRelE() Subbasin-wide reference elevation level for evaporation [100m].

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

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

  • RfCF() Rainfall correction factor [-].

  • SfCF() Snowfall correction factor [-].

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

  • ECorr() General evaporation correction factor [-].

  • ECAlt() Elevation correction factor for evaporation [-1/100m].

  • EPF() Decrease in potential evaporation due to precipitation [T/mm].

  • ETF() Temperature factor for evaporation [1/°C].

  • ERed() Factor for restricting actual to potential evaporation [-].

  • TTIce() Temperature threshold for lake evaporation [°C].

  • IcMax() Maximum interception storage [mm].

  • 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() Degree day factor for snow (on glaciers or not) [mm/°C/T].

  • GMelt() Degree day factor for glacial ice [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].

  • LP() Relative limit for potential evaporation [-].

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

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

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

  • MaxBaz() Base length of the triangle unit hydrograph [T].

  • Abstr() Abstraction of water from computed outflow [m³/s].

class hydpy.models.hland_v1.DerivedParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Derived parameters of model hland_v1.

The following classes are selected:
class hydpy.models.hland_v1.FluxSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.OutputSequences[FluxSequence]

Flux sequences of model hland_v1.

The following classes are selected:
  • TMean() Mean subbasin temperature [°C].

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

  • PC() Corrected precipitation [mm].

  • EP() Potential evaporation [mm].

  • EPC() Corrected potential evaporation [mm].

  • EI() Interception evaporation [mm].

  • TF() Throughfall [mm].

  • GlMelt() Glacier melt [mm].

  • Melt() Actual melting of frozen water stored in the snow layer [mm].

  • Refr() Actual (re)freezing of liquid water stored in the snow layer [mm].

  • In_() Snow module release/soil module inflow [mm].

  • R() Effective soil response [mm].

  • EA() Actual soil evaporation [mm].

  • CF() Actual capillary flow [mm].

  • ContriArea() Fraction of the soil area contributing to runoff generation [-].

  • InUZ() Inflow to the upper zone layer [mm].

  • Perc() Percolation from the upper to the lower zone layer [mm].

  • Q0() Outflow from the upper zone layer [mm].

  • EL() Actual lake evaporation [mm].

  • Q1() Outflow from the lower zone layer [mm].

  • InUH() Input of the triangle unit hydrograph [m].

  • OutUH() Output of the triangle unit hydrograph [m].

  • QT() Total model outflow [m³/s].

class hydpy.models.hland_v1.InputSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.ModelIOSequences[InputSequence, hydpy.core.sequencetools.FastAccessInputSequence]

Input sequences of model hland_v1.

The following classes are selected:
  • P() Precipitation [mm].

  • T() Temperature [°C].

  • TN() Normal temperature [°C].

  • EPN() Normal potential evaporation [mm].

class hydpy.models.hland_v1.LogSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.ModelSequences[LogSequence, hydpy.core.variabletools.FastAccess]

Log sequences of model hland_v1.

The following classes are selected:
  • QUH() Whole outflow delayed by means of the unit hydrograph [mm].

class hydpy.models.hland_v1.OutletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.LinkSequences[OutletSequence]

Outlet sequences of model hland_v1.

The following classes are selected:
  • Q() Runoff [m³/s].

class hydpy.models.hland_v1.StateSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.OutputSequences[StateSequence]

State sequences of model hland_v1.

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

  • LZ() Storage in the lower zone layer [mm].