HydPy-Dam-V2 (dam model, version 2)

Application model dam_v002 is a simplification of dam_v001. While most functionalities are identical, dam_v002 does not calculate RequiredRemoteRelease on its own but picks this information from the simulation results of another model.

The following explanations focus on this difference. For further information on using dam_v002, please read the documentation on model dam_v001.

Integration tests

Note

When new to HydPy, consider reading section Integration Tests first.

Each of the following examples repeats one example demonstrating a specific functionality of application model dam_v001. We define identical parameter values, initial conditions, and input time series to achieve comparability. The sequence RequiredRemoteRelease requires special care. dam_v001 calculates its values based on other information, but dam_v002 expects externally calculated values for it. Hence, we use the tabulated results of the selected dam_v001 examples as the input data of the node object demand, which passes this information to dam_v002 during simulation. The limited precision of the copy-pasted RequiredRemoteRelease values causes tiny deviations between the results of both models.

The following time- and space-related setup is identical to the one of dam_v001, except we do not need to add other models to construct meaningful examples:

>>> from hydpy import pub
>>> pub.timegrids = "01.01.2000", "21.01.2000",  "1d"
>>> from hydpy import Node
>>> inflow = Node("inflow")
>>> outflow = Node("outflow")
>>> demand = Node("demand", variable="D")
>>> from hydpy import Element
>>> dam = Element("dam", inlets=inflow, outlets=outflow, receivers=demand)
>>> from hydpy.models.dam_v002 import *
>>> parameterstep("1d")
>>> dam.model = model

We prepare an identical IntegrationTest object:

>>> from hydpy import IntegrationTest
>>> test = IntegrationTest(dam)
>>> test.dateformat = "%d.%m."
>>> test.plotting_options.axis1 = fluxes.inflow, fluxes.outflow
>>> test.plotting_options.axis2 = states.watervolume

As initial conditions, dam_v002 requires logged values for the required remote release instead of logged values for the total remote discharge and outflow. Following the above reasoning, we copy-paste the first value of the “requiredremoterelease” column that is identical for all drought-related calculations performed by dam_v001:

>>> test.inits=((states.watervolume, 0.0),
...             (logs.loggedadjustedevaporation, 0.0),
...             (logs.loggedrequiredremoterelease, 0.005))

For a start, ihe inflow is constant again:

>>> inflow.sequences.sim.series = 1.0

dam_v002 implements fewer parameters than dam_v001. Besides that, all parameter settings are identical:

>>> watervolume2waterlevel(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 0.25]))
>>> waterlevel2flooddischarge(PPoly.from_data(xs=[0.0], ys=[0.0]))
>>> catchmentarea(86.4)
>>> neardischargeminimumthreshold(0.2)
>>> neardischargeminimumtolerance(0.2)
>>> waterlevelminimumthreshold(0.0)
>>> waterlevelminimumtolerance(0.0)
>>> restricttargetedrelease(True)
>>> surfacearea(1.44)
>>> correctionprecipitation(1.2)
>>> correctionevaporation(1.2)
>>> weightevaporation(0.8)
>>> thresholdevaporation(0.0)
>>> toleranceevaporation(0.001)

smooth near minimum

This example repeats the smooth near minimum example of application model dam_v001. We use the values of RequiredRemoteRelease calculated by dam_v001, as explained above:

>>> demand.sequences.sim.series = [
...     0.008588, 0.010053, 0.013858, 0.027322, 0.064075, 0.235523, 0.470414,
...     0.735001, 0.891263, 0.696325, 0.349797, 0.105231, 0.111928, 0.240436,
...     0.229369, 0.058622, 0.016958, 0.008447, 0.004155, 0.0]

Note that the first tabulated value (0.005 m³/s) serves as an initial condition, and we have to assign the following nineteen values to the time series of the demand node. The last value of the node’s time series is of no importance. We arbitrarily set it to 0.0 m³/s.

The test results confirm that both models behave identically under low flow conditions for a “near” and a “remote” need for water supply:

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

restriction enabled

This example repeats the restriction enabled example of application model dam_v001. We update the time series of the inflow and the required remote release accordingly:

>>> inflow.sequences.sim.series[10:] = 0.1
>>> demand.sequences.sim.series = [
...     0.008746, 0.010632, 0.015099, 0.03006, 0.068641, 0.242578, 0.474285,
...     0.784512, 0.95036, 0.35, 0.034564, 0.299482, 0.585979, 0.557422,
...     0.229369, 0.142578, 0.068641, 0.029844, 0.012348, 0.0]
>>> neardischargeminimumtolerance(0.0)

The recalculation confirms that the restriction on releasing water when there is little inflow works as explained for model dam_v001:

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

smooth stage minimum

This example repeats the smooth stage minimum example of application model dam_v001. We update parameters NearDischargeMinimumThreshold, WaterLevelMinimumThreshold, and WaterLevelMinimumTolerance, as well as the time series of the inflow and the required remote release, accordingly:

>>> inflow.sequences.sim.series = numpy.linspace(0.2, 0.0, 20)
>>> neardischargeminimumthreshold(0.0)
>>> waterlevelminimumthreshold(0.005)
>>> waterlevelminimumtolerance(0.01)
>>> demand.sequences.sim.series = [
...     0.01232, 0.029323, 0.064084, 0.120198, 0.247367, 0.45567, 0.608464,
...     0.537314, 0.629775, 0.744091, 0.82219, 0.841916, 0.701812, 0.533258,
...     0.351863, 0.185207, 0.107697, 0.055458, 0.025948, 0.0]

dam_v002 deals with limited water availability, as already known from dam_v001:

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

evaporation

This example repeats the evaporation example of application model dam_v001. We add an evap_ret_io submodel and update the time series of the required remote release time series accordingly:

>>> with model.add_pemodel_v1("evap_ret_io") as pemodel:
...     evapotranspirationfactor(1.0)
>>> pemodel.prepare_inputseries()
>>> pemodel.sequences.inputs.referenceevapotranspiration.series = 10 * [1.0] + 10 * [5.0]
>>> demand.sequences.sim.series = [
...     0.012321, 0.029352, 0.064305, 0.120897, 0.248435, 0.453671, 0.585089,
...     0.550583, 0.694398, 0.784979, 0.81852, 0.840207, 0.72592, 0.575373,
...     0.386003, 0.198088, 0.113577, 0.05798, 0.026921, 0.0]

dam_v002 uses the evaporation values discussed for dam_v001:

>>> test("dam_v002_evaporation")
Click to see the table
Click to see the graph
>>> del model.pemodel

flood retention

This example repeats the flood retention example of application model dam_v001. We use the same parameter and input time series configuration:

>>> neardischargeminimumthreshold(0.0)
>>> neardischargeminimumtolerance(0.0)
>>> waterlevelminimumthreshold(0.0)
>>> waterlevelminimumtolerance(0.0)
>>> waterlevel2flooddischarge(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 2.5]))
>>> neardischargeminimumthreshold(0.0)
>>> with model.add_precipmodel_v2("meteo_precip_io") as precipmodel:
...     precipitationfactor(1.0)
>>> precipmodel.prepare_inputseries()
>>> precipmodel.sequences.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]
>>> inflow.sequences.sim.series = [0.0, 0.0, 5.0, 9.0, 8.0, 5.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]
>>> demand.sequences.sim.series = 0.0
>>> test.inits.loggedrequiredremoterelease = 0.0

The recalculation results confirm the equality of both models for high-flow conditions:

>>> test("dam_v002_flood_retention")
Click to see the table
Click to see the graph
class hydpy.models.dam_v002.Model[source]

Bases: ELSIEModel, Main_PrecipModel_V2, Main_PEModel_V1

HydPy-Dam-V2 (dam model, version 2).

The following “receiver update methods” are called in the given sequence before performing a simulation step:
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.

Users can hook submodels into the defined main model if they satisfy one of the following interfaces:

  • PrecipModel_V2 Simple interface for determining precipitation in one step.

  • PETModel_V1 Simple interface for calculating all potential evapotranspiration values in one step.

DOCNAME: DocName = ('Dam-V2', 'dam model, version 2')
OBSERVER_METHODS: ClassVar[tuple[type[Method], ...]] = ()
precipmodel: modeltools.SubmodelProperty

Optional submodel that complies with the following interface: PrecipModel_V2.

pemodel: modeltools.SubmodelProperty

Optional submodel that complies with the following interface: PETModel_V1.

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
numconsts: NumConstsELS
numvars: NumVarsELS
cymodel: CyModelProtocol | None
parameters: parametertools.Parameters
sequences: sequencetools.Sequences
masks: masktools.Masks
class hydpy.models.dam_v002.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Control parameters of model dam_v002.

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

Bases: SubParameters

Derived parameters of model dam_v002.

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

Bases: FactorSequences

Factor sequences of model dam_v002.

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

Bases: FluxSequences

Flux sequences of model dam_v002.

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

Bases: InletSequences

Inlet sequences of model dam_v002.

The following classes are selected:

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

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

Bases: LogSequences

Log sequences of model dam_v002.

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

Bases: OutletSequences

Outlet sequences of model dam_v002.

The following classes are selected:

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

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

Bases: ReceiverSequences

Receiver sequences of model dam_v002.

The following classes are selected:

  • D() Water demand [m³/s].

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

Bases: SubParameters

Solver parameters of model dam_v002.

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

  • MaxEval() Maximum number of function evaluations before stopping the Explicit Labatto Sequence [-].

  • MaxCFL() Maximum Caurant-Friedrichs-Lewy number for using the Explicit Labatto Sequence [-].

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

Bases: StateSequences

State sequences of model dam_v002.

The following classes are selected: