hland ¶

NmbZones SClass ZoneType SMax

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:

Updates the state sequences:

NmbZones SClass ZoneType SFDist SMax SRed

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:

Requires the derived parameters:

RelLandArea RelZoneAreas ZoneAreaRatios IndicesZoneZ SRedNumber SRedOrder SRedEnd

Requires the flux sequences:

SPL WCL

Updates the state sequences:

NmbZones ZoneType CFMax CFVar

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:

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:

NmbZones SClass ZoneType CFR CFMax

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:

Requires the derived parameter:

TTM

Requires the factor sequence:

TC

Updates the state sequences:

NmbZones SClass ZoneType WHC

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)
>>> 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:

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)
>>> 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_V1[source]¶

Bases: Method

Calculate soil evaporation and update the soil moisture.

Requires the control parameters:

NmbZones SClass ZoneType LP FC ERed

Requires the flux sequences:

EPC EI

Requires the state sequence:

SP

Updates the state sequence:

SM

Calculates the flux sequence:

EA

Basic equations:

\(\frac{dSM}{dt} = - EA\)

\[\begin{split}EA_{temp} = EPC \cdot \begin{cases} min \left( \frac{SM}{LP \cdot FC}, 1 \right) &|\ SP = 0 \\ 0 &|\ SP > 0 \end{cases}\end{split}\]

\(EA = EA_{temp} - max(ERed \cdot (EA_{temp} + EI - EPC), 0)\)

Examples:

We initialise eight zones of different types. For all fields and forests, the field capacity is 200 mm. Potential evaporation and interception evaporation are 2 mm and 1 mm, respectively:
>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(8)
>>> sclass(1)
>>> zonetype(ILAKE, GLACIER, SEALED, FIELD, FOREST, FIELD, FIELD, FIELD)
>>> fc(200.0)
>>> lp(0.0, 0.0, 0.0, 0.5, 0.5, 0.0, 0.8, 1.0)
>>> ered(0.0)
>>> fluxes.epc = 2.0
>>> fluxes.ei = 1.0
>>> states.sp = 0.0
Only fields and forests include soils. Hence, there is no soil evaporation for internal lakes, glaciers, and sealed areas. In the following example, the relative soil moisture is 50 % for all field and forest zones. Differences in soil evaporation are only related to the different soil evaporation parameter values (the underlying equations are the same):
>>> states.sm = 100.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, 0.0, 2.0, 2.0, 2.0, 1.25, 1.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 98.0, 98.0, 98.0, 98.75, 99.0)
The above calculations result in evaporation values of 2 mm for some zones, although interception evaporation is 1 mm and the (total) potential evaporation is only 2 mm. Use parameter ERed to reduce or completely exclude such an exceedance of the potential evaporation:
>>> states.sm = 100.0
>>> ered(0.5)
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, 0.0, 1.5, 1.5, 1.5, 1.125, 1.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 98.5, 98.5, 98.5, 98.875, 99.0)
>>> states.sm = 100.0
>>> ered(1.0)
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 1.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 99.0, 99.0, 99.0, 99.0, 99.0)
For soils with zero field capacity, soil evaporation is always zero:
>>> fc(0.0)
>>> states.sm = 0.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 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, 0.0)
Any occurrence of snow suppresses soil evaporation completely:
>>> fc(200.0)
>>> states.sp = 0.01
>>> states.sm = 100.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 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, 100.0, 100.0, 100.0)
In the last example, we did not divide the zones into snow classes. If we do so, method Calc_EA_SM_V1 suppresses soil evaporation only for individual snow classes. Hence, the reduction of soil evaporation does not depend on the total amount of snow within a zone but the fraction of its snow-covered surface:
>>> sclass(4)
>>> lp(1.0)
>>> states.sp = [[0.0, 0.0, 0.0, 0.0, 0.1, 0.1, 0.1, 0.1],
...              [0.0, 0.0, 0.0, 0.0, 0.0, 0.1, 0.1, 0.1],
...              [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1, 0.1],
...              [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1]]
>>> states.sm = 100.0
>>> model.calc_ea_sm_v1()
>>> fluxes.ea
ea(0.0, 0.0, 0.0, 1.0, 0.75, 0.5, 0.25, 0.0)
>>> states.sm
sm(0.0, 0.0, 0.0, 99.0, 99.25, 99.5, 99.75, 100.0)

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_V1[source]¶

Bases: Method

Determine the internal lake evaporation and remove it from the first-order and the second-order slow response groundwater reservoir.

Requires the control parameters:

NmbZones ZoneType TTIce

Requires the derived parameters:

RelZoneAreas RelLowerZoneArea

Requires the fixed parameter:

FSG

Requires the factor sequence:

TC

Requires the flux sequence:

EPC

Updates the state sequences:

SG2 SG3

Calculates the flux sequence:

EL

Basic equations:

\[EL = \begin{cases} EPC &|\ TC > TTIce \ 0 &|\ TC \leq TTIce \end{cases}\]

\(\frac{dSG2}{dt} = -FSG \cdot EL\)

\(\frac{dSG3}{dt} = -(1 - FSG) \cdot EL\)

Example:

Method Calc_EL_SG2_SG3_V1 applies the given basic equations for hydrological response units of type ILAKE only and sets EL to zero for all other land-use types:
>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(8)
>>> zonetype(ILAKE, ILAKE, ILAKE, ILAKE, FIELD, FOREST, GLACIER, SEALED)
>>> ttice(1.0)
>>> derived.relzoneareas(0.1, 0.1, 0.1, 0.3, 0.1, 0.1, 0.1, 0.1)
>>> derived.rellowerzonearea(0.5)
>>> factors.tc = 0.0, 1.0, 2.0, 2.0, nan, nan, nan, nan
>>> fluxes.epc = 1.0, 1.0, 0.9, 1.8, nan, nan, nan, nan
>>> states.sg2 = 1.0
>>> states.sg3 = 1.0
>>> model.calc_el_sg2_sg3_v1()
>>> fluxes.el
el(0.0, 0.0, 0.9, 1.8, 0.0, 0.0, 0.0, 0.0)
>>> states.sg2
sg2(-0.12)
>>> states.sg3
sg3(0.86)
Due to the assumption that internal lakes have a fixed size, they never dry and always evaporate water. The above example shows that this might result in negative SG2 or SG3 values.

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_V1[source]¶

Bases: Method

Calculate lake evaporation.

Requires the control parameters:: NmbZones ZoneType TTIce
Requires the derived parameters:: RelZoneAreas RelLowerZoneArea
Requires the factor sequence:: TC
Requires the flux sequence:: EPC
Updates the state sequence:: LZ
Calculates the flux sequence:: EL
Basic equations:: \(\frac{dLZ}{dt} = -EL\)

\[\begin{split}EL = \begin{cases} EPC &|\ TC > TTIce \\ 0 &|\ TC \leq TTIce \end{cases}\end{split}\]

Examples:

We initialise seven zones of the same size. The first four zones are no internal lakes, so they do not show any lake evaporation. Of the last three zones, which are internal lakes, only the last one evaporates water. The fifth and the sixth zone suppress evaporation due to the assumption that an ice layer prevents any exchange between the water body and the atmosphere:
>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbzones(7)
>>> zonetype(FIELD, FOREST, GLACIER, SEALED, ILAKE, ILAKE, ILAKE)
>>> ttice(-1.0)
>>> derived.relzoneareas(1.0/7.0)
>>> derived.rellowerzonearea(6.0/7.0)
>>> fluxes.epc = 0.6
>>> factors.tc = 0.0, 0.0, 0.0, 0.0, 0.0, -1.0, -2.0
>>> states.lz = 10.0
>>> model.calc_el_lz_v1()
>>> fluxes.el
el(0.0, 0.0, 0.0, 0.0, 0.6, 0.0, 0.0)
>>> states.lz
lz(9.9)
Note that internal lakes always contain water. Hence, applying Calc_EL_LZ_V1 might result in negative values of the lower zone storage:
>>> states.lz = 0.05
>>> model.calc_el_lz_v1()
>>> fluxes.el
el(0.0, 0.0, 0.0, 0.0, 0.6, 0.0, 0.0)
>>> states.lz
lz(-0.05)

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_InUH_V1[source]¶

Bases: Method

Calculate the unit hydrograph or linear storage cascade input.

Requires the control parameters:: NmbZones ZoneType
Requires the derived parameters:: RelZoneAreas RelUpperZoneArea RelLowerZoneArea
Requires the flux sequences:: R Q0 Q1
Calculates the flux sequence:: InUH
Basic equation:: \(InUH = RelUpperZoneArea \cdot Q0 + RelLowerZoneArea \cdot Q1\)

\[\begin{split}InUH = RelUpperZoneArea \cdot Q0 + RelLowerZoneArea \cdot Q1 + \sum_{k=1}^{NmbZones} RelZoneAreas_k \cdot \begin{cases} R &|\ ZoneType_k = SEALED \\ 0 &|\ ZoneType_k \neq SEALED \end{cases}\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 unit hydrograph 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_inuh_v1()
>>> fluxes.inuh
inuh(4.1)

class hydpy.models.hland.hland_model.Calc_InUH_V2[source]¶

Bases: Method

Calculate linear storage cascade input.

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:: InUH
Basic equation:: \[\begin{split}InUH = RelLowerZoneArea \cdot (RG2 + RG3) + \sum_{k=1}^{NmbZones} \begin{cases} RS + RI + RG1 &|\ ZoneType_k \in \{FIELD, FOREST, GLACIER \} \\ R &|\ ZoneType_k = SEALED \\ 0 &|\ ZoneType_k = ILAKE \end{cases}\end{split}\]

Example:

Besides adding all components, method Calc_InUH_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_inuh_v2()
>>> fluxes.inuh
inuh(7.53)

class hydpy.models.hland.hland_model.Calc_InUH_V3[source]¶

Bases: Method

Calculate linear storage cascade input.

Requires the control parameters:: NmbZones ZoneType
Requires the derived parameters:: RelZoneAreas RelLandArea
Requires the flux sequences:: R QAb1 QAb2
Calculates the flux sequence:: InUH
Basic equation:: \[\begin{split}InUH = \sum_{k=1}^{NmbZones} \frac{RelZoneAreas_k}{RelLandArea} \cdot \begin{cases} QAb1 + QAb2 &|\ ZoneType_k \in \{FIELD, FOREST, GLACIER \} \\ R &|\ ZoneType_k = SEALED \\ 0 &|\ ZoneType_k = ILAKE \end{cases}\end{split}\]

Example:

The unit hydrograph 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_inuh_v3()
>>> fluxes.inuh
inuh(7.0)

class hydpy.models.hland.hland_model.Calc_OutUH_QUH_V1[source]¶

Bases: Method

Calculate the unit hydrograph output (convolution).

Requires the derived parameter:: UH
Requires the flux sequence:: InUH
Updates the log sequence:: QUH
Calculates the flux sequence:: OutUH

Examples:

Prepare a unit hydrograph with only three ordinates representing a fast catchment response compared to the selected simulation step size:
>>> from hydpy.models.hland import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> derived.uh.shape = 3
>>> derived.uh = 0.3, 0.5, 0.2
>>> logs.quh.shape = 3
>>> logs.quh = 1.0, 3.0, 0.0
Without new input, the actual output is simply the first value stored in the logging sequence, and the values of the logging sequence shift to the left:
>>> fluxes.inuh = 0.0
>>> model.calc_outuh_quh_v1()
>>> fluxes.outuh
outuh(1.0)
>>> logs.quh
quh(3.0, 0.0, 0.0)
With a new input of 4 mm, the actual output consists of the first value stored in the logging sequence and the input value multiplied with the first unit hydrograph ordinate. The updated logging sequence values result from the multiplication of the input values and the remaining ordinates:
>>> fluxes.inuh = 4.0
>>> model.calc_outuh_quh_v1()
>>> fluxes.outuh
outuh(4.2)
>>> logs.quh
quh(2.0, 0.8, 0.0)
The following example demonstrates the updating of a non-empty logging sequence:
>>> fluxes.inuh = 4.0
>>> model.calc_outuh_quh_v1()
>>> fluxes.outuh
outuh(3.2)
>>> logs.quh
quh(2.8, 0.8, 0.0)
A unit hydrograph consisting of one ordinate routes the received input directly:
>>> derived.uh.shape = 1
>>> derived.uh = 1.0
>>> fluxes.inuh = 0.0
>>> logs.quh.shape = 1
>>> logs.quh = 0.0
>>> model.calc_outuh_quh_v1()
>>> fluxes.outuh
outuh(0.0)
>>> logs.quh
quh(0.0)
>>> fluxes.inuh = 4.0
>>> model.calc_outuh_quh()
>>> fluxes.outuh
outuh(4.0)
>>> logs.quh
quh(0.0)

class hydpy.models.hland.hland_model.Calc_OutUH_SC_V1[source]¶

Bases: Method

Calculate the linear storage cascade output (state-space approach).

Requires the control parameters:

NmbStorages RecStep

Requires the derived parameters:

DT KSC

Requires the flux sequence:

InUH

Updates the state sequence:

SC

Calculates the flux sequence:

OutUH

Basic equations:

\(OutUH = KSC \cdot SC\)

\(\frac{dSC}{dt} = InUH - OutUH\)

Note that the given base equations only hold for one single linear storage, while Calc_OutUH_SC_V1 supports a cascade of linear storages. Also, the equations do not reflect the possibility to increase numerical accuracy via decreasing the internal simulation step size.

Examples:

If the number of storages is zero, Calc_OutUH_SC_V1 routes the received input directly:

>>> from hydpy.models.hland import *
>>> simulationstep("1d")
>>> parameterstep("1d")
>>> nmbstorages(0)
>>> fluxes.inuh = 2.0
>>> model.calc_outuh_sc_v1()
>>> fluxes.outuh
outuh(2.0)

We solve the underlying ordinary differential equation via the explicit Euler method. Nevertheless, defining arbitrarily high storage coefficients does not pose any stability problems due to truncating too high outflow values:

>>> control.recstep(1)
>>> derived.dt.update()
>>> nmbstorages(5)
>>> derived.ksc(inf)
>>> model.calc_outuh_sc_v1()
>>> fluxes.outuh
outuh(2.0)

Increasing the number of internal calculation steps via parameter RecStep results in higher numerical accuracy without violating the water balance:

>>> derived.ksc(2.0)
>>> states.sc = 0.0
>>> model.calc_outuh_sc_v1()
>>> fluxes.outuh
outuh(2.0)
>>> states.sc
sc(0.0, 0.0, 0.0, 0.0, 0.0)

>>> control.recstep(10)
>>> derived.dt.update()
>>> states.sc = 0.0
>>> model.calc_outuh_sc_v1()
>>> fluxes.outuh
outuh(0.084262)
>>> states.sc
sc(0.714101, 0.542302, 0.353323, 0.202141, 0.103872)
>>> from hydpy import round_
>>> round_(fluxes.outuh + sum(states.sc))
2.0

>>> control.recstep(100)
>>> derived.dt.update()
>>> states.sc = 0.0
>>> model.calc_outuh_sc_v1()
>>> fluxes.outuh
outuh(0.026159)
>>> states.sc
sc(0.850033, 0.590099, 0.327565, 0.149042, 0.057103)
>>> round_(fluxes.outuh + sum(states.sc))
2.0

class hydpy.models.hland.hland_model.Calc_RT_V1[source]¶

Bases: Method

Calculate the total discharge in mm.

Requires the flux sequence:: OutUH
Calculates the flux sequence:: RT
Basic equation:: \(RT = OutUH\)

Examples:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> fluxes.outuh = 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:: OutUH Q1
Calculates the flux sequence:: RT
Basic equation:: \(RT = RelUpperZoneArea \cdot OutUH + RelLowerZoneArea \cdot Q1\)

Example:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> derived.rellandarea(0.8)
>>> derived.rellowerzonearea(0.6)
>>> fluxes.outuh = 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

Parameter Features¶

Parameter tools¶

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

Bases: ZipParameter

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.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)
>>> pcorr.values
array([2., 1., 4., 3., 2., 5.])

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
>>> from hydpy import round_
>>> 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

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

mask¶

property refweights¶: Reference to the associated instance of RelZoneAreas for calculating areal mean values.

name: str = 'parametercomplete'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterLand works similar 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¶

name: str = 'parameterland'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterInterception works similar 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¶

name: str = 'parameterinterception'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterSoil works similar 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¶

name: str = 'parametersoil'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterLand works similar 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¶

name: str = 'parameterupperzone'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterLake works similar to ParameterComplete. Some examples based on the parameter TTIce:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(ILAKE, FOREST, GLACIER, ILAKE, FIELD)
>>> ttice(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
>>> ttice
ttice(3.0)
>>> ttice(field=2.0, forest=9.0, default=9.0)
>>> ttice
ttice(9.0)
>>> zonearea.values = 1.0, nan, nan, 1.0, nan
>>> from hydpy import round_
>>> round_(ttice.average_values())
9.0

mask¶

name: str = 'parameterlake'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterLake works similar 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¶

name: str = 'parameterglacier'¶: Name of the variable in lower case letters.

unit: str = '?'¶: Unit of the variable.

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

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

ParameterNoGlacier works similar to ParameterComplete. Some examples based on the parameter ECorr:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
>>> ecorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
>>> ecorr
ecorr(field=2.0, forest=1.0, ilake=3.0)
>>> ecorr(field=2.0, default=9.0)
>>> ecorr
ecorr(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_(ecorr.average_values())
5.5

mask¶

name: str = 'parameternoglacier'¶: Name of the variable in lower case 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 also 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].
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].
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].
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].
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 [-].
MaxBaz() Base length of the triangle unit hydrograph [T].
NmbStorages() Number of storages of the linear storage cascade [-].

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 lower case 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 [-].

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 lower case 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_EA_SM_V1 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

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 lower case letters.

unit: str = '-'¶: Unit of the variable.

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

Bases: NameParameter

Type of each zone [-].

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)
>>> zonetype.values
array([1, 2, 3, 4, 4, 1])
>>> zonetype
zonetype(FIELD, FOREST, GLACIER, ILAKE, ILAKE, FIELD)

NDIM: int = 1¶

TYPE¶: alias of int

TIME: bool | None = None¶

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (1, 5)¶

CONSTANTS: Constants = {'FIELD': 1, 'FOREST': 2, 'GLACIER': 3, 'ILAKE': 4, 'SEALED': 5}¶

name: str = 'zonetype'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

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

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)[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 lower case 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 lower case letters.

unit: str = '-'¶: Unit of the variable.

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

Zone elevation [100m].

Required by the methods:: Calc_EPC_V1 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 lower case letters.

unit: str = '100m'¶: Unit of the variable.

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

Bases: Parameter

Subbasin-wide reference elevation level for precipitation [100m].

Required by the method:: Calc_PC_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'zrelp'¶: Name of the variable in lower case letters.

unit: str = '100m'¶: Unit of the variable.

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

Bases: Parameter

Subbasin-wide reference elevation level for temperature [100m].

Required by the method:: 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)¶

name: str = 'zrelt'¶: Name of the variable in lower case letters.

unit: str = '100m'¶: Unit of the variable.

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

Bases: Parameter

Subbasin-wide reference elevation level for evaporation [100m].

Required by the method:: Calc_EPC_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'zrele'¶: Name of the variable in lower case letters.

unit: str = '100m'¶: Unit of the variable.

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

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)¶

name: str = 'pcorr'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

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

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)¶

name: str = 'pcalt'¶: Name of the variable in lower case letters.

unit: str = '1/100m'¶: Unit of the variable.

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

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)¶

name: str = 'rfcf'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

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

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)¶

name: str = 'sfcf'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

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

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)¶

name: str = 'tcalt'¶: Name of the variable in lower case letters.

unit: str = '-1°C/100m'¶: Unit of the variable.

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

General evaporation correction factor [-].

Required by the method:: Calc_EPC_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 = 'ecorr'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

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

Elevation correction factor for evaporation [-1/100m].

Required by the method:: Calc_EPC_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 = 'ecalt'¶: Name of the variable in lower case letters.

unit: str = '-1/100m'¶: Unit of the variable.

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

Decrease in potential evaporation due to precipitation [T/mm].

Required by the method:: Calc_EPC_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 = 'epf'¶: Name of the variable in lower case letters.

unit: str = 'T/mm'¶: Unit of the variable.

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

Temperature factor for evaporation [1/°C].

Required by the method:: Calc_EP_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 = 'etf'¶: Name of the variable in lower case letters.

unit: str = '1/°C'¶: Unit of the variable.

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

Bases: ParameterSoil

Factor for restricting actual to potential evaporation [-].

Required by the method:: Calc_EA_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, 1.0)¶

name: str = 'ered'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

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

Bases: ParameterLake

Temperature threshold for lake evaporation [°C].

Required by the methods:: Calc_EL_LZ_V1 Calc_EL_SG2_SG3_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 = 'ttice'¶: Name of the variable in lower case letters.

unit: str = '°C'¶: 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 lower case 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_values
>>> def test(**kwargs):
...     for nmb in range(1, 6):
...         sclass(nmb)
...         sfdist(**kwargs)
...         print_values(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)
0
0, 1.0
0, 1.0, 1.0
0, 1.0, 1.0, 1.0
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)
0
0, 2.0
0, 1.0, 2.0
0, 0.666667, 1.333333, 2.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)
0
5, 1.5
5, 1.0, 1.5
5, 0.833333, 1.166667, 1.5
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)
0
0, 1.0
0, 1.0, 1.0
0, 1.0, 1.0, 1.0
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)
0
992021, 1.007979
989116, 0.999953, 1.010931
987332, 0.996711, 1.003204, 1.012754
986061, 0.994647, 0.999951, 1.005284, 1.014057

>>> test(lognormal=0.1)
0
920344, 1.079656
893412, 0.995313, 1.111276
877282, 0.963406, 1.028038, 1.131273
865966, 0.943604, 0.995118, 1.049519, 1.145792

>>> test(lognormal=1.0)
0
317311, 1.682689
228763, 0.624994, 2.146243
188069, 0.446552, 0.854969, 2.51041
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 lower case 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 lower case 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 lower case letters.

unit: str = '-'¶: Unit of the variable.

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

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)¶

name: str = 'tt'¶: Name of the variable in lower case letters.

unit: str = '°C'¶: Unit of the variable.

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

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)¶

name: str = 'ttint'¶: Name of the variable in lower case 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)¶

name: str = 'dttm'¶: Name of the variable in lower case 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)¶

name: str = 'cfmax'¶: Name of the variable in lower case 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 lower case 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)¶

name: str = 'gmelt'¶: Name of the variable in lower case 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 lower case 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)¶

name: str = 'cfr'¶: Name of the variable in lower case 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)¶

name: str = 'whc'¶: Name of the variable in lower case 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_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)¶

name: str = 'fc'¶: Name of the variable in lower case letters.

unit: str = 'mm'¶: Unit of the variable.

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

Bases: ParameterSoil

Relative limit for potential evaporation [-].

Required by the method:: Calc_EA_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, 1.0)¶

name: str = 'lp'¶: Name of the variable in lower case letters.

unit: str = '-'¶: 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)¶

name: str = 'beta'¶: Name of the variable in lower case 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 lower case 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)¶

name: str = 'cflux'¶: Name of the variable in lower case 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 lower case 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 methods:: Calc_OutUH_SC_V1 Calc_Q0_Perc_UZ_V1

>>> 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)¶

name: str = 'recstep'¶: Name of the variable in lower case 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)¶

name: str = 'alpha'¶: Name of the variable in lower case 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.

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 = 'k'¶: Name of the variable in lower case letters.

unit: str = '1/T/mm^alpha'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

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

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)[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 lower case letters.

unit: str = 'T'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'T'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'T'¶: Unit of the variable.

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

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)[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 lower case letters.

unit: str = 'T'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

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

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 lower case letters.

unit: str = 'T'¶: Unit of the variable.

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

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 lower case 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)¶

name: str = 'k4'¶: Name of the variable in lower case letters.

unit: str = '1/T'¶: Unit of the variable.

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

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)[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 lower case 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)[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 lower case 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 lower case 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

TIME: bool | None = False¶

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'maxbaz'¶: Name of the variable in lower case letters.

unit: str = 'T'¶: Unit of the variable.

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

Bases: Parameter

Number of storages of the linear storage cascade [-].

Required by the method:: Calc_OutUH_SC_V1

Defining a value for parameter NmbStorages automatically sets the shape of state sequence SC:

>>> from hydpy.models.hland import *
>>> parameterstep()
>>> nmbstorages(5)
>>> states.sc.shape
(5,)

NDIM: int = 0¶

TYPE¶: alias of int

name: str = 'nmbstorages'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

TIME: bool | None = None¶

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (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 [-].
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 [-].
UH() Unit hydrograph ordinates based on an isosceles triangle [-].
KSC() Coefficient of the individual storages of the linear storage cascade [1/T].
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 lower case letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.hland.hland_derived.RelZoneAreas(subvars: SubParameters)[source]¶

Relative area of all zones [-].

Required by the methods:: Calc_ContriArea_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_V1 Calc_GR2_GR3_V1 Calc_InUH_V1 Calc_InUH_V2 Calc_InUH_V3 Calc_InUZ_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_SPG_WCG_SP_WC_V1 Calc_TMean_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 lower case 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 lower case 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_InUH_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 lower case 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_InUH_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 lower case 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_V1 Calc_EL_SG2_SG3_V1 Calc_GR2_GR3_V1 Calc_InUH_V1 Calc_InUH_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 lower case 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 lower case 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 lower case letters.

unit: str = '-'¶: 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 lower case 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_v1 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 lower case 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 lower case 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 lower case 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 methods:: Calc_OutUH_SC_V1 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.hland.hland_derived.UH(subvars: SubParameters)[source]¶

Bases: Parameter

Unit hydrograph ordinates based on an isosceles triangle [-].

Required by the method:: Calc_OutUH_QUH_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()[source]¶

Update UH based on MaxBaz.

Note

This method also updates the shape of the log sequence QUH.

MaxBaz determines the endpoint of the triangle. A value of MaxBaz being not larger than the simulation step size is identical with applying no unit hydrograph at all:

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> maxbaz(0.0)
>>> derived.uh.update()
>>> logs.quh.shape
(1,)
>>> derived.uh
uh(1.0)

Note that, due to the given difference of the parameter and the simulation step size, the largest assigned value resulting in an “inactive” unit hydrograph is 1/2:

>>> maxbaz(0.5)
>>> derived.uh.update()
>>> logs.quh.shape
(1,)
>>> derived.uh
uh(1.0)

When the value of MaxBaz is twice the simulation step size, both unit hydrograph ordinates must be 1/2 due to the symmetry of the triangle:

>>> maxbaz(1.0)
>>> derived.uh.update()
>>> logs.quh.shape
(2,)
>>> derived.uh
uh(0.5)
>>> derived.uh.values
array([0.5, 0.5])

A MaxBaz value three times the simulation step size results in the ordinate values 2/9, 5/9, and 2/9:

>>> maxbaz(1.5)
>>> derived.uh.update()
>>> logs.quh.shape
(3,)
>>> derived.uh
uh(0.222222, 0.555556, 0.222222)

When the end of the triangle lies in the middle of the fourth interval, the resulting fractions are:

>>> maxbaz(1.75)
>>> derived.uh.update()
>>> logs.quh.shape
(4,)
>>> derived.uh
uh(0.163265, 0.469388, 0.326531, 0.040816)

name: str = 'uh'¶: Name of the variable in lower case letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.hland.hland_derived.KSC(subvars: SubParameters)[source]¶

Bases: Parameter

Coefficient of the individual storages of the linear storage cascade [1/T].

Required by the method:: Calc_OutUH_SC_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)¶

update()[source]¶

Update KSC based on \(KSC = \frac{2 \cdot NmbStorages}{MaxBaz}\).

>>> from hydpy.models.hland import *
>>> simulationstep('12h')
>>> parameterstep('1d')
>>> maxbaz(8.0)
>>> nmbstorages(2.0)
>>> derived.ksc.update()
>>> derived.ksc
ksc(0.5)

>>> maxbaz(0.0)
>>> nmbstorages(2.0)
>>> derived.ksc.update()
>>> derived.ksc
ksc(inf)

name: str = 'ksc'¶: Name of the variable in lower case letters.

unit: str = '1/T'¶: 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 lower case 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 | None = 3.141592653589793¶

name: str = 'pi'¶: Name of the variable in lower case 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_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 | None = 0.8888888888888888¶

name: str = 'fsg'¶: Name of the variable in lower case 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
>>> 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 | None = 1.4426950408889632¶

name: str = 'k1l'¶: Name of the variable in lower case 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 lower case 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: Vector[float]¶

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_values
>>> print_values(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_values([factors.swe.average_values()])
3.5

property seriesmatrix: Matrix[float]¶

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_values
>>> for values in factors.swe.seriesmatrix:
...     print_values(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_values(factors.swe.average_series())
3.5, 4.5, 5.5, 6.5

name: str = 'factor2dsequence'¶: Name of the variable in lower case 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 lower case 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: Vector[float]¶

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_values
>>> print_values(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_values([fluxes.melt.average_values()])
3.5

property seriesmatrix: Matrix[float]¶

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_values
>>> for values in fluxes.melt.seriesmatrix:
...     print_values(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_values(fluxes.melt.average_series())
3.5, 4.5, 5.5, 6.5

name: str = 'flux2dsequence'¶: Name of the variable in lower case 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 lower case 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: Vector[float]¶

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_values
>>> print_values(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_values([states.sp.average_values()])
3.5

property seriesmatrix: Matrix[float]¶

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_values
>>> for values in states.sp.seriesmatrix:
...     print_values(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_values(states.sp.average_series())
3.5, 4.5, 5.5, 6.5

name: str = 'state2dsequence'¶: Name of the variable in lower case 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].
TN() Normal temperature [°C].
EPN() Normal potential evaporation [mm].

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¶

name: str = 'p'¶: Name of the variable in lower case 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 method:: Calc_TC_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 't'¶: Name of the variable in lower case letters.

unit: str = '°C'¶: Unit of the variable.

class hydpy.models.hland.hland_inputs.TN(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: InputSequence

Normal temperature [°C].

Required by the method:: Calc_EP_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'tn'¶: Name of the variable in lower case letters.

unit: str = '°C'¶: Unit of the variable.

class hydpy.models.hland.hland_inputs.EPN(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: InputSequence

Normal potential evaporation [mm].

Required by the method:: Calc_EP_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'epn'¶: Name of the variable in lower case letters.

unit: str = 'mm'¶: 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:

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 [-].
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.TMean(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: FactorSequence

Mean subbasin temperature [°C].

Calculated by the method:: Calc_TMean_V1
Required by the method:: Calc_EP_V1

NDIM: int = 0¶

name: str = 'tmean'¶: Name of the variable in lower case letters.

unit: str = '°C'¶: Unit of the variable.

class hydpy.models.hland.hland_factors.TC(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Corrected temperature [°C].

Calculated by the method:: Calc_TC_V1
Required by the methods:: Calc_EL_LZ_V1 Calc_EL_SG2_SG3_V1 Calc_FracRain_V1 Calc_GlMelt_In_V1 Calc_Melt_SP_WC_V1 Calc_Refr_SP_WC_V1 Calc_TMean_V1

mask¶

name: str = 'tc'¶: Name of the variable in lower case letters.

unit: str = '°C'¶: Unit of the variable.

class hydpy.models.hland.hland_factors.FracRain(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.hland.hland_factors.RfC(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.hland.hland_factors.SfC(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.hland.hland_factors.CFAct(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case 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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.hland.hland_factors.GAct(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case 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 lower case 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].
EP() Potential evaporation [mm/T].
EPC() Corrected potential evaporation [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].
InUH() Input of the triangle unit hydrograph [mm/T].
OutUH() Output of the triangle unit hydrograph [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_EPC_V1 Calc_GR2_GR3_V1 Calc_LZ_V1 Calc_LZ_V2 Calc_TF_Ic_V1

mask¶

name: str = 'pc'¶: Name of the variable in lower case letters.

unit: str = 'mm/T'¶: Unit of the variable.

class hydpy.models.hland.hland_fluxes.EP(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: Flux1DSequence

Potential evaporation [mm/T].

Calculated by the method:: Calc_EP_V1
Required by the method:: Calc_EPC_V1

mask¶

name: str = 'ep'¶: Name of the variable in lower case letters.

unit: str = 'mm/T'¶: Unit of the variable.

class hydpy.models.hland.hland_fluxes.EPC(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: Flux1DSequence

Corrected potential evaporation [mm/T].

Calculated by the method:: Calc_EPC_V1
Required by the methods:: Calc_EA_SM_V1 Calc_EI_Ic_V1 Calc_EL_LZ_V1 Calc_EL_SG2_SG3_V1

mask¶

name: str = 'epc'¶: Name of the variable in lower case 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 method:: Calc_EI_Ic_V1
Required by the method:: Calc_EA_SM_V1

mask¶

name: str = 'ei'¶: Name of the variable in lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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
Required by the methods:: Calc_CF_SM_V1 Calc_InUH_V1 Calc_InUH_V2 Calc_InUH_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 lower case 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 lower case 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 method:: Calc_EA_SM_V1

mask¶

name: str = 'ea'¶: Name of the variable in lower case 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 lower case 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 lower case 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 lower case 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 lower case 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 lower case 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_InUH_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'q0'¶: Name of the variable in lower case 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 lower case 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_InUH_V3

Note that COSERO uses the abbreviation QAB1ZON instead.

mask¶

name: str = 'qab1'¶: Name of the variable in lower case 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 lower case 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_InUH_V3

Note that COSERO uses the abbreviation QAB2ZON instead.

mask¶

name: str = 'qab2'¶: Name of the variable in lower case 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_V1 Calc_EL_SG2_SG3_V1

mask¶

name: str = 'el'¶: Name of the variable in lower case 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_InUH_V1 Calc_RT_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'q1'¶: Name of the variable in lower case 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_InUH_V2

mask¶

name: str = 'rs'¶: Name of the variable in lower case 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_InUH_V2

mask¶

name: str = 'ri'¶: Name of the variable in lower case 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 lower case 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_InUH_V2

mask¶

name: str = 'rg1'¶: Name of the variable in lower case 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 lower case 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_InUH_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'rg2'¶: Name of the variable in lower case 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 lower case 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_InUH_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'rg3'¶: Name of the variable in lower case letters.

unit: str = 'mm/T'¶: Unit of the variable.

class hydpy.models.hland.hland_fluxes.InUH(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: FluxSequence

Input of the triangle unit hydrograph [mm/T].

Calculated by the methods:: Calc_InUH_V1 Calc_InUH_V2 Calc_InUH_V3
Required by the methods:: Calc_OutUH_QUH_V1 Calc_OutUH_SC_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'inuh'¶: Name of the variable in lower case letters.

unit: str = 'mm/T'¶: Unit of the variable.

class hydpy.models.hland.hland_fluxes.OutUH(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: FluxSequence

Output of the triangle unit hydrograph [mm/T].

Calculated by the methods:: Calc_OutUH_QUH_V1 Calc_OutUH_SC_V1
Required by the methods:: Calc_RT_V1 Calc_RT_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'outuh'¶: Name of the variable in lower case 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 lower case 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 lower case 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 lower case 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 lower case 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].
SC() Storage cascade for runoff concentration [mm].

class hydpy.models.hland.hland_states.Ic(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Interception storage [mm].

Updated by the methods:: Calc_EI_Ic_V1 Calc_TF_Ic_V1

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

mask¶

trim(lower=None, upper=None)[source]¶

Trim Ic following \(0 \leq IC \leq ICMAX\).

>>> from hydpy.models.hland import *
>>> parameterstep("1d")
>>> nmbzones(5)
>>> icmax(2.0)
>>> states.ic(-1.0, 0.0, 1.0, 2.0, 3.0)
>>> states.ic
ic(0.0, 0.0, 1.0, 2.0, 2.0)

name: str = 'ic'¶: Name of the variable in lower case 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_EA_SM_V1 Calc_GlMelt_In_V1 Calc_In_WC_V1 Calc_SWE_V1

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

mask¶

trim(lower=None, upper=None)[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 lower case 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)[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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.hland.hland_states.SM(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Soil moisture [mm].

Updated by the methods:: Calc_CF_SM_V1 Calc_EA_SM_V1 Calc_R_SM_V1
Required by the method:: Calc_ContriArea_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)[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 lower case 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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.hland.hland_states.SUZ(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.hland.hland_states.BW1(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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] = (False, (0.0, None))¶

mask¶

name: str = 'bw1'¶: Name of the variable in lower case letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.hland.hland_states.BW2(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

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 lower case 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_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)[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 lower case letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.hland.hland_states.SG1(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶