HydPy-Rconc (base model)

The HydPy-Rconc model family supplies features for calculating runoff concentration. Method Features —————

class hydpy.models.rconc.rconc_model.Model[source]

Bases: AdHocModel

HydPy-Rconc (base model).

The following interface methods are available to main models using the defined model as a submodel:
DOCNAME: DocName = ('Rconc', 'base model')
REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.rconc.rconc_model.Determine_Outflow_V1[source]

Bases: Method

Calculate the unit hydrograph output (convolution).

Requires the control parameter:

UH

Requires the flux sequence:

Inflow

Updates the log sequence:

QUH

Calculates the flux sequence:

Outflow

Examples:

Prepare a unit hydrograph with only three ordinates representing a fast catchment response compared to the selected simulation step size:

>>> from hydpy.models.rconc import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> control.uh.shape = 3
>>> control.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.inflow = 0.0
>>> model.determine_outflow_v1()
>>> fluxes.outflow
outflow(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 multiplying input values and the remaining ordinates:

>>> fluxes.inflow = 4.0
>>> model.determine_outflow_v1()
>>> fluxes.outflow
outflow(4.2)
>>> logs.quh
quh(2.0, 0.8, 0.0)

The following example demonstrates the updating of a non-empty logging sequence:

>>> fluxes.inflow = 4.0
>>> model.determine_outflow_v1()
>>> fluxes.outflow
outflow(3.2)
>>> logs.quh
quh(2.8, 0.8, 0.0)

A unit hydrograph consisting of one ordinate routes the received input directly:

>>> control.uh.shape = 1
>>> control.uh = 1.0
>>> fluxes.inflow = 0.0
>>> logs.quh.shape = 1
>>> logs.quh = 0.0
>>> model.determine_outflow_v1()
>>> fluxes.outflow
outflow(0.0)
>>> logs.quh
quh(0.0)
>>> fluxes.inflow = 4.0
>>> model.determine_outflow_v1()
>>> fluxes.outflow
outflow(4.0)
>>> logs.quh
quh(0.0)
class hydpy.models.rconc.rconc_model.Determine_Outflow_V2[source]

Bases: Method

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

Requires the control parameters:

NmbStorages NmbSteps

Requires the derived parameters:

DT KSC

Requires the flux sequence:

Inflow

Updates the state sequence:

SC

Calculates the flux sequence:

Outflow

Basic equations:

\(Outflow = KSC \cdot SC\)

\(\frac{dSC}{dt} = Inflow - Outflow\)

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

Examples:

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

>>> from hydpy.models.rconc import *
>>> simulationstep("1d")
>>> parameterstep("1d")
>>> nmbstorages(0)
>>> fluxes.inflow = 2.0
>>> model.determine_outflow_v2()
>>> fluxes.outflow
outflow(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.nmbsteps(1)
>>> derived.dt.update()
>>> nmbstorages(5)
>>> derived.ksc(inf)
>>> model.determine_outflow_v2()
>>> fluxes.outflow
outflow(2.0)

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

>>> derived.ksc(2.0)
>>> states.sc = 0.0
>>> model.determine_outflow_v2()
>>> fluxes.outflow
outflow(2.0)
>>> states.sc
sc(0.0, 0.0, 0.0, 0.0, 0.0)

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

>>> control.nmbsteps(100)
>>> derived.dt.update()
>>> states.sc = 0.0
>>> model.determine_outflow_v2()
>>> fluxes.outflow
outflow(0.026159)
>>> states.sc
sc(0.850033, 0.590099, 0.327565, 0.149042, 0.057103)
>>> round_(fluxes.outflow + sum(states.sc))
2.0
class hydpy.models.rconc.rconc_model.Set_Inflow_V1[source]

Bases: Method

Set the runoff concentration input in mm/T.

Calculates the flux sequence:

Inflow

class hydpy.models.rconc.rconc_model.Get_Outflow_V1[source]

Bases: Method

Get the previously calculated runoff concentration output in mm/T.

Requires the flux sequence:

Outflow

Example:

>>> from hydpy.models.rconc import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> retentiontime(3.0)
>>> fluxes.outflow = 2.0
>>> model.get_outflow_v1()
2.0
class hydpy.models.rconc.rconc_model.Sub_RConcModel[source]

Bases: AdHocModel

Base class for submodels that comply with the submodel interfaces defined in module rconcinterfaces.

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

Parameter Features

Control parameters

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

Bases: SubParameters

Control parameters of model rconc.

The following classes are selected:

  • UH() Unit Hydrograph ordinates [-].

  • RetentionTime() Retention time of the linear storage cascade [T].

  • NmbStorages() Number of storages of the linear storage cascade [-].

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

class hydpy.models.rconc.rconc_control.UH(subvars: SubParameters)[source]

Bases: Parameter

Unit Hydrograph ordinates [-].

Required by the method:

Determine_Outflow_V1

The ordinates of the unit hydrograph can be set directly by calling the UH instance with a list of float values as one positional argument:

>>> from hydpy.models.rconc import *
>>> simulationstep("1d")
>>> parameterstep("1d")
>>> uh([0.1,0.2,0.4,0.2,0.1])
>>> logs.quh = 0.0, 0.0, 0.0, 0.0, 0.0
>>> uh
uh(0.1, 0.2, 0.4, 0.2, 0.1)

Alternatively, implemented geometries can be specified via a positional ‘option’ parameter and parameterised with the corresponding arguments.

We generate the ordinates of a unit hydrograph in the form of an isosceles triangle with a base length of 10 days:

>>> from hydpy import print_vector
>>> from hydpy.models.rconc import *
>>> uh("triangle", tb=10.0)
>>> uh
uh("triangle", tb=10.0)
>>> print_vector(uh.values)
0.02, 0.06, 0.1, 0.14, 0.18, 0.18, 0.14, 0.1, 0.06, 0.02

The value of tb depends on the current parameter step size:

>>> from hydpy import pub
>>> with pub.options.parameterstep("2d"):
...     uh
uh("triangle", tb=5.0)

Omitting the option string will result in an error:

>>> uh(tb=10.0)
Traceback (most recent call last):
...
ValueError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: Exactly one positional argument is expected, but none or more than one is given.

Also, calling uh with more than one positional argument or with a positional argument of the wrong type is not allowed:

>>> uh([0.1,0.2,0.1], "triangle", tb=10.0)
Traceback (most recent call last):
...
ValueError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: Exactly one positional argument is expected, but none or more than one is given.

>>> uh(True)
Traceback (most recent call last):
...
TypeError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: The expected type of the positional argument is a sequence of floats but a value of `bool` is given.

The optional argument ‘tp’ specifies the position of the peak:

>>> uh("triangle", tb=10.0, tp=7.0)
>>> uh
uh("triangle", tb=10.0, tp=7.0)
>>> print_vector(uh.values)
0.014286, 0.042857, 0.071429, 0.1, 0.128571, 0.157143, 0.185714,
0.166667, 0.1, 0.033333

Any positive real numbers are allowed:

>>> uh("triangle", tb=9.5, tp=6.7)
>>> uh
uh("triangle", tb=9.5, tp=6.7)
>>> print_vector(uh.values)
0.015711, 0.047133, 0.078555, 0.109976, 0.141398, 0.17282, 0.199445,
0.150376, 0.075188, 0.009398

Parameter ‘tp’ must not be greater than ‘tb’:

>>> uh("triangle", tb=2.0, tp=3.0)
Traceback (most recent call last):
...
ValueError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: Parameter 'tp' must not be greater than 'tb'.

In addition to the HBV96-oriented triangular unit hydrograph (with the general purpose of damping the flood pulse; see Harlin (1992)), the unit hydrographs used in the GR4J model (which reflect the outflow of the two conceptional storages used in this approach; see Perrin et al. (2007)) are also available:

>>> uh("gr_uh1", x4=6.3)
>>> uh
uh("gr_uh1", x4=6.3)
>>> print_vector(uh.values)
0.010038, 0.046746, 0.099694, 0.16474, 0.239926, 0.324027, 0.11483

>>> uh("gr_uh1", x4=0.8)
>>> print_vector(uh.values)
1.0

>>> uh("gr_uh2", x4=2.8)
>>> uh
uh("gr_uh2", x4=2.8)
>>> print_vector(uh.values)
0.038113, 0.177487, 0.368959, 0.292023, 0.112789, 0.010628

>>> uh("gr_uh2", x4=0.8)
>>> print_vector(uh.values)
0.75643, 0.24357

According to Perrin et al. (2007), the exponent ‘beta’ is 2.5 by default but can be changed:

>>> uh("gr_uh1", x4=6.3, beta=1.5)
>>> print_vector(uh.values)
0.06324, 0.115629, 0.149734, 0.177314, 0.201123, 0.222388, 0.070571

>>> uh("gr_uh2", x4=2.8, beta=1.5)
>>> print_vector(uh.values)
0.106717, 0.195124, 0.250762, 0.231417, 0.166382, 0.049598

The triangle unit hydrograph must not be called with the parameters for the GR4J-like unit hydrograph:

>>> uh("triangle", x4=2.0)
Traceback (most recent call last):
...
ValueError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: Wrong arguments for option 'triangle'.

The GR4J-based options cannot be mixed with the triangle parameters:

>>> uh("gr_uh1", tb=2.0, tp=3.0)
Traceback (most recent call last):
...
ValueError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: Wrong arguments for option 'gr_uh1'.

>>> uh("gr_uh2", tb=2.0, tp=3.0)
Traceback (most recent call last):
...
ValueError: While trying to set the values of parameter `uh` of element `?`, the following error occurred: Wrong arguments for option 'gr_uh2'.

The following tests examine the correct calculation of ordinates in edge cases:

>>> uh("gr_uh2", x4=0.4)
>>> print_vector(uh.values)
1.0

>>> uh("gr_uh2", x4=0.0)
>>> print_vector(uh.values)
1.0

>>> uh("gr_uh2", x4=1.0)
>>> print_vector(uh.values)
0.5, 0.5

>>> uh("gr_uh2", x4=1.5)
>>> print_vector(uh.values)
0.181444, 0.637113, 0.181444
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
KEYWORDS: Mapping[str, Keyword] = {'beta': ('beta', <class 'float'>, False, (None, None)), 'tb': ('tb', <class 'float'>, False, (None, None)), 'tp': ('tp', <class 'float'>, False, (None, None)), 'x4': ('x4', <class 'float'>, False, (None, None))}
set_gr_uh1(x4: float, beta: float = 2.5) → None[source]

Calculate and set the ordinates of a unit hydrograph as done by GR4J for modifying base flow.

set_gr_uh2(x4: float, beta: float = 2.5) → None[source]

Calculate and set the ordinates of a unit hydrograph as done by GR4J for modifying direct runoff.

name: str = 'uh'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.rconc.rconc_control.RetentionTime(subvars: SubParameters)[source]

Bases: Parameter

Retention time of the linear storage cascade [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 = 'retentiontime'

Name of the variable in lowercase letters.

unit: str = 'T'

Unit of the variable.

class hydpy.models.rconc.rconc_control.NmbStorages(subvars: SubParameters)[source]

Bases: Parameter

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

Required by the method:

Determine_Outflow_V2

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

>>> from hydpy.models.rconc import *
>>> parameterstep()
>>> nmbstorages(5)
>>> states.sc.shape
(5,)
NDIM: int = 0
TYPE

alias of int

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

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.rconc.rconc_control.NmbSteps(subvars: SubParameters)[source]

Bases: Parameter

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

Required by the method:

Determine_Outflow_V2

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

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

alias of int

TIME: bool | None = True
name: str = 'nmbsteps'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (1, None)
INIT: int | float | bool | None = 1440.0

Derived parameters

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

Bases: SubParameters

Derived parameters of model rconc.

The following classes are selected:

  • KSC() Coefficient of the individual storages of the linear storage cascade [1/T].

  • DT() Relative length of each simulation step [-].

class hydpy.models.rconc.rconc_derived.KSC(subvars: SubParameters)[source]

Bases: Parameter

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

Required by the method:

Determine_Outflow_V2

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}{RetentionTime}\).

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

>>> retentiontime(0.0)
>>> nmbstorages(2.0)
>>> derived.ksc.update()
>>> derived.ksc
ksc(inf)
name: str = 'ksc'

Name of the variable in lowercase letters.

unit: str = '1/T'

Unit of the variable.

class hydpy.models.rconc.rconc_derived.DT(subvars: SubParameters)[source]

Bases: Parameter

Relative length of each simulation step [-].

Required by the method:

Determine_Outflow_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 DT based on \(DT = \frac{1}{NmbSteps}\).

>>> from hydpy.models.rconc import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> nmbsteps(2.0)
>>> derived.dt.update()
>>> derived.dt
dt(1.0)
>>> nmbsteps(10.0)
>>> derived.dt.update()
>>> derived.dt
dt(0.2)

Note that the value assigned to parameter NmbSteps depends on the current parameter step size (one day). Due to the current simulation step size (one hour), the applied NmbSteps value is five:

>>> nmbsteps.value
5
name: str = 'dt'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

Sequence Features

Flux sequences

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

Bases: FluxSequences

Flux sequences of model rconc.

The following classes are selected:
class hydpy.models.rconc.rconc_fluxes.Inflow(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Inflow [mm/T].

Calculated by the method:

Set_Inflow_V1

Required by the methods:

Determine_Outflow_V1 Determine_Outflow_V2

NDIM: int = 0
NUMERIC: bool = False
name: str = 'inflow'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

class hydpy.models.rconc.rconc_fluxes.Outflow(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Outflow [mm/T].

Calculated by the methods:

Determine_Outflow_V1 Determine_Outflow_V2

Required by the method:

Get_Outflow_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'outflow'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

State sequences

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

Bases: StateSequences

State sequences of model rconc.

The following classes are selected:

  • SC() Storage cascade for runoff concentration [mm].

class hydpy.models.rconc.rconc_states.SC(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: StateSequence

Storage cascade for runoff concentration [mm].

Updated by the method:

Determine_Outflow_V2

NDIM: int = 1
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'sc'

Name of the variable in lowercase letters.

unit: str = 'mm'

Unit of the variable.

Log sequences

class hydpy.models.rconc.LogSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: LogSequences

Log sequences of model rconc.

The following classes are selected:

  • QUH() All temporary outflow values of the unit hydrograph [mm/T].

class hydpy.models.rconc.rconc_logs.QUH(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: LogSequence

All temporary outflow values of the unit hydrograph [mm/T].

Updated by the method:

Determine_Outflow_V1

The last value is always set to zero to avoid biased results:

>>> from hydpy.models.rconc import *
>>> parameterstep("1h")
>>> simulationstep("1h")
>>> uh("triangle", tb=3.0)
>>> logs.quh(1.0, 2.0, 1.0)
>>> logs.quh
quh(1.0, 2.0, 0.0)

For a wrong number of input values, QUH distributes their sum equally and emits the following warning:

>>> logs.quh(1.0, 2.0, 3.0, 0.0)   
Traceback (most recent call last):
...
UserWarning: Due to the following problem, log sequence `quh` of element `?` handling model `rconc` could be initialised with a averaged value only: While trying to set the value(s) of variable `quh`, the following error occurred: While trying to convert the value(s) `(1.0, 2.0, 3.0, 0.0)` to a numpy ndarray with shape `(3...)` and type `float`, the following error occurred: could not broadcast input array from shape (4...) into shape (3...)

>>> logs.quh
quh(3.0, 3.0, 0.0)
NDIM: int = 1
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
property refweights: ndarray[Any, dtype[float64]]

A vector with identical values (so that averaging the values of QUH results in the arithmetic mean value).

>>> from hydpy.models.rconc import *
>>> parameterstep()
>>> logs.quh.shape = 3
>>> from hydpy import print_vector
>>> print_vector(logs.quh.refweights)
1.0, 1.0, 1.0
name: str = 'quh'

Name of the variable in lowercase letters.

unit: str = 'mm/T'

Unit of the variable.

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

Bases: SubParameters

Control parameters of model rconc.

The following classes are selected:

  • UH() Unit Hydrograph ordinates [-].

  • RetentionTime() Retention time of the linear storage cascade [T].

  • NmbStorages() Number of storages of the linear storage cascade [-].

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

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

Bases: SubParameters

Derived parameters of model rconc.

The following classes are selected:

  • KSC() Coefficient of the individual storages of the linear storage cascade [1/T].

  • DT() Relative length of each simulation step [-].

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

Bases: FluxSequences

Flux sequences of model rconc.

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

Bases: LogSequences

Log sequences of model rconc.

The following classes are selected:

  • QUH() All temporary outflow values of the unit hydrograph [mm/T].

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

Bases: StateSequences

State sequences of model rconc.

The following classes are selected:

  • SC() Storage cascade for runoff concentration [mm].