lland_v1

Version 1 of the L-Land model is a LARSIM type model applying relatively simple approaches for calculating evapotranspiration (after Turc-Wendling) and snowmelt (degree-day method). Hence, it requires only three meteorological input variables (precipitation, temperature, and global radiation). We created lland_v1 on behalf of the German Federal Institute of Hydrology (BfG) for large scale hydrological applications in central Europe.

The following list summarises the main components of lland_v1:

  • Simple routines for adjusting the meteorological input data

  • Reference evapotranspiration after Turc-Wendling (DVWK, 2002)

  • Mixed precipitation within a definable temperature-range

  • An enhanced degree-day method for calculating snowmelt

  • A simple snow retention routine

  • Landuse and month specific potential evapotranspiration.

  • Actual soil evapotranspiration after ATV-DVWK-504 (DVWK, 2002)

  • A soil routine based on the Xinanjiang model (Zhao, 1977)

  • One base flow, two interflow and two direct flow components

  • A freely configurable capillary rise routine

  • Options to limit the capacity of the base flow storage

  • Separate linear storages for modelling runoff concentration

  • Additional evaporation from water areas within the subcatchment

  • Optional evaporation from inflowing runoff

The following figure shows the general structure of L-Land Version 1. Besides water areas and sealed surfaces, all land-use types rely on the same set of process equations:

_images/HydPy-L-Land_Version-1.png

As for all models implemented in HydPy, you can principally apply all L-Land models on arbitrary simulation step sizes. But application model lland_v1, one must be aware that the Turc-Wendling equation for calculating reference evaporation targets daily time steps only.

Integration tests

Note

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

We perform all integration tests over five days, including an extreme precipitation event. Despite the mentioned limitation of the Turc-Wendling equation, we select an hourly simulation step size, which reveals more details than a daily step size:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2000-01-05", "1h"

Next, we prepare a model instance:

>>> from hydpy.models.lland_v1 import *
>>> parameterstep("1h")

lland_v1 provides a type of optional routing approach, which adds the runoff from the upstream sub-catchments to the runoff generated by the actual sub-catchment (see example acre (routing)). This approach allows lland_v1 to subtract water area evaporation not only from the runoff generated within the actual sub-catchment but from the total runoff flowing through it (see example water (routing)). The documentation on method Calc_QAH_V1 gives further information.

The optionality of this routing approach results in different configuration possibilities of the related Element objects. The element only requires an outlet node if you do not want to use the routing approach (generally or because the relevant catchment is a headwater catchment):

>>> from hydpy import Node, Element
>>> outlet = Node("outlet")
>>> land = Element("land", outlets=outlet)
>>> land.model = model

If you want to use the routing approach, you also need to define one or more inlet nodes, providing the inflowing runoff (we rely on such an element throughout the following examples but make our catchment effectively to a headwater by setting the inflow to zero most of the time):

>>> inlet = Node("inlet")
>>> land = Element("land", inlets=inlet, outlets=outlet)
>>> land.model = model

We focus on a single hydrological response unit with one square kilometre at an altitude of 100 meters:

>>> nhru(1)
>>> ft(1.0)
>>> fhru(1.0)
>>> hnn(100.0)

We initialise a test function object that prepares and runs the tests and prints and plots their results:

>>> from hydpy import IntegrationTest
>>> test = IntegrationTest(land)

acre (summer)

In the first example, arable land is the land-use class of our choice (for all other land-use types, except the ones mentioned below, the results were the same):

>>> lnk(ACKER)

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

>>> kg(1.2)
>>> kt(0.8)
>>> ke(0.4)
>>> kf(0.6)
>>> fln(0.5)
>>> hinz(0.2)
>>> lai(4.0)
>>> treft(0.0)
>>> trefn(0.0)
>>> tgr(1.0)
>>> tsp(2.0)
>>> gtf(0.5)
>>> pwmax(1.4)
>>> grasref_r(5.0)
>>> wmax(200.0)
>>> fk(relative=0.5)
>>> pwp(relative=0.05)
>>> kapgrenz(option="0_WMax/10")
>>> kapmax(0.08)
>>> beta(0.005)
>>> fbeta(1.0)
>>> rbeta(False)
>>> dmax(1.0)
>>> dmin(0.1)
>>> bsf(0.4)
>>> volbmax(inf)
>>> gsbmax(1.0)
>>> gsbgrad1(inf)
>>> gsbgrad2(inf)
>>> a1(1.0)
>>> a2(1.0)
>>> tind(1.0)
>>> eqb(100.0)
>>> eqi1(20.0)
>>> eqi2(10.0)
>>> eqd1(5.0)
>>> eqd2(2.0)
>>> negq(False)

Initially, relative soil moisture is 10 %, but all other storages are empty (this setting is not very realistic but makes it easier to understand the results of the different integration tests):

>>> test.inits = ((states.inzp, 0.0),
...               (states.wats, 0.0),
...               (states.waes, 0.0),
...               (states.bowa, 20.0),
...               (states.qdgz1, 0.0),
...               (states.qdgz2, 0.0),
...               (states.qigz1, 0.0),
...               (states.qigz2, 0.0),
...               (states.qbgz, 0.0),
...               (states.qdga1, 0.0),
...               (states.qdga2, 0.0),
...               (states.qiga1, 0.0),
...               (states.qiga2, 0.0),
...               (states.qbga, 0.0))

The first input data set mimics an extreme summer precipitation event and sets the inflow to zero.:

>>> inputs.nied.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.teml.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.globalradiation.series = (
...     0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 11.2, 105.5, 248.3, 401.3, 449.7, 493.4, 261.5,
...     363.6, 446.2, 137.6, 103.0, 63.7, 41.4, 7.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
...     0.0, 0.0, 0.0, 6.1, 77.9, 196.7, 121.9, 156.6, 404.7, 217.9, 582.0, 263.9,
...     136.8, 146.6, 190.6, 103.5, 13.8, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
...     0.0, 4.4, 26.1, 74.2, 287.1, 299.8, 363.5, 368.4, 317.8, 534.7, 319.4, 350.6,
...     215.4, 97.8, 13.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 17.0,
...     99.7, 239.4, 391.2, 525.6, 570.2, 559.1, 668.0, 593.4, 493.0, 391.2, 186.0,
...     82.4, 17.0, 0.0, 0.0, 0.0, 0.0)
>>> inlet.sequences.sim.series = 0.0

The following results show that all relevant model components, except the snow routines, are activated at least once within the simulation period. Take your time to select different time series and see, for example, how the soil moisture content BoWa varies over time. One might realise the “linear storage” type of relationship between input Nied and outflow QAH. This pattern is due to the dominance of the direct runoff generation (QDGZ) based on the Xinanjiang model and modelling runoff concentration via linear storages (inspectable through clicking on QDGZ1 and QDGA1):

>>> test.reset_inits()
>>> conditions = sequences.conditions
>>> test("lland_v1_acker_summer",
...      axis1=(inputs.nied, fluxes.qah), axis2=states.bowa)
Click to see the table
Click to see the graph

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

>>> from hydpy import round_
>>> round_(model.check_waterbalance(conditions))
0.0

acre (routing)

For all non-water areas, lland_v1 effectively just adds the inflow to the catchment-specific outflow:

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

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

water

L-Land defines three types of water areas. The first one, WASSER, is also implemented in the original LARSIM model. To represent the effects of water areas in a straightforward manner, lland_v1 adds precipitation (NKor) to and tries to remove potential evaporation (EvPo) from the total discharge (QAH.

In the following example (again with zero inflow), this simple approach has the unfavourable side effect of discharge dropping to zero in periods with no precipitation but relevant potential evaporation during the daytime. Similar problems arise when WASSER is only one of many selected land-use types, possibly even when the water area is below 1 % of the total catchment area. Hence, it seems advisable to use the land-use types FLUSS and SEE instead, under most circumstances. Note that sequence EvI contains the actual evaporation values of WASSER (and other water-type) response units:

>>> lnk(WASSER)
>>> inlet.sequences.sim.series = 0.0
>>> test("lland_v1_wasser",
...      axis1=(fluxes.nkor, fluxes.evpo, fluxes.evi, fluxes.qah))
Click to see the table
Click to see the graph

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

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

water (routing)

With given inflow, more water is available for evaporation, and the differences between potential and actual evaporation are less pronounced (hence, the routing approach offers the opportunity to capture the evaporation effects of small lakes one does not want to represent by a separate specialised lake model like dam_v006):

>>> inlet.sequences.sim.series = 0.3
>>> test("lland_v1_wasser_routing",
...      axis1=(fluxes.nkor, fluxes.evpo, fluxes.evi, fluxes.qah))
Click to see the table
Click to see the graph

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

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

water (negative runoff)

In the integration test water, discharge is zero in all periods with evaporation exceeding precipitation but never negative. This non-negativity is due to trimming flux sequence QAH, which we can disable by setting parameter NegQ to True (negative values might be problematic for the models downstream, so set NegQ to True only for good reasons). When allowing negative QAH values, potential evaporation (EvPo) and actual water evaporation (EvI) are always identical:

>>> negq(True)
>>> inlet.sequences.sim.series = 0.0
>>> test("lland_v1_wasser_negq",
...      axis1=(fluxes.nkor, fluxes.evpo, fluxes.evi, fluxes.qah))
Click to see the table
Click to see the graph

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

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

lakes

As an alternative for water type WASSER, HydPy-L offers water type SEE for representing lakes not directly connected to the stream network but the groundwater. In some agreement with the implementation of “internal lakes” in the HBV96 model (see hland), precipitation and evaporation values are directly added and removed from the input of the linear storage for base flow (QBGZ). Hence, defining SEE areas results in reduced responsiveness of a catchment.

Note that we again disable the NegQ option. However, in contrast to integration test water, the actual evaporation (EvI) is identical with the potential one (EvPo) during and after the precipitation event. At the beginning of the simulation period, we can see the result slight correction because we are starting our test with zero groundwater storage (method Calc_QAH_V1 gives more information on the adjustment of QAH and EvI):

>>> lnk(SEE)
>>> negq(False)
>>> test("lland_v1_see",
...      axis1=(fluxes.nkor, fluxes.evpo, fluxes.evi, fluxes.qah))
Click to see the table
Click to see the graph

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

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

streams

The second alternative for water type WASSER is water type FLUSS for representing streams. Precipitation and evaporation values of FLUSS areas are directly added and removed from the (not yet separated) input of the linear storages for direct flow (QDGZ). In contrast to water type SEE (see integration test lakes), using water type FLUSS increases the responsiveness of a catchment, but to a lesser extent than using water type WASSER (see test water).

Using FLUSS instead of WASSER reduces the discussed problem during low flow conditions. However, it may persist for catchments with a very dense stream network. Compare the series EvPo and EvI to see how method Calc_QAH_V1 adjusts the actual evaporation in the most extreme case of a “stream network only” catchment, resulting even in some condensation periods with negative EvI values:

>>> lnk(FLUSS)
>>> test("lland_v1_fluss",
...      axis1=(fluxes.nkor, fluxes.evpo, fluxes.evi, fluxes.qah))
Click to see the table
Click to see the graph

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

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

sealed surfaces

We assume retention processes below the surface to be negligible for sealed surfaces. Therefore, all water reaching the sealed surface becomes direct discharge immediately:

>>> lnk(VERS)
>>> test("lland_v1_vers",
...      axis1=(inputs.nied, fluxes.qah, states.bowa))
Click to see the table
Click to see the graph

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

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

acre (limited groundwater volume)

Usually, HydPy-L represents groundwater processes by a simple linear runoff concentration storage, capturing the aspect of the relative slowness of groundwater but leaving other relevant characteristics aside. The control parameter VolBMax offers the chance to explicitly account for another groundwater characteristic: the aquifer’s limited size.

In this example, we set the maximum capacity of the groundwater storage to 25 mm, corresponding to a maximum outflow of 0.25 mm/h (see the documentation on the derived parameter QBGAMax). As soon as groundwater discharge (QBGA) reaches this threshold, it converts all recharge excess (QBGZ) into direct runoff (QDGZ, see the documentation on method Update_QDGZ_QBGZ_QBGA_V1 for further information). This additional generation of direct runoff leads to a small increase in total runoff (QAH) at the end of the simulation period:

>>> lnk(ACKER)
>>> volbmax(25.0)
>>> test("lland_v1_acker_gw_vol",
...      axis1=(states.qbgz, states.qbga, fluxes.qdgz, fluxes.qah))
Click to see the table
Click to see the graph

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

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

acre (limited groundwater rise)

Similar to restricting an aquifer’s capacity (acre (limited groundwater volume)), HydPy-L allows to limit the speed of the rise of the water table (see the documentation on method Update_QDGZ_QBGZ_QBGA_V2 for further information). After setting the related threshold parameters to 0.4 mm/h (GSBGrad1) and 0.6 mm/h (GSBGrad2), we see an increase in runoff due to the redirection of groundwater recharge to direct runoff at the end of the event:

>>> volbmax(inf)
>>> gsbgrad1(0.4)
>>> gsbgrad2(0.6)
>>> test("lland_v1_acker_gw_rise",
...      axis1=(states.qbgz, states.qbga, fluxes.qdgz, fluxes.qah))
Click to see the table
Click to see the graph

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

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

acre (capillary rise, water balance error)

Now we focus on the capillary rise (QKap), being configurable via the parameters KapMax and KapGrenz. Please first read the documentation on parameter KapGrenz to understand its keyword argument option.

In integration test acre (summer), capillary rise occurs only for a short period where the soil water content (BoWa) is less than 10 % of its capacity (WMax) due to the selected option 0_WMax/10. Additionally, there is no deep percolation (QBB) during this short period due to parameter RBeta set to False. (A note for LARSIM users: this combination of parameter settings corresponds to the option KOPPELUNG BODEN/GRUNDWASSER.)

Now we assign FK to parameter KapGrenz and True to parameter RBeta. Consequently, capillary rise and deep percolation exclude each other, and there is an abrupt transition from capillary rise to deep percolation when the soil moisture exceeds FK (which agrees with the LARSIM option KAPILLARER AUFSTIEG):

>>> gsbgrad2(inf)
>>> gsbgrad1(inf)
>>> kapgrenz(option="FK")
>>> rbeta(True)
>>> test("lland_v1_acker_qkap_negq-false",
...      axis1=(fluxes.qbb, fluxes.qkap), axis2=states.bowa)
Click to see the table
Click to see the graph

There is an error in the water balance for this particularly dry situation:

>>> round_(model.check_waterbalance(conditions))
-0.066414

Generally, the calculated capillary rise depends solemnly on the soil moisture deficit. In our example, the base flow storage is empty but must supply the water required for the capillary rise. Hence, its content and subsequently its outflow QBGA becomes negative. To prevent negative discharges at the catchment’s outlet (due to the disabled option NegQ, see the documentation on method Calc_QAH_V1 for further information), lland_v1 simply sets it to zero without trying to compensate the resulting water balance error.

acre (capillary rise, negative discharge)

If we repeat the acre (capillary rise, water balance error) experiment but set NegQ to False, the water balance error vanishes at the price of temporarily negative discharge at the catchment’s outlet:

>>> negq(True)
>>> test("lland_v1_acker_qkap_negq-true",
...      axis1=(fluxes.qbb, fluxes.qkap), axis2=states.bowa)
Click to see the table
Click to see the graph

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

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

acre (winter)

In the next example, we modify the input temperature series TemL to demonstrate the functioning of the snow routine. For simplicity, TemL increases linearly from -20 to +20 °C. The ice content of the snow layer (WATS) starts to melt when the temperature crosses the threshold temperature TGr. However, snow layer’s actual water release (WaDa) starts one day later when the liquid water content of the snow layer finally exceeds its holding capacity:

>>> inputs.teml.series = numpy.linspace(-20.0, 20.0, 96)
>>> test("lland_v1_acker_winter",
...      axis1=(inputs.nied, fluxes.wada), axis2=(states.waes, states.wats))
Click to see the table
Click to see the graph

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

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

Bases: AdHocModel

Turc-Wendling/degree-day version of HydPy-L-Land.

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

  • Pick_QZ_V1 Query the current inflow from all inlet nodes.

The following “run methods” are called in the given sequence during each simulation step:

  • Calc_QZH_V1 Calculate the inflow in mm.

  • Calc_NKor_V1 Adjust the given precipitation value according to LEG (2020).

  • Calc_TKor_V1 Adjust the given air temperature value.

  • Calc_ET0_V1 Calculate reference evapotranspiration after Turc-Wendling.

  • Calc_EvPo_V1 Calculate the potential evapotranspiration for the relevant land use and month.

  • Calc_NBes_Inzp_V1 Calculate stand precipitation and update the interception storage accordingly.

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

  • Calc_SNRatio_V1 Calculate the ratio of frozen to total precipitation according to LEG (2020).

  • Calc_SBes_V1 Calculate the frozen part of stand precipitation.

  • Calc_WATS_V1 Add the snow fall to the frozen water equivalent of the snow cover.

  • Calc_WGTF_V1 Calculate the heat flux according to the degree-day method according to LEG (2020).

  • Calc_WNied_V1 Calculate the heat flux into the snow layer due to the total amount of ingoing precipitation (LEG (2020), modified).

  • Calc_SchmPot_V1 Calculate the potential snow melt according to the day degree method.

  • Calc_Schm_WATS_V1 Calculate the actual amount of water melting within the snow layer.

  • Calc_WaDa_WAeS_V1 Add as much liquid precipitation to the snow cover as it is able to hold.

  • Calc_EvB_V1 Calculate the actual soil evapotranspiration.

  • Calc_QKap_V1 Calculate the capillary rise.

  • Calc_QBB_V1 Calculate the amount of base flow released from the soil.

  • Calc_QIB1_V1 Calculate the first inflow component released from the soil.

  • Calc_QIB2_V1 Calculate the second inflow component released from the soil.

  • Calc_QDB_V1 Calculate direct runoff released from the soil.

  • Calc_BoWa_V1 Update the soil moisture and, if necessary, correct the ingoing and outgoing fluxes.

  • Calc_QBGZ_V1 Aggregate the amount of base flow released by all “soil type” HRUs and the “net precipitation” above water areas of type SEE.

  • Calc_QIGZ1_V1 Aggregate the amount of the first interflow component released by all HRUs.

  • Calc_QIGZ2_V1 Aggregate the amount of the second interflow component released by all HRUs.

  • Calc_QDGZ_V1 Aggregate the amount of total direct flow released by all HRUs.

  • Calc_QBGA_V1 Perform the runoff concentration calculation for base flow.

  • Update_QDGZ_QBGZ_QBGA_V1 Redirect the inflow into the storage compartment for base flow into the storage compartments for direct flow upon exceedance of the groundwater aquifer’s limited volume according to LEG (2020).

  • Update_QDGZ_QBGZ_QBGA_V2 Redirect (a portion of) the inflow into the storage compartment for base flow into the storage compartments for direct flow due to the groundwater table’s too fast rise according to LEG (2020).

  • Calc_QIGA1_V1 Perform the runoff concentration calculation for the first interflow component.

  • Calc_QIGA2_V1 Perform the runoff concentration calculation for the second interflow component.

  • Calc_QDGZ1_QDGZ2_V1 Separate total direct flow into a slower and a faster component.

  • Calc_QDGA1_V1 Perform the runoff concentration calculation for “slow” direct runoff.

  • Calc_QDGA2_V1 Perform the runoff concentration calculation for “fast” direct runoff.

  • Calc_QAH_V1 Calculate the final runoff in mm.

  • Calc_QA_V1 Calculate the final runoff in m³/s.

The following “outlet update methods” are called in the given sequence at the end of each simulation step:
check_waterbalance(initial_conditions: Dict[str, Dict[str, ArrayFloat]]) → float[source]

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

Method check_waterbalance() calculates the balance error as follows:

\[\sum_{t=t0}^{t1} \Bigg( NKor_t + QZH_t - \bigg( \sum_{k=1}^{nhru} fhru^k \cdot \Big( EvI_t^k + EvB_t^k \Big) \bigg) - QAH_t \Bigg) + \sum_{k=1}^{nhru} fhru^k \cdot \bigg( \Big( Inzp_{t0}^k - Inzp_{t1}^k \Big) + \Big( WAeS_{t0}^{k} - WAeS_{t1}^{k} \Big) + \Big( BoWa_{t0}^{k} - BoWa_{t1}^{k} \Big) \bigg) - \sum_{t=t0}^{t1} \bigg( \Big( QDGZ1_t - QDGA1_t \Big) + \Big( QDGZ2_t - QDGA2_t \Big) + \Big( QIGZ1_t - QIGA1_t \Big) + \Big( QIGZ2_t - QIGA2_t \Big) + \Big( QBGZ_t - QBGA_t \Big) \bigg)\]

The returned error should usually be in scale with numerical precision so that it does not affect the simulation results in any relevant manner. The only exception we are aware of is the “generation” of additional water when the base flow storage cannot meet the water demand required for the calculated capillary rise (see acre (capillary rise, water balance error)).

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

class hydpy.models.lland_v1.Masks[source]

Bases: Masks

Masks applicable to lland_v1.

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

Bases: AideSequences

Aide sequences of model lland_v1.

The following classes are selected:

  • SNRatio() Ratio of frozen precipitation to total precipitation [-].

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

Bases: SubParameters

Control parameters of model lland_v1.

The following classes are selected:

  • FT() Teileinzugsgebietsfläche (subbasin area) [km²].

  • NHRU() Anzahl der Hydrotope (number of hydrological response units) [-].

  • Lnk() Landnutzungsklasse (land use class) [-].

  • FHRU() Flächenanteile der Hydrotope (area percentages of the respective HRUs) [-].

  • HNN() Höhe über Normal-Null (height above sea level) [m].

  • KG() Niederschlagskorrekturfaktor (adjustment factor for precipitation) [-].

  • KT() Temperaturkorrektursummand (adjustment summand for air temperature) [°C].

  • KE() Grasreferenzverdunstungskorrekturfaktor (adjustment factor for reference evapotranspiration) [-].

  • LAI() Blattflächenindex (leaf area index) [-].

  • HInz() Interzeptionskapazität bezogen auf die Blattoberfläche (interception capacity normalized to the leaf surface area) [mm].

  • TRefT() Lufttemperaturgrenzwert des Grad-Tag-Verfahrens (air temperature threshold of the degree-day method) [°C].

  • TRefN() Niederschlagstemperaturgrenzwert des zur Berechnung des Wärmeeintrags durch Regen (precipitation temperature threshold to calculate heat flux caused by liquid precipitation on snow) [°C].

  • TGr() Temperaturgrenzwert flüssiger/fester Niederschlag (threshold temperature liquid/frozen precipitation) [°C].

  • TSp() Temperaturspanne flüssiger/fester Niederschlag (temperature range with mixed precipitation) [°C].

  • GTF() Grad-Tag-Faktor (factor of the degree-day method) [mm/°C/T].

  • PWMax() Maximalverhältnis Gesamt- zu Trockenschnee (maximum ratio of the total and the frozen water equivalent stored in the snow cover) [-].

  • KF() Küstenfaktor (“coast factor” of Turc-Wendling’s evaporation equation [-].

  • FLn() Landnutzungsabhängiger Verdunstungsfaktor (factor for adjusting reference evapotranspiration to different land use classes) [-].

  • GrasRef_R() Bodenfeuchte-Verdunstung-Parameter (soil moisture-dependent evaporation factor) [-].

  • WMax() Maximaler Bodenwasserspeicher (maximum soil water storage) [mm].

  • FK() Feldkapazität / Mindestbodenfeuchte für die Interflowentstehung (field capacity / threshold value of soil moisture for interflow generation) [mm].

  • PWP() Permanenter Welkepunkt / Mindestbodenfeuchte für die Basisabflussentstehung (permanent wilting point threshold value of soil moisture for base flow generation) [mm].

  • BSf() Bodenfeuchte-Sättigungsfläche-Parameter (shape parameter for the relation between the avarage soil moisture and the relative saturated area of a subbasin) [-].

  • DMin() Drainageindex des mittleren Bodenspeichers (flux rate for releasing interflow from the middle soil compartment) [mm/T].

  • DMax() Drainageindex des oberen Bodenspeichers (additional flux rate for releasing interflow from the upper soil compartment) [mm/T].

  • Beta() Drainageindex des tiefen Bodenspeichers (storage coefficient for releasing base flow from the lower soil compartment) [1/T].

  • FBeta() Faktor zur Erhöhung der Perkolation im Grobporenbereich (factor for increasing percolation under wet conditions) [-].

  • KapMax() Maximale kapillare Aufstiegsrate (maximum capillary rise) [mm/T].

  • KapGrenz() Grenzwerte für den kapillaren Aufstieg (threshold values related to the capillary rise) [mm].

  • RBeta() Boolscher Parameter der steuert, ob the Perkolation unterhalb der Feldkapazität auf Null reduziert wird (flag to indicate if seepage is reduced to zero below field capacity) [-].

  • VolBMax() Maximaler Inhalt des Gebietsspeichers für Basisabfluss (maximum value of the storage compartment for base flow) [mm].

  • GSBMax() Faktor zur Anpassung von VolBMax (factor for adjusting VolBMax) [-].

  • GSBGrad1() Höchste Volumenzunahme des Gebietsspeichers für Basisabfluss ohne Begrenzung des Zuflusses (highest possible storage increase of the compartment for base flow without inflow reductions) [mm/T].

  • GSBGrad2() Volumenzunahme des Gebietsspeichers für Basisabfluss, oberhalb der jeglicher Zufluss ausgeschlossen ist (highest possible storage increase of the compartment for base flow) [mm/T].

  • A1() Parameter für die kontinuierliche Aufteilung der Direktabflusskomponenten (threshold value for the continuous seperation of direct runoff in a slow and a fast component) [mm/T]

  • A2() Parameter für die diskontinuierliche Aufteilung der Direktabflusskomponenten (threshold value for the discontinuous seperation of direct runoff in a slow and a fast component) [mm/T]

  • TInd() Fließzeitindex (factor related to the time of concentration) [T].

  • EQB() Kalibrierfaktor für die Basisabflusskonzentration (factor for adjusting the concentration time of baseflow). [-].

  • EQI1() Kalibrierfaktor für die “untere” Zwischenabflusskonzentration (factor for adjusting the concentration time of the first interflow component) [-].

  • EQI2() Kalibrierfaktor für die “obere” Zwischenabflusskonzentration (factor for adjusting the concentration time of the second interflow component) [-].

  • EQD1() Kalibrierfaktor für die langsamere Direktabflusskonzentration (factor for adjusting the concentration time of the slower component of direct runoff). [-].

  • EQD2() Kalibrierfaktor für die schnellere Direktabflusskonzentration (factor for adjusting the concentration time of the faster component of direct runoff). [-].

  • NegQ() Option: sind negative Abflüsse erlaubt (flag that indicated wether negative discharge values are allowed or not) [-].

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

Bases: SubParameters

Derived parameters of model lland_v1.

The following classes are selected:

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

  • AbsFHRU() Flächen der Hydrotope (areas of the respective HRUs) [km²].

  • KInz() Interzeptionskapazität bezogen auf die Bodenoberfläche (interception capacity normalized to the soil surface area) [mm].

  • KB() Konzentrationszeit des Basisabflusses (concentration time of baseflow) [T].

  • KI1() Konzentrationszeit des “unteren” Zwischenabflusses (concentration time of the first interflow component) [T].

  • KI2() Konzentrationszeit des “oberen” Zwischenabflusses” (concentration time of the second interflow component) [T].

  • KD1() Konzentrationszeit des “langsamen” Direktabflusses (concentration time of the slower component of direct runoff) [T].

  • KD2() Konzentrationszeit des “schnellen” Direktabflusses (concentration time of the faster component of direct runoff) [T].

  • QBGAMax() Maximaler Abfluss aus dem Basisabfluss-Gebietsspeicher (maximum outflow from the storage compartment for base flow) [mm/T].

  • QFactor() Factor for converting mm/T to m³/s.

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

Bases: SubParameters

Fixed parameters of model lland_v1.

The following classes are selected:

  • CPWasser() Spezifische Wärmekapazität von Wasser (specific heat capacity of water) [WT/kg/K].

  • CPEis() Spezifische Wärmekapazität von Eis bei 0 °C (specific heat capacity of ice at a temperature of 0 °C) [WT/kg/K].

  • RSchmelz() Spezifische Schmelzwärme von Wasser (specific melt heat of water) [WT/kg].

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

Bases: FluxSequences

Flux sequences of model lland_v1.

The following classes are selected:

  • QZ() Zufluss in das Teilgebiet (inflow into the subcatchment) [m³/s].

  • QZH() Abflussspende in das Teilgebiet (inflow into the subcatchment) [mm/T].

  • NKor() Korrigierter Niederschlag (corrected precipitation) [mm/T].

  • TKor() Korrigierte Lufttemperatur (corrected air temperature) [°C].

  • NBes() Gesamter Bestandsniederschlag (total stand precipitation) [mm/T].

  • SBes() Schneeanteil Bestandsniederschlag (frozen stand precipitation) [mm/T].

  • ET0() Grasreferenzverdunstung (reference evapotranspiration) [mm/T].

  • EvPo() Evapotranspiration (evapotranspiration) [mm/T].

  • EvI() Tatsächliche Interzeptionsverdunstung (actual evaporation of intercepted water) [mm/T].

  • EvB() Tatsächliche Verdunstung von Bodenwasser (actual evaporation of soil water) [mm/T].

  • WGTF() Mit dem Grad-Tag-Verfahren berechneter Wärmeestrom in die Schneedecke (heat flux into the snow layer calculated with the degree-day method) [W/m²].

  • WNied() Niederschlagsbedingter Wärmestrom in die Schneedecke (heat flux into the snow layer due to precipitation) [W/m²].

  • SchmPot() Potentielle Schneeschmelze (potential amount of water melting within the snow cover) [mm/T].

  • Schm() Tatsächliche Schneeschmelze (actual amount of water melting within the snow cover) [mm/T].

  • WaDa() Wasserdargebot (water reaching the soil routine) [mm/T].

  • QDB() Direktabfluss-Abgabe aus dem Bodenspeicher (direct runoff release from the soil storage) [mm/T].

  • QIB1() Erste Komponente der Interflow-Abgabe aus dem Bodenspeicher (first component of the interflow release from the soil storage) [mm/T].

  • QIB2() Zweite Komponente der Interflow-Abgabe aus dem Bodenspeicher (second component of the interflow release from the soil storage) [mm/T].

  • QBB() Basisabfluss-Abgabe aus dem Bodenspeicher (base flow release from the soil storage) [mm/T].

  • QKap() Kapillarer Aufstieg in den Bodenspeicher (capillary rise to soil storage) [mm/T].

  • QDGZ() Gesamtzufluss in beide Direktabfluss-Gebietsspeicher (total inflow into both storage compartments for direct runoff) [mm/T].

  • QAH() Abflussspende des Teilgebiets (runoff at the catchment outlet) [mm/T].

  • QA() Abfluss des Teilgebiets (runoff at the catchment outlet) [m³/s].

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

Bases: InletSequences

Inlet sequences of model lland_v1.

The following classes are selected:

  • Q() Abfluss (runoff) [m³/s].

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

Bases: InputSequences

Input sequences of model lland_v1.

The following classes are selected:

  • Nied() Niederschlag (precipitation) [mm/T].

  • TemL() Lufttemperatur (air temperature) [°C].

  • GlobalRadiation() Globalstrahlung (global radiation) [W/m²].

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

Bases: OutletSequences

Outlet sequences of model lland_v1.

The following classes are selected:

  • Q() Abfluss (runoff) [m³/s].

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

Bases: StateSequences

State sequences of model lland_v1.

The following classes are selected:

  • Inzp() Interzeptionsspeicherung (interception storage) [mm].

  • WATS() Wasseräquivalent Trockenschnee auf der Bodenoberfläche (frozen water equivalent of the snow cover) [mm].

  • WAeS() Wasseräquivalent Gesamtschnee auf der Bodenoberfläche (total water equivalent of the snow cover) [mm].

  • BoWa() Bodenwasserspeicherung (soil water storage) [mm].

  • QDGZ1() Zufluss in den trägeren Direktabfluss-Gebietsspeicher (inflow into the less responsive storage compartment for direct runoff) [mm/T].

  • QDGZ2() Zufluss in den dynamischeren Direktabfluss-Gebietsspeicher (inflow into the more responsive storage compartment for direct runoff) [mm/T].

  • QIGZ1() “Zufluss in den ersten Zwischenabfluss-Gebietsspeicher (inflow into the first storage compartment for interflow) [mm/T].

  • QIGZ2() Zufluss in den zweiten Zwischenabfluss-Gebietsspeicher (inflow into the second storage compartment for interflow) [mm/T].

  • QBGZ() Zufluss in den Basisabfluss-Gebietsspeicher (inflow into the storage compartment for base flow) [mm/T].

  • QDGA1() Abfluss aus dem trägeren Direktabfluss-Gebietsspeicher (outflow from the less responsive storage compartment for direct runoff) [mm/T].

  • QDGA2() Abfluss aus dem dynamischeren Direktabfluss-Gebietsspeicher (outflow from the more responsive storage compartment for direct runoff) [mm/T].

  • QIGA1() Abfluss aus dem “unteren” Zwischenabfluss-Gebietsspeicher (outflow from the storage compartment for the first interflow component) [mm/T].

  • QIGA2() Abfluss aus dem “oberen” Zwischenabfluss-Gebietsspeicher (outflow from the storage compartment for the second interflow component) [mm/T].

  • QBGA() Abfluss aus dem Basisabfluss-Gebietsspeicher (outflow from the storage compartment for base flow) [mm/T].