iuhtools

This module supports modelling based on instantaneous unit hydrographs.

This module implements some abstract descriptor classes, metaclasses and base classes. If you are just interested in applying a certain instantaneous unit hydrograph (iuh) function or if you want to implement an additional iuh, see the examples or the source code of class TranslationDiffusionEquation.

Module iuhtools implements the following members:

class hydpy.auxs.iuhtools.ParameterIUH(name: str, type_: type[~typing.Any] = <class 'float'>, doc: object | None = None)[source]

Bases: object

Descriptor base class for PrimaryParameterIUH and SecondaryParameterIUH.

The first initialisation argument is the parameters name. Optionally, an alternative type (the default type is float) and a documentation string can be passed.

name: str

Name of the handled IUH parameter.

type_: type[float]

Type of the handled IUH parameter.

class hydpy.auxs.iuhtools.PrimaryParameterIUH(name: str, type_: type[~typing.Any] = <class 'float'>, doc: object | None = None)[source]

Bases: ParameterIUH

Descriptor base class for parameters of instantaneous unit hydrograph functions to be defined by the user.

When a primary parameter value is set or deleted, the master instance is instructed to update() all secondary parameter values.

class hydpy.auxs.iuhtools.SecondaryParameterIUH(name: str, type_: type[~typing.Any] = <class 'float'>, doc: object | None = None)[source]

Bases: ParameterIUH

Descriptor base class for parameters of instantaneous unit hydrograph functions which can be determined automatically.

class hydpy.auxs.iuhtools.MetaIUH(name: str, parents: tuple[type[Any]], dict_: dict[str, Any])[source]

Bases: type

Metaclass for class IUH.

For storing PrimaryParameterIUH and SecondaryParameterIUH in separate dictionaries.

class hydpy.auxs.iuhtools.IUH(**kwargs: float)[source]

Bases: object

Base class for instantaneous unit hydrograph function objects.

See class TranslationDiffusionEquation for explanations and application examples.

For developers: The string representation does also work for parameter-free IUH subclasses:

>>> from hydpy.auxs.iuhtools import IUH
>>> class Test(IUH):
...     __call__ = None
...     calc_secondary_parameters = None
>>> Test()
Test()
dt_response: float = 0.01

Relative stepsize for plotting and analyzing iuh functions.

smallest_response: float = 1e-09

Smallest value taken into account for plotting and analyzing iuh functions.

ma: MA

Moving Average model

arma: ARMA

Autoregressive-Moving Average model.

set_primary_parameters(**kwargs: float) → None[source]

Set all primary parameters at once.

property primary_parameters_complete: bool

True/False flag that indicates whether the values of all primary parameters are defined or not.

abstractmethod calc_secondary_parameters() → None[source]

Must be implemented by the concrete IUH subclass.

update() → None[source]

Delete the coefficients of the pure MA model and also all MA and AR coefficients of the ARMA model. Also calculate or delete the values of all secondary iuh parameters, depending on the completeness of the values of the primary parameters.

property delay_response_series: tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

A tuple of two numpy arrays, which hold the time delays and the associated iuh values respectively.

plot(threshold: float | None = None, **kwargs) → None[source]

Plot the instanteneous unit hydrograph.

The optional argument allows for defining a threshold of the cumulative sum of the hydrograph, used to adjust the largest value of the x-axis. It must be a value between zero and one.

property moment1: float

The first time delay weighted statistical moment of the instantaneous unit hydrograph.

property moment2: float

The second time delay weighted statistical momens of the instantaneous unit hydrograph.

property moments: tuple[float, float]

The first two time delay weighted statistical moments of the instantaneous unit hydrograph.

class hydpy.auxs.iuhtools.TranslationDiffusionEquation(**kwargs: float)[source]

Bases: IUH

An instantaneous unit hydrograph based on the translation diffusion equation.

The equation used is a linear approximation of the Saint-Venant equations for channel routing:

\(h(t) = \frac{a}{t \cdot \sqrt{\pi \cdot t}} \cdot e^{-t \cdot (a/t-b)^2}\)

with:

\(a = \frac{x}{2 \cdot \sqrt{d}}\)

\(b = \frac{u}{2 \cdot \sqrt{d}}\)

There are three primary parameters, u, d, and x, whichs values need to be defined by the user:

>>> from hydpy import TranslationDiffusionEquation
>>> tde = TranslationDiffusionEquation(u=5.0, d=15.0, x=50.0)
>>> tde
TranslationDiffusionEquation(d=15.0, u=5.0, x=50.0)

The values of both secondary parameters are determined automatically:

>>> from hydpy import round_
>>> round_((tde.a, tde.b))
6.454972, 0.645497

The function can principally be evaluated for time delays larger zero, but not for zero time delay, which can cause trouble when applying numerical integration algorithms. This is why we clip the given time delay to minimum value of 1e-10 internally. In most cases (like the following), the returned result should be workable for integration algorithms:

>>> round_(tde([0.0, 5.0, 10.0, 15.0, 20.0]))
0.0, 0.040559, 0.115165, 0.031303, 0.00507
>>> round_([tde(value) for value in [0.0, 5.0, 10.0, 15.0, 20.0]])
0.0, 0.040559, 0.115165, 0.031303, 0.00507

The first delay weighted central moment of the translation diffusion equation corresponds to the time lag (x/u), the second one to wave diffusion:

>>> round_(tde.moments)
10.0, 3.464101

Class TranslationDiffusionEquation implements its own property moment1 (used in the example above), which is computationally more efficient and robust than the one of its base class IUH. But both normally, both should return very similar values:

>>> from hydpy.auxs.iuhtools import IUH
>>> round_(IUH.moment1.fget(tde))
10.0

You can also plot the graph corresponding to the actual parameterization:

>>> tde.plot(threshold=0.9)

All instances of the subclasses of IUH provide a pure Moving Average and an Autoregressive-Moving Average approximation to the dt standard impulse of the instantaneous unit hydrograph function. In the given example, the MA approximation involves 57 coefficients, and the ARMA approximation invoves 17 coefficients:

>>> tde.ma.order
57
>>> tde.arma.order
(3, 14)

The diffusion of the MA model deviates from the iuh function due to aggregation. For the ARMA model, there is also a slight deviation in time delay, as the ARMA model itself is only a approximation of the MA model:

>>> round_(tde.ma.moments)
10.0, 3.488074
>>> round_(tde.arma.moments)
10.000091, 3.488377

For further information on using MA and ARMA models, read the documentation on module armatools.

Changing a primary parameter results in an updating of the secondary parameters as well as the MA and the ARMA model:

>>> tde.x = 5.
>>> round_((tde.a, tde.b))
0.645497, 0.645497
>>> tde.ma.order
37
>>> tde.arma.order
(4, 5)

As long as the primary parameter values are incomplete, no secondary parameter values are available:

>>> del tde.x
>>> round_((tde.a, tde.b))
None, None

Suitable type conversions are performed when new parameter values are set:

>>> tde.x = "1."
>>> tde.x
1.0

It a new value cannot be converted, an error is raised:

>>> tde.x = "a"
Traceback (most recent call last):
...
TypeError: The value `a` of type `str` could not be converted to type `float` of the instantaneous unit hydrograph parameter `x`.

When passing parameter values as initialization arguments or when using method set_primary_parameters, tests for completeness are performed:

>>> TranslationDiffusionEquation(u=5.0, d=15.0)
Traceback (most recent call last):
...
ValueError: When passing primary parameter values as initialization arguments of the instantaneous unit hydrograph class `TranslationDiffusionEquation`, or when using method `set_primary_parameters`, one has to to define all values at once via keyword arguments.  But instead of the primary parameter names `d, u, and x` the following keywords were given: d and u.
u

Instantaneous unit hydrograph parameter: Wave velocity [L/T].

d

Instantaneous unit hydrograph parameter: Diffusion coefficient [L²/T].

x

Instantaneous unit hydrograph parameter: Routing distance [L].

a

Instantaneous unit hydrograph parameter: Distance related coefficient.

b

Instantaneous unit hydrograph parameter: Velocity related coefficient.

calc_secondary_parameters() → None[source]

Determine the values of the secondary parameters a and b.

property moment1: float

The first time delay weighted statistical moment of the translation diffusion equation.

class hydpy.auxs.iuhtools.LinearStorageCascade(**kwargs: float)[source]

Bases: IUH

An instantaneous unit hydrograph based on the linear storage cascade.

The equation involves the gamma function, allowing for a fractional number of storages:

\(h(t) = c \cdot (t/k)^{n-1} \cdot e^{-t/k}\)

with:

\(c = \frac{1}{k \cdot \gamma(n)}\)

After defining the values of the two primary parameters n and k, the function object can be applied:

>>> from hydpy import LinearStorageCascade
>>> lsc = LinearStorageCascade(n=2.5, k=2.0)
>>> from hydpy import round_
>>> round_(lsc.c)
0.376126
>>> round_(lsc([0.0, 5.0, 10.0, 15.0, 20.0]))
0.0, 0.122042, 0.028335, 0.004273, 0.00054
>>> round_([lsc(value) for value in [0.0, 5.0, 10.0, 15.0, 20.0]])
0.0, 0.122042, 0.028335, 0.004273, 0.00054

Note that we do not use the above equation directly. Instead, we apply a logarithmic transformation, which allows defining extremely high values for parameter n, resulting in spiky response functions:

>>> round_(LinearStorageCascade(n=10, k=1.0/10)(1.0))
1.2511
>>> round_(LinearStorageCascade(n=10000, k=1.0/10000)(1.0))
39.893896

>>> round_(LinearStorageCascade(n=10, k=1.0/10)([0.9, 1.0, 1.1]))
1.317556, 1.2511, 1.085255
>>> round_(LinearStorageCascade(n=10000, k=1.0/10000)([0.9, 1.0, 1.1]))
0.0, 39.893896, 0.0
n

Instantaneous unit hydrograph parameter: Number of linear storages [-].

k

Instantaneous unit hydrograph parameter: Time of concentration of each individual storage [T].

c

Instantaneous unit hydrograph parameter: Proportionality factor.

log_c

Instantaneous unit hydrograph parameter: Logarithmic value of c.

log_k

Instantaneous unit hydrograph parameter: Logarithmic value of k.

calc_secondary_parameters() → None[source]

Determine the values of the secondary parameters c, log_c, and log_k.

property moment1: float

The first time delay weighted statistical moment of the linear storage cascade.