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:
Set_Inflow_V1
Set the runoff concentration input in mm/T.Determine_Outflow_V1
Calculate the unit hydrograph output (convolution).Determine_Outflow_V2
Calculate the linear storage cascade output (state-space approach).Get_Outflow_V1
Get the previously calculated runoff concentration output in mm/T.
- 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:
- Requires the flux sequence:
- Updates the log sequence:
- Calculates the flux sequence:
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:
- Requires the derived parameters:
- Requires the flux sequence:
- Updates the state sequence:
- Calculates the flux sequence:
- 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:
- 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:
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:
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
- 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.
- class hydpy.models.rconc.rconc_control.RetentionTime(subvars: SubParameters)[source]¶
Bases:
Parameter
Retention time of the linear storage cascade [T].
- class hydpy.models.rconc.rconc_control.NmbStorages(subvars: SubParameters)[source]¶
Bases:
Parameter
Number of storages of the linear storage cascade [-].
- Required by the method:
Defining a value for parameter
NmbStorages
automatically sets the shape of state sequenceSC
:>>> from hydpy.models.rconc import * >>> parameterstep() >>> nmbstorages(5) >>> states.sc.shape (5,)
- 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:
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)
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.
- 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:
- 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)
- class hydpy.models.rconc.rconc_derived.DT(subvars: SubParameters)[source]¶
Bases:
Parameter
Relative length of each simulation step [-].
- Required by the method:
- 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 appliedNmbSteps
value is five:>>> nmbsteps.value 5
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.
- class hydpy.models.rconc.rconc_fluxes.Inflow(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FluxSequence
Inflow [mm/T].
- Calculated by the method:
- Required by the methods:
- class hydpy.models.rconc.rconc_fluxes.Outflow(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FluxSequence
Outflow [mm/T].
- Calculated by the methods:
- Required by the method:
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:
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:
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)
- 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
- 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.
- 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.
- 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].