dam_v007

Retention basin version of HydPy-Dam.

dam_v007 is a simple “retention basin” model, similar to the “RUEC” model of LARSIM. One can understand it as an extension of dam_v006, and it partly requires equal specifications. Hence, before continuing, please first read the documentation on dam_v006.

In extension to dam_v006, dam_v007 implements the control parameter AllowedRelease (and the related parameters WaterLevelMinimumThreshold and WaterLevelMinimumTolerance). Usually, one takes the discharge not causing any harm downstream as the “allowed release”, making dam_v007 behave like a retention basin without active control. However, one can vary the allowed release seasonally (AllowedRelease inherits from class SeasonalParameter).

In contrast to dam_v006, dam_v007 does not allow to restrict the speed of the water level decrease during periods with little inflow and thus does not use the parameter AllowedWaterLevelDrop.

Integration tests

Note

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

We create the same test set as for application model dam_v006, including identical input series and an identical relationship between stage and volume:

>>> from hydpy import IntegrationTest, Element, pub
>>> pub.timegrids = "01.01.2000", "21.01.2000", "1d"
>>> parameterstep("1d")
>>> element = Element("element", inlets="input_", outlets="output")
>>> element.model = model
>>> test = IntegrationTest(element)
>>> test.dateformat = "%d.%m."
>>> test.plotting_options.axis1 = fluxes.inflow, fluxes.outflow
>>> test.plotting_options.axis2 = states.watervolume
>>> test.inits = [
...     (states.watervolume, 0.0),
...     (logs.loggedadjustedevaporation, 0.0)]
>>> test.reset_inits()
>>> conditions = sequences.conditions
>>> watervolume2waterlevel(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 1.0]))
>>> surfacearea(1.44)
>>> catchmentarea(86.4)
>>> correctionprecipitation(1.2)
>>> correctionevaporation(1.2)
>>> weightevaporation(0.8)
>>> thresholdevaporation(0.0)
>>> toleranceevaporation(0.001)
>>> inputs.precipitation.series = [
...     0.0, 50.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]
>>> element.inlets.input_.sequences.sim.series = [
...     0.0, 0.0, 6.0, 12.0, 10.0, 6.0, 3.0, 2.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]
>>> inputs.evaporation.series = 0.0

base scenario

To show that dam_v007 extends dam_v006 correctly, we also define the same quasi-linear relation between discharge and stage used throughout the integration tests of dam_v006 and additionally set the allowed release to 0 m³/s (which makes the values of the two water-related control parameters irrelevant). As expected, dam_v007 now calculates outflow values identical with the ones of the base scenario example of dam_v006 (where AllowedWaterLevelDrop is inf):

>>> waterlevel2flooddischarge(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 10.0]))
>>> allowedrelease(0.0)
>>> waterlevelminimumtolerance(0.1)
>>> waterlevelminimumthreshold(0.0)
>>> test("dam_v007_base_scenario")
Click to see the table
Click to see the graph

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

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

spillway

Now, we introduce a more realistic relationship between flood discharge and stage based on class ANN, where the spillway of the retention basin starts to become relevant when the water volume exceeds about 1.4 million m³:

>>> waterlevel2flooddischarge(ANN(weights_input=10.0, weights_output=50.0,
...                               intercepts_hidden=-20.0, intercepts_output=0.0))
>>> figure = waterlevel2flooddischarge.plot(0.0, 2.0)
>>> from hydpy.core.testtools import save_autofig
>>> save_autofig("dam_v007_waterlevel2flooddischarge.png", figure=figure)
_images/dam_v007_waterlevel2flooddischarge.png

The initially available storage volume of about 1.4 million m³ reduces the peak flow to 7.3 m³/s:

>>> test("dam_v007_spillway")
Click to see the table
Click to see the graph

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

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

allowed release

In the spillway example, dam_v007 would not handle a second event following the first one similarly well due to the retention basin not releasing the remaining 1.4 million m³ water. Setting the allowed release to 4 m³/s solves this problem and decreases the amount of water stored during the beginning of the event and thus further reduces the peak flow to 4.6 m³/s:

>>> allowedrelease(4.0)
>>> waterlevelminimumthreshold(0.1)
>>> test("dam_v007_allowed_release")
Click to see the table
Click to see the graph

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

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

The initial and final water volumes shown in the last table are slightly negative, which is due to the periods of zero inflow in combination with the value of parameter WaterLevelMinimumTolerance set to 0.1 m. One could avoid such negative values by increasing parameter WaterLevelMinimumThreshold or decreasing parameter WaterLevelMinimumTolerance. Theoretically, one could set WaterLevelMinimumTolerance to zero, but at the cost of potentially increased computation times.

evaporation

This example takes up the evaporation example of application model dam_v006. The effect of evaporation on the retention of the flood wave is as little as to be expected:

>>> inputs.evaporation.series = 10 * [1.0] + 10 * [5.0]
>>> test("dam_v007_evaporation")
Click to see the table
Click to see the graph

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

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

Bases: ELSModel

Version 7 of HydPy-Dam.

The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:
The following methods define the relevant components of a system of ODE equations (e.g. direct runoff):
The following methods define the complete equations of an ODE system (e.g. change in storage of fast water due to effective precipitation and direct runoff):
The following “outlet update methods” are called in the given sequence at the end of each simulation step:

  • Calc_WaterLevel_V1 Determine the water level based on an interpolation approach approximating the relationship between water volume and water level.

  • Pass_Outflow_V1 Update the outlet link sequence Q.

check_waterbalance(initial_conditions: Dict[str, Dict[str, ArrayFloat]]) → float[source]

Determine the water balance error of the previous simulation run in million m³.

Method check_waterbalance() calculates the balance error as follows:

\(Seconds \cdot 10^{-6} \cdot \sum_{t=t0}^{t1} \big( AdjustedPrecipitation_t - ActualEvaporation_t + Inflow_t - Outflow_t \big) + \big( WaterVolume_{t0}^k - WaterVolume_{t1}^k \big)\)

The returned error should always be in scale with numerical precision so that it does not affect the simulation results in any relevant manner.

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

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

Bases: SubParameters

Control parameters of model dam_v007.

The following classes are selected:
class hydpy.models.dam_v007.DerivedParameters(master: Parameters, cls_fastaccess: Type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model dam_v007.

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

Bases: FactorSequences

Factor sequences of model dam_v007.

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

Bases: FluxSequences

Flux sequences of model dam_v007.

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

Bases: InletSequences

Inlet sequences of model dam_v007.

The following classes are selected:

  • Q() Inflow [m³/s].

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

Bases: InputSequences

Input sequences of model dam_v007.

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

Bases: LogSequences

Log sequences of model dam_v007.

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

Bases: OutletSequences

Outlet sequences of model dam_v007.

The following classes are selected:

  • Q() Outflow [m³/s].

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

Bases: SubParameters

Solver parameters of model dam_v007.

The following classes are selected:

  • AbsErrorMax() Absolute numerical error tolerance [m³/s].

  • RelErrorMax() Relative numerical error tolerance [1/T].

  • RelDTMin() Smallest relative integration time step size allowed [-].

  • RelDTMax() Largest relative integration time step size allowed [-].

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

Bases: StateSequences

State sequences of model dam_v007.

The following classes are selected: