HydPy-Dam (base model)¶

The HydPy-Dam base model provides features to implement water barriers like dams, weirs, lakes, or polders.

Method Features¶

class hydpy.models.dam.dam_model.Model[source]¶

Bases: ELSModel

HydPy-Dam (base model)

The following “receiver update methods” are called in the given sequence before performing a simulation step:

Pick_TotalRemoteDischarge_V1 Update the receiver sequence TotalRemoteDischarge.
Update_LoggedTotalRemoteDischarge_V1 Log a new entry of the discharge at a cross-section far downstream.
Pick_LoggedOuterWaterLevel_V1 Update the receiver sequence LoggedOuterWaterLevel.
Pick_LoggedRemoteWaterLevel_V1 Update the receiver sequence LoggedRemoteWaterLevel.
Pick_LoggedRequiredRemoteRelease_V1 Update the receiver sequence LoggedRequiredRemoteRelease.
Pick_LoggedRequiredRemoteRelease_V2 Update the receiver sequence LoggedRequiredRemoteRelease.
Pick_Exchange_V1 Update the inlet sequence Exchange.
Calc_RequiredRemoteRelease_V2 Get the required remote release of the last simulation step.
Pick_LoggedAllowedRemoteRelief_V1 Update the receiver sequence LoggedAllowedRemoteRelief.
Calc_AllowedRemoteRelief_V1 Get the allowed remote relief of the last simulation step.

The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:

Calc_Precipitation_V1 If available, let a submodel that complies with the PrecipModel_V2 interface determine precipitation.
Calc_AdjustedPrecipitation_V1 Adjust the given precipitation.
Calc_PotentialEvaporation_V1 If available, let a submodel that complies with the PETModel_V1 interface determine potential evaporation.
Calc_AdjustedEvaporation_V1 Adjust the given potential evaporation.
Calc_ActualEvaporation_V1 Calculate the actual evaporation.
Calc_ActualEvaporation_V2 Calculate the actual evaporation before and after the commission date.
Calc_ActualEvaporation_V3 Calculate the actual evaporation before and after the commission date.
Pick_Inflow_V1 Update the inlet sequence Inflow.
Pick_Inflow_V2 Update the inlet sequence Inflow.
Calc_NaturalRemoteDischarge_V1 Estimate the natural discharge of a cross-section far downstream based on the last few simulation steps.
Calc_RemoteDemand_V1 Estimate the discharge demand of a cross-section far downstream.
Calc_RemoteFailure_V1 Estimate the shortfall of actual discharge under the required discharge of a cross section far downstream.
Calc_RequiredRemoteRelease_V1 Guess the required release necessary to not fall below the threshold value at a cross section far downstream with a certain level of certainty.
Calc_RequiredRelease_V1 Calculate the total water release (immediately and far downstream) required for reducing drought events.
Calc_RequiredRelease_V2 Calculate the water release (immediately downstream) required for reducing drought events.
Calc_TargetedRelease_V1 Calculate the targeted water release for reducing drought events, taking into account both the required water release and the actual inflow into the dam.

The following methods define the relevant components of a system of ODE equations (e.g. direct runoff):

Pick_Inflow_V1 Update the inlet sequence Inflow.
Pick_Inflow_V2 Update the inlet sequence Inflow.
Calc_WaterLevel_V1 Determine the water level based on an interpolation approach approximating the relationship between water volume and water level.
Calc_OuterWaterLevel_V1 Get the water level directly below the dam of the last simulation step.
Calc_RemoteWaterLevel_V1 Get the water level at a remote location of the last simulation step.
Calc_WaterLevelDifference_V1 Calculate the difference between the inner and the outer water level.
Calc_EffectiveWaterLevelDifference_V1 Calculate the “effective” difference between the inner and the outer water level above a threshold level.
Calc_SurfaceArea_V1 Determine the surface area based on an interpolation approach approximating the relationship between the water level and the surface area.
Calc_AllowedDischarge_V1 Calculate the maximum discharge not leading to exceedance of the allowed water level drop.
Calc_AllowedDischarge_V2 Calculate the maximum discharge not leading to exceedance of the allowed water level drop.
Calc_ActualRelease_V1 Calculate the actual water release that can be supplied by the dam considering the targeted release and the given water level.
Calc_ActualRelease_V2 Calculate the actual water release in aggrement with the allowed release not causing harm downstream and the actual water volume.
Calc_ActualRelease_V3 Calculate an actual water release that tries to change the water storage into the direction of the actual target volume without violating the required minimum and the allowed maximum flow.
Calc_PossibleRemoteRelief_V1 Calculate the highest possible water release that can be routed to a remote location based on an interpolation approach approximating the relationship between possible release and water stage.
Calc_ActualRemoteRelief_V1 Calculate the actual amount of water released to a remote location to relieve the dam during high flow conditions.
Calc_ActualRemoteRelease_V1 Calculate the actual remote water release that can be supplied by the dam considering the required remote release and the given water level.
Update_ActualRemoteRelief_V1 Constrain the actual relief discharge to a remote location.
Update_ActualRemoteRelease_V1 Constrain the actual release (supply discharge) to a remote location.
Calc_FloodDischarge_V1 Calculate the discharge during and after a flood event based on seasonally varying interpolation approaches approximating the relationship(s) between discharge and water stage.
Calc_MaxForcedDischarge_V1 Approximate the currently highest possible forced water release through structures as pumps based on seasonally varying interpolation approaches that take the water level difference as input.
Calc_MaxFreeDischarge_V1 Approximate the currently highest possible free water release through structures as sluices based on seasonally varying interpolation approaches that take the water level difference as input.
Calc_ForcedDischarge_V1 Calculate the actual forced water release through structures as pumps to prevent a too-high inner water level if a maximum water level at a remote location is not violated.
Calc_FreeDischarge_V1 Calculate the actual water flow through a hydraulic structure like a (flap) sluice that generally depends on the water level gradient but can be suppressed to stop releasing water if a maximum water level at a remote location is violated.
Calc_Outflow_V1 Calculate the total outflow of the dam.
Calc_Outflow_V2 Calculate the total outflow of the dam before and after the commission date, taking the allowed water discharge into account.
Calc_Outflow_V3 Take the forced discharge as the only outflow.
Calc_Outflow_V4 Take the free discharge as the only outflow.
Calc_Outflow_V5 Calculate the total outflow as the sum of free and forced discharge.
Calc_Outflow_V7 Calculate the total outflow of the dam before and after the commission date

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):

Update_WaterVolume_V1 Update the actual water volume.
Update_WaterVolume_V2 Update the actual water volume.
Update_WaterVolume_V3 Update the actual water volume.
Update_WaterVolume_V4 Update the actual water volume.

The following “outlet update methods” are called in the given sequence at the end of each simulation step:

Pass_Outflow_V1 Update the outlet link sequence Q.
Update_LoggedOutflow_V1 Log a new entry of discharge at a cross section far downstream.
Pass_ActualRemoteRelease_V1 Update the outlet link sequence S.
Pass_ActualRemoteRelief_V1 Update the outlet link sequence R.

The following “sender update methods” are called in the given sequence after performing a simulation step:

Calc_MissingRemoteRelease_V1 Calculate the portion of the required remote demand that could not be met by the actual discharge release.
Pass_MissingRemoteRelease_V1 Update the outlet link sequence D.
Calc_AllowedRemoteRelief_V2 Calculate the allowed maximum relief that another location is allowed to discharge into the dam.
Pass_AllowedRemoteRelief_V1 Update the outlet link sequence R.
Calc_RequiredRemoteSupply_V1 Calculate the supply required from another location.
Pass_RequiredRemoteSupply_V1 Update the outlet link sequence S.

The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:

Fix_Min1_V1 Apply function smooth_min1() without risking negative results.
Calc_ActualEvaporation_WaterVolume_V1 Calculate the actual evaporation and update the stored water volume.
Calc_AllowedWaterLevel_V1 Calculate the water level at the end of a simulation step that would follow from applying the allowed water level drop [m].
Calc_AllowedDischarge_V3 Calculate the maximum discharge not leading to exceedance of the allowed water level drop.
Calc_SafeRelease_V1 Calculate the safe release as the minimum of the dam-specific allowed release and the values suggested by the safe release submodels.
Calc_AimedRelease_WaterVolume_V1 Calculate the ideal controlled release and update the stored water volume.
Calc_UnavoidableRelease_WaterVolume_V1 Calculate the water release that cannot be avoided due to limited storage capacity and update the stored water volume.
Calc_Outflow_V6 Calculate the outflow as the sum of the aimed and the unavoidable release.
Update_WaterVolume_V5 Update the actual water volume based on inflow and precipitation.
Return_WaterLevelError_V1 Calculate and return the difference between the allowed water level and the water level that corresponds to the given water volume.

The following “submodels” might be called by one or more of the implemented methods or are meant to be directly called by the user:

PegasusWaterVolume Pegasus iterator for finding the water volume corresponding to the allowed water level.

DOCNAME: DocName = ('Dam', 'base model')¶

OBSERVER_METHODS: ClassVar[tuple[type[Method], ...]] = ()¶

precipmodel¶: Optional submodel that complies with the following interface: PrecipModel_V2.

precipmodel_is_mainmodel¶

precipmodel_typeid¶

pemodel¶: Optional submodel that complies with the following interface: PETModel_V1.

pemodel_is_mainmodel¶

pemodel_typeid¶

safereleasemodels¶: Vector of submodels that comply with the following interface: ExchangeModel_V1.

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

class hydpy.models.dam.dam_model.Calc_Precipitation_V1[source]¶

Bases: Method

If available, let a submodel that complies with the PrecipModel_V2 interface determine precipitation.

Calculates the flux sequence:
Precipitation

Examples:

We use dam_v001 as an example:
>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
Without a submodel, Calc_Precipitation_V1 generally sets precipitation to zero:
>>> model.calc_precipitation_v1()
>>> fluxes.precipitation
precipitation(0.0)
Otherwise, it triggers the determination and queries the resulting value from the available submodel:
>>> surfacearea(2.0)
>>> with model.add_precipmodel_v2("meteo_precip_io"):
...     precipitationfactor(1.1)
...     inputs.precipitation = 3.0
>>> model.calc_precipitation_v1()
>>> fluxes.precipitation
precipitation(3.3)

class hydpy.models.dam.dam_model.Calc_AdjustedPrecipitation_V1[source]¶

Bases: Method

Adjust the given precipitation.

Requires the control parameter:
CorrectionPrecipitation

Requires the derived parameter:
InputFactor

Requires the flux sequence:
Precipitation

Calculates the flux sequence:
AdjustedPrecipitation

Basic equation:: \(AdjustedPrecipitation = InputFactor \cdot CorrectionPrecipitation \cdot Precipitation\)

Example:

>>> from hydpy.models.dam import *
>>> simulationstep("1h")
>>> parameterstep()
>>> surfacearea(36.0)
>>> correctionprecipitation(1.25)
>>> derived.seconds.update()
>>> derived.inputfactor.update()
>>> fluxes.precipitation = 2.0
>>> model.calc_adjustedprecipitation_v1()
>>> fluxes.adjustedprecipitation
adjustedprecipitation(25.0)

class hydpy.models.dam.dam_model.Calc_PotentialEvaporation_V1[source]¶

Bases: Method

If available, let a submodel that complies with the PETModel_V1 interface determine potential evaporation.

Calculates the flux sequence:
PotentialEvaporation

Examples:

We use dam_v001 as an example:
>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
Without a submodel, Calc_PotentialEvaporation_V1 generally sets potential evaporation to zero:
>>> model.calc_potentialevaporation_v1()
>>> fluxes.potentialevaporation
potentialevaporation(0.0)
Otherwise, it triggers the determination and queries the resulting value from the available submodel:
>>> surfacearea(2.0)
>>> with model.add_pemodel_v1("evap_ret_io"):
...     evapotranspirationfactor(1.1)
...     inputs.referenceevapotranspiration = 3.0
>>> model.calc_potentialevaporation_v1()
>>> fluxes.potentialevaporation
potentialevaporation(3.3)

class hydpy.models.dam.dam_model.Calc_AdjustedEvaporation_V1[source]¶

Bases: Method

Adjust the given potential evaporation.

Requires the control parameters:
CorrectionEvaporation WeightEvaporation

Requires the derived parameter:
InputFactor

Requires the flux sequence:
PotentialEvaporation

Updates the log sequence:
LoggedAdjustedEvaporation

Calculates the flux sequence:
AdjustedEvaporation

Basic equation:: \(AdjustedEvaporation = WeightEvaporation \cdot InputFactor \cdot CorrectionEvaporation \cdot PotentialEvaporation + (1 - WeightEvaporation) \cdot LoggedAdjustedEvaporation\)

Examples:

Besides transforming units (mm/T to m³/s), method Calc_AdjustedEvaporation_V1 modifies the given potential evaporation values in two ways. First, it increases or reduces its general level via parameter CorrectionEvaporation and, second, it delays and damps its variability via parameter WeightEvaporation. We begin with the first functionality by setting the correction factor to 1.25 and the weighting factor to 1.0:
>>> from hydpy.models.dam import *
>>> simulationstep("1h")
>>> parameterstep("1h")
>>> surfacearea(36.0)
>>> correctionevaporation(1.25)
>>> weightevaporation(1.0)
>>> derived.seconds.update()
>>> derived.inputfactor.update()
>>> fluxes.potentialevaporation = 2.0
>>> logs.loggedadjustedevaporation = 20.0
>>> model.calc_adjustedevaporation_v1()
>>> fluxes.adjustedevaporation
adjustedevaporation(25.0)
Note that method Calc_AdjustedEvaporation_V1 also updates the log sequence LoggedAdjustedEvaporation with the same value as flux sequence AdjustedEvaporation:
>>> logs.loggedadjustedevaporation
loggedadjustedevaporation(25.0)
Setting the weighting factor to a value smaller one activates the damping-delay mechanism. A value of 0.6 implies a weighting of 60 % of the “new” evaporation value (here: 2.0 mm/h or 25 m³/s) and of 40 % of the “old” evaporation value (here: 1.6 mm/h or 20 m³/s):
>>> weightevaporation(0.6)
>>> logs.loggedadjustedevaporation = 20.0
>>> model.calc_adjustedevaporation_v1()
>>> fluxes.adjustedevaporation
adjustedevaporation(23.0)
>>> logs.loggedadjustedevaporation
loggedadjustedevaporation(23.0)

class hydpy.models.dam.dam_model.Calc_ActualEvaporation_V1[source]¶

Bases: Method

Calculate the actual evaporation.

Requires the control parameter:
ThresholdEvaporation

Requires the derived parameter:
SmoothParEvaporation

Requires the factor sequence:
WaterLevel

Requires the flux sequence:
AdjustedEvaporation

Calculates the flux sequence:
ActualEvaporation

Basic equation:: \(ActualEvaporation = AdjustedEvaporation \cdot smooth_{logistic1}(ThresholdEvaporation - WaterLevel, SmoothParEvaporation)\)
Used auxiliary method:: smooth_logistic1()

Examples:

First, we prepare a UnitTest object to illustrate the relationship between the water level and actual evaporation for different settings:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.adjustedevaporation = 2.0
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualevaporation_v1,
...                 last_example=10,
...                 parseqs=(factors.waterlevel,
...                          fluxes.actualevaporation))
>>> test.nexts.waterlevel = [value / 1000.0 for value in range(-1, 9)]

The most intuitive way to configure method Calc_ActualEvaporation_V1 is to set WaterLevelMinimumThreshold and WaterLevelMinimumTolerance to zero. Then, there is a sharp transition between zero and potential evaporation around a water level of 0 m:

>>> thresholdevaporation(0.0)
>>> toleranceevaporation(0.0)
>>> derived.smoothparevaporation.update()

>>> test()
| ex. | waterlevel | actualevaporation |
----------------------------------------
|   1 |     -0.001 |               0.0 |
|   2 |        0.0 |               1.0 |
|   3 |      0.001 |               2.0 |
|   4 |      0.002 |               2.0 |
|   5 |      0.003 |               2.0 |
|   6 |      0.004 |               2.0 |
|   7 |      0.005 |               2.0 |
|   8 |      0.006 |               2.0 |
|   9 |      0.007 |               2.0 |
|  10 |      0.008 |               2.0 |

For numerical efficiency (and more natural transitions), it is preferable to set WaterLevelMinimumTolerance to a value larger than zero. Here, we set it to 1 mm and adjust WaterLevelMinimumThreshold so that the actual evaporation values are (at least for the shown precision) zero below a water level of 0 mm:

>>> thresholdevaporation(0.004)
>>> toleranceevaporation(0.001)
>>> derived.smoothparevaporation.update()
>>> test()
| ex. | waterlevel | actualevaporation |
----------------------------------------
|   1 |     -0.001 |               0.0 |
|   2 |        0.0 |               0.0 |
|   3 |      0.001 |          0.000002 |
|   4 |      0.002 |          0.000204 |
|   5 |      0.003 |              0.02 |
|   6 |      0.004 |               1.0 |
|   7 |      0.005 |              1.98 |
|   8 |      0.006 |          1.999796 |
|   9 |      0.007 |          1.999998 |
|  10 |      0.008 |               2.0 |

class hydpy.models.dam.dam_model.Calc_ActualEvaporation_V2[source]¶

Bases: Method

Calculate the actual evaporation before and after the commission date.

Requires the control parameters:
Commission ThresholdEvaporation

Requires the derived parameter:
SmoothParEvaporation

Requires the factor sequence:
WaterLevel

Requires the flux sequences:
AdjustedEvaporation AdjustedPrecipitation Inflow Exchange

Calculates the flux sequence:
ActualEvaporation

Basic equation:: \[\begin{split}ActualEvaporation = \begin{cases} min(A, \, I + E + P) &|& i_{sim} < i_{commission} \\ A \cdot f(T- W, \, S) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ A = AdjustedEvaporation \\ I = Inflow \\ E = Exchange \\ P = AdjustedPrecipitation \\ f = smooth_{logistic1} \\ T = ThresholdEvaporation \\ W = WaterLevel \\ S = SmoothParEvaporation\end{split}\]
Used auxiliary method:: smooth_logistic1()

Examples:

After the commission date (when the dam is active), method Calc_ActualEvaporation_V2 works exactly like method Calc_ActualEvaporation_V1. We demonstrate this by picking a single data point from the second example on method Calc_ActualEvaporation_V1:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2001-01-01", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission("2000-01-01")
>>> thresholdevaporation(0.004)
>>> toleranceevaporation(0.001)
>>> derived.smoothparevaporation.update()
>>> factors.waterlevel = 0.005
>>> fluxes.adjustedevaporation = 2.0
>>> model.calc_actualevaporation_v2()
>>> fluxes.actualevaporation
actualevaporation(1.98)

Before the commission date, only the current net input, consisting of inflow, (positive) exchange flow, and precipitation, can evaporate:

>>> commission("2000-01-02")
>>> fluxes.inflow = 0.2
>>> fluxes.exchange = 0.3
>>> fluxes.adjustedprecipitation = 0.5
>>> model.calc_actualevaporation_v2()
>>> fluxes.actualevaporation
actualevaporation(1.0)

>>> fluxes.inflow = 2.2
>>> model.calc_actualevaporation_v2()
>>> fluxes.actualevaporation
actualevaporation(2.0)

class hydpy.models.dam.dam_model.Calc_ActualEvaporation_V3[source]¶

Bases: Method

Calculate the actual evaporation before and after the commission date.

Requires the control parameters:
Commission ThresholdEvaporation

Requires the derived parameter:
SmoothParEvaporation

Requires the factor sequence:
WaterLevel

Requires the flux sequences:
AdjustedEvaporation AdjustedPrecipitation Inflow

Calculates the flux sequence:
ActualEvaporation

Basic equation:: \[\begin{split}ActualEvaporation = \begin{cases} min(A, \, I + P) &|& i_{sim} < i_{commission} \\ A \cdot f(T- W, \, S) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ A = AdjustedEvaporation \\ I = Inflow \\ P = AdjustedPrecipitation \\ f = smooth_{logistic1} \\ T = ThresholdEvaporation \\ W = WaterLevel \\ S = SmoothParEvaporation\end{split}\]
Used auxiliary method:: smooth_logistic1()

Examples:

Method Calc_ActualEvaporation_V3 works exactly like method Calc_ActualEvaporation_V2 except that it does not consider exchange flows with other (dam-like) models. Hence, we repeat its examples with only a slight modification:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2001-01-01", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission("2000-01-01")
>>> thresholdevaporation(0.004)
>>> toleranceevaporation(0.001)
>>> derived.smoothparevaporation.update()
>>> factors.waterlevel = 0.005
>>> fluxes.adjustedevaporation = 2.0
>>> model.calc_actualevaporation_v3()
>>> fluxes.actualevaporation
actualevaporation(1.98)

>>> commission("2000-01-02")
>>> fluxes.inflow = 0.2
>>> fluxes.adjustedprecipitation = 0.8
>>> model.calc_actualevaporation_v3()
>>> fluxes.actualevaporation
actualevaporation(1.0)

>>> fluxes.inflow = 2.2
>>> model.calc_actualevaporation_v3()
>>> fluxes.actualevaporation
actualevaporation(2.0)

class hydpy.models.dam.dam_model.Calc_ActualEvaporation_WaterVolume_V1[source]¶

Bases: Method

Calculate the actual evaporation and update the stored water volume.

Requires the control parameter:
Commission

Requires the derived parameter:
Seconds

Requires the flux sequences:
Inflow AdjustedPrecipitation AdjustedEvaporation

Updates the state sequence:
WaterVolume

Calculates the flux sequence:
ActualEvaporation

Basic equation:: \[\begin{split}ActualEvaporation = \begin{cases} min(A, \, I + P) &|& i_{sim} < i_{commission} \\ min(E, \, V \cdot 1e6 / s) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ A = AdjustedEvaporation \\ I = Inflow \\ P = AdjustedPrecipitation \\ V = WaterVolume \\ s = Seconds\end{split}\]

Examples:

After the commission date, water evaporation losses are taken from the current water volume:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission(0)
>>> derived.seconds(1e6)
>>> states.watervolume = 3.0
>>> fluxes.adjustedevaporation = 2.0

>>> model.calc_actualevaporation_watervolume_v1()
>>> fluxes.actualevaporation
actualevaporation(2.0)
>>> states.watervolume
watervolume(1.0)

>>> model.calc_actualevaporation_watervolume_v1()
>>> fluxes.actualevaporation
actualevaporation(1.0)
>>> states.watervolume
watervolume(0.0)

Before the commission date, only the current net input, consisting of inflow and precipitation, can evaporate:

>>> commission(1)
>>> fluxes.inflow = 1.0
>>> fluxes.adjustedprecipitation = 2.0
>>> model.calc_actualevaporation_watervolume_v1()
>>> fluxes.actualevaporation
actualevaporation(2.0)
>>> states.watervolume
watervolume(0.0)

>>> fluxes.adjustedprecipitation = 0.0
>>> model.calc_actualevaporation_watervolume_v1()
>>> fluxes.actualevaporation
actualevaporation(1.0)
>>> states.watervolume
watervolume(0.0)

class hydpy.models.dam.dam_model.Pick_Inflow_V1[source]¶

Bases: Method

Update the inlet sequence Inflow.

Requires the inlet sequence:
Q

Calculates the flux sequence:
Inflow

Basic equation:: \(Inflow = \sum Q\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> inlets.q.shape = 2
>>> inlets.q = 2.0, 4.0
>>> model.pick_inflow_v1()
>>> fluxes.inflow
inflow(6.0)

class hydpy.models.dam.dam_model.Pick_Inflow_V2[source]¶

Bases: Method

Update the inlet sequence Inflow.

Requires the inlet sequences:
Q S R

Calculates the flux sequence:
Inflow

Basic equation:: \(Inflow = S + R + \sum Q\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> inlets.s = 0.5
>>> inlets.r = 1.0
>>> inlets.q.shape = 2
>>> inlets.q = 2.0, 4.0
>>> model.pick_inflow_v2()
>>> fluxes.inflow
inflow(7.5)

class hydpy.models.dam.dam_model.Pick_TotalRemoteDischarge_V1[source]¶

Bases: Method

Update the receiver sequence TotalRemoteDischarge.

Requires the receiver sequence:
Q

Calculates the flux sequence:
TotalRemoteDischarge

Basic equation:: \(TotalRemoteDischarge = Q\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> receivers.q = 2.0
>>> model.pick_totalremotedischarge_v1()
>>> fluxes.totalremotedischarge
totalremotedischarge(2.0)

class hydpy.models.dam.dam_model.Pick_LoggedOuterWaterLevel_V1[source]¶

Bases: Method

Update the receiver sequence LoggedOuterWaterLevel.

Requires the receiver sequence:
OWL

Calculates the log sequence:
LoggedOuterWaterLevel

Basic equation:: \(LoggedOuterWaterLevel = OWL\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> receivers.owl = 2.0
>>> model.pick_loggedouterwaterlevel_v1()
>>> logs.loggedouterwaterlevel
loggedouterwaterlevel(2.0)

class hydpy.models.dam.dam_model.Pick_LoggedRemoteWaterLevel_V1[source]¶

Bases: Method

Update the receiver sequence LoggedRemoteWaterLevel.

Requires the receiver sequence:
RWL

Calculates the log sequence:
LoggedRemoteWaterLevel

Basic equation:: \(LoggedRemoteWaterLevel = RWL\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> receivers.rwl = 2.0
>>> model.pick_loggedremotewaterlevel_v1()
>>> logs.loggedremotewaterlevel
loggedremotewaterlevel(2.0)

class hydpy.models.dam.dam_model.Pick_LoggedRequiredRemoteRelease_V1[source]¶

Bases: Method

Update the receiver sequence LoggedRequiredRemoteRelease.

Requires the receiver sequence:
D

Calculates the log sequence:
LoggedRequiredRemoteRelease

Basic equation:: \(LoggedRequiredRemoteRelease = D\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> receivers.d = 2.0
>>> model.pick_loggedrequiredremoterelease_v1()
>>> logs.loggedrequiredremoterelease
loggedrequiredremoterelease(2.0)

class hydpy.models.dam.dam_model.Pick_LoggedRequiredRemoteRelease_V2[source]¶

Bases: Method

Update the receiver sequence LoggedRequiredRemoteRelease.

Requires the receiver sequence:
S

Calculates the log sequence:
LoggedRequiredRemoteRelease

Basic equation:: \(LoggedRequiredRemoteRelease = S\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> receivers.s = 2.0
>>> model.pick_loggedrequiredremoterelease_v2()
>>> logs.loggedrequiredremoterelease
loggedrequiredremoterelease(2.0)

class hydpy.models.dam.dam_model.Pick_Exchange_V1[source]¶

Bases: Method

Update the inlet sequence Exchange.

Requires the inlet sequence:
E

Calculates the flux sequence:
Exchange

Basic equation:: \(Exchange = \sum E_{inlets}\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> inlets.e.shape = 2
>>> inlets.e = 2.0, 4.0
>>> model.pick_exchange_v1()
>>> fluxes.exchange
exchange(6.0)

class hydpy.models.dam.dam_model.Pick_LoggedAllowedRemoteRelief_V1[source]¶

Bases: Method

Update the receiver sequence LoggedAllowedRemoteRelief.

Requires the receiver sequence:
R

Calculates the log sequence:
LoggedAllowedRemoteRelief

Basic equation:: \(LoggedAllowedRemoteRelief = R\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> receivers.r = 2.0
>>> model.pick_loggedallowedremoterelief_v1()
>>> logs.loggedallowedremoterelief
loggedallowedremoterelief(2.0)

class hydpy.models.dam.dam_model.Update_LoggedTotalRemoteDischarge_V1[source]¶

Bases: Method

Log a new entry of the discharge at a cross-section far downstream.

Requires the control parameter:
NmbLogEntries

Requires the flux sequence:
TotalRemoteDischarge

Updates the log sequence:
LoggedTotalRemoteDischarge

Example:

The following example shows that method Update_LoggedTotalRemoteDischarge_V1 moves the three memorised values successively to the right and stores the respective new value on the bare left position:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> nmblogentries(3)
>>> logs.loggedtotalremotedischarge = 0.0
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.update_loggedtotalremotedischarge_v1,
...                 last_example=4,
...                 parseqs=(fluxes.totalremotedischarge,
...                          logs.loggedtotalremotedischarge))
>>> test.nexts.totalremotedischarge = [1.0, 3.0, 2.0, 4.0]
>>> del test.inits.loggedtotalremotedischarge
>>> test()
| ex. | totalremotedischarge |           loggedtotalremotedischarge |
---------------------------------------------------------------------
|   1 |                  1.0 | 1.0  0.0                         0.0 |
|   2 |                  3.0 | 3.0  1.0                         0.0 |
|   3 |                  2.0 | 2.0  3.0                         1.0 |
|   4 |                  4.0 | 4.0  2.0                         3.0 |

class hydpy.models.dam.dam_model.Calc_WaterLevel_V1[source]¶

Bases: Method

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

Requires the control parameter:
WaterVolume2WaterLevel

Requires the state sequence:
WaterVolume

Calculates the factor sequence:
WaterLevel

Example:

We prepare a straightforward relationship based on a single neuron in the hidden layer:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> watervolume2waterlevel(
...     ANN(nmb_inputs=1, nmb_neurons=(1,), nmb_outputs=1,
...         weights_input=0.5, weights_output=1.0,
...         intercepts_hidden=0.0, intercepts_output=-0.5))

At least in the water volume range used in the following examples, the shape of the relationship looks acceptable:

>>> from hydpy import UnitTest
>>> test = UnitTest(
...     model, model.calc_waterlevel_v1,
...     last_example=10,
...     parseqs=(states.watervolume, factors.waterlevel))
>>> test.nexts.watervolume = range(10)
>>> test()
| ex. | watervolume | waterlevel |
----------------------------------
|   1 |         0.0 |        0.0 |
|   2 |         1.0 |   0.122459 |
|   3 |         2.0 |   0.231059 |
|   4 |         3.0 |   0.317574 |
|   5 |         4.0 |   0.380797 |
|   6 |         5.0 |   0.424142 |
|   7 |         6.0 |   0.452574 |
|   8 |         7.0 |   0.470688 |
|   9 |         8.0 |   0.482014 |
|  10 |         9.0 |   0.489013 |

Larger neural networks or piecewise polynomials allow for more realistic approximations of measured relationships between water volume and water level.

class hydpy.models.dam.dam_model.Calc_OuterWaterLevel_V1[source]¶

Bases: Method

Get the water level directly below the dam of the last simulation step.

Requires the log sequence:
LoggedOuterWaterLevel

Calculates the factor sequence:
OuterWaterLevel

Basic equation:: \(OuterWaterLevel = LoggedOuterWaterLevel\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> logs.loggedouterwaterlevel = 2.0
>>> model.calc_outerwaterlevel_v1()
>>> factors.outerwaterlevel
outerwaterlevel(2.0)

class hydpy.models.dam.dam_model.Calc_RemoteWaterLevel_V1[source]¶

Bases: Method

Get the water level at a remote location of the last simulation step.

Requires the log sequence:
LoggedRemoteWaterLevel

Calculates the factor sequence:
RemoteWaterLevel

Basic equation:: \(RemoteWaterLevel = LoggedRemoteWaterLevel\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> logs.loggedremotewaterlevel = 2.0
>>> model.calc_remotewaterlevel_v1()
>>> factors.remotewaterlevel
remotewaterlevel(2.0)

class hydpy.models.dam.dam_model.Calc_WaterLevelDifference_V1[source]¶

Bases: Method

Calculate the difference between the inner and the outer water level.

Requires the factor sequences:
WaterLevel OuterWaterLevel

Calculates the factor sequence:
WaterLevelDifference

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> factors.waterlevel = 5.0
>>> factors.outerwaterlevel = 3.0
>>> model.calc_waterleveldifference_v1()
>>> factors.waterleveldifference
waterleveldifference(2.0)

class hydpy.models.dam.dam_model.Calc_EffectiveWaterLevelDifference_V1[source]¶

Bases: Method

Calculate the “effective” difference between the inner and the outer water level above a threshold level.

Requires the control parameter:
CrestLevel

Requires the derived parameter:
CrestLevelSmoothPar

Requires the factor sequences:
WaterLevel OuterWaterLevel

Calculates the factor sequence:
EffectiveWaterLevelDifference

Basic equation:: \[\begin{split}EffectiveWaterLevelDifference = h_1 - h_2 \\ \\ h_1 = f_{smooth \, max1}(WaterLevel, \, CrestLevelThreshold, \, CrestLevelSmoothPar) \\ \\ h_2 = f_{smooth \, max2}(OuterWaterLevel, \, CrestLevelThreshold, \, CrestLevelSmoothPar)\end{split}\]
Used auxiliary method:: smooth_max1()

Examples:

We prepare a UnitTest object to illustrate how the effective water level difference depends on the inner and the outer water level:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_effectivewaterleveldifference_v1,
...                 last_example=21,
...                 parseqs=(factors.waterlevel,
...                          factors.outerwaterlevel,
...                          factors.effectivewaterleveldifference))
>>> test.nexts.waterlevel = numpy.linspace(3.15, 3.35, 21)
>>> test.nexts.outerwaterlevel = numpy.linspace(3.05, 3.25, 21)

When setting CrestLevelTolerance to zero, EffectiveWaterLevelDifference is identical to the water level difference above the weir’s crest:

>>> crestlevel(3.2)
>>> crestleveltolerance(0.0)
>>> derived.crestlevelsmoothpar.update()
>>> test()
| ex. | waterlevel | outerwaterlevel | effectivewaterleveldifference |
----------------------------------------------------------------------
|   1 |       3.15 |            3.05 |                           0.0 |
|   2 |       3.16 |            3.06 |                           0.0 |
|   3 |       3.17 |            3.07 |                           0.0 |
|   4 |       3.18 |            3.08 |                           0.0 |
|   5 |       3.19 |            3.09 |                           0.0 |
|   6 |        3.2 |             3.1 |                           0.0 |
|   7 |       3.21 |            3.11 |                          0.01 |
|   8 |       3.22 |            3.12 |                          0.02 |
|   9 |       3.23 |            3.13 |                          0.03 |
|  10 |       3.24 |            3.14 |                          0.04 |
|  11 |       3.25 |            3.15 |                          0.05 |
|  12 |       3.26 |            3.16 |                          0.06 |
|  13 |       3.27 |            3.17 |                          0.07 |
|  14 |       3.28 |            3.18 |                          0.08 |
|  15 |       3.29 |            3.19 |                          0.09 |
|  16 |        3.3 |             3.2 |                           0.1 |
|  17 |       3.31 |            3.21 |                           0.1 |
|  18 |       3.32 |            3.22 |                           0.1 |
|  19 |       3.33 |            3.23 |                           0.1 |
|  20 |       3.34 |            3.24 |                           0.1 |
|  21 |       3.35 |            3.25 |                           0.1 |

For more natural transitions (and also for computational efficiency), it is preferable to define a tolerance value larger than zero. We set CrestLevelTolerance to 10 mm:

>>> crestleveltolerance(0.01)
>>> derived.crestlevelsmoothpar.update()
>>> test()
| ex. | waterlevel | outerwaterlevel | effectivewaterleveldifference |
----------------------------------------------------------------------
|   1 |       3.15 |            3.05 |                      0.001779 |
|   2 |       3.16 |            3.06 |                      0.002805 |
|   3 |       3.17 |            3.07 |                      0.004364 |
|   4 |       3.18 |            3.08 |                      0.006658 |
|   5 |       3.19 |            3.09 |                      0.009896 |
|   6 |        3.2 |             3.1 |                      0.014236 |
|   7 |       3.21 |            3.11 |                      0.019728 |
|   8 |       3.22 |            3.12 |                      0.026285 |
|   9 |       3.23 |            3.13 |                      0.033701 |
|  10 |       3.24 |            3.14 |                      0.041703 |
|  11 |       3.25 |            3.15 |                          0.05 |
|  12 |       3.26 |            3.16 |                      0.058297 |
|  13 |       3.27 |            3.17 |                      0.066299 |
|  14 |       3.28 |            3.18 |                      0.073715 |
|  15 |       3.29 |            3.19 |                      0.080272 |
|  16 |        3.3 |             3.2 |                      0.085764 |
|  17 |       3.31 |            3.21 |                      0.090104 |
|  18 |       3.32 |            3.22 |                      0.093342 |
|  19 |       3.33 |            3.23 |                      0.095636 |
|  20 |       3.34 |            3.24 |                      0.097195 |
|  21 |       3.35 |            3.25 |                      0.098221 |

Swapping the inner and outer water levels changes only the calculated difference’s signs:

>>> test.nexts.waterlevel, test.nexts.outerwaterlevel = (
...     test.nexts.outerwaterlevel, test.nexts.waterlevel)
>>> test()
| ex. | waterlevel | outerwaterlevel | effectivewaterleveldifference |
----------------------------------------------------------------------
|   1 |       3.05 |            3.15 |                     -0.001779 |
|   2 |       3.06 |            3.16 |                     -0.002805 |
|   3 |       3.07 |            3.17 |                     -0.004364 |
|   4 |       3.08 |            3.18 |                     -0.006658 |
|   5 |       3.09 |            3.19 |                     -0.009896 |
|   6 |        3.1 |             3.2 |                     -0.014236 |
|   7 |       3.11 |            3.21 |                     -0.019728 |
|   8 |       3.12 |            3.22 |                     -0.026285 |
|   9 |       3.13 |            3.23 |                     -0.033701 |
|  10 |       3.14 |            3.24 |                     -0.041703 |
|  11 |       3.15 |            3.25 |                         -0.05 |
|  12 |       3.16 |            3.26 |                     -0.058297 |
|  13 |       3.17 |            3.27 |                     -0.066299 |
|  14 |       3.18 |            3.28 |                     -0.073715 |
|  15 |       3.19 |            3.29 |                     -0.080272 |
|  16 |        3.2 |             3.3 |                     -0.085764 |
|  17 |       3.21 |            3.31 |                     -0.090104 |
|  18 |       3.22 |            3.32 |                     -0.093342 |
|  19 |       3.23 |            3.33 |                     -0.095636 |
|  20 |       3.24 |            3.34 |                     -0.097195 |
|  21 |       3.25 |            3.35 |                     -0.098221 |

class hydpy.models.dam.dam_model.Calc_SurfaceArea_V1[source]¶

Bases: Method

Determine the surface area based on an interpolation approach approximating the relationship between the water level and the surface area.

Requires the control parameter:
WaterVolume2WaterLevel

Requires the state sequence:
WaterVolume

Calculates the aide sequence:
SurfaceArea

Basic equation:: \(SurfaceArea = \frac{dWaterVolume}{WaterLevel}\)

Example:

Method Calc_SurfaceArea_V1 relies on the identical neural network as method Calc_WaterLevel_V1. Therefore, we reuse the same network configuration:

>>> from hydpy.models.dam import *
>>> parameterstep()

>>> watervolume2waterlevel(
...     ANN(nmb_inputs=1, nmb_neurons=(1,), nmb_outputs=1,
...         weights_input=0.5, weights_output=1.0,
...         intercepts_hidden=0.0, intercepts_output=-0.5))

>>> from hydpy import UnitTest
>>> test = UnitTest(
...     model, model.calc_surfacearea_v1,
...     last_example=10,
...     parseqs=(states.watervolume, aides.surfacearea))
>>> test.nexts.watervolume = range(10)
>>> test()
| ex. | watervolume | surfacearea |
-----------------------------------
|   1 |         0.0 |         8.0 |
|   2 |         1.0 |    8.510504 |
|   3 |         2.0 |   10.172323 |
|   4 |         3.0 |   13.409638 |
|   5 |         4.0 |   19.048783 |
|   6 |         5.0 |   28.529158 |
|   7 |         6.0 |   44.270648 |
|   8 |         7.0 |   70.291299 |
|   9 |         8.0 |  113.232931 |
|  10 |         9.0 |  184.056481 |

We apply the class NumericalDifferentiator to validate the calculated surface area corresponding to a water volume of 9 million m³:

>>> from hydpy import NumericalDifferentiator, round_
>>> numdiff = NumericalDifferentiator(
...     xsequence=states.watervolume,
...     ysequences=[factors.waterlevel],
...     methods=[model.calc_waterlevel_v1])
>>> numdiff()
d_waterlevel/d_watervolume: 0.005433

Calculating the inverse of the above result (\(dV/dh\) instead of \(dh/dV\)) gives the surface area tabulated above:

>>> round_(1.0/0.005433115, decimals=5)
184.05648

class hydpy.models.dam.dam_model.Calc_AllowedRemoteRelief_V2[source]¶

Bases: Method

Calculate the allowed maximum relief that another location is allowed to discharge into the dam.

Requires the control parameters:
HighestRemoteRelief WaterLevelReliefThreshold

Requires the derived parameters:
TOY WaterLevelReliefSmoothPar

Requires the factor sequence:
WaterLevel

Calculates the flux sequence:
AllowedRemoteRelief

Used auxiliary method:: smooth_logistic1()
Basic equation:: \(ActualRemoteRelief = HighestRemoteRelief \cdot smooth_{logistic1}(WaterLevelReliefThreshold-WaterLevel, WaterLevelReliefSmoothPar)\)

Examples:

All control parameters involved in the calculation of AllowedRemoteRelief are subclasses of SeasonalParameter. This design allows simulating seasonal dam control schemes. To show how this works, we first define a short simulation period of two days:
>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
We prepare the dam model and define two different control schemes for the hydrological summer (April to October) and winter month (November to May):
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> highestremoterelief(_11_1_12=1.0, _03_31_12=1.0,
...                     _04_1_12=2.0, _10_31_12=2.0)
>>> waterlevelreliefthreshold(_11_1_12=3.0, _03_31_12=2.0,
...                           _04_1_12=4.0, _10_31_12=4.0)
>>> waterlevelrelieftolerance(_11_1_12=0.0, _03_31_12=0.0,
...                           _04_1_12=1.0, _10_31_12=1.0)
>>> derived.waterlevelreliefsmoothpar.update()
>>> derived.toy.update()
The following test function calculates AllowedRemoteRelief water levels ranging from 0.0 and 8.0 meters:
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.calc_allowedremoterelief_v2,
...                 last_example=9,
...                 parseqs=(factors.waterlevel,
...                          fluxes.allowedremoterelief))
>>> test.nexts.waterlevel = range(9)
On March 30 (which is the last day of the winter month and the first day of the simulation period), the value of WaterLevelReliefSmoothPar is zero. Hence, AllowedRemoteRelief drops abruptly from 1 m³/s (defined by HighestRemoteRelief) to 0 m³/s as soon as WaterLevel reaches 3 m (defined by of WaterLevelReliefThreshold):
>>> model.idx_sim = pub.timegrids.init["2001.03.30"]
>>> test(first_example=2, last_example=6)
| ex. | waterlevel | allowedremoterelief |
------------------------------------------
|   3 |        1.0 |                 1.0 |
|   4 |        2.0 |                 1.0 |
|   5 |        3.0 |                 0.0 |
|   6 |        4.0 |                 0.0 |
April 1 (the first day of the summer and the last day of the simulation period) comes with increased parameter values. The value of parameter WaterLevelReliefSmoothPar is 1 m. Hence, loosely speaking, AllowedRemoteRelief approaches the “discontinuous extremes (2 m³/s – defined by HighestRemoteRelief – and 0 m³/s) to 99 % within a span of 2 m³/s around the original threshold value of 4 m³/s defined by WaterLevelReliefThreshold:
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | waterlevel | allowedremoterelief |
------------------------------------------
|   1 |        0.0 |                 2.0 |
|   2 |        1.0 |            1.999998 |
|   3 |        2.0 |            1.999796 |
|   4 |        3.0 |                1.98 |
|   5 |        4.0 |                 1.0 |
|   6 |        5.0 |                0.02 |
|   7 |        6.0 |            0.000204 |
|   8 |        7.0 |            0.000002 |
|   9 |        8.0 |                 0.0 |

class hydpy.models.dam.dam_model.Calc_RequiredRemoteSupply_V1[source]¶

Bases: Method

Calculate the supply required from another location.

Requires the control parameters:
HighestRemoteSupply WaterLevelSupplyThreshold

Requires the derived parameters:
TOY WaterLevelSupplySmoothPar

Requires the factor sequence:
WaterLevel

Calculates the flux sequence:
RequiredRemoteSupply

Used auxiliary method:: smooth_logistic1()
Basic equation:: \(RequiredRemoteSupply = HighestRemoteSupply \cdot smooth_{logistic1}(WaterLevelSupplyThreshold-WaterLevel, WaterLevelSupplySmoothPar)\)

Examples:

Method Calc_RequiredRemoteSupply_V1 is functionally identical with method Calc_AllowedRemoteRelief_V2. Hence, the following examples serve for testing purposes only (see the documentation on function Calc_AllowedRemoteRelief_V2 for more detailed information):

>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> highestremotesupply(_11_1_12=1.0, _03_31_12=1.0,
...                     _04_1_12=2.0, _10_31_12=2.0)
>>> waterlevelsupplythreshold(_11_1_12=3.0, _03_31_12=2.0,
...                           _04_1_12=4.0, _10_31_12=4.0)
>>> waterlevelsupplytolerance(_11_1_12=0.0, _03_31_12=0.0,
...                           _04_1_12=1.0, _10_31_12=1.0)
>>> derived.waterlevelsupplysmoothpar.update()
>>> derived.toy.update()
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.calc_requiredremotesupply_v1,
...                 last_example=9,
...                 parseqs=(factors.waterlevel,
...                          fluxes.requiredremotesupply))
>>> test.nexts.waterlevel = range(9)
>>> model.idx_sim = pub.timegrids.init["2001.03.30"]
>>> test(first_example=2, last_example=6)
| ex. | waterlevel | requiredremotesupply |
-------------------------------------------
|   3 |        1.0 |                  1.0 |
|   4 |        2.0 |                  1.0 |
|   5 |        3.0 |                  0.0 |
|   6 |        4.0 |                  0.0 |
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | waterlevel | requiredremotesupply |
-------------------------------------------
|   1 |        0.0 |                  2.0 |
|   2 |        1.0 |             1.999998 |
|   3 |        2.0 |             1.999796 |
|   4 |        3.0 |                 1.98 |
|   5 |        4.0 |                  1.0 |
|   6 |        5.0 |                 0.02 |
|   7 |        6.0 |             0.000204 |
|   8 |        7.0 |             0.000002 |
|   9 |        8.0 |                  0.0 |

class hydpy.models.dam.dam_model.Calc_NaturalRemoteDischarge_V1[source]¶

Bases: Method

Estimate the natural discharge of a cross-section far downstream based on the last few simulation steps.

Requires the control parameter:
NmbLogEntries

Requires the log sequences:
LoggedTotalRemoteDischarge LoggedOutflow

Calculates the flux sequence:
NaturalRemoteDischarge

Basic equation:: \(RemoteDemand = max(\frac{\Sigma(LoggedTotalRemoteDischarge - LoggedOutflow)}{NmbLogEntries}), 0)\)

Examples:

Usually, the mean total remote flow should be larger than the mean dam outflow. Then, the estimated natural remote discharge is simply the difference between both averages:
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> nmblogentries(3)
>>> logs.loggedtotalremotedischarge(2.5, 2.0, 1.5)
>>> logs.loggedoutflow(2.0, 1.0, 0.0)
>>> model.calc_naturalremotedischarge_v1()
>>> fluxes.naturalremotedischarge
naturalremotedischarge(1.0)
Due to the wave travel times, the difference between remote discharge and dam outflow might sometimes be negative. To avoid negative estimates of natural discharge, Calc_NaturalRemoteDischarge_V1 sets its value to zero in such cases:
>>> logs.loggedoutflow(4.0, 3.0, 5.0)
>>> model.calc_naturalremotedischarge_v1()
>>> fluxes.naturalremotedischarge
naturalremotedischarge(0.0)

class hydpy.models.dam.dam_model.Calc_RemoteDemand_V1[source]¶

Bases: Method

Estimate the discharge demand of a cross-section far downstream.

Requires the control parameter:
RemoteDischargeMinimum

Requires the derived parameter:
TOY

Requires the flux sequence:
NaturalRemoteDischarge

Calculates the flux sequence:
RemoteDemand

Basic equation:: \(RemoteDemand = max(RemoteDischargeMinimum - NaturalRemoteDischarge, 0)\)

Examples:

Low water elevation is often restricted to specific months of the year. Sometimes the pursued lowest discharge value varies over the year to allow for a low flow variability in some agreement with the natural flow regime. The HydPy-Dam model supports such variations. Hence we define a short simulation period first, allowing us to show how we can define the corresponding parameter values and how calculating the remote water demand throughout the year works:
>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
Prepare the dam model:
>>> from hydpy.models.dam import *
>>> parameterstep()
Assume the required discharge at a gauge downstream being 2 m³/s in the hydrological summer half-year (April to October). In the winter month (November to May), there is no such requirement:
>>> remotedischargeminimum(_11_1_12=0.0, _03_31_12=0.0,
...                        _04_1_12=2.0, _10_31_12=2.0)
>>> derived.toy.update()
Prepare a test function, that calculates the remote discharge demand based on the parameter values defined above and for natural remote discharge values ranging between 0 and 3 m³/s:
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_remotedemand_v1, last_example=4,
...                 parseqs=(fluxes.naturalremotedischarge,
...                          fluxes.remotedemand))
>>> test.nexts.naturalremotedischarge = range(4)
On April 1, the required discharge is 2 m³/s:
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | naturalremotedischarge | remotedemand |
-----------------------------------------------
|   1 |                    0.0 |          2.0 |
|   2 |                    1.0 |          1.0 |
|   3 |                    2.0 |          0.0 |
|   4 |                    3.0 |          0.0 |
On May 31, the required discharge is 0 m³/s:
>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> test()
| ex. | naturalremotedischarge | remotedemand |
-----------------------------------------------
|   1 |                    0.0 |          0.0 |
|   2 |                    1.0 |          0.0 |
|   3 |                    2.0 |          0.0 |
|   4 |                    3.0 |          0.0 |

class hydpy.models.dam.dam_model.Calc_RemoteFailure_V1[source]¶

Bases: Method

Estimate the shortfall of actual discharge under the required discharge of a cross section far downstream.

Requires the control parameters:
NmbLogEntries RemoteDischargeMinimum

Requires the derived parameter:
TOY

Requires the log sequence:
LoggedTotalRemoteDischarge

Calculates the flux sequence:
RemoteFailure

Basic equation:: \(RemoteFailure = \frac{\Sigma(LoggedTotalRemoteDischarge)}{NmbLogEntries} - RemoteDischargeMinimum\)

Examples:

As explained in the documentation on method Calc_RemoteDemand_V1, we have to define a simulation period first:
>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
Now we prepare a dam model with log sequences memorizing three values:
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> nmblogentries(3)
Again, the required discharge is 2 m³/s in summer and 0 m³/s in winter:
>>> remotedischargeminimum(_11_1_12=0.0, _03_31_12=0.0,
...                        _04_1_12=2.0, _10_31_12=2.0)
>>> derived.toy.update()
Let it be supposed that the actual discharge at the remote cross section droped from 2 m³/s to 0 m³/s over the last three days:
>>> logs.loggedtotalremotedischarge(0.0, 1.0, 2.0)
This means that for the April 1 there would have been an averaged shortfall of 1 m³/s:
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> model.calc_remotefailure_v1()
>>> fluxes.remotefailure
remotefailure(1.0)
Instead for May 31 there would have been an excess of 1 m³/s, which is interpreted to be a “negative failure”:
>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> model.calc_remotefailure_v1()
>>> fluxes.remotefailure
remotefailure(-1.0)

class hydpy.models.dam.dam_model.Calc_RequiredRemoteRelease_V1[source]¶

Bases: Method

Guess the required release necessary to not fall below the threshold value at a cross section far downstream with a certain level of certainty.

Requires the control parameter:
RemoteDischargeSafety

Requires the derived parameters:
TOY RemoteDischargeSmoothPar

Requires the flux sequences:
RemoteDemand RemoteFailure

Calculates the flux sequence:
RequiredRemoteRelease

Used auxiliary method:: smooth_logistic1()
Basic equation:: \(RequiredRemoteRelease = RemoteDemand + RemoteDischargeSafety \cdot smooth_{logistic1}(RemoteFailure, RemoteDischargeSmoothPar)\)

Examples:

As in the examples above, define a short simulation time period first:
>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
Prepare the dam model:
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.toy.update()
Define a safety factor of 0.5 m³/s for the summer months and no safety factor at all for the winter months:
>>> remotedischargesafety(_11_1_12=0.0, _03_31_12=0.0,
...                       _04_1_12=1.0, _10_31_12=1.0)
>>> derived.remotedischargesmoothpar.update()
Assume the actual demand at the cross section downsstream has actually been estimated to be 2 m³/s:
>>> fluxes.remotedemand = 2.0
Prepare a test function, that calculates the required discharge based on the parameter values defined above and for a “remote failure” values ranging between -4 and 4 m³/s:
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_requiredremoterelease_v1,
...                 last_example=9,
...                 parseqs=(fluxes.remotefailure,
...                          fluxes.requiredremoterelease))
>>> test.nexts.remotefailure = range(-4, 5)
On May 31, the safety factor is 0 m³/s. Hence no discharge is added to the estimated remote demand of 2 m³/s:
>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> test()
| ex. | remotefailure | requiredremoterelease |
-----------------------------------------------
|   1 |          -4.0 |                   2.0 |
|   2 |          -3.0 |                   2.0 |
|   3 |          -2.0 |                   2.0 |
|   4 |          -1.0 |                   2.0 |
|   5 |           0.0 |                   2.0 |
|   6 |           1.0 |                   2.0 |
|   7 |           2.0 |                   2.0 |
|   8 |           3.0 |                   2.0 |
|   9 |           4.0 |                   2.0 |
On April 1, the safety factor is 1 m³/s. If the remote failure was exactly zero in the past, meaning the control of the dam was perfect, only 0.5 m³/s are added to the estimated remote demand of 2 m³/s. If the actual recharge did actually fall below the threshold value, up to 1 m³/s is added. If the the actual discharge exceeded the threshold value by 2 or 3 m³/s, virtually nothing is added:
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | remotefailure | requiredremoterelease |
-----------------------------------------------
|   1 |          -4.0 |                   2.0 |
|   2 |          -3.0 |              2.000001 |
|   3 |          -2.0 |              2.000102 |
|   4 |          -1.0 |                  2.01 |
|   5 |           0.0 |                   2.5 |
|   6 |           1.0 |                  2.99 |
|   7 |           2.0 |              2.999898 |
|   8 |           3.0 |              2.999999 |
|   9 |           4.0 |                   3.0 |

class hydpy.models.dam.dam_model.Calc_RequiredRemoteRelease_V2[source]¶

Bases: Method

Get the required remote release of the last simulation step.

Requires the log sequence:
LoggedRequiredRemoteRelease

Calculates the flux sequence:
RequiredRemoteRelease

Basic equation:: \(RequiredRemoteRelease = LoggedRequiredRemoteRelease\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> logs.loggedrequiredremoterelease = 3.0
>>> model.calc_requiredremoterelease_v2()
>>> fluxes.requiredremoterelease
requiredremoterelease(3.0)

class hydpy.models.dam.dam_model.Calc_AllowedRemoteRelief_V1[source]¶

Bases: Method

Get the allowed remote relief of the last simulation step.

Requires the log sequence:
LoggedAllowedRemoteRelief

Calculates the flux sequence:
AllowedRemoteRelief

Basic equation:: \(AllowedRemoteRelief = LoggedAllowedRemoteRelief\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> logs.loggedallowedremoterelief = 2.0
>>> model.calc_allowedremoterelief_v1()
>>> fluxes.allowedremoterelief
allowedremoterelief(2.0)

class hydpy.models.dam.dam_model.Calc_RequiredRelease_V1[source]¶

Bases: Method

Calculate the total water release (immediately and far downstream) required for reducing drought events.

Requires the control parameter:
NearDischargeMinimumThreshold

Requires the derived parameters:
TOY NearDischargeMinimumSmoothPar2

Requires the flux sequence:
RequiredRemoteRelease

Calculates the flux sequence:
RequiredRelease

Used auxiliary method:: smooth_logistic2()
Basic equation:: \(RequiredRelease = RequiredRemoteRelease \cdot smooth_{logistic2}( RequiredRemoteRelease-NearDischargeMinimumThreshold, NearDischargeMinimumSmoothPar2)\)

Examples:

As in the examples above, define a short simulation time period first:
>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
Prepare the dam model:
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.toy.update()
Define a minimum discharge value for a cross section immediately downstream of 4 m³/s for the summer months and of 0 m³/s for the winter months:
>>> neardischargeminimumthreshold(_11_1_12=0.0, _03_31_12=0.0,
...                               _04_1_12=4.0, _10_31_12=4.0)
Also define related tolerance values that are 1 m³/s in summer and 0 m³/s in winter:
>>> neardischargeminimumtolerance(_11_1_12=0.0, _03_31_12=0.0,
...                               _04_1_12=1.0, _10_31_12=1.0)
>>> derived.neardischargeminimumsmoothpar2.update()
Prepare a test function, that calculates the required total discharge based on the parameter values defined above and for a required value for a cross section far downstream ranging from 0 m³/s to 8 m³/s:
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_requiredrelease_v1,
...                 last_example=9,
...                 parseqs=(fluxes.requiredremoterelease,
...                          fluxes.requiredrelease))
>>> test.nexts.requiredremoterelease = range(9)
On May 31, both the threshold and the tolerance value are 0 m³/s. Hence the required total and the required remote release are equal:
>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> test()
| ex. | requiredremoterelease | requiredrelease |
-------------------------------------------------
|   1 |                   0.0 |             0.0 |
|   2 |                   1.0 |             1.0 |
|   3 |                   2.0 |             2.0 |
|   4 |                   3.0 |             3.0 |
|   5 |                   4.0 |             4.0 |
|   6 |                   5.0 |             5.0 |
|   7 |                   6.0 |             6.0 |
|   8 |                   7.0 |             7.0 |
|   9 |                   8.0 |             8.0 |
On April 1, the threshold value is 4 m³/s and the tolerance value is 1 m³/s. For low values of the required remote release, the required total release approximates the threshold value. For large values, it approximates the required remote release itself. Around the threshold value, due to the tolerance value of 1 m³/s, the required total release is a little larger than both the treshold value and the required remote release value:
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | requiredremoterelease | requiredrelease |
-------------------------------------------------
|   1 |                   0.0 |             4.0 |
|   2 |                   1.0 |        4.000012 |
|   3 |                   2.0 |        4.000349 |
|   4 |                   3.0 |            4.01 |
|   5 |                   4.0 |        4.205524 |
|   6 |                   5.0 |            5.01 |
|   7 |                   6.0 |        6.000349 |
|   8 |                   7.0 |        7.000012 |
|   9 |                   8.0 |             8.0 |

class hydpy.models.dam.dam_model.Calc_RequiredRelease_V2[source]¶

Bases: Method

Calculate the water release (immediately downstream) required for reducing drought events.

Requires the control parameter:
NearDischargeMinimumThreshold

Requires the derived parameter:
TOY

Calculates the flux sequence:
RequiredRelease

Basic equation:: \(RequiredRelease = NearDischargeMinimumThreshold\)

Examples:

As in the examples above, define a short simulation time period first:
>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"
Prepare the dam model:
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.toy.update()
Define a minimum discharge value for a cross section immediately downstream of 4 m³/s for the summer months and of 0 m³/s for the winter months:
>>> neardischargeminimumthreshold(_11_1_12=0.0, _03_31_12=0.0,
...                               _04_1_12=4.0, _10_31_12=4.0)
As to be expected, the calculated required release is 0.0 m³/s on May 31 and 4.0 m³/s on April 1:
>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> model.calc_requiredrelease_v2()
>>> fluxes.requiredrelease
requiredrelease(0.0)
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> model.calc_requiredrelease_v2()
>>> fluxes.requiredrelease
requiredrelease(4.0)

class hydpy.models.dam.dam_model.Calc_PossibleRemoteRelief_V1[source]¶

Bases: Method

Calculate the highest possible water release that can be routed to a remote location based on an interpolation approach approximating the relationship between possible release and water stage.

Requires the control parameter:
WaterLevel2PossibleRemoteRelief

Requires the factor sequence:
WaterLevel

Calculates the flux sequence:
PossibleRemoteRelief

Example:

For simplicity, the example of method Calc_FloodDischarge_V1 is reused. See the documentation on the mentioned method for further information:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevel2possibleremoterelief(
...     ANN(nmb_inputs=1,
...         nmb_neurons=(2,),
...         nmb_outputs=1,
...         weights_input=[[50.0, 4]],
...         weights_output=[[2.0], [30]],
...         intercepts_hidden=[[-13000, -1046]],
...         intercepts_output=[0.0]))
>>> from hydpy import UnitTest
>>> test = UnitTest(
...     model, model.calc_possibleremoterelief_v1,
...     last_example=21,
...     parseqs=(factors.waterlevel, fluxes.possibleremoterelief))
>>> test.nexts.waterlevel = numpy.arange(257, 261.1, 0.2)
>>> test()
| ex. | waterlevel | possibleremoterelief |
-------------------------------------------
|   1 |      257.0 |                  0.0 |
|   2 |      257.2 |             0.000001 |
|   3 |      257.4 |             0.000002 |
|   4 |      257.6 |             0.000005 |
|   5 |      257.8 |             0.000011 |
|   6 |      258.0 |             0.000025 |
|   7 |      258.2 |             0.000056 |
|   8 |      258.4 |             0.000124 |
|   9 |      258.6 |             0.000275 |
|  10 |      258.8 |             0.000612 |
|  11 |      259.0 |             0.001362 |
|  12 |      259.2 |             0.003031 |
|  13 |      259.4 |             0.006745 |
|  14 |      259.6 |             0.015006 |
|  15 |      259.8 |             0.033467 |
|  16 |      260.0 |             1.074179 |
|  17 |      260.2 |             2.164498 |
|  18 |      260.4 |             2.363853 |
|  19 |      260.6 |              2.79791 |
|  20 |      260.8 |             3.719725 |
|  21 |      261.0 |             5.576088 |

class hydpy.models.dam.dam_model.Fix_Min1_V1[source]¶

Bases: Method

Apply function smooth_min1() without risking negative results.

Used auxiliary methods:: smooth_min1() smooth_max1()

When applying function smooth_min1() straight-forward (\(result = smooth_min1(input, threshold, smoothpar\)), it likely results in slightly negative result values for a positive threshold value and an input value of zero. Some methods of the dam models rely on smooth_min1() but should never return negative values. Therefore, methods Fix_Min1_V1 modifies smooth_min1() for such cases.

Method both supports “absolute” (where the smoothing parameter value is taken as is) and “relative” smoothers (where the actual smoothing parameter value depends on the current threshold value). Please see the detailed documentation on methods Calc_ActualRemoteRelief_V1 (implementing a “relative” smoother approach), which explains the strategy behind method Fix_Min1_V1 in depths. The documentation on method Update_ActualRemoteRelief_V1 provides test calculation results for the “aboslute” smoother approach.

class hydpy.models.dam.dam_model.Calc_ActualRemoteRelief_V1[source]¶

Bases: Method

Calculate the actual amount of water released to a remote location to relieve the dam during high flow conditions.

Requires the control parameter:
RemoteReliefTolerance

Requires the flux sequences:
AllowedRemoteRelief PossibleRemoteRelief

Calculates the flux sequence:
ActualRemoteRelief

Basic equation - discontinous:: \(ActualRemoteRelease = min(PossibleRemoteRelease, AllowedRemoteRelease)\)
Used additional method:: Fix_Min1_V1
Basic equation - continous:: \(ActualRemoteRelease = smooth_min1(PossibleRemoteRelease, AllowedRemoteRelease, RemoteReliefTolerance)\)

Note that the given continous basic equation is a simplification of the complete algorithm to calculate ActualRemoteRelief, which also makes use of smooth_max1() to prevent from gaining negative values in a smooth manner.

Examples:

Prepare a dam model:

>>> from hydpy.models.dam import *
>>> parameterstep()

Prepare a test function object that performs seven examples with PossibleRemoteRelief ranging from -1 to 5 m³/s:

>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualremoterelief_v1,
...                 last_example=7,
...                 parseqs=(fluxes.possibleremoterelief,
...                          fluxes.actualremoterelief))
>>> test.nexts.possibleremoterelief = range(-1, 6)

We begin with a AllowedRemoteRelief value of 3 m³/s:

>>> fluxes.allowedremoterelief = 3.0

Through setting the value of RemoteReliefTolerance to the lowest possible value, there is no smoothing. Instead, the relationship between ActualRemoteRelief and PossibleRemoteRelief follows the simple discontinous minimum function:

>>> remoterelieftolerance(0.0)
>>> test()
| ex. | possibleremoterelief | actualremoterelief |
---------------------------------------------------
|   1 |                 -1.0 |                0.0 |
|   2 |                  0.0 |                0.0 |
|   3 |                  1.0 |                1.0 |
|   4 |                  2.0 |                2.0 |
|   5 |                  3.0 |                3.0 |
|   6 |                  4.0 |                3.0 |
|   7 |                  5.0 |                3.0 |

Increasing the value of parameter RemoteReliefTolerance to a sensible value results in a moderate smoothing:

>>> remoterelieftolerance(0.2)
>>> test()
| ex. | possibleremoterelief | actualremoterelief |
---------------------------------------------------
|   1 |                 -1.0 |                0.0 |
|   2 |                  0.0 |                0.0 |
|   3 |                  1.0 |           0.970639 |
|   4 |                  2.0 |            1.89588 |
|   5 |                  3.0 |           2.584112 |
|   6 |                  4.0 |           2.896195 |
|   7 |                  5.0 |           2.978969 |

Even when setting a very large smoothing parameter value, the actual remote relief does not fall below 0 m³/s:

>>> remoterelieftolerance(1.0)
>>> test()
| ex. | possibleremoterelief | actualremoterelief |
---------------------------------------------------
|   1 |                 -1.0 |                0.0 |
|   2 |                  0.0 |                0.0 |
|   3 |                  1.0 |           0.306192 |
|   4 |                  2.0 |           0.634882 |
|   5 |                  3.0 |           1.037708 |
|   6 |                  4.0 |           1.436494 |
|   7 |                  5.0 |           1.788158 |

Now we repeat the last example with an allowed remote relief of only 0.03 m³/s instead of 3 m³/s:

>>> fluxes.allowedremoterelief = 0.03
>>> test()
| ex. | possibleremoterelief | actualremoterelief |
---------------------------------------------------
|   1 |                 -1.0 |                0.0 |
|   2 |                  0.0 |                0.0 |
|   3 |                  1.0 |               0.03 |
|   4 |                  2.0 |               0.03 |
|   5 |                  3.0 |               0.03 |
|   6 |                  4.0 |               0.03 |
|   7 |                  5.0 |               0.03 |

The result above is as expected, but the smooth part of the relationship is not resolved. By increasing the resolution we see a relationship that corresponds to the one shown above for an allowed relief of 3 m³/s. This points out, that the degree of smoothing is releative to the allowed relief:

>>> import numpy
>>> test.nexts.possibleremoterelief = numpy.arange(-0.01, 0.06, 0.01)
>>> test()
| ex. | possibleremoterelief | actualremoterelief |
---------------------------------------------------
|   1 |                -0.01 |                0.0 |
|   2 |                  0.0 |                0.0 |
|   3 |                 0.01 |           0.003062 |
|   4 |                 0.02 |           0.006349 |
|   5 |                 0.03 |           0.010377 |
|   6 |                 0.04 |           0.014365 |
|   7 |                 0.05 |           0.017882 |

One can reperform the shown experiments with an even higher resolution to see that the relationship between ActualRemoteRelief and PossibleRemoteRelief is (at least in most cases) in fact very smooth. But a more analytical approach would possibly be favourable regarding the smoothness in some edge cases and computational efficiency.

class hydpy.models.dam.dam_model.Calc_TargetedRelease_V1[source]¶

Bases: Method

Calculate the targeted water release for reducing drought events, taking into account both the required water release and the actual inflow into the dam.

Requires the control parameters:
RestrictTargetedRelease NearDischargeMinimumThreshold

Requires the derived parameters:
NearDischargeMinimumSmoothPar1 TOY

Requires the flux sequences:
Inflow RequiredRelease

Calculates the flux sequence:
TargetedRelease

Some dams are supposed to maintain a certain degree of low flow variability downstream. In case parameter RestrictTargetedRelease is set to True, method Calc_TargetedRelease_V1 simulates this by (approximately) passing inflow as outflow whenever inflow is below the value of the threshold parameter NearDischargeMinimumThreshold. If parameter RestrictTargetedRelease is set to False, does nothing except assigning the value of sequence RequiredRelease to sequence TargetedRelease.

Used auxiliary method:

smooth_logistic1()

Basic equation:

\(TargetedRelease = w \cdot RequiredRelease + (1-w) \cdot Inflow\)

\(w = smooth_{logistic1}( Inflow-NearDischargeMinimumThreshold, NearDischargeMinimumSmoothPar1)\)

Examples:

As in the examples above, define a short simulation time period first:

>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1d"

Prepare the dam model:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.toy.update()

We start with enabling RestrictTargetedRelease:

>>> restricttargetedrelease(True)

Define a minimum discharge value for a cross section immediately downstream of 6 m³/s for the summer months and of 4 m³/s for the winter months:

>>> neardischargeminimumthreshold(_11_1_12=6.0, _03_31_12=6.0,
...                               _04_1_12=4.0, _10_31_12=4.0)

Also define related tolerance values that are 1 m³/s in summer and 0 m³/s in winter:

>>> neardischargeminimumtolerance(_11_1_12=0.0, _03_31_12=0.0,
...                               _04_1_12=2.0, _10_31_12=2.0)
>>> derived.neardischargeminimumsmoothpar1.update()

Prepare a test function that calculates the targeted water release based on the parameter values defined above and for inflows into the dam ranging from 0 m³/s to 10 m³/s:

>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_targetedrelease_v1,
...                 last_example=21,
...                 parseqs=(fluxes.inflow,
...                          fluxes.targetedrelease))
>>> test.nexts.inflow = numpy.arange(0.0, 10.5, .5)

Firstly, assume the required release of water for reducing droughts has already been determined to be 10 m³/s:

>>> fluxes.requiredrelease = 10.

On May 31, the tolerance value is 0 m³/s. Hence the targeted release jumps from the inflow value to the required release when exceeding the threshold value of 6 m³/s:

>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |             0.0 |
|   2 |    0.5 |             0.5 |
|   3 |    1.0 |             1.0 |
|   4 |    1.5 |             1.5 |
|   5 |    2.0 |             2.0 |
|   6 |    2.5 |             2.5 |
|   7 |    3.0 |             3.0 |
|   8 |    3.5 |             3.5 |
|   9 |    4.0 |             4.0 |
|  10 |    4.5 |             4.5 |
|  11 |    5.0 |             5.0 |
|  12 |    5.5 |             5.5 |
|  13 |    6.0 |             8.0 |
|  14 |    6.5 |            10.0 |
|  15 |    7.0 |            10.0 |
|  16 |    7.5 |            10.0 |
|  17 |    8.0 |            10.0 |
|  18 |    8.5 |            10.0 |
|  19 |    9.0 |            10.0 |
|  20 |    9.5 |            10.0 |
|  21 |   10.0 |            10.0 |

On April 1, the threshold value is 4 m³/s and the tolerance value is 2 m³/s. Hence there is a smooth transition for inflows ranging between 2 m³/s and 6 m³/s:

>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |         0.00102 |
|   2 |    0.5 |        0.503056 |
|   3 |    1.0 |        1.009127 |
|   4 |    1.5 |        1.527132 |
|   5 |    2.0 |            2.08 |
|   6 |    2.5 |        2.731586 |
|   7 |    3.0 |        3.639277 |
|   8 |    3.5 |        5.064628 |
|   9 |    4.0 |             7.0 |
|  10 |    4.5 |        8.676084 |
|  11 |    5.0 |        9.543374 |
|  12 |    5.5 |        9.861048 |
|  13 |    6.0 |            9.96 |
|  14 |    6.5 |        9.988828 |
|  15 |    7.0 |        9.996958 |
|  16 |    7.5 |        9.999196 |
|  17 |    8.0 |        9.999796 |
|  18 |    8.5 |        9.999951 |
|  19 |    9.0 |         9.99999 |
|  20 |    9.5 |        9.999998 |
|  21 |   10.0 |            10.0 |

An required release substantially below the threshold value is a rather unlikely scenario, but is at least instructive regarding the functioning of the method (when plotting the results graphically…):

>>> fluxes.requiredrelease = 2.

On May 31, the relationship between targeted release and inflow is again highly discontinous:

>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |             0.0 |
|   2 |    0.5 |             0.5 |
|   3 |    1.0 |             1.0 |
|   4 |    1.5 |             1.5 |
|   5 |    2.0 |             2.0 |
|   6 |    2.5 |             2.5 |
|   7 |    3.0 |             3.0 |
|   8 |    3.5 |             3.5 |
|   9 |    4.0 |             4.0 |
|  10 |    4.5 |             4.5 |
|  11 |    5.0 |             5.0 |
|  12 |    5.5 |             5.5 |
|  13 |    6.0 |             4.0 |
|  14 |    6.5 |             2.0 |
|  15 |    7.0 |             2.0 |
|  16 |    7.5 |             2.0 |
|  17 |    8.0 |             2.0 |
|  18 |    8.5 |             2.0 |
|  19 |    9.0 |             2.0 |
|  20 |    9.5 |             2.0 |
|  21 |   10.0 |             2.0 |

And on April 1, it is again absolutely smooth:

>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |        0.000204 |
|   2 |    0.5 |        0.500483 |
|   3 |    1.0 |        1.001014 |
|   4 |    1.5 |        1.501596 |
|   5 |    2.0 |             2.0 |
|   6 |    2.5 |        2.484561 |
|   7 |    3.0 |        2.908675 |
|   8 |    3.5 |        3.138932 |
|   9 |    4.0 |             3.0 |
|  10 |    4.5 |         2.60178 |
|  11 |    5.0 |        2.273976 |
|  12 |    5.5 |        2.108074 |
|  13 |    6.0 |            2.04 |
|  14 |    6.5 |        2.014364 |
|  15 |    7.0 |        2.005071 |
|  16 |    7.5 |         2.00177 |
|  17 |    8.0 |        2.000612 |
|  18 |    8.5 |         2.00021 |
|  19 |    9.0 |        2.000072 |
|  20 |    9.5 |        2.000024 |
|  21 |   10.0 |        2.000008 |

For required releases equal with the threshold value, there is generally no jump in the relationship. But on May 31, there remains a discontinuity in the first derivative:

>>> fluxes.requiredrelease = 6.
>>> model.idx_sim = pub.timegrids.init["2001.03.31"]
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |             0.0 |
|   2 |    0.5 |             0.5 |
|   3 |    1.0 |             1.0 |
|   4 |    1.5 |             1.5 |
|   5 |    2.0 |             2.0 |
|   6 |    2.5 |             2.5 |
|   7 |    3.0 |             3.0 |
|   8 |    3.5 |             3.5 |
|   9 |    4.0 |             4.0 |
|  10 |    4.5 |             4.5 |
|  11 |    5.0 |             5.0 |
|  12 |    5.5 |             5.5 |
|  13 |    6.0 |             6.0 |
|  14 |    6.5 |             6.0 |
|  15 |    7.0 |             6.0 |
|  16 |    7.5 |             6.0 |
|  17 |    8.0 |             6.0 |
|  18 |    8.5 |             6.0 |
|  19 |    9.0 |             6.0 |
|  20 |    9.5 |             6.0 |
|  21 |   10.0 |             6.0 |

On April 1, this second order discontinuity is smoothed with the help of a little hump around the threshold:

>>> fluxes.requiredrelease = 4.
>>> model.idx_sim = pub.timegrids.init["2001.04.01"]
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |        0.000408 |
|   2 |    0.5 |        0.501126 |
|   3 |    1.0 |        1.003042 |
|   4 |    1.5 |         1.50798 |
|   5 |    2.0 |            2.02 |
|   6 |    2.5 |        2.546317 |
|   7 |    3.0 |        3.091325 |
|   8 |    3.5 |        3.620356 |
|   9 |    4.0 |             4.0 |
|  10 |    4.5 |        4.120356 |
|  11 |    5.0 |        4.091325 |
|  12 |    5.5 |        4.046317 |
|  13 |    6.0 |            4.02 |
|  14 |    6.5 |         4.00798 |
|  15 |    7.0 |        4.003042 |
|  16 |    7.5 |        4.001126 |
|  17 |    8.0 |        4.000408 |
|  18 |    8.5 |        4.000146 |
|  19 |    9.0 |        4.000051 |
|  20 |    9.5 |        4.000018 |
|  21 |   10.0 |        4.000006 |

Repeating the above example with the RestrictTargetedRelease flag disabled results in identical values for sequences RequiredRelease and TargetedRelease:

>>> restricttargetedrelease(False)
>>> test()
| ex. | inflow | targetedrelease |
----------------------------------
|   1 |    0.0 |             4.0 |
|   2 |    0.5 |             4.0 |
|   3 |    1.0 |             4.0 |
|   4 |    1.5 |             4.0 |
|   5 |    2.0 |             4.0 |
|   6 |    2.5 |             4.0 |
|   7 |    3.0 |             4.0 |
|   8 |    3.5 |             4.0 |
|   9 |    4.0 |             4.0 |
|  10 |    4.5 |             4.0 |
|  11 |    5.0 |             4.0 |
|  12 |    5.5 |             4.0 |
|  13 |    6.0 |             4.0 |
|  14 |    6.5 |             4.0 |
|  15 |    7.0 |             4.0 |
|  16 |    7.5 |             4.0 |
|  17 |    8.0 |             4.0 |
|  18 |    8.5 |             4.0 |
|  19 |    9.0 |             4.0 |
|  20 |    9.5 |             4.0 |
|  21 |   10.0 |             4.0 |

class hydpy.models.dam.dam_model.Calc_ActualRelease_V1[source]¶

Bases: Method

Calculate the actual water release that can be supplied by the dam considering the targeted release and the given water level.

Requires the control parameter:
WaterLevelMinimumThreshold

Requires the derived parameter:
WaterLevelMinimumSmoothPar

Requires the factor sequence:
WaterLevel

Requires the flux sequence:
TargetedRelease

Calculates the flux sequence:
ActualRelease

Used auxiliary method:: smooth_logistic1()
Basic equation:: \(ActualRelease = TargetedRelease \cdot smooth_{logistic1}(WaterLevelMinimumThreshold - WaterLevel, WaterLevelMinimumSmoothPar)\)

Examples:

Prepare the dam model:
>>> from hydpy.models.dam import *
>>> parameterstep()
Assume the required release has previously been estimated to be 2 m³/s:
>>> fluxes.targetedrelease = 2.0
Prepare a test function, that calculates the targeted water release for water levels ranging between -1 and 5 m:
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualrelease_v1,
...                 last_example=7,
...                 parseqs=(factors.waterlevel,
...                          fluxes.actualrelease))
>>> test.nexts.waterlevel = range(-1, 6)
Example 1

Firstly, we define a sharp minimum water level tolerance of 0 m:
>>> waterlevelminimumthreshold(0.0)
>>> waterlevelminimumtolerance(0.0)
>>> derived.waterlevelminimumsmoothpar.update()
The following test results show that the water release is reduced to 0 m³/s for water levels (even slightly) lower than 0 m and is identical with the required value of 2 m³/s (even slighlty) above 0 m:
>>> test()
| ex. | waterlevel | actualrelease |
------------------------------------
|   1 |       -1.0 |           0.0 |
|   2 |        0.0 |           1.0 |
|   3 |        1.0 |           2.0 |
|   4 |        2.0 |           2.0 |
|   5 |        3.0 |           2.0 |
|   6 |        4.0 |           2.0 |
|   7 |        5.0 |           2.0 |
One may have noted that in the above example the calculated water release is 1 m³/s (which is exactly the half of the targeted release) at a water level of 1 m. This looks suspiciously lake a flaw but is not of any importance considering the fact, that numerical integration algorithms will approximate the analytical solution of a complete emptying of a dam emtying (which is a water level of 0 m), only with a certain accuracy.

Example 2

Nonetheless, it can (besides some other possible advantages) dramatically increase the speed of numerical integration algorithms to define a smooth transition area instead of sharp threshold value, like in the following example:
>>> waterlevelminimumthreshold(4.0)
>>> waterlevelminimumtolerance(1.0)
>>> derived.waterlevelminimumsmoothpar.update()
Now, 98 % of the variation of the total range from 0 m³/s to 2 m³/s occurs between a water level of 3 m and 5 m:
>>> test()
| ex. | waterlevel | actualrelease |
------------------------------------
|   1 |       -1.0 |           0.0 |
|   2 |        0.0 |           0.0 |
|   3 |        1.0 |      0.000002 |
|   4 |        2.0 |      0.000204 |
|   5 |        3.0 |          0.02 |
|   6 |        4.0 |           1.0 |
|   7 |        5.0 |          1.98 |
Example 3

Note that it is possible to set both parameters in a manner that might result in negative water stages beyond numerical inaccuracy:
>>> waterlevelminimumthreshold(1.0)
>>> waterlevelminimumtolerance(2.0)
>>> derived.waterlevelminimumsmoothpar.update()
Here, the actual water release is 0.18 m³/s for a water level of 0 m. Hence water stages in the range of 0 m to -1 m or even -2 m might occur during the simulation of long drought events:
>>> test()
| ex. | waterlevel | actualrelease |
------------------------------------
|   1 |       -1.0 |          0.02 |
|   2 |        0.0 |       0.18265 |
|   3 |        1.0 |           1.0 |
|   4 |        2.0 |       1.81735 |
|   5 |        3.0 |          1.98 |
|   6 |        4.0 |      1.997972 |
|   7 |        5.0 |      1.999796 |

class hydpy.models.dam.dam_model.Calc_ActualRelease_V2[source]¶

Bases: Method

Calculate the actual water release in aggrement with the allowed release not causing harm downstream and the actual water volume.

Requires the control parameters:
AllowedRelease WaterLevelMinimumThreshold

Requires the derived parameters:
TOY WaterLevelMinimumSmoothPar

Requires the factor sequence:
WaterLevel

Calculates the flux sequence:
ActualRelease

Used auxiliary method:: smooth_logistic1()
Basic equation:: \(ActualRelease = AllowedRelease \cdot smooth_{logistic1}(WaterLevel, WaterLevelMinimumSmoothPar)\)

Examples:

We assume a short simulation period spanning the last and first two days of March and April, respectively:

>>> from hydpy import pub
>>> pub.timegrids = "2001-03-30", "2001-04-03", "1d"

We prepare the dam model and set the allowed release to 2 m³/s and to 4 m³/s for March and February, respectively, and set the water level threshold to 0.5 m:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> allowedrelease(_11_1_12=2.0, _03_31_12=2.0,
...                _04_1_12=4.0, _10_31_12=4.0)
>>> waterlevelminimumthreshold(0.5)
>>> derived.toy.update()

Next, wrepare a test function, that calculates the actual water release for water levels ranging between 0.1 and 0.9 m:

>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualrelease_v2,
...                 last_example=9,
...                 parseqs=(factors.waterlevel,
...                          fluxes.actualrelease))
>>> test.nexts.waterlevel = 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9

First, we define a sharp minimum water level tolerance of 0 m, resulting in a sharp transition from 0 to 2 m³/s around the a water level threshold of 0.5 m, shown for the 31st March:

>>> model.idx_sim = pub.timegrids.init["2001-03-31"]
>>> waterlevelminimumtolerance(0.0)
>>> derived.waterlevelminimumsmoothpar.update()
>>> test()
| ex. | waterlevel | actualrelease |
------------------------------------
|   1 |        0.1 |           0.0 |
|   2 |        0.2 |           0.0 |
|   3 |        0.3 |           0.0 |
|   4 |        0.4 |           0.0 |
|   5 |        0.5 |           1.0 |
|   6 |        0.6 |           2.0 |
|   7 |        0.7 |           2.0 |
|   8 |        0.8 |           2.0 |
|   9 |        0.9 |           2.0 |

Second, we define a numerically more sensible tolerance value of 0.1 m, causing 98 % of the variation of the actual release to occur between water levels of 0.4 m and 0.6 m, shown for the 1th April:

>>> model.idx_sim = pub.timegrids.init["2001-04-01"]
>>> waterlevelminimumtolerance(0.1)
>>> derived.waterlevelminimumsmoothpar.update()
>>> test()
| ex. | waterlevel | actualrelease |
------------------------------------
|   1 |        0.1 |           0.0 |
|   2 |        0.2 |      0.000004 |
|   3 |        0.3 |      0.000408 |
|   4 |        0.4 |          0.04 |
|   5 |        0.5 |           2.0 |
|   6 |        0.6 |          3.96 |
|   7 |        0.7 |      3.999592 |
|   8 |        0.8 |      3.999996 |
|   9 |        0.9 |           4.0 |

class hydpy.models.dam.dam_model.Calc_ActualRelease_V3[source]¶

Bases: Method

Calculate an actual water release that tries to change the water storage into the direction of the actual target volume without violating the required minimum and the allowed maximum flow.

Requires the control parameters:
TargetVolume TargetRangeAbsolute TargetRangeRelative NearDischargeMinimumThreshold WaterVolumeMinimumThreshold

Requires the derived parameters:
TOY VolumeSmoothParLog1 VolumeSmoothParLog2 DischargeSmoothPar

Requires the flux sequence:
Inflow

Requires the state sequence:
WaterVolume

Requires the aide sequence:
AllowedDischarge

Calculates the flux sequence:
ActualRelease

Used auxiliary methods:: smooth_logistic1() smooth_logistic2() smooth_min1() smooth_max1()

Examples:

Method Calc_ActualRelease_V3 is quite complex. As it is the key component of application model dam_lreservoir, we advise to read its documentation including some introductory examples first, and to inspect the following detailled examples afterwards, which hopefully cover all of the mentioned corner cases.

>>> from hydpy import pub
>>> pub.timegrids = "2001-03-30", "2001-04-03", "1d"

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> targetvolume(_11_1_12=5.0, _03_31_12=5.0,
...              _04_1_12=0.0, _10_31_12=0.0)
>>> neardischargeminimumthreshold(_11_1_12=3.0, _03_31_12=3.0,
...                               _04_1_12=0.0, _10_31_12=0.0)
>>> watervolumeminimumthreshold(0.0)
>>> derived.toy.update()

>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualrelease_v3,
...                 last_example=31,
...                 parseqs=(states.watervolume,
...                          fluxes.actualrelease))
>>> import numpy
>>> test.nexts.watervolume = numpy.arange(3.5, 6.6, 0.1)

>>> model.idx_sim = pub.timegrids.init["2001-03-31"]
>>> aides.alloweddischarge = 6.0

>>> def set_tolerances(value):
...     volumetolerance(value)
...     dischargetolerance(value)
...     derived.volumesmoothparlog1.update()
...     derived.volumesmoothparlog2.update()
...     derived.dischargesmoothpar.update()

>>> def apply_targetrange(flag):
...     if flag:
...         targetrangeabsolute(0.1)
...         targetrangerelative(0.2)
...     else:
...         targetrangeabsolute(0.0)
...         targetrangerelative(0.0)

Standard case, without smoothing, without interpolation:

>>> fluxes.inflow = 4.0
>>> set_tolerances(0.0)
>>> apply_targetrange(False)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |           3.0 |
|  15 |         4.9 |           3.0 |
|  16 |         5.0 |           4.0 |
|  17 |         5.1 |           6.0 |
|  18 |         5.2 |           6.0 |
|  19 |         5.3 |           6.0 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Standard case, without smoothing, with interpolation:

>>> fluxes.inflow = 4.0
>>> set_tolerances(0.0)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.1 |
|   8 |         4.2 |           3.2 |
|   9 |         4.3 |           3.3 |
|  10 |         4.4 |           3.4 |
|  11 |         4.5 |           3.5 |
|  12 |         4.6 |           3.6 |
|  13 |         4.7 |           3.7 |
|  14 |         4.8 |           3.8 |
|  15 |         4.9 |           3.9 |
|  16 |         5.0 |           4.0 |
|  17 |         5.1 |           4.2 |
|  18 |         5.2 |           4.4 |
|  19 |         5.3 |           4.6 |
|  20 |         5.4 |           4.8 |
|  21 |         5.5 |           5.0 |
|  22 |         5.6 |           5.2 |
|  23 |         5.7 |           5.4 |
|  24 |         5.8 |           5.6 |
|  25 |         5.9 |           5.8 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Standard case, moderate smoothing, without interpolation:

>>> fluxes.inflow = 4.0
>>> set_tolerances(0.1)
>>> apply_targetrange(False)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |      3.000001 |
|  14 |         4.8 |      3.000102 |
|  15 |         4.9 |          3.01 |
|  16 |         5.0 |           4.0 |
|  17 |         5.1 |          5.98 |
|  18 |         5.2 |      5.999796 |
|  19 |         5.3 |      5.999998 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Standard case, moderate smoothing, with interpolation:

>>> fluxes.inflow = 4.0
>>> set_tolerances(0.1)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |      3.000013 |
|   2 |         3.6 |      3.000068 |
|   3 |         3.7 |      3.000369 |
|   4 |         3.8 |      3.001974 |
|   5 |         3.9 |          3.01 |
|   6 |         4.0 |      3.040983 |
|   7 |         4.1 |          3.11 |
|   8 |         4.2 |      3.201974 |
|   9 |         4.3 |      3.300369 |
|  10 |         4.4 |      3.400067 |
|  11 |         4.5 |           3.5 |
|  12 |         4.6 |      3.599933 |
|  13 |         4.7 |      3.699632 |
|  14 |         4.8 |      3.798047 |
|  15 |         4.9 |        3.8913 |
|  16 |         5.0 |           4.0 |
|  17 |         5.1 |        4.2177 |
|  18 |         5.2 |      4.403907 |
|  19 |         5.3 |      4.600737 |
|  20 |         5.4 |      4.800134 |
|  21 |         5.5 |           5.0 |
|  22 |         5.6 |      5.199866 |
|  23 |         5.7 |      5.399263 |
|  24 |         5.8 |      5.596051 |
|  25 |         5.9 |          5.78 |
|  26 |         6.0 |      5.918035 |
|  27 |         6.1 |          5.98 |
|  28 |         6.2 |      5.996051 |
|  29 |         6.3 |      5.999262 |
|  30 |         6.4 |      5.999864 |
|  31 |         6.5 |      5.999975 |

Inflow smaller than minimum release, without smoothing, without interpolation:

>>> fluxes.inflow = 2.0
>>> set_tolerances(0.0)
>>> apply_targetrange(False)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |           3.0 |
|  15 |         4.9 |           3.0 |
|  16 |         5.0 |           3.0 |
|  17 |         5.1 |           6.0 |
|  18 |         5.2 |           6.0 |
|  19 |         5.3 |           6.0 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Inflow smaller than minimum release, without smoothing, with interpolation:

>>> fluxes.inflow = 2.0
>>> set_tolerances(0.0)
>>> apply_targetrange(True)
>>> fluxes.inflow = 2.0
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |           3.0 |
|  15 |         4.9 |           3.0 |
|  16 |         5.0 |           3.0 |
|  17 |         5.1 |           3.3 |
|  18 |         5.2 |           3.6 |
|  19 |         5.3 |           3.9 |
|  20 |         5.4 |           4.2 |
|  21 |         5.5 |           4.5 |
|  22 |         5.6 |           4.8 |
|  23 |         5.7 |           5.1 |
|  24 |         5.8 |           5.4 |
|  25 |         5.9 |           5.7 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Inflow smaller than minimum release, moderate smoothing, without interpolation:

>>> fluxes.inflow = 2.0
>>> set_tolerances(0.1)
>>> apply_targetrange(False)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |           3.0 |
|  15 |         4.9 |           3.0 |
|  16 |         5.0 |           3.0 |
|  17 |         5.1 |          5.97 |
|  18 |         5.2 |      5.999694 |
|  19 |         5.3 |      5.999997 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Inflow smaller than minimum release, moderate smoothing, with interpolation:

>>> fluxes.inflow = 2.0
>>> set_tolerances(0.1)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |      3.000001 |
|  15 |         4.9 |        3.0003 |
|  16 |         5.0 |           3.0 |
|  17 |         5.1 |        3.3267 |
|  18 |         5.2 |      3.605861 |
|  19 |         5.3 |      3.901105 |
|  20 |         5.4 |      4.200201 |
|  21 |         5.5 |           4.5 |
|  22 |         5.6 |      4.799799 |
|  23 |         5.7 |      5.098894 |
|  24 |         5.8 |      5.394077 |
|  25 |         5.9 |          5.67 |
|  26 |         6.0 |      5.877052 |
|  27 |         6.1 |          5.97 |
|  28 |         6.2 |      5.994077 |
|  29 |         6.3 |      5.998894 |
|  30 |         6.4 |      5.999796 |
|  31 |         6.5 |      5.999962 |

Inflow larger than maximum release, without smoothing, without interpolation:

>>> fluxes.inflow = 7.0
>>> set_tolerances(0.0)
>>> apply_targetrange(False)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |           3.0 |
|  15 |         4.9 |           3.0 |
|  16 |         5.0 |           6.0 |
|  17 |         5.1 |           6.0 |
|  18 |         5.2 |           6.0 |
|  19 |         5.3 |           6.0 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Inflow larger than maximum release, without smoothing, with interpolation:

>>> fluxes.inflow = 7.0
>>> set_tolerances(0.0)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.3 |
|   8 |         4.2 |           3.6 |
|   9 |         4.3 |           3.9 |
|  10 |         4.4 |           4.2 |
|  11 |         4.5 |           4.5 |
|  12 |         4.6 |           4.8 |
|  13 |         4.7 |           5.1 |
|  14 |         4.8 |           5.4 |
|  15 |         4.9 |           5.7 |
|  16 |         5.0 |           6.0 |
|  17 |         5.1 |           6.0 |
|  18 |         5.2 |           6.0 |
|  19 |         5.3 |           6.0 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Inflow larger than maximum release, moderate smoothing, without interpolation:

>>> fluxes.inflow = 7.0
>>> apply_targetrange(False)
>>> set_tolerances(0.1)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |      3.000003 |
|  14 |         4.8 |      3.000306 |
|  15 |         4.9 |          3.03 |
|  16 |         5.0 |           6.0 |
|  17 |         5.1 |           6.0 |
|  18 |         5.2 |           6.0 |
|  19 |         5.3 |           6.0 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Inflow larger than maximum release, moderate smoothing, with interpolation:

>>> fluxes.inflow = 7.0
>>> apply_targetrange(True)
>>> set_tolerances(0.1)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |      3.000038 |
|   2 |         3.6 |      3.000204 |
|   3 |         3.7 |      3.001106 |
|   4 |         3.8 |      3.005923 |
|   5 |         3.9 |          3.03 |
|   6 |         4.0 |      3.122948 |
|   7 |         4.1 |          3.33 |
|   8 |         4.2 |      3.605923 |
|   9 |         4.3 |      3.901106 |
|  10 |         4.4 |      4.200201 |
|  11 |         4.5 |           4.5 |
|  12 |         4.6 |      4.799799 |
|  13 |         4.7 |      5.098895 |
|  14 |         4.8 |      5.394139 |
|  15 |         4.9 |        5.6733 |
|  16 |         5.0 |           6.0 |
|  17 |         5.1 |        5.9997 |
|  18 |         5.2 |      5.999999 |
|  19 |         5.3 |           6.0 |
|  20 |         5.4 |           6.0 |
|  21 |         5.5 |           6.0 |
|  22 |         5.6 |           6.0 |
|  23 |         5.7 |           6.0 |
|  24 |         5.8 |           6.0 |
|  25 |         5.9 |           6.0 |
|  26 |         6.0 |           6.0 |
|  27 |         6.1 |           6.0 |
|  28 |         6.2 |           6.0 |
|  29 |         6.3 |           6.0 |
|  30 |         6.4 |           6.0 |
|  31 |         6.5 |           6.0 |

Maximum release smaller than minimum release, without smoothing, with interpolation:

>>> aides.alloweddischarge = 1.0
>>> set_tolerances(0.0)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |           3.0 |
|   2 |         3.6 |           3.0 |
|   3 |         3.7 |           3.0 |
|   4 |         3.8 |           3.0 |
|   5 |         3.9 |           3.0 |
|   6 |         4.0 |           3.0 |
|   7 |         4.1 |           3.0 |
|   8 |         4.2 |           3.0 |
|   9 |         4.3 |           3.0 |
|  10 |         4.4 |           3.0 |
|  11 |         4.5 |           3.0 |
|  12 |         4.6 |           3.0 |
|  13 |         4.7 |           3.0 |
|  14 |         4.8 |           3.0 |
|  15 |         4.9 |           3.0 |
|  16 |         5.0 |           3.0 |
|  17 |         5.1 |           3.0 |
|  18 |         5.2 |           3.0 |
|  19 |         5.3 |           3.0 |
|  20 |         5.4 |           3.0 |
|  21 |         5.5 |           3.0 |
|  22 |         5.6 |           3.0 |
|  23 |         5.7 |           3.0 |
|  24 |         5.8 |           3.0 |
|  25 |         5.9 |           3.0 |
|  26 |         6.0 |           3.0 |
|  27 |         6.1 |           3.0 |
|  28 |         6.2 |           3.0 |
|  29 |         6.3 |           3.0 |
|  30 |         6.4 |           3.0 |
|  31 |         6.5 |           3.0 |

Maximum release smaller than minimum release, moderate smoothing, with interpolation:

>>> aides.alloweddischarge = 1.0
>>> set_tolerances(0.1)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |         3.5 |      3.000001 |
|   2 |         3.6 |      3.000003 |
|   3 |         3.7 |      3.000015 |
|   4 |         3.8 |      3.000081 |
|   5 |         3.9 |       3.00041 |
|   6 |         4.0 |       3.00168 |
|   7 |         4.1 |      3.004508 |
|   8 |         4.2 |      3.008277 |
|   9 |         4.3 |       3.01231 |
|  10 |         4.4 |      3.016396 |
|  11 |         4.5 |      3.020491 |
|  12 |         4.6 |      3.024587 |
|  13 |         4.7 |      3.028673 |
|  14 |         4.8 |      3.032702 |
|  15 |         4.9 |       3.03611 |
|  16 |         5.0 |      3.040983 |
|  17 |         5.1 |      3.000406 |
|  18 |         5.2 |      3.000004 |
|  19 |         5.3 |           3.0 |
|  20 |         5.4 |           3.0 |
|  21 |         5.5 |           3.0 |
|  22 |         5.6 |           3.0 |
|  23 |         5.7 |           3.0 |
|  24 |         5.8 |           3.0 |
|  25 |         5.9 |           3.0 |
|  26 |         6.0 |           3.0 |
|  27 |         6.1 |           3.0 |
|  28 |         6.2 |           3.0 |
|  29 |         6.3 |           3.0 |
|  30 |         6.4 |           3.0 |
|  31 |         6.5 |           3.0 |

>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualrelease_v3,
...                 last_example=21,
...                 parseqs=(states.watervolume,
...                          fluxes.actualrelease))
>>> test.nexts.watervolume = numpy.arange(-0.5, 1.6, 0.1)
>>> model.idx_sim = pub.timegrids.init["2001-04-01"]
>>> fluxes.inflow = 0.0

Zero values, without smoothing, with interpolation:

>>> set_tolerances(0.0)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |        -0.5 |           0.0 |
|   2 |        -0.4 |           0.0 |
|   3 |        -0.3 |           0.0 |
|   4 |        -0.2 |           0.0 |
|   5 |        -0.1 |           0.0 |
|   6 |         0.0 |           0.0 |
|   7 |         0.1 |           1.0 |
|   8 |         0.2 |           1.0 |
|   9 |         0.3 |           1.0 |
|  10 |         0.4 |           1.0 |
|  11 |         0.5 |           1.0 |
|  12 |         0.6 |           1.0 |
|  13 |         0.7 |           1.0 |
|  14 |         0.8 |           1.0 |
|  15 |         0.9 |           1.0 |
|  16 |         1.0 |           1.0 |
|  17 |         1.1 |           1.0 |
|  18 |         1.2 |           1.0 |
|  19 |         1.3 |           1.0 |
|  20 |         1.4 |           1.0 |
|  21 |         1.5 |           1.0 |

Zero values, moderate smoothing, with interpolation:

>>> set_tolerances(0.1)
>>> apply_targetrange(True)
>>> test()
| ex. | watervolume | actualrelease |
-------------------------------------
|   1 |        -0.5 |           0.0 |
|   2 |        -0.4 |           0.0 |
|   3 |        -0.3 |           0.0 |
|   4 |        -0.2 |      0.000004 |
|   5 |        -0.1 |       0.00042 |
|   6 |         0.0 |      0.032478 |
|   7 |         0.1 |      0.941985 |
|   8 |         0.2 |        0.9998 |
|   9 |         0.3 |      0.999998 |
|  10 |         0.4 |           1.0 |
|  11 |         0.5 |           1.0 |
|  12 |         0.6 |           1.0 |
|  13 |         0.7 |           1.0 |
|  14 |         0.8 |           1.0 |
|  15 |         0.9 |           1.0 |
|  16 |         1.0 |           1.0 |
|  17 |         1.1 |           1.0 |
|  18 |         1.2 |           1.0 |
|  19 |         1.3 |           1.0 |
|  20 |         1.4 |           1.0 |
|  21 |         1.5 |           1.0 |

class hydpy.models.dam.dam_model.Calc_MissingRemoteRelease_V1[source]¶

Bases: Method

Calculate the portion of the required remote demand that could not be met by the actual discharge release.

Requires the flux sequences:
ActualRelease RequiredRemoteRelease

Calculates the flux sequence:
MissingRemoteRelease

Basic equation:: \(MissingRemoteRelease = max( RequiredRemoteRelease-ActualRelease, 0)\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.requiredremoterelease = 2.0
>>> fluxes.actualrelease = 1.0
>>> model.calc_missingremoterelease_v1()
>>> fluxes.missingremoterelease
missingremoterelease(1.0)
>>> fluxes.actualrelease = 3.0
>>> model.calc_missingremoterelease_v1()
>>> fluxes.missingremoterelease
missingremoterelease(0.0)

class hydpy.models.dam.dam_model.Calc_ActualRemoteRelease_V1[source]¶

Bases: Method

Calculate the actual remote water release that can be supplied by the dam considering the required remote release and the given water level.

Requires the control parameter:
WaterLevelMinimumRemoteThreshold

Requires the derived parameter:
WaterLevelMinimumRemoteSmoothPar

Requires the factor sequence:
WaterLevel

Requires the flux sequence:
RequiredRemoteRelease

Calculates the flux sequence:
ActualRemoteRelease

Used auxiliary method:: smooth_logistic1()
Basic equation:: \(ActualRemoteRelease = RequiredRemoteRelease \cdot smooth_{logistic1}(WaterLevelMinimumRemoteThreshold-WaterLevel, WaterLevelMinimumRemoteSmoothPar)\)

Examples:

Note that method Calc_ActualRemoteRelease_V1 is functionally identical to method Calc_ActualRelease_V1. This is why we omit to explain the following examples, as they are just repetitions of the ones of method Calc_ActualRemoteRelease_V1 with partly different variable names. Please follow the links to read the corresponding explanations.

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.requiredremoterelease = 2.0
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_actualremoterelease_v1,
...                 last_example=7,
...                 parseqs=(factors.waterlevel,
...                          fluxes.actualremoterelease))
>>> test.nexts.waterlevel = range(-1, 6)

Recalculation of example 1

>>> waterlevelminimumremotethreshold(0.)
>>> waterlevelminimumremotetolerance(0.)
>>> derived.waterlevelminimumremotesmoothpar.update()
>>> test()
| ex. | waterlevel | actualremoterelease |
------------------------------------------
|   1 |       -1.0 |                 0.0 |
|   2 |        0.0 |                 1.0 |
|   3 |        1.0 |                 2.0 |
|   4 |        2.0 |                 2.0 |
|   5 |        3.0 |                 2.0 |
|   6 |        4.0 |                 2.0 |
|   7 |        5.0 |                 2.0 |

Recalculation of example 2

>>> waterlevelminimumremotethreshold(4.)
>>> waterlevelminimumremotetolerance(1.)
>>> derived.waterlevelminimumremotesmoothpar.update()
>>> test()
| ex. | waterlevel | actualremoterelease |
------------------------------------------
|   1 |       -1.0 |                 0.0 |
|   2 |        0.0 |                 0.0 |
|   3 |        1.0 |            0.000002 |
|   4 |        2.0 |            0.000204 |
|   5 |        3.0 |                0.02 |
|   6 |        4.0 |                 1.0 |
|   7 |        5.0 |                1.98 |

Recalculation of example 3

>>> waterlevelminimumremotethreshold(1.)
>>> waterlevelminimumremotetolerance(2.)
>>> derived.waterlevelminimumremotesmoothpar.update()
>>> test()
| ex. | waterlevel | actualremoterelease |
------------------------------------------
|   1 |       -1.0 |                0.02 |
|   2 |        0.0 |             0.18265 |
|   3 |        1.0 |                 1.0 |
|   4 |        2.0 |             1.81735 |
|   5 |        3.0 |                1.98 |
|   6 |        4.0 |            1.997972 |
|   7 |        5.0 |            1.999796 |

class hydpy.models.dam.dam_model.Update_ActualRemoteRelief_V1[source]¶

Bases: Method

Constrain the actual relief discharge to a remote location.

Requires the control parameter:
HighestRemoteDischarge

Requires the derived parameter:
HighestRemoteSmoothPar

Updates the flux sequence:
ActualRemoteRelief

Used additional method:: Fix_Min1_V1
Basic equation - discontinous:: \(ActualRemoteRelief = min(ActualRemoteRelease, HighestRemoteDischarge)\)
Basic equation - continous:: \(ActualRemoteRelief = smooth_min1(ActualRemoteRelief, HighestRemoteDischarge, HighestRemoteSmoothPar)\)

Examples:

Prepare a dam model:

>>> from hydpy.models.dam import *
>>> parameterstep()

Prepare a test function object that performs eight examples with ActualRemoteRelief ranging from 0 to 8 m³/s and a fixed initial value of parameter HighestRemoteDischarge of 4 m³/s:

>>> highestremotedischarge(4.0)
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.update_actualremoterelief_v1,
...                 last_example=8,
...                 parseqs=(fluxes.actualremoterelief,))
>>> test.nexts.actualremoterelief = range(8)

Through setting the value of HighestRemoteTolerance to the lowest possible value, there is no smoothing. Instead, the shown relationship agrees with a combination of the discontinuous minimum and maximum function:

>>> highestremotetolerance(0.0)
>>> derived.highestremotesmoothpar.update()
>>> test()
| ex. | actualremoterelief |
----------------------------
|   1 |                0.0 |
|   2 |                1.0 |
|   3 |                2.0 |
|   4 |                3.0 |
|   5 |                4.0 |
|   6 |                4.0 |
|   7 |                4.0 |
|   8 |                4.0 |

Setting a sensible HighestRemoteTolerance value results in a moderate smoothing:

>>> highestremotetolerance(0.1)
>>> derived.highestremotesmoothpar.update()
>>> test()
| ex. | actualremoterelief |
----------------------------
|   1 |                0.0 |
|   2 |           0.999999 |
|   3 |            1.99995 |
|   4 |           2.996577 |
|   5 |           3.836069 |
|   6 |           3.991578 |
|   7 |           3.993418 |
|   8 |           3.993442 |

class hydpy.models.dam.dam_model.Update_ActualRemoteRelease_V1[source]¶

Bases: Method

Constrain the actual release (supply discharge) to a remote location.

Requires the control parameter:
HighestRemoteDischarge

Requires the derived parameter:
HighestRemoteSmoothPar

Requires the flux sequence:
ActualRemoteRelief

Updates the flux sequence:
ActualRemoteRelease

Used additional method:: Fix_Min1_V1
Basic equation - discontinous:: \(ActualRemoteRelease = min(ActualRemoteRelease, HighestRemoteDischarge - ActualRemoteRelief)\)
Basic equation - continous:: \(ActualRemoteRelease = smooth_min1(ActualRemoteRelease, HighestRemoteDischarge - ActualRemoteRelief, HighestRemoteSmoothPar)\)

Examples:

Prepare a dam model:
>>> from hydpy.models.dam import *
>>> parameterstep()
Prepare a test function object that performs eight examples with ActualRemoteRelief ranging from 0 to 8 m³/s and a fixed initial value of parameter ActualRemoteRelease of 2 m³/s:
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.update_actualremoterelease_v1,
...                 last_example=8,
...                 parseqs=(fluxes.actualremoterelief,
...                          fluxes.actualremoterelease))
>>> test.nexts.actualremoterelief = range(8)
>>> test.inits.actualremoterelease = 2.0
Through setting the value of HighestRemoteTolerance to the lowest possible value, there is no smoothing. Instead, the shown relationship agrees with a combination of the discontinuous minimum and maximum function:
>>> highestremotedischarge(6.0)
>>> highestremotetolerance(0.0)
>>> derived.highestremotesmoothpar.update()
>>> test()
| ex. | actualremoterelief | actualremoterelease |
--------------------------------------------------
|   1 |                0.0 |                 2.0 |
|   2 |                1.0 |                 2.0 |
|   3 |                2.0 |                 2.0 |
|   4 |                3.0 |                 2.0 |
|   5 |                4.0 |                 2.0 |
|   6 |                5.0 |                 1.0 |
|   7 |                6.0 |                 0.0 |
|   8 |                7.0 |                 0.0 |
Setting a sensible HighestRemoteTolerance value results in a moderate smoothing. But note that this is only true for the minimum function (restricting the larger ActualRemoteRelease values). Instead of smoothing the maximum function as well, ActualRemoteRelease is exactly 0 m³/s for a ActualRemoteRelief value of 6 m³/s (within the shown precision). The remaining discontinuity does not pose a problem, as long ActualRemoteRelief does not exceed the value of HighestRemoteDischarge. (Application models using method Update_ActualRemoteRelease_V1 should generally enforce this restriction). In case of exceedance, extended computation times might occur:
>>> highestremotetolerance(0.1)
>>> derived.highestremotesmoothpar.update()
>>> test()
| ex. | actualremoterelief | actualremoterelease |
--------------------------------------------------
|   1 |                0.0 |            1.999996 |
|   2 |                1.0 |            1.999925 |
|   3 |                2.0 |            1.998739 |
|   4 |                3.0 |            1.979438 |
|   5 |                4.0 |            1.754104 |
|   6 |                5.0 |            0.976445 |
|   7 |                6.0 |                 0.0 |
|   8 |                7.0 |                 0.0 |

class hydpy.models.dam.dam_model.Calc_FloodDischarge_V1[source]¶

Bases: Method

Calculate the discharge during and after a flood event based on seasonally varying interpolation approaches approximating the relationship(s) between discharge and water stage.

Requires the control parameter:
WaterLevel2FloodDischarge

Requires the derived parameter:
TOY

Requires the factor sequence:
WaterLevel

Calculates the flux sequence:
FloodDischarge

Example:

The control parameter WaterLevel2FloodDischarge is derived from SeasonalInterpolator. This allows to simulate different seasonal dam control schemes. To show that the seasonal selection mechanism is implemented properly, we define a short simulation period of three days:

>>> from hydpy import pub
>>> pub.timegrids = "2001.01.01", "2001.01.04", "1d"

Now we prepare a dam model and define two different relationships between water level and flood discharge using artificial neural networks as interpolators. The first relatively simple relationship (for January 2) is based on two neurons contained in a single hidden layer and is used in the following example. The second neural network (for January 3) is not applied at all, which is why we do not need to assign any parameter values to it:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevel2flooddischarge(
...     _01_02_12 = ANN(nmb_inputs=1,
...                     nmb_neurons=(2,),
...                     nmb_outputs=1,
...                     weights_input=[[50.0, 4]],
...                     weights_output=[[2.0], [30]],
...                     intercepts_hidden=[[-13000, -1046]],
...                     intercepts_output=[0.0]),
...     _01_03_12 = ANN(nmb_inputs=1,
...                     nmb_neurons=(2,),
...                     nmb_outputs=1))
>>> derived.toy.update()
>>> model.idx_sim = pub.timegrids.sim["2001.01.02"]

The following example shows two distinct effects of both neurons in the first network. One neuron describes a relatively sharp increase between 259.8 and 260.2 meters from about 0 to 2 m³/s. This could describe a release of water through a bottom outlet controlled by a valve. The add something like an exponential increase between 260 and 261 meters, which could describe the uncontrolled flow over a spillway:

>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.calc_flooddischarge_v1,
...                 last_example=21,
...                 parseqs=(factors.waterlevel,
...                          fluxes.flooddischarge))
>>> test.nexts.waterlevel = numpy.arange(257, 261.1, 0.2)
>>> test()
| ex. | waterlevel | flooddischarge |
-------------------------------------
|   1 |      257.0 |            0.0 |
|   2 |      257.2 |       0.000001 |
|   3 |      257.4 |       0.000002 |
|   4 |      257.6 |       0.000005 |
|   5 |      257.8 |       0.000011 |
|   6 |      258.0 |       0.000025 |
|   7 |      258.2 |       0.000056 |
|   8 |      258.4 |       0.000124 |
|   9 |      258.6 |       0.000275 |
|  10 |      258.8 |       0.000612 |
|  11 |      259.0 |       0.001362 |
|  12 |      259.2 |       0.003031 |
|  13 |      259.4 |       0.006745 |
|  14 |      259.6 |       0.015006 |
|  15 |      259.8 |       0.033467 |
|  16 |      260.0 |       1.074179 |
|  17 |      260.2 |       2.164498 |
|  18 |      260.4 |       2.363853 |
|  19 |      260.6 |        2.79791 |
|  20 |      260.8 |       3.719725 |
|  21 |      261.0 |       5.576088 |

class hydpy.models.dam.dam_model.Calc_MaxForcedDischarge_V1[source]¶

Bases: Method

Approximate the currently highest possible forced water release through structures as pumps based on seasonally varying interpolation approaches that take the water level difference as input.

Requires the control parameter:
WaterLevelDifference2MaxForcedDischarge

Requires the derived parameter:
TOY

Requires the factor sequence:
WaterLevelDifference

Calculates the flux sequence:
MaxForcedDischarge

Examples:

We consider a simulation period of five days:

>>> from hydpy import pub
>>> pub.timegrids = "2001-01-01", "2001-01-06", "1d"

For the second day, the maximum possible discharge of 2 m³/s does not depend on the water level difference. For the fourth day, it is -4 m³/s for negative and 4 m³/s for positive water level differences:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterleveldifference2maxforceddischarge(
...     _01_02_12 = PPoly(Poly(x0=0.0, cs=[2.0])),
...     _01_04_12 = PPoly(Poly(x0=-2.0, cs=[-4.0]), Poly(x0=0.0, cs=[4.0]))
... )
>>> derived.toy.update()

All results are as expected:

>>> model.idx_sim = pub.timegrids.sim["2001-01-02"]
>>> factors.waterleveldifference = -1.0
>>> model.calc_maxforceddischarge_v1()
>>> fluxes.maxforceddischarge
maxforceddischarge(2.0)

>>> model.idx_sim = pub.timegrids.sim["2001-01-03"]
>>> model.calc_maxforceddischarge_v1()
>>> fluxes.maxforceddischarge
maxforceddischarge(-1.0)

>>> model.idx_sim = pub.timegrids.sim["2001-01-04"]
>>> factors.waterleveldifference = 1.0
>>> model.calc_maxforceddischarge_v1()
>>> fluxes.maxforceddischarge
maxforceddischarge(4.0)

class hydpy.models.dam.dam_model.Calc_MaxFreeDischarge_V1[source]¶

Bases: Method

Approximate the currently highest possible free water release through structures as sluices based on seasonally varying interpolation approaches that take the water level difference as input.

Requires the control parameter:
WaterLevelDifference2MaxFreeDischarge

Requires the derived parameter:
TOY

Requires the factor sequence:
EffectiveWaterLevelDifference

Calculates the flux sequence:
MaxFreeDischarge

Examples:

We consider a simulation period of five days:

>>> from hydpy import pub
>>> pub.timegrids = "2001-01-01", "2001-01-06", "1d"

For the second day, the maximum possible discharge is 2 m³/s does not depend on the water level difference. For the fourth day, it is -4 m³/s for negative and 4 m³/s for positive water level differences:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterleveldifference2maxfreedischarge(
...     _01_02_12 = PPoly(Poly(x0=0.0, cs=[2.0])),
...     _01_04_12 = PPoly(Poly(x0=-2.0, cs=[-4.0]), Poly(x0=0.0, cs=[4.0]))
... )
>>> derived.toy.update()

All results are as expected:

>>> model.idx_sim = pub.timegrids.sim["2001-01-02"]
>>> factors.effectivewaterleveldifference = -1.0
>>> model.calc_maxfreedischarge_v1()
>>> fluxes.maxfreedischarge
maxfreedischarge(2.0)

>>> model.idx_sim = pub.timegrids.sim["2001-01-03"]
>>> model.calc_maxfreedischarge_v1()
>>> fluxes.maxfreedischarge
maxfreedischarge(-1.0)

>>> model.idx_sim = pub.timegrids.sim["2001-01-04"]
>>> factors.effectivewaterleveldifference = 1.0
>>> model.calc_maxfreedischarge_v1()
>>> fluxes.maxfreedischarge
maxfreedischarge(4.0)

class hydpy.models.dam.dam_model.Calc_ForcedDischarge_V1[source]¶

Bases: Method

Calculate the actual forced water release through structures as pumps to prevent a too-high inner water level if a maximum water level at a remote location is not violated.

Requires the control parameters:
WaterLevelMaximumThreshold RemoteWaterLevelMaximumThreshold

Requires the derived parameters:
WaterLevelMaximumSmoothPar RemoteWaterLevelMaximumSmoothPar

Requires the factor sequences:
WaterLevel RemoteWaterLevel

Requires the flux sequence:
MaxForcedDischarge

Calculates the flux sequence:
ForcedDischarge

In the case of a negative value for MaxForcedDischarge (e.g. the simulation of irrigation processes), the inner water level will be kept higher than a minimum level if the remote water level is higher than WaterLevelMaximumThreshold.

Basic equation:: \[\begin{split}ForcedDischarge = \begin{cases} MaxForcedDischarge \cdot (1 - r_1) \cdot r_2, & | MaxForcedDischarge < 0 \\ MaxForcedDischarge \cdot r_1 \cdot (1 - r_2), & | MaxForcedDischarge \geq 0 \end{cases} \\ \\ r_1 = f_{smooth \, logistic1}(WaterLevel - WaterLevelMaximumThreshold, \, WaterLevelMaximumSmoothPar) \\ r_2 = f_{smooth \, logistic1}(RemoteWaterLevel - RemoteWaterLevelMaximumThreshold, \, RemoteWaterLevelMaximumSmoothPar)\end{split}\]
Used auxiliary method:: smooth_logistic1()

Examples:

First, we prepare a UnitTest object to illustrate how the actual forced discharge depends on the inner and the remote water level:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.maxforceddischarge = 2.0
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_forceddischarge_v1,
...                 last_example=21,
...                 parseqs=(factors.waterlevel,
...                          factors.remotewaterlevel,
...                          fluxes.forceddischarge))
>>> test.nexts.waterlevel = numpy.linspace(2.95, 3.15, 21)
>>> test.nexts.remotewaterlevel = numpy.linspace(4.85, 5.05, 21)

When setting WaterLevelMaximumTolerance and RemoteWaterLevelMaximumTolerance to zero, there is a discontinuous increase from zero to MaxForcedDischarge around WaterLevelMaximumThreshold and a discontinuous decrease back to zero around RemoteWaterLevelMaximumThreshold:

>>> waterlevelmaximumthreshold(3.0)
>>> waterlevelmaximumtolerance(0.0)
>>> derived.waterlevelmaximumsmoothpar.update()
>>> remotewaterlevelmaximumthreshold(5.0)
>>> remotewaterlevelmaximumtolerance(0.0)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> test()
| ex. | waterlevel | remotewaterlevel | forceddischarge |
---------------------------------------------------------
|   1 |       2.95 |             4.85 |             0.0 |
|   2 |       2.96 |             4.86 |             0.0 |
|   3 |       2.97 |             4.87 |             0.0 |
|   4 |       2.98 |             4.88 |             0.0 |
|   5 |       2.99 |             4.89 |             0.0 |
|   6 |        3.0 |              4.9 |             1.0 |
|   7 |       3.01 |             4.91 |             2.0 |
|   8 |       3.02 |             4.92 |             2.0 |
|   9 |       3.03 |             4.93 |             2.0 |
|  10 |       3.04 |             4.94 |             2.0 |
|  11 |       3.05 |             4.95 |             2.0 |
|  12 |       3.06 |             4.96 |             2.0 |
|  13 |       3.07 |             4.97 |             2.0 |
|  14 |       3.08 |             4.98 |             2.0 |
|  15 |       3.09 |             4.99 |             2.0 |
|  16 |        3.1 |              5.0 |             1.0 |
|  17 |       3.11 |             5.01 |             0.0 |
|  18 |       3.12 |             5.02 |             0.0 |
|  19 |       3.13 |             5.03 |             0.0 |
|  20 |       3.14 |             5.04 |             0.0 |
|  21 |       3.15 |             5.05 |             0.0 |

For more natural transitions (and in the case of WaterLevelMaximumTolerance, also for computational efficiency), it is preferable to define tolerance values larger than zero. We set WaterLevelMaximumTolerance to 15 mm and RemoteWaterLevelMaximumTolerance to 10 mm:

>>> waterlevelmaximumtolerance(0.015)
>>> derived.waterlevelmaximumsmoothpar.update()
>>> remotewaterlevelmaximumtolerance(0.01)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> test()
| ex. | waterlevel | remotewaterlevel | forceddischarge |
---------------------------------------------------------
|   1 |       2.95 |             4.85 |             0.0 |
|   2 |       2.96 |             4.86 |         0.00001 |
|   3 |       2.97 |             4.87 |        0.000204 |
|   4 |       2.98 |             4.88 |        0.004357 |
|   5 |       2.99 |             4.89 |        0.089284 |
|   6 |        3.0 |              4.9 |             1.0 |
|   7 |       3.01 |             4.91 |        1.910716 |
|   8 |       3.02 |             4.92 |        1.995643 |
|   9 |       3.03 |             4.93 |        1.999796 |
|  10 |       3.04 |             4.94 |         1.99999 |
|  11 |       3.05 |             4.95 |             2.0 |
|  12 |       3.06 |             4.96 |             2.0 |
|  13 |       3.07 |             4.97 |        1.999998 |
|  14 |       3.08 |             4.98 |        1.999796 |
|  15 |       3.09 |             4.99 |            1.98 |
|  16 |        3.1 |              5.0 |             1.0 |
|  17 |       3.11 |             5.01 |            0.02 |
|  18 |       3.12 |             5.02 |        0.000204 |
|  19 |       3.13 |             5.03 |        0.000002 |
|  20 |       3.14 |             5.04 |             0.0 |
|  21 |       3.15 |             5.05 |             0.0 |

When MaxForcedDischarge is negative, the flow direction is reversed. Forced discharge will start when the RemoteWaterLevelMaximumThreshold is higher than 4.9 and drop to zero as soon as the WaterLevelMaximumThreshold is reached.

>>> fluxes.maxforceddischarge = -2.0
>>> waterlevelmaximumthreshold(3.1)
>>> remotewaterlevelmaximumthreshold(4.9)
>>> test()
| ex. | waterlevel | remotewaterlevel | forceddischarge |
---------------------------------------------------------
|   1 |       2.95 |             4.85 |             0.0 |
|   2 |       2.96 |             4.86 |             0.0 |
|   3 |       2.97 |             4.87 |       -0.000002 |
|   4 |       2.98 |             4.88 |       -0.000204 |
|   5 |       2.99 |             4.89 |           -0.02 |
|   6 |        3.0 |              4.9 |            -1.0 |
|   7 |       3.01 |             4.91 |           -1.98 |
|   8 |       3.02 |             4.92 |       -1.999796 |
|   9 |       3.03 |             4.93 |       -1.999998 |
|  10 |       3.04 |             4.94 |            -2.0 |
|  11 |       3.05 |             4.95 |            -2.0 |
|  12 |       3.06 |             4.96 |        -1.99999 |
|  13 |       3.07 |             4.97 |       -1.999796 |
|  14 |       3.08 |             4.98 |       -1.995643 |
|  15 |       3.09 |             4.99 |       -1.910716 |
|  16 |        3.1 |              5.0 |            -1.0 |
|  17 |       3.11 |             5.01 |       -0.089284 |
|  18 |       3.12 |             5.02 |       -0.004357 |
|  19 |       3.13 |             5.03 |       -0.000204 |
|  20 |       3.14 |             5.04 |        -0.00001 |
|  21 |       3.15 |             5.05 |             0.0 |

class hydpy.models.dam.dam_model.Calc_FreeDischarge_V1[source]¶

Bases: Method

Calculate the actual water flow through a hydraulic structure like a (flap) sluice that generally depends on the water level gradient but can be suppressed to stop releasing water if a maximum water level at a remote location is violated.

Requires the control parameter:
RemoteWaterLevelMaximumThreshold

Requires the derived parameters:
RemoteWaterLevelMaximumSmoothPar DischargeSmoothPar

Requires the factor sequence:
RemoteWaterLevel

Requires the flux sequence:
MaxFreeDischarge

Calculates the flux sequence:
FreeDischarge

Basic equation:: \[\begin{split}FreeDischarge = \omega \cdot q_{trimmed} + (1 - \omega) \cdot MaxFreeDischarge \\ \\ \omega = f_{smooth \, logistic1}(RemoteWaterLevelMaximumThreshold - RemoteWaterLevel, \, RemoteWaterLevelMaximumSmoothPar) \\ \\ q_{trimmed} = -f_{smooth \, logistic2}(MaxFreeDischarge, \, DischargeSmoothPar)\end{split}\]
Used auxiliary methods:: smooth_logistic1() smooth_logistic2()

Examples:

First, we prepare a UnitTest object to illustrate how the actual free discharge depends on the possible free discharge and the remote water level:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.maxfreedischarge = 2.0
>>> from hydpy import UnitTest
>>> test = UnitTest(model, model.calc_freedischarge_v1,
...                 last_example=21,
...                 parseqs=(factors.remotewaterlevel,
...                          fluxes.maxfreedischarge,
...                          fluxes.freedischarge))

We constantly decrease MaxFreeDischarge and increase RemoteWaterLevel between successive examples:

>>> test.nexts.maxfreedischarge = numpy.linspace(0.15, -0.05, 21)
>>> test.nexts.remotewaterlevel = numpy.linspace(4.95, 5.15, 21)

In the first two experiments, the remote water level overshoots its threshold while the possible discharge is still positive:

>>> remotewaterlevelmaximumthreshold(5.0)

When setting RemoteWaterLevelMaximumTolerance and DischargeTolerance to zero, the actual discharge drops suddenly to zero when the remote water level reaches RemoteWaterLevelMaximumThreshold and stays there until the possible discharge becomes negative:

>>> remotewaterlevelmaximumtolerance(0.0)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> dischargetolerance(0.0)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | remotewaterlevel | maxfreedischarge | freedischarge |
-------------------------------------------------------------
|   1 |             4.95 |             0.15 |          0.15 |
|   2 |             4.96 |             0.14 |          0.14 |
|   3 |             4.97 |             0.13 |          0.13 |
|   4 |             4.98 |             0.12 |          0.12 |
|   5 |             4.99 |             0.11 |          0.11 |
|   6 |              5.0 |              0.1 |          0.05 |
|   7 |             5.01 |             0.09 |           0.0 |
|   8 |             5.02 |             0.08 |           0.0 |
|   9 |             5.03 |             0.07 |           0.0 |
|  10 |             5.04 |             0.06 |           0.0 |
|  11 |             5.05 |             0.05 |           0.0 |
|  12 |             5.06 |             0.04 |           0.0 |
|  13 |             5.07 |             0.03 |           0.0 |
|  14 |             5.08 |             0.02 |           0.0 |
|  15 |             5.09 |             0.01 |           0.0 |
|  16 |              5.1 |              0.0 |           0.0 |
|  17 |             5.11 |            -0.01 |         -0.01 |
|  18 |             5.12 |            -0.02 |         -0.02 |
|  19 |             5.13 |            -0.03 |         -0.03 |
|  20 |             5.14 |            -0.04 |         -0.04 |
|  21 |             5.15 |            -0.05 |         -0.05 |

For more natural transitions (and in the case of DischargeTolerance, also for computational efficiency), defining tolerance values larger than zero is preferable. We set RemoteWaterLevelMaximumTolerance to 10 mm and DischargeTolerance to 0.01 m³/s:

>>> remotewaterlevelmaximumtolerance(0.01)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> dischargetolerance(0.01)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | remotewaterlevel | maxfreedischarge | freedischarge |
-------------------------------------------------------------
|   1 |             4.95 |             0.15 |          0.15 |
|   2 |             4.96 |             0.14 |          0.14 |
|   3 |             4.97 |             0.13 |          0.13 |
|   4 |             4.98 |             0.12 |      0.119988 |
|   5 |             4.99 |             0.11 |      0.108899 |
|   6 |              5.0 |              0.1 |      0.049916 |
|   7 |             5.01 |             0.09 |      0.000631 |
|   8 |             5.02 |             0.08 |     -0.000429 |
|   9 |             5.03 |             0.07 |     -0.000704 |
|  10 |             5.04 |             0.06 |     -0.001127 |
|  11 |             5.05 |             0.05 |     -0.001794 |
|  12 |             5.06 |             0.04 |      -0.00283 |
|  13 |             5.07 |             0.03 |     -0.004404 |
|  14 |             5.08 |             0.02 |     -0.006723 |
|  15 |             5.09 |             0.01 |         -0.01 |
|  16 |              5.1 |              0.0 |     -0.014404 |
|  17 |             5.11 |            -0.01 |         -0.02 |
|  18 |             5.12 |            -0.02 |     -0.026723 |
|  19 |             5.13 |            -0.03 |     -0.034404 |
|  20 |             5.14 |            -0.04 |      -0.04283 |
|  21 |             5.15 |            -0.05 |     -0.051794 |

In the following two experiments, we let MaxFreeDischarge reach 0 m³/s earlier and increase RemoteWaterLevelMaximumThreshold so that its violation occurs later:

>>> test.nexts.maxfreedischarge = numpy.linspace(0.05, -0.15, 21)
>>> remotewaterlevelmaximumthreshold(5.1)

Without smoothing, free discharge now strictly follows potential discharge:

>>> remotewaterlevelmaximumtolerance(0.0)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> dischargetolerance(0.0)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | remotewaterlevel | maxfreedischarge | freedischarge |
-------------------------------------------------------------
|   1 |             4.95 |             0.05 |          0.05 |
|   2 |             4.96 |             0.04 |          0.04 |
|   3 |             4.97 |             0.03 |          0.03 |
|   4 |             4.98 |             0.02 |          0.02 |
|   5 |             4.99 |             0.01 |          0.01 |
|   6 |              5.0 |              0.0 |           0.0 |
|   7 |             5.01 |            -0.01 |         -0.01 |
|   8 |             5.02 |            -0.02 |         -0.02 |
|   9 |             5.03 |            -0.03 |         -0.03 |
|  10 |             5.04 |            -0.04 |         -0.04 |
|  11 |             5.05 |            -0.05 |         -0.05 |
|  12 |             5.06 |            -0.06 |         -0.06 |
|  13 |             5.07 |            -0.07 |         -0.07 |
|  14 |             5.08 |            -0.08 |         -0.08 |
|  15 |             5.09 |            -0.09 |         -0.09 |
|  16 |              5.1 |             -0.1 |          -0.1 |
|  17 |             5.11 |            -0.11 |         -0.11 |
|  18 |             5.12 |            -0.12 |         -0.12 |
|  19 |             5.13 |            -0.13 |         -0.13 |
|  20 |             5.14 |            -0.14 |         -0.14 |
|  21 |             5.15 |            -0.15 |         -0.15 |

With smoothing, there is a slight deviation between potential and actual discharge:

ToDo: Is there a smoothing alternative that circumvents this deviation without: complicating the calculation too much? (low priority).

>>> remotewaterlevelmaximumtolerance(0.01)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> dischargetolerance(0.01)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | remotewaterlevel | maxfreedischarge | freedischarge |
-------------------------------------------------------------
|   1 |             4.95 |             0.05 |          0.05 |
|   2 |             4.96 |             0.04 |          0.04 |
|   3 |             4.97 |             0.03 |          0.03 |
|   4 |             4.98 |             0.02 |          0.02 |
|   5 |             4.99 |             0.01 |          0.01 |
|   6 |              5.0 |              0.0 |           0.0 |
|   7 |             5.01 |            -0.01 |         -0.01 |
|   8 |             5.02 |            -0.02 |         -0.02 |
|   9 |             5.03 |            -0.03 |         -0.03 |
|  10 |             5.04 |            -0.04 |         -0.04 |
|  11 |             5.05 |            -0.05 |         -0.05 |
|  12 |             5.06 |            -0.06 |         -0.06 |
|  13 |             5.07 |            -0.07 |         -0.07 |
|  14 |             5.08 |            -0.08 |         -0.08 |
|  15 |             5.09 |            -0.09 |     -0.090003 |
|  16 |              5.1 |             -0.1 |     -0.100084 |
|  17 |             5.11 |            -0.11 |     -0.110103 |
|  18 |             5.12 |            -0.12 |     -0.120064 |
|  19 |             5.13 |            -0.13 |      -0.13004 |
|  20 |             5.14 |            -0.14 |     -0.140025 |
|  21 |             5.15 |            -0.15 |     -0.150015 |

class hydpy.models.dam.dam_model.Calc_Outflow_V1[source]¶

Bases: Method

Calculate the total outflow of the dam.

Requires the flux sequences:
ActualRelease FloodDischarge

Calculates the flux sequence:
Outflow

Note that the maximum function is used to prevent from negative outflow values, which could otherwise occur within the required level of numerical accuracy.

Basic equation:: \(Outflow = max(ActualRelease + FloodDischarge, \, 0)\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.actualrelease = 2.0
>>> fluxes.flooddischarge = 3.0
>>> model.calc_outflow_v1()
>>> fluxes.outflow
outflow(5.0)
>>> fluxes.flooddischarge = -3.0
>>> model.calc_outflow_v1()
>>> fluxes.outflow
outflow(0.0)

class hydpy.models.dam.dam_model.Calc_AllowedDischarge_V1[source]¶

Bases: Method

Calculate the maximum discharge not leading to exceedance of the allowed water level drop.

Requires the control parameter:
AllowedWaterLevelDrop

Requires the derived parameter:
Seconds

Requires the flux sequences:
AdjustedPrecipitation ActualEvaporation Inflow Exchange

Requires the aide sequence:
SurfaceArea

Calculates the aide sequence:
AllowedDischarge

Basic equation:: \(Outflow = AllowedWaterLevelDrop \cdot SurfaceArea + Inflow + AdjustedPrecipitation - AdjustedEvaporation + Exchange\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep("1d")
>>> simulationstep("1h")
>>> allowedwaterleveldrop(0.1)
>>> derived.seconds.update()
>>> fluxes.adjustedprecipitation = 1.0
>>> fluxes.inflow = 3.0
>>> fluxes.actualevaporation = 2.0
>>> fluxes.exchange = 4.0
>>> aides.surfacearea = 0.864
>>> model.calc_alloweddischarge_v1()
>>> aides.alloweddischarge
alloweddischarge(7.0)

class hydpy.models.dam.dam_model.Calc_AllowedDischarge_V2[source]¶

Bases: Method

Calculate the maximum discharge not leading to exceedance of the allowed water level drop.

Requires the control parameters:
AllowedRelease AllowedWaterLevelDrop

Requires the derived parameters:
TOY Seconds DischargeSmoothPar

Requires the flux sequence:
Inflow

Requires the aide sequence:
SurfaceArea

Calculates the aide sequence:
AllowedDischarge

Used additional methods:: smooth_min1()
Basic (discontinuous) equation:: \(Outflow = min(AllowedRelease, AllowedWaterLevelDrop \cdot SurfaceArea + Inflow\)

Example:

>>> from hydpy import pub
>>> pub.timegrids = "2001.03.30", "2001.04.03", "1h"

>>> from hydpy.models.dam import *
>>> parameterstep("1d")

>>> allowedwaterleveldrop(0.1)
>>> allowedrelease(_11_01_12=1.0, _03_31_12=1.0,
...                _04_01_00=3.0, _04_02_00=3.0,
...                _04_02_12=5.0, _10_31_12=5.0)

>>> derived.seconds.update()
>>> derived.toy.update()

>>> aides.surfacearea = 0.864
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.calc_alloweddischarge_v2,
...                 last_example=7,
...                 parseqs=(fluxes.inflow,
...                          aides.alloweddischarge))
>>> import numpy
>>> test.nexts.inflow = 1.0, 1.5, 1.9, 2.0, 2.1, 2.5, 3.0

>>> model.idx_sim = pub.timegrids.init["2001-04-01"]

>>> dischargetolerance(0.0)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | inflow | alloweddischarge |
-----------------------------------
|   1 |    1.0 |              2.0 |
|   2 |    1.5 |              2.5 |
|   3 |    1.9 |              2.9 |
|   4 |    2.0 |              3.0 |
|   5 |    2.1 |              3.0 |
|   6 |    2.5 |              3.0 |
|   7 |    3.0 |              3.0 |

>>> dischargetolerance(0.1)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | inflow | alloweddischarge |
-----------------------------------
|   1 |    1.0 |              2.0 |
|   2 |    1.5 |         2.499987 |
|   3 |    1.9 |             2.89 |
|   4 |    2.0 |         2.959017 |
|   5 |    2.1 |             2.99 |
|   6 |    2.5 |         2.999987 |
|   7 |    3.0 |              3.0 |

class hydpy.models.dam.dam_model.Calc_AllowedWaterLevel_V1[source]¶

Bases: Method

Calculate the water level at the end of a simulation step that would follow from applying the allowed water level drop [m].

Requires the control parameters:
WaterVolume2WaterLevel AllowedWaterLevelDrop

Requires the state sequence:
WaterVolume

Calculates the aide sequence:
AllowedWaterLevel

Basic equation:: \[\begin{split}W_{min} = f_{V2W}(V) - D \\ \\ W_{min} = AllowedWaterLevel \\ f_{V2W} = WaterVolume2WaterLevel \\ D = AllowedWaterLevelDrop\end{split}\]

Examples:

>>> from hydpy.models.dam import *
>>> simulationstep("2d")
>>> parameterstep("1d")
>>> allowedwaterleveldrop(inf)
>>> model.calc_allowedwaterlevel_v1()
>>> aides.allowedwaterlevel
allowedwaterlevel(-inf)

>>> from hydpy import PPoly
>>> watervolume2waterlevel(PPoly.from_data([0.0, 1.0, 2.0], [1.0, 2.0, 4.0]))
>>> allowedwaterleveldrop(1.0)
>>> states.watervolume = 1.5
>>> model.calc_allowedwaterlevel_v1()
>>> aides.allowedwaterlevel
allowedwaterlevel(1.0)

class hydpy.models.dam.dam_model.Calc_AllowedDischarge_V3[source]¶

Bases: Method

Calculate the maximum discharge not leading to exceedance of the allowed water level drop.

Requires the derived parameter:
Seconds

Requires the flux sequences:
Inflow AdjustedPrecipitation AdjustedEvaporation

Requires the state sequence:
WaterVolume

Requires the aide sequence:
AllowedWaterLevel

Calculates the aide sequence:
AllowedDischarge

Basic equations:: \[ \begin{align}\begin{aligned}\begin{split}f_{V2W}(V_{min}) = W_{min} \\ V_{max} = V + s / 1e6 \cdot (I + P - E) \\ Q = 1e6 / s \cdot (V_{max} - V_{min})\end{split}\\\begin{split}\\ \\ f_{V2W} = WaterVolume2WaterLevel \\ W_{min} = AllowedWaterLevel \\ V = WaterVolume \\ s = Seconds \\ I = Inflow \\ P = AdjustedPrecipitation \\ E = AdjustedEvaporation \\ Q = AllowedDischarge\end{split}\end{aligned}\end{align} \]

Note that solving the potentially nonlinear equation \(f_{V2W}(V_{min}) = W_{min}\) relies on the Pegasus iteration method provided by the PegasusWaterVolume submodel.

Examples:

Without a water level restriction, the allowed discharge is also unrestricted:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> aides.allowedwaterlevel(-inf)
>>> model.calc_alloweddischarge_v3()
>>> aides.alloweddischarge
alloweddischarge(inf)

A simplified case without additional fluxes:

>>> from hydpy import PPoly
>>> watervolume2waterlevel(PPoly.from_data([0.0, 2.0, 4.0], [1.0, 3.0, 7.0]))
>>> derived.seconds(1e6)
>>> states.watervolume = 3.0
>>> aides.allowedwaterlevel = 2.0
>>> fluxes.inflow = 0.0
>>> fluxes.adjustedprecipitation = 0.0
>>> fluxes.adjustedevaporation = 0.0
>>> model.calc_alloweddischarge_v3()
>>> aides.alloweddischarge
alloweddischarge(2.0)

The same case but with additional fluxes:

>>> fluxes.inflow = 1.0
>>> fluxes.adjustedprecipitation = 2.0
>>> fluxes.adjustedevaporation = 4.0
>>> model.calc_alloweddischarge_v3()
>>> aides.alloweddischarge
alloweddischarge(1.0)

The resulting allowed discharge is never negative:

>>> fluxes.adjustedevaporation = 6.0
>>> model.calc_alloweddischarge_v3()
>>> aides.alloweddischarge
alloweddischarge(0.0)

>>> fluxes.adjustedevaporation = 4.0
>>> aides.allowedwaterlevel = 7.0
>>> model.calc_alloweddischarge_v3()
>>> aides.alloweddischarge
alloweddischarge(0.0)

class hydpy.models.dam.dam_model.Calc_SafeRelease_V1[source]¶

Bases: Method

Calculate the safe release as the minimum of the dam-specific allowed release and the values suggested by the safe release submodels.

Requires the control parameters:
NmbSafeReleaseModels AllowedRelease

Requires the derived parameter:
TOY

Calculates the flux sequence:
SafeRelease

Examples:

Without any safe release submodels involved, Calc_SafeRelease_V1 just determines the allowed release for the current time of the year:

>>> from hydpy import pub
>>> pub.timegrids = "2001-03-30", "2001-04-03", "1d"
>>> from hydpy.models.dam_detention import *
>>> parameterstep()
>>> allowedrelease(toy_03_31_12=2.0, toy_04_1_12=4.0)
>>> derived.toy.update()
>>> model.idx_sim = pub.timegrids.init["2001-03-31"]
>>> model.calc_saferelease_v1()
>>> fluxes.saferelease
saferelease(2.0)

>>> model.idx_sim = pub.timegrids.init["2001-04-01"]
>>> model.calc_saferelease_v1()
>>> fluxes.saferelease
saferelease(4.0)

With available safe release submodels, it searches for the lowest of all suggested release values:

>>> from hydpy import PPoly
>>> nmbsafereleasemodels(2)
>>> with model.add_safereleasemodel("exch_interp", position=0):
...     observernodes("gauge_1")
...     x2y(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 1.0]))
...     observers.x = 5.0
>>> with model.add_safereleasemodel("exch_interp", position=1):
...     observernodes("gauge_2")
...     x2y(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 1.0]))
...     observers.x = 6.0
>>> model.calc_saferelease_v1()
>>> fluxes.saferelease
saferelease(4.0)

>>> model.safereleasemodels[0].sequences.observers.x = 3.0
>>> model.calc_saferelease_v1()
>>> fluxes.saferelease
saferelease(3.0)

class hydpy.models.dam.dam_model.Calc_AimedRelease_WaterVolume_V1[source]¶

Bases: Method

Calculate the ideal controlled release and update the stored water volume.

Requires the control parameters:
TargetVolume MinimumRelease Commission

Requires the derived parameters:
Seconds TOY

Requires the flux sequence:
SafeRelease

Requires the aide sequence:
AllowedDischarge

Updates the state sequence:
WaterVolume

Calculates the flux sequence:
AimedRelease

Basic equation:: \[\begin{split}AimedRelease = \begin{cases} 0 &|& i_{sim} < i_{commission} \\ min \Big( max \big( 1e6 / s \cdot (V - T), \, M \big), \, S, \, D \Big) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ s = Seconds \\ V = WaterVolume \\ T = TargetVolume \\ M = MinimumRelease \\ S = SafeRelease \\ D = AllowedDischarge\end{split}\]

Examples:

As long as no restrictions apply, Calc_AimedRelease_WaterVolume_V1 releases enough water to reach the targeted volume in one simulation step:

>>> from hydpy import pub
>>> pub.timegrids = "2001-03-30", "2001-04-03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission("2001-03-30")
>>> targetvolume(toy_03_31_12=1.0, toy_04_01_12=3.0)
>>> minimumrelease(0.0)
>>> derived.seconds(1e6)
>>> derived.toy.update()
>>> fluxes.saferelease = inf
>>> aides.alloweddischarge = inf
>>> states.watervolume = 3.0
>>> model.idx_sim = pub.timegrids.init["2001-03-31"]
>>> model.calc_aimedrelease_watervolume_v1()
>>> fluxes.aimedrelease
aimedrelease(2.0)
>>> states.watervolume
watervolume(1.0)

Required minimum releases can cause the actual water volume to fall below the targeted volume:

>>> minimumrelease(1.0)
>>> states.watervolume = 3.0
>>> model.idx_sim = pub.timegrids.init["2001-04-01"]
>>> model.calc_aimedrelease_watervolume_v1()
>>> fluxes.aimedrelease
aimedrelease(1.0)
>>> states.watervolume
watervolume(2.0)

The total available water volume restricts the actual release:

>>> states.watervolume = 0.5
>>> model.calc_aimedrelease_watervolume_v1()
>>> fluxes.aimedrelease
aimedrelease(0.5)
>>> states.watervolume
watervolume(0.0)

The suggested “safe release” always caps the aimed release (the limited storage capacity becomes relevant when calculating the “unavoidable release):

>>> states.watervolume = 10.0
>>> fluxes.saferelease = 6.0
>>> model.calc_aimedrelease_watervolume_v1()
>>> fluxes.aimedrelease
aimedrelease(6.0)
>>> states.watervolume
watervolume(4.0)

The “allowed discharge” (which corresponds to the highest acceptable water level drop) restricts the release in the same manner:

>>> states.watervolume = 10.0
>>> aides.alloweddischarge = 4.0
>>> model.calc_aimedrelease_watervolume_v1()
>>> fluxes.aimedrelease
aimedrelease(4.0)
>>> states.watervolume
watervolume(6.0)

All previous examples assume that the modelled detention basin is already active. Before its commissioning, AimedRelease is generally zero and WaterVolume remains constant:

>>> commission("2001-04-02")
>>> model.calc_aimedrelease_watervolume_v1()
>>> fluxes.aimedrelease
aimedrelease(0.0)
>>> states.watervolume
watervolume(6.0)

class hydpy.models.dam.dam_model.Calc_UnavoidableRelease_WaterVolume_V1[source]¶

Bases: Method

Calculate the water release that cannot be avoided due to limited storage capacity and update the stored water volume.

Requires the control parameters:
MaximumVolume Commission

Requires the derived parameter:
Seconds

Requires the flux sequences:
Inflow AdjustedPrecipitation ActualEvaporation

Updates the state sequence:
WaterVolume

Calculates the flux sequence:
UnavoidableRelease

Basic equation:: \[\begin{split}UnavoidableRelease = \begin{cases} I + P - E &|& i_{sim} < i_{commission} \\ 1e6 / s \cdot (V - M) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ I = Inflow \\ P = AdjustedPrecipitation \\ E = ActualEvaporation \\ s = Seconds \\ V = WaterVolume \\ M = MaximumVolume\end{split}\]

Examples:

After the commission date, all water exceeding the available storage volume is released immediately:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission(0)
>>> maximumvolume(3.0)
>>> derived.seconds(1e6)
>>> states.watervolume = 5.0
>>> model.calc_unavoidablerelease_watervolume_v1()
>>> fluxes.unavoidablerelease
unavoidablerelease(2.0)
>>> states.watervolume
watervolume(3.0)

>>> states.watervolume = 2.0
>>> model.calc_unavoidablerelease_watervolume_v1()
>>> fluxes.unavoidablerelease
unavoidablerelease(0.0)
>>> states.watervolume
watervolume(2.0)

Before the commission date, the detention basin’s water volume remains unchanged. Hence, we calculate the outflow so that it closes the water balance accordingly:

>>> commission(1)
>>> fluxes.inflow = 4.0
>>> fluxes.adjustedprecipitation = 3.0
>>> fluxes.actualevaporation = 2.0
>>> model.calc_unavoidablerelease_watervolume_v1()
>>> fluxes.unavoidablerelease
unavoidablerelease(5.0)
>>> states.watervolume
watervolume(2.0)

class hydpy.models.dam.dam_model.Calc_Outflow_V2[source]¶

Bases: Method

Calculate the total outflow of the dam before and after the commission date, taking the allowed water discharge into account.

Requires the control parameter:
Commission

Requires the derived parameter:
DischargeSmoothPar

Requires the flux sequences:
Inflow Exchange AdjustedPrecipitation ActualEvaporation FloodDischarge

Requires the aide sequence:
AllowedDischarge

Calculates the flux sequence:
Outflow

Basic equation:: \[\begin{split}Outflow = \begin{cases} I + X + P - E &|& i_{sim} < i_{commission} \\ f(F, \, A, \, D) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ I = Inflow \\ X = Exchange \\ P = AdjustedPrecipitation \\ E = ActualEvaporation \\ f = smooth_{Fix\_Min1\_V1} \\ F = FloodDischarge \\ A = AllowedDischarge\\ D = DischargeSmoothPar\end{split}\]
Used additional method:: Fix_Min1_V1

Examples:

Before the commission date, the dam’s water volume should not change (neither increase nor decrease). Hence, we calculate the outflow so that it closes the water balance accordingly:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2001-01-01", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission("2000-01-02")
>>> fluxes.inflow = 1.0
>>> fluxes.exchange = 2.0
>>> fluxes.adjustedprecipitation = 3.0
>>> fluxes.actualevaporation = 4.0
>>> model.calc_outflow_v2()
>>> fluxes.outflow
outflow(2.0)

After the commission date, the final outflow is the (eventually smoothed) minimum of FloodDischarge and AllowedDischarge:

>>> commission("2000-01-01")
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.calc_outflow_v2,
...                 last_example=8,
...                 parseqs=(fluxes.flooddischarge,
...                          fluxes.outflow))
>>> test.nexts.flooddischarge = range(8)

>>> aides.alloweddischarge = 3.0

>>> dischargetolerance(0.0)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | flooddischarge | outflow |
----------------------------------
|   1 |            0.0 |     0.0 |
|   2 |            1.0 |     1.0 |
|   3 |            2.0 |     2.0 |
|   4 |            3.0 |     3.0 |
|   5 |            4.0 |     3.0 |
|   6 |            5.0 |     3.0 |
|   7 |            6.0 |     3.0 |
|   8 |            7.0 |     3.0 |

>>> dischargetolerance(1.0)
>>> derived.dischargesmoothpar.update()
>>> test()
| ex. | flooddischarge |  outflow |
-----------------------------------
|   1 |            0.0 |      0.0 |
|   2 |            1.0 | 0.999651 |
|   3 |            2.0 |     1.99 |
|   4 |            3.0 | 2.794476 |
|   5 |            4.0 | 2.985755 |
|   6 |            5.0 | 2.991603 |
|   7 |            6.0 | 2.991773 |
|   8 |            7.0 | 2.991779 |

>>> aides.alloweddischarge = 0.0
>>> test()
| ex. | flooddischarge | outflow |
----------------------------------
|   1 |            0.0 |     0.0 |
|   2 |            1.0 |     0.0 |
|   3 |            2.0 |     0.0 |
|   4 |            3.0 |     0.0 |
|   5 |            4.0 |     0.0 |
|   6 |            5.0 |     0.0 |
|   7 |            6.0 |     0.0 |
|   8 |            7.0 |     0.0 |

class hydpy.models.dam.dam_model.Calc_Outflow_V3[source]¶

Bases: Method

Take the forced discharge as the only outflow.

Requires the flux sequence:
ForcedDischarge

Calculates the flux sequence:
Outflow

Basic equation:: \(Outflow = ForcedDischaerge\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.forceddischarge = 2.0
>>> model.calc_outflow_v3()
>>> fluxes.outflow
outflow(2.0)

class hydpy.models.dam.dam_model.Calc_Outflow_V4[source]¶

Bases: Method

Take the free discharge as the only outflow.

Requires the flux sequence:
FreeDischarge

Calculates the flux sequence:
Outflow

Basic equation:: \(Outflow = FreeDischaerge\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.freedischarge = 2.0
>>> model.calc_outflow_v4()
>>> fluxes.outflow
outflow(2.0)

class hydpy.models.dam.dam_model.Calc_Outflow_V5[source]¶

Bases: Method

Calculate the total outflow as the sum of free and forced discharge.

Requires the flux sequences:
FreeDischarge ForcedDischarge

Calculates the flux sequence:
Outflow

Basic equation:: \(Outflow = FreeDischarge + ForcedDischarge\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.freedischarge = 2.0
>>> fluxes.forceddischarge = 3.0
>>> model.calc_outflow_v5()
>>> fluxes.outflow
outflow(5.0)

class hydpy.models.dam.dam_model.Calc_Outflow_V6[source]¶

Bases: Method

Calculate the outflow as the sum of the aimed and the unavoidable release.

Requires the flux sequences:
AimedRelease UnavoidableRelease

Updates the flux sequence:
Outflow

Basic equation:: \(Outflow = AimedRelease + UnavoidableRelease\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.aimedrelease = 1.0
>>> fluxes.unavoidablerelease = 2.0
>>> model.calc_outflow_v6()
>>> fluxes.outflow
outflow(3.0)

class hydpy.models.dam.dam_model.Calc_Outflow_V7[source]¶

Bases: Method

Calculate the total outflow of the dam before and after the commission date

Requires the control parameter:
Commission

Requires the flux sequences:
Inflow AdjustedPrecipitation ActualEvaporation ActualRelease FloodDischarge

Calculates the flux sequence:
Outflow

Basic equation:: \[\begin{split}Outflow = \begin{cases} I + P - E &|& i_{sim} < i_{commission} \\ max(R + F, \, 0) &|& i_{sim} \geq i_{commission} \end{cases} \\ \\ I = Inflow \\ P = AdjustedPrecipitation \\ E = ActualEvaporation \\ f = smooth_{Fix\_Min1\_V1} \\ R = AllowedDischarge\\ F = FloodDischarge\end{split}\]

Examples:

Before the commission date, the dam’s water volume should not change (neither increase nor decrease). Hence, we calculate the outflow so that it closes the water balance accordingly:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2001-01-01", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission("2000-01-02")
>>> fluxes.inflow = 2.0
>>> fluxes.adjustedprecipitation = 3.0
>>> fluxes.actualevaporation = 4.0
>>> model.calc_outflow_v7()
>>> fluxes.outflow
outflow(1.0)

After the commission date, the final outflow is the (never negative) sum of ActualRelease and FloodDischarge:

>>> commission("2000-01-01")
>>> fluxes.actualrelease = 2.0
>>> fluxes.flooddischarge = 3.0
>>> model.calc_outflow_v7()
>>> fluxes.outflow
outflow(5.0)

>>> fluxes.flooddischarge = -3.0
>>> model.calc_outflow_v7()
>>> fluxes.outflow
outflow(0.0)

class hydpy.models.dam.dam_model.Update_WaterVolume_V1[source]¶

Bases: Method

Update the actual water volume.

Requires the derived parameter:
Seconds

Requires the flux sequences:
AdjustedPrecipitation ActualEvaporation Inflow Outflow

Updates the state sequence:
WaterVolume

Basic equation:: \(\frac{d}{dt}WaterVolume = 1e-6 \cdot (AdjustedPrecipitation - AdjustedEvaporation - Inflow - Outflow)\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.seconds = 2e6
>>> states.watervolume.old = 5.0
>>> fluxes.adjustedprecipitation = 1.0
>>> fluxes.actualevaporation = 2.0
>>> fluxes.inflow = 3.0
>>> fluxes.outflow = 4.0
>>> model.update_watervolume_v1()
>>> states.watervolume
watervolume(1.0)

class hydpy.models.dam.dam_model.Update_WaterVolume_V2[source]¶

Bases: Method

Update the actual water volume.

Requires the derived parameter:
Seconds

Requires the flux sequences:
AdjustedPrecipitation ActualEvaporation Inflow Outflow ActualRemoteRelease

Updates the state sequence:
WaterVolume

Basic equation:: \(\frac{d}{dt}WaterVolume = 10^{-6} \cdot (AdjustedPrecipitation - AdjustedEvaporation - Inflow - Outflow - ActualRemoteRelease)\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.seconds = 2e6
>>> states.watervolume.old = 9.0
>>> fluxes.adjustedprecipitation = 2.0
>>> fluxes.actualevaporation = 1.0
>>> fluxes.inflow = 4.0
>>> fluxes.outflow = 3.0
>>> fluxes.actualremoterelease = 6.0
>>> model.update_watervolume_v2()
>>> states.watervolume
watervolume(1.0)

class hydpy.models.dam.dam_model.Update_WaterVolume_V3[source]¶

Bases: Method

Update the actual water volume.

Requires the derived parameter:
Seconds

Requires the flux sequences:
AdjustedPrecipitation ActualEvaporation Inflow Outflow ActualRemoteRelease ActualRemoteRelief

Updates the state sequence:
WaterVolume

Basic equation:: \(\frac{d}{dt}WaterVolume = 10^{-6} \cdot (AdjustedPrecipitation - AdjustedEvaporation + Inflow - Outflow - ActualRemoteRelease - ActualRemoteRelief)\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.seconds = 2e6
>>> states.watervolume.old = 6.0
>>> fluxes.adjustedprecipitation = 5.0
>>> fluxes.actualevaporation = 4.0
>>> fluxes.inflow = 2.0
>>> fluxes.outflow = 3.0
>>> fluxes.actualremoterelease = 1.0
>>> fluxes.actualremoterelief = 0.5
>>> model.update_watervolume_v3()
>>> states.watervolume
watervolume(3.0)

class hydpy.models.dam.dam_model.Update_WaterVolume_V4[source]¶

Bases: Method

Update the actual water volume.

Requires the derived parameter:
Seconds

Requires the flux sequences:
AdjustedPrecipitation ActualEvaporation Inflow Outflow Exchange

Updates the state sequence:
WaterVolume

Basic equation:: \(\frac{d}{dt}WaterVolume = 1e-6 \cdot (AdjustedPrecipitation - AdjustedEvaporation - Inflow - Outflow + Exchange)\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> derived.seconds = 2e6
>>> states.watervolume.old = 5.0
>>> fluxes.adjustedprecipitation = 1.0
>>> fluxes.actualevaporation = 2.0
>>> fluxes.inflow = 3.0
>>> fluxes.outflow = 4.0
>>> fluxes.exchange = 5.0
>>> model.update_watervolume_v4()
>>> states.watervolume
watervolume(11.0)

class hydpy.models.dam.dam_model.Update_WaterVolume_V5[source]¶

Bases: Method

Update the actual water volume based on inflow and precipitation.

Requires the control parameter:
Commission

Requires the derived parameter:
Seconds

Requires the flux sequences:
Inflow AdjustedPrecipitation

Updates the state sequence:
WaterVolume

Basic equation:: \[\begin{split}V_{new} = V_{old} + s / 1e6 \cdot (I + P) \\ \\ V = WaterVolume \\ s = Seconds \\ I = Inflow \\ P = AdjustedPrecipitation\end{split}\]

class hydpy.models.dam.dam_model.Pass_Outflow_V1[source]¶

Bases: Method

Update the outlet link sequence Q.

Requires the flux sequence:
Outflow

Calculates the outlet sequence:
Q

Basic equation:: \(Q = Outflow\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.outflow = 2.0
>>> model.pass_outflow_v1()
>>> outlets.q
q(2.0)

class hydpy.models.dam.dam_model.Pass_ActualRemoteRelease_V1[source]¶

Bases: Method

Update the outlet link sequence S.

Requires the flux sequence:
ActualRemoteRelease

Calculates the outlet sequence:
S

Basic equation:: \(S = ActualRemoteRelease\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.actualremoterelease = 2.0
>>> model.pass_actualremoterelease_v1()
>>> outlets.s
s(2.0)

class hydpy.models.dam.dam_model.Pass_ActualRemoteRelief_V1[source]¶

Bases: Method

Update the outlet link sequence R.

Requires the flux sequence:
ActualRemoteRelief

Calculates the outlet sequence:
R

Basic equation:: \(R = ActualRemoteRelief\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.actualremoterelief = 2.0
>>> model.pass_actualremoterelief_v1()
>>> outlets.r
r(2.0)

class hydpy.models.dam.dam_model.Pass_MissingRemoteRelease_V1[source]¶

Bases: Method

Update the outlet link sequence D.

Requires the flux sequence:
MissingRemoteRelease

Calculates the sender sequence:
D

Basic equation:: \(D = MissingRemoteRelease\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.missingremoterelease = 2.0
>>> model.pass_missingremoterelease_v1()
>>> senders.d
d(2.0)

class hydpy.models.dam.dam_model.Pass_AllowedRemoteRelief_V1[source]¶

Bases: Method

Update the outlet link sequence R.

Requires the flux sequence:
AllowedRemoteRelief

Calculates the sender sequence:
R

Basic equation:: \(R = AllowedRemoteRelief\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.allowedremoterelief = 2.0
>>> model.pass_allowedremoterelief_v1()
>>> senders.r
r(2.0)

class hydpy.models.dam.dam_model.Pass_RequiredRemoteSupply_V1[source]¶

Bases: Method

Update the outlet link sequence S.

Requires the flux sequence:
RequiredRemoteSupply

Calculates the sender sequence:
S

Basic equation:: \(S = RequiredRemoteSupply\)

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> fluxes.requiredremotesupply = 2.0
>>> model.pass_requiredremotesupply_v1()
>>> senders.s
s(2.0)

class hydpy.models.dam.dam_model.Update_LoggedOutflow_V1[source]¶

Bases: Method

Log a new entry of discharge at a cross section far downstream.

Requires the control parameter:
NmbLogEntries

Requires the flux sequence:
Outflow

Updates the log sequence:
LoggedOutflow

Example:

The following example shows that, with each new method call, the three memorized values are successively moved to the right and the respective new value is stored on the bare left position:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> nmblogentries(3)
>>> logs.loggedoutflow = 0.0
>>> from hydpy import UnitTest
>>> test = UnitTest(model,
...                 model.update_loggedoutflow_v1,
...                 last_example=4,
...                 parseqs=(fluxes.outflow,
...                          logs.loggedoutflow))
>>> test.nexts.outflow = [1.0, 3.0, 2.0, 4.0]
>>> del test.inits.loggedoutflow
>>> test()
| ex. | outflow |           loggedoutflow |
-------------------------------------------
|   1 |     1.0 | 1.0  0.0            0.0 |
|   2 |     3.0 | 3.0  1.0            0.0 |
|   3 |     2.0 | 2.0  3.0            1.0 |
|   4 |     4.0 | 4.0  2.0            3.0 |

class hydpy.models.dam.dam_model.Return_WaterLevelError_V1[source]¶

Bases: Method

Calculate and return the difference between the allowed water level and the water level that corresponds to the given water volume.

Requires the control parameter:
WaterVolume2WaterLevel

Requires the aide sequence:
AllowedWaterLevel

Basic equation:: \[\begin{split}f_{V2W}(v) - A \\ \\ f_{V2W} = WaterVolume2WaterLevel \\ A = AllowedWaterLevel\end{split}\]

Example:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> from hydpy import PPoly, round_
>>> watervolume2waterlevel(PPoly.from_data([0.0, 1.0, 2.0], [1.0, 2.0, 4.0]))
>>> aides.allowedwaterlevel = 3.0
>>> round_(model.return_waterlevelerror_v1(0.5))
-1.5

class hydpy.models.dam.dam_model.PegasusWaterVolume(model: Model)[source]¶

Bases: Pegasus

Pegasus iterator for finding the water volume corresponding to the allowed water level.

METHODS: ClassVar[tuple[type[Method], ...]] = (<class 'hydpy.models.dam.dam_model.Return_WaterLevelError_V1'>,)¶

name: ClassVar[str] = 'pegasuswatervolume'¶

class hydpy.models.dam.dam_model.Main_PrecipModel_V2[source]¶

Bases: Model, ABC

Base class for HydPy-Dam models that use submodels that comply with the PrecipModel_V2 interface.

precipmodel: SubmodelProperty¶

precipmodel_is_mainmodel¶

precipmodel_typeid¶

add_precipmodel_v2¶

Initialise the given precipmodel that follows the PrecipModel_V2 interface.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> surfacearea(2.0)
>>> with model.add_precipmodel_v2("meteo_precip_io"):
...     nmbhru
...     hruarea
...     precipitationfactor(1.5)
nmbhru(1)
hruarea(2.0)
>>> model.precipmodel.parameters.control.precipitationfactor
precipitationfactor(1.5)

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

class hydpy.models.dam.dam_model.Main_PEModel_V1[source]¶

Bases: Model, ABC

Base class for HydPy-Dam models that use submodels that comply with the PETModel_V1 interface.

pemodel: SubmodelProperty¶

pemodel_is_mainmodel¶

pemodel_typeid¶

add_pemodel_v1¶

Initialise the given pemodel that follows the PETModel_V1 interface.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> surfacearea(2.0)
>>> with model.add_pemodel_v1("evap_ret_tw2002"):
...     nmbhru
...     hruarea
...     evapotranspirationfactor(1.5)
nmbhru(1)
hruarea(2.0)

>>> model.pemodel.parameters.control.evapotranspirationfactor
evapotranspirationfactor(1.5)

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

class hydpy.models.dam.dam_model.MixinSimpleWaterBalance[source]¶

Bases: Model, ABC

Mixin class for the HydPy-Dam models with the simplest water balance equation.

check_waterbalance(initial_conditions: dict[str, dict[str, dict[str, float | ndarray[tuple[Any, ...], dtype[float64]]]]]) → 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_lretention for some examples.

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

cymodel: CyModelProtocol | None¶

parameters: parametertools.Parameters¶

sequences: sequencetools.Sequences¶

masks: masktools.Masks¶

OBSERVER_METHODS: ClassVar[tuple[type[Method], ...]]¶

METHOD_GROUPS: ClassVar[tuple[str, ...]]¶

DOCNAME: DocName¶

class hydpy.models.dam.dam_model.ELSIEModel[source]¶

Bases: ELSIEModel

Base class for all dam models formulated in the state-space form.

stop_els(nmbeval: int) → bool[source]¶

Stop the Explicit Lobatto Sequence early if the first function evaluation indicates an exceedance of the allowed Courant number, or if the actual number of function evaluations reached the permitted number.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> solver.maxcfl = 1.0
>>> solver.maxeval = 10
>>> derived.seconds(1000)
>>> states.watervolume.old = 2.0
>>> fluxes.outflow = 2000.0
>>> assert not model.stop_els(1)
>>> fluxes.outflow = 2000.1
>>> assert model.stop_els(1)
>>> assert not model.stop_els(0)
>>> assert not model.stop_els(2)
>>> assert not model.stop_els(9)
>>> assert model.stop_els(10)
>>> assert model.stop_els(11)

adjust_backwards_error(value: float) → float[source]¶

Adjust the given water volume error [million m³] to a discharge error [m³/s].

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> derived.seconds(1000)
>>> model.adjust_backwards_error(1.0)
1000.0

get_state_old() → float[source]¶

Get the water volume that corresponds to the beginning of the current simulation step.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> states.watervolume.old = 1.0
>>> model.get_state_old()
1.0

set_state_old(value: float) → None[source]¶

Set the water volume that corresponds to the beginning of the current simulation step.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> model.set_state_old(2.0)
>>> states.watervolume.old
2.0

get_state_new() → float[source]¶

Get the water volume that corresponds to the end of the current simulation step.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> states.watervolume.new = 3.0
>>> model.get_state_new()
3.0

set_state_new(value: float) → None[source]¶

Set the water volume that corresponds to the end of the current simulation step.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> model.set_state_new(4.0)
>>> states.watervolume.new
4.0

get_state_min() → float[source]¶

Return no minimum water volume.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> model.get_state_min()
-inf

get_state_max() → float[source]¶

Return no maximum water volume.

>>> from hydpy.models.dam_v001 import *
>>> parameterstep()
>>> model.get_state_max()
inf

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

Parameter Features¶

Control parameters¶

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

Bases: SubParameters

Control parameters of model dam.

The following classes are selected:

SurfaceArea() Average size of the water surface [km²].
CatchmentArea() Size of the catchment draining into the dam [km²].
NmbLogEntries() Number of log entries for certain variables [-].
CorrectionPrecipitation() Precipitation correction factor [-].
CorrectionEvaporation() Evaporation correction factor [-].
WeightEvaporation() Time weighting factor for evaporation [-].
RemoteDischargeMinimum() Discharge threshold of a cross-section far downstream not to be undercut by the actual discharge [m³/s].
RemoteDischargeSafety() Safety factor for reducing the risk of insufficient water release [m³/s].
WaterLevel2PossibleRemoteRelief() An interpolation function describing the relationship between water level and the highest possible water release used to relieve the dam during high flow conditions [-].
RemoteReliefTolerance() A tolerance value for PossibleRemoteRelief [m³/s].
NearDischargeMinimumThreshold() Discharge threshold of a cross-section near the dam not to be undercut by the actual discharge [m³/s].
NearDischargeMinimumTolerance() A tolerance value for the “near discharge minimum” [m³/s].
MinimumRelease() Minimum water release [m³/s].
RestrictTargetedRelease() A flag indicating whether low flow variability has to be preserved or not [-].
WaterVolumeMinimumThreshold() The minimum operating water volume of the dam [million m³].
WaterLevelMinimumThreshold() The minimum operating water level of the dam [m].
WaterLevelMinimumTolerance() A tolerance value for the minimum operating water level [m].
WaterLevelMaximumThreshold() The water level not to be exceeded [m].
WaterLevelMaximumTolerance() A tolerance value for the water level maximum [m].
RemoteWaterLevelMaximumThreshold() The remote water level not to be exceeded [m].
RemoteWaterLevelMaximumTolerance() Tolerance value for the remote water level maximum [m].
ThresholdEvaporation() The water level at which actual evaporation is 50 % of potential evaporation [m].
ToleranceEvaporation() A tolerance value defining the steepness of the transition of actual evaporation between zero and potential evaporation [m].
WaterLevelMinimumRemoteThreshold() The minimum operating water level of the dam regarding remote water supply [m].
WaterLevelMinimumRemoteTolerance() A tolerance value for the minimum operating water level regarding remote water supply [m].
HighestRemoteRelief() The highest possible relief discharge from another location [m³/s].
WaterLevelReliefThreshold() The threshold water level of the dam regarding the allowed relief discharge from another location [m].
WaterLevelReliefTolerance() A tolerance value for parameter WaterLevelReliefThreshold [m].
HighestRemoteSupply() The highest possible supply discharge from another location [m³/s].
WaterLevelSupplyThreshold() The threshold water level of the dam regarding the required supply discharge from another location [m].
WaterLevelSupplyTolerance() A tolerance value for parameter WaterLevelSupplyThreshold [m].
HighestRemoteDischarge() The highest possible discharge between two remote locations [m³/s].
HighestRemoteTolerance() Smoothing parameter associated with HighestRemoteDischarge [m³/s].
WaterVolume2WaterLevel() An interpolation function that describes the relationship between water level and water volume [-].
WaterLevel2FloodDischarge() An interpolation function that describesg the relationship between flood discharge and water volume [-].
WaterLevelDifference2MaxForcedDischarge() An interpolation function that describes the relationship between the highest possible forced discharge and the water level difference [-].
WaterLevelDifference2MaxFreeDischarge() An interpolation function that describes the relationship between the highest possible free discharge and the water level difference [-].
AllowedWaterLevelDrop() The highest allowed water level decrease [m/T].
AllowedRelease() The maximum water release not causing any harm downstream [m³/s].
TargetVolume() The desired volume of water required within the dam at specific times of the year [Mio. m³].
TargetRangeAbsolute() The absolute interpolation range related to parameter TargetVolume [Mio. m³].
TargetRangeRelative() The relative interpolation range related to parameter TargetVolume [-].
MaximumVolume() Maximum storable volume of water where uncontrolled discharge can be prevented [Mio. m³].
VolumeTolerance() Smoothing parameter for volume-related smoothing operations [Mio. m³].
DischargeTolerance() Smoothing parameter for discharge-related smoothing operations [m³/s].
CrestLevel() The crest level of a weir [m].
CrestLevelTolerance() A tolerance value for the crest level of a weir [m].
NmbSafeReleaseModels() The number of submodels that suggest release values that serve for flood protection at remote locations [-].
Commission() Commission date [-].

class hydpy.models.dam.dam_control.SurfaceArea(subvars: SubParameters)[source]¶

Bases: Parameter

Average size of the water surface [km²].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'surfacearea'¶: Name of the variable in lowercase letters.

unit: str = 'km²'¶: Unit of the variable.

class hydpy.models.dam.dam_control.CatchmentArea(subvars: SubParameters)[source]¶

Bases: Parameter

Size of the catchment draining into the dam [km²].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'catchmentarea'¶: Name of the variable in lowercase letters.

unit: str = 'km²'¶: Unit of the variable.

class hydpy.models.dam.dam_control.NmbLogEntries(subvars: SubParameters)[source]¶

Bases: Parameter

Number of log entries for certain variables [-].

Required by the methods:
Calc_NaturalRemoteDischarge_V1 Calc_RemoteFailure_V1 Update_LoggedOutflow_V1 Update_LoggedTotalRemoteDischarge_V1

Note that setting a new value by calling the parameter object sets the shapes of all associated log sequences automatically, except those with a predefined default shape:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> nmblogentries(3)
>>> for seq in logs:
...     print(seq)
loggedtotalremotedischarge(nan, nan, nan)
loggedoutflow(nan, nan, nan)
loggedadjustedevaporation(nan)
loggedrequiredremoterelease(nan)
loggedallowedremoterelief(nan)
loggedouterwaterlevel(nan)
loggedremotewaterlevel(nan)

To prevent losing information, updating parameter NmbLogEntries resets the shape of the relevant log sequences only when necessary:

>>> logs.loggedtotalremotedischarge = 1.0
>>> nmblogentries(3)
>>> logs.loggedtotalremotedischarge
loggedtotalremotedischarge(1.0, 1.0, 1.0)

NDIM: int = 0¶

TYPE¶: alias of int

TIME: bool | None = None¶

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

name: str = 'nmblogentries'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.CorrectionPrecipitation(subvars: SubParameters)[source]¶

Bases: Parameter

Precipitation correction factor [-].

Required by the method:: Calc_AdjustedPrecipitation_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'correctionprecipitation'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.CorrectionEvaporation(subvars: SubParameters)[source]¶

Bases: Parameter

Evaporation correction factor [-].

Required by the method:: Calc_AdjustedEvaporation_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'correctionevaporation'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WeightEvaporation(subvars: SubParameters)[source]¶

Bases: Parameter

Time weighting factor for evaporation [-].

Required by the method:: Calc_AdjustedEvaporation_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = True¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, 1.0)¶

name: str = 'weightevaporation'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.RemoteDischargeMinimum(subvars)[source]¶

Bases: SeasonalParameter

Discharge threshold of a cross-section far downstream not to be undercut by the actual discharge [m³/s].

Required by the methods:
Calc_RemoteDemand_V1 Calc_RemoteFailure_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'remotedischargeminimum'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.RemoteDischargeSafety(subvars)[source]¶

Bases: SeasonalParameter

Safety factor for reducing the risk of insufficient water release [m³/s].

Required by the method:: Calc_RequiredRemoteRelease_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'remotedischargesafety'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevel2PossibleRemoteRelief(subvars: SubParameters)[source]¶

Bases: SimpleInterpolator

An interpolation function describing the relationship between water level and the highest possible water release used to relieve the dam during high flow conditions [-].

Required by the method:
Calc_PossibleRemoteRelief_V1

XLABEL = 'water level [m]'¶

YLABEL = 'possible remote relieve [m³/s]'¶

name: str = 'waterlevel2possibleremoterelief'¶: Class name in lowercase letters.

class hydpy.models.dam.dam_control.RemoteReliefTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

A tolerance value for PossibleRemoteRelief [m³/s].

Required by the method:: Calc_ActualRemoteRelief_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'remoterelieftolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.NearDischargeMinimumThreshold(subvars)[source]¶

Bases: SeasonalParameter

Discharge threshold of a cross-section near the dam not to be undercut by the actual discharge [m³/s].

Required by the methods:
Calc_ActualRelease_V3 Calc_RequiredRelease_V1 Calc_RequiredRelease_V2 Calc_TargetedRelease_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'neardischargeminimumthreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.NearDischargeMinimumTolerance(subvars)[source]¶

Bases: SeasonalParameter

A tolerance value for the “near discharge minimum” [m³/s].

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'neardischargeminimumtolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.MinimumRelease(subvars: SubParameters)[source]¶

Bases: Parameter

Minimum water release [m³/s].

Required by the method:: Calc_AimedRelease_WaterVolume_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'minimumrelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.RestrictTargetedRelease(subvars: SubParameters)[source]¶

Bases: Parameter

A flag indicating whether low flow variability has to be preserved or not [-].

Required by the method:
Calc_TargetedRelease_V1

NDIM: int = 0¶

TYPE¶: alias of bool

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'restricttargetedrelease'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterVolumeMinimumThreshold(subvars)[source]¶

Bases: SeasonalParameter

The minimum operating water volume of the dam [million m³].

Required by the method:: Calc_ActualRelease_V3

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)¶

name: str = 'watervolumeminimumthreshold'¶: Name of the variable in lowercase letters.

unit: str = 'million m³'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelMinimumThreshold(subvars: SubParameters)[source]¶

Bases: Parameter

The minimum operating water level of the dam [m].

Required by the methods:: Calc_ActualRelease_V1 Calc_ActualRelease_V2

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'waterlevelminimumthreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelMinimumTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

A tolerance value for the minimum operating water level [m].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'waterlevelminimumtolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelMaximumThreshold(subvars: SubParameters)[source]¶

Bases: Parameter

The water level not to be exceeded [m].

Required by the method:: Calc_ForcedDischarge_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'waterlevelmaximumthreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelMaximumTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

A tolerance value for the water level maximum [m].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'waterlevelmaximumtolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.RemoteWaterLevelMaximumThreshold(subvars: SubParameters)[source]¶

Bases: Parameter

The remote water level not to be exceeded [m].

Required by the methods:: Calc_ForcedDischarge_V1 Calc_FreeDischarge_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'remotewaterlevelmaximumthreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.RemoteWaterLevelMaximumTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

Tolerance value for the remote water level maximum [m].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'remotewaterlevelmaximumtolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.ThresholdEvaporation(subvars: SubParameters)[source]¶

Bases: Parameter

The water level at which actual evaporation is 50 % of potential evaporation [m].

Required by the methods:
Calc_ActualEvaporation_V1 Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'thresholdevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.ToleranceEvaporation(subvars: SubParameters)[source]¶

Bases: Parameter

A tolerance value defining the steepness of the transition of actual evaporation between zero and potential evaporation [m].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)¶

name: str = 'toleranceevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelMinimumRemoteThreshold(subvars: SubParameters)[source]¶

Bases: Parameter

The minimum operating water level of the dam regarding remote water supply [m].

Required by the method:
Calc_ActualRemoteRelease_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)¶

name: str = 'waterlevelminimumremotethreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelMinimumRemoteTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

A tolerance value for the minimum operating water level regarding remote water supply [m].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)¶

name: str = 'waterlevelminimumremotetolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.HighestRemoteRelief(subvars)[source]¶

Bases: SeasonalParameter

The highest possible relief discharge from another location [m³/s].

Required by the method:: Calc_AllowedRemoteRelief_V2

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'highestremoterelief'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelReliefThreshold(subvars)[source]¶

Bases: SeasonalParameter

The threshold water level of the dam regarding the allowed relief discharge from another location [m].

Required by the method:
Calc_AllowedRemoteRelief_V2

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'waterlevelreliefthreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelReliefTolerance(subvars)[source]¶

Bases: SeasonalParameter

A tolerance value for parameter WaterLevelReliefThreshold [m].

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'waterlevelrelieftolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.HighestRemoteSupply(subvars)[source]¶

Bases: SeasonalParameter

The highest possible supply discharge from another location [m³/s].

Required by the method:: Calc_RequiredRemoteSupply_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'highestremotesupply'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelSupplyThreshold(subvars)[source]¶

Bases: SeasonalParameter

The threshold water level of the dam regarding the required supply discharge from another location [m].

Required by the method:
Calc_RequiredRemoteSupply_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'waterlevelsupplythreshold'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterLevelSupplyTolerance(subvars)[source]¶

Bases: SeasonalParameter

A tolerance value for parameter WaterLevelSupplyThreshold [m].

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'waterlevelsupplytolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.HighestRemoteDischarge(subvars: SubParameters)[source]¶

Bases: Parameter

The highest possible discharge between two remote locations [m³/s].

Required by the methods:: Update_ActualRemoteRelease_V1 Update_ActualRemoteRelief_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'highestremotedischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.HighestRemoteTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter associated with HighestRemoteDischarge [m³/s].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'highestremotetolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.WaterVolume2WaterLevel(subvars: SubParameters)[source]¶

Bases: SimpleInterpolator

An interpolation function that describes the relationship between water level and water volume [-].

Required by the methods:
Calc_AllowedWaterLevel_V1 Calc_SurfaceArea_V1 Calc_WaterLevel_V1 Return_WaterLevelError_V1

XLABEL = 'water volume [million m³]'¶

YLABEL = 'water level [m]'¶

name: str = 'watervolume2waterlevel'¶: Class name in lowercase letters.

class hydpy.models.dam.dam_control.WaterLevel2FloodDischarge(subvars: SubParameters)[source]¶

Bases: SeasonalInterpolator

An interpolation function that describesg the relationship between flood discharge and water volume [-].

Required by the method:
Calc_FloodDischarge_V1

XLABEL = 'water level [m]'¶

YLABEL = 'flood discharge [m³/s]'¶

name: str = 'waterlevel2flooddischarge'¶: Class name in lowercase letters.

class hydpy.models.dam.dam_control.WaterLevelDifference2MaxForcedDischarge(subvars: SubParameters)[source]¶

Bases: SeasonalInterpolator

An interpolation function that describes the relationship between the highest possible forced discharge and the water level difference [-].

Required by the method:
Calc_MaxForcedDischarge_V1

XLABEL = 'water level difference [m]'¶

YLABEL = 'max. forced discharge [m³/s]'¶

name: str = 'waterleveldifference2maxforceddischarge'¶: Class name in lowercase letters.

class hydpy.models.dam.dam_control.WaterLevelDifference2MaxFreeDischarge(subvars: SubParameters)[source]¶

Bases: SeasonalInterpolator

An interpolation function that describes the relationship between the highest possible free discharge and the water level difference [-].

Required by the method:
Calc_MaxFreeDischarge_V1

XLABEL = 'water level difference [m]'¶

YLABEL = 'max. free discharge [m³/s]'¶

name: str = 'waterleveldifference2maxfreedischarge'¶: Class name in lowercase letters.

class hydpy.models.dam.dam_control.AllowedWaterLevelDrop(subvars: SubParameters)[source]¶

Bases: Parameter

The highest allowed water level decrease [m/T].

Required by the methods:: Calc_AllowedDischarge_V1 Calc_AllowedDischarge_V2 Calc_AllowedWaterLevel_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = True¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'allowedwaterleveldrop'¶: Name of the variable in lowercase letters.

unit: str = 'm/T'¶: Unit of the variable.

class hydpy.models.dam.dam_control.AllowedDischargeTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter eventually associated with AllowedWaterLevelDrop [m³/s].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'alloweddischargetolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.AllowedRelease(subvars)[source]¶

Bases: SeasonalParameter

The maximum water release not causing any harm downstream [m³/s].

Required by the methods:: Calc_ActualRelease_V2 Calc_AllowedDischarge_V2 Calc_SafeRelease_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'allowedrelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.TargetVolume(subvars)[source]¶

Bases: SeasonalParameter

The desired volume of water required within the dam at specific times of the year [Mio. m³].

Required by the methods:
Calc_ActualRelease_V3 Calc_AimedRelease_WaterVolume_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'targetvolume'¶: Name of the variable in lowercase letters.

unit: str = 'Mio. m³'¶: Unit of the variable.

class hydpy.models.dam.dam_control.TargetRangeAbsolute(subvars: SubParameters)[source]¶

Bases: Parameter

The absolute interpolation range related to parameter TargetVolume [Mio. m³].

Required by the method:
Calc_ActualRelease_V3

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'targetrangeabsolute'¶: Name of the variable in lowercase letters.

unit: str = 'Mio. m³'¶: Unit of the variable.

class hydpy.models.dam.dam_control.TargetRangeRelative(subvars: SubParameters)[source]¶

Bases: Parameter

The relative interpolation range related to parameter TargetVolume [-].

Required by the method:: Calc_ActualRelease_V3

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'targetrangerelative'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.MaximumVolume(subvars: SubParameters)[source]¶

Bases: Parameter

Maximum storable volume of water where uncontrolled discharge can be prevented [Mio. m³].

Required by the method:
Calc_UnavoidableRelease_WaterVolume_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'maximumvolume'¶: Name of the variable in lowercase letters.

unit: str = 'Mio. m³'¶: Unit of the variable.

class hydpy.models.dam.dam_control.VolumeTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter for volume-related smoothing operations [Mio. m³].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'volumetolerance'¶: Name of the variable in lowercase letters.

unit: str = 'Mio. m³'¶: Unit of the variable.

class hydpy.models.dam.dam_control.DischargeTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter for discharge-related smoothing operations [m³/s].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'dischargetolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_control.CrestLevel(subvars: SubParameters)[source]¶

Bases: Parameter

The crest level of a weir [m].

Required by the method:: Calc_EffectiveWaterLevelDifference_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'crestlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.CrestLevelTolerance(subvars: SubParameters)[source]¶

Bases: Parameter

A tolerance value for the crest level of a weir [m].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

name: str = 'crestleveltolerance'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_control.NmbSafeReleaseModels(subvars: SubParameters)[source]¶

Bases: Parameter

The number of submodels that suggest release values that serve for flood protection at remote locations [-].

Required by the method:
Calc_SafeRelease_V1

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> nmbsafereleasemodels(2)
>>> model.safereleasemodels.number
2

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 = 'nmbsafereleasemodels'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_control.Commission(subvars: SubParameters)[source]¶

Bases: Parameter

Commission date [-].

Required by the methods:
Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3 Calc_ActualEvaporation_WaterVolume_V1 Calc_AimedRelease_WaterVolume_V1 Calc_Outflow_V2 Calc_Outflow_V7 Calc_UnavoidableRelease_WaterVolume_V1 Update_WaterVolume_V5

Parameter Commission requires a date as input. It compares this date with the current initialisation period, which must therefore be defined first:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission("2000-01-05")
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: While trying to set the commission date via parameter `commission` of element `?`, the following error occurred: Attribute timegrids of module `pub` is not defined at the moment.

After defining the initialisation period, you can pass the commission data, for example, in the form of a Date instance or a suitable string:

>>> from hydpy import Date, pub
>>> pub.timegrids = "2000-01-01", "2000-01-10", "1d"

>>> commission(Date("2000-01-01"))
>>> commission
commission("2000-01-01 00:00:00")

>>> commission("2000-01-05")
>>> commission
commission("2000-01-05 00:00:00")

Parameter Commission internally transforms the given date into an index value with respect to the initialisation period:

>>> commission.value
4

Commission dates outside the initialisation period pose no problems:

>>> commission("1999-12-01")
>>> commission
commission("1999-12-01 00:00:00")
>>> commission.value
-31

>>> commission("2000-02-01")
>>> commission
commission("2000-02-01 00:00:00")
>>> commission.value
31

However, we expect a date that lies precisely at the start or end of one simulation step:

>>> commission("2000-02-01 12:00")
Traceback (most recent call last):
...
ValueError: While trying to set the commission date via parameter `commission` of element `?`, the following error occurred: The given date `2000-02-01 12:00:00` is not properly alligned on the indexed timegrid `Timegrid("2000-01-01 00:00:00", "2000-01-10 00:00:00", "1d")`.

Alternatively, you can set the commission date by passing the mentioned index value:

>>> commission(4)
>>> commission
commission("2000-01-05 00:00:00")
>>> commission.value
4

NDIM: int = 0¶

TYPE¶: alias of int

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)¶

INIT: int | float | bool | None = 0¶

update() → None[source]¶

Always fall back to the default value if the user provides none (deprecated).

>>> import warnings
>>> warnings.filterwarnings("error")

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-01", "2001-01-01", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> commission.update()
Traceback (most recent call last):
...
hydpy.core.exceptiontools.HydPyDeprecationWarning: The value of parameter `commission` (introduced in HydPy 6.2), has not been explicitly defined and is automatically set to `1500-01-01 00:00:00`.  We will remove this fallback mechanism in HydPy 8.0; therefore, please consider updating your model setup.

>>> commission
commission("1500-01-01 00:00:00")

>>> commission("2000-01-02")
>>> commission
commission("2000-01-02 00:00:00")
>>> commission.value
1

name: str = 'commission'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

Derived parameters¶

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

Bases: SubParameters

Derived parameters of model dam.

The following classes are selected:

TOY() References the timeofyear index array provided by the instance of class Indexer available in module pub [-].
Seconds() Length of the actual simulation step size [s].
InputFactor() Factor for converting meteorological input from mm/T to million m³/s.
RemoteDischargeSmoothPar() Smoothing parameter to be derived from RemoteDischargeSafety [m³/s].
NearDischargeMinimumSmoothPar1() Smoothing parameter to be derived from NearDischargeMinimumThreshold for smoothing kernel smooth_logistic1() [m³/s].
NearDischargeMinimumSmoothPar2() Smoothing parameter to be derived from NearDischargeMinimumThreshold for smoothing kernel smooth_logistic2() [m³/s].
WaterLevelMinimumSmoothPar() Smoothing parameter to be derived from WaterLevelMinimumTolerance for smoothing kernel smooth_logistic1() [m].
WaterLevelMaximumSmoothPar() Smoothing parameter to be derived from WaterLevelMaximumTolerance for smoothing kernel smooth_logistic1() [m].
RemoteWaterLevelMaximumSmoothPar() Smoothing parameter to be derived from RemoteWaterLevelMaximumTolerance for smoothing kernel smooth_logistic1() [m].
SmoothParEvaporation() Smoothing parameter to be derived from ToleranceEvaporation for smoothing kernel smooth_logistic1() [m].
WaterLevelMinimumRemoteSmoothPar() Smoothing parameter to be derived from WaterLevelMinimumRemoteTolerance [m].
WaterLevelReliefSmoothPar() Smoothing parameter to be derived from WaterLevelReliefTolerance for smoothing kernel smooth_logistic1() [m³/s].
WaterLevelSupplySmoothPar() Smoothing parameter to be derived from WaterLevelSupplyTolerance for smoothing kernel smooth_logistic1() [m³/s].
HighestRemoteSmoothPar() Smoothing parameter to be derived from HighestRemoteTolerance for smoothing kernel smooth_min1() [m³/s].
VolumeSmoothParLog1() Smoothing parameter to be derived from VolumeTolerance for smoothing kernel smooth_logistic1() [million m³].
VolumeSmoothParLog2() Smoothing parameter to be derived from VolumeTolerance for smoothing kernel smooth_logistic2() [million m³].
DischargeSmoothPar() Smoothing parameter to be derived from DischargeTolerance for smoothing kernels smooth_logistic2(), smooth_min1(), and smooth_max1() [m³/s].
CrestLevelSmoothPar() Smoothing parameter to be derived from CrestLevelTolerance for smoothing kernel smooth_max1() [m].

class hydpy.models.dam.dam_derived.TOY(subvars: SubParameters)[source]¶

Bases: TOYParameter

References the timeofyear index array provided by the instance of class Indexer available in module pub [-].

Required by the methods:
Calc_ActualRelease_V2 Calc_ActualRelease_V3 Calc_AimedRelease_WaterVolume_V1 Calc_AllowedDischarge_V2 Calc_AllowedRemoteRelief_V2 Calc_FloodDischarge_V1 Calc_MaxForcedDischarge_V1 Calc_MaxFreeDischarge_V1 Calc_RemoteDemand_V1 Calc_RemoteFailure_V1 Calc_RequiredRelease_V1 Calc_RequiredRelease_V2 Calc_RequiredRemoteRelease_V1 Calc_RequiredRemoteSupply_V1 Calc_SafeRelease_V1 Calc_TargetedRelease_V1

name: str = 'toy'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.Seconds(subvars: SubParameters)[source]¶

Bases: SecondsParameter

Length of the actual simulation step size [s].

Required by the methods:: Calc_ActualEvaporation_WaterVolume_V1 Calc_AimedRelease_WaterVolume_V1 Calc_AllowedDischarge_V1 Calc_AllowedDischarge_V2 Calc_AllowedDischarge_V3 Calc_UnavoidableRelease_WaterVolume_V1 Update_WaterVolume_V1 Update_WaterVolume_V2 Update_WaterVolume_V3 Update_WaterVolume_V4 Update_WaterVolume_V5

name: str = 'seconds'¶: Name of the variable in lowercase letters.

unit: str = 's'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.InputFactor(subvars: SubParameters)[source]¶

Bases: Parameter

Factor for converting meteorological input from mm/T to million m³/s.

Required by the methods:: Calc_AdjustedEvaporation_V1 Calc_AdjustedPrecipitation_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Update InputFactor based on the control parameter SurfaceArea and the derived parameter Seconds:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> surfacearea(36.0)
>>> derived.seconds(3600.0)
>>> derived.inputfactor.update()
>>> derived.inputfactor
inputfactor(10.0)

name: str = 'inputfactor'¶: Name of the variable in lowercase letters.

unit: str = '?'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.RemoteDischargeSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from RemoteDischargeSafety [m³/s].

Required by the method:: Calc_RequiredRemoteRelease_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter values.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy import pub
>>> pub.timegrids = "2000.01.01", "2000.01.03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> remotedischargesafety(0.0)
>>> remotedischargesafety.values[1] = 2.5
>>> derived.remotedischargesmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1, derived.remotedischargesmoothpar[0]))
1.0
>>> round_(smooth_logistic1(2.5, derived.remotedischargesmoothpar[1]))
0.99

name: str = 'remotedischargesmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.NearDischargeMinimumSmoothPar1(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from NearDischargeMinimumThreshold for smoothing kernel smooth_logistic1() [m³/s].

Required by the method:
Calc_TargetedRelease_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter values.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy import pub
>>> pub.timegrids = "2000.01.01", "2000.01.03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> neardischargeminimumtolerance(0.0)
>>> neardischargeminimumtolerance.values[1] = 2.5
>>> derived.neardischargeminimumsmoothpar1.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(1.0, derived.neardischargeminimumsmoothpar1[0]))
1.0
>>> round_(smooth_logistic1(2.5, derived.neardischargeminimumsmoothpar1[1]))
0.99

name: str = 'neardischargeminimumsmoothpar1'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.NearDischargeMinimumSmoothPar2(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from NearDischargeMinimumThreshold for smoothing kernel smooth_logistic2() [m³/s].

Required by the method:
Calc_RequiredRelease_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter values.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy import pub
>>> pub.timegrids = "2000.01.01", "2000.01.03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> neardischargeminimumtolerance(0.0)
>>> neardischargeminimumtolerance.values[1] = 2.5
>>> derived.neardischargeminimumsmoothpar2.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic2
>>> from hydpy import round_
>>> round_(smooth_logistic2(0.0, derived.neardischargeminimumsmoothpar2[0]))
0.0
>>> round_(smooth_logistic2(2.5, derived.neardischargeminimumsmoothpar2[1]))
2.51

name: str = 'neardischargeminimumsmoothpar2'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.WaterLevelMinimumSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from WaterLevelMinimumTolerance for smoothing kernel smooth_logistic1() [m].

Required by the methods:
Calc_ActualRelease_V1 Calc_ActualRelease_V2

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevelminimumtolerance(0.0)
>>> derived.waterlevelminimumsmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1, derived.waterlevelminimumsmoothpar))
1.0
>>> waterlevelminimumtolerance(2.5)
>>> derived.waterlevelminimumsmoothpar.update()
>>> round_(smooth_logistic1(2.5, derived.waterlevelminimumsmoothpar))
0.99

name: str = 'waterlevelminimumsmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.WaterLevelMaximumSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from WaterLevelMaximumTolerance for smoothing kernel smooth_logistic1() [m].

Required by the method:
Calc_ForcedDischarge_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevelmaximumtolerance(0.0)
>>> derived.waterlevelmaximumsmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1, derived.waterlevelmaximumsmoothpar))
1.0
>>> waterlevelmaximumtolerance(2.5)
>>> derived.waterlevelmaximumsmoothpar.update()
>>> round_(smooth_logistic1(2.5, derived.waterlevelmaximumsmoothpar))
0.99

name: str = 'waterlevelmaximumsmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.RemoteWaterLevelMaximumSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from RemoteWaterLevelMaximumTolerance for smoothing kernel smooth_logistic1() [m].

Required by the methods:
Calc_ForcedDischarge_V1 Calc_FreeDischarge_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> remotewaterlevelmaximumtolerance(0.0)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1, derived.remotewaterlevelmaximumsmoothpar))
1.0
>>> remotewaterlevelmaximumtolerance(2.5)
>>> derived.remotewaterlevelmaximumsmoothpar.update()
>>> round_(smooth_logistic1(2.5, derived.remotewaterlevelmaximumsmoothpar))
0.99

name: str = 'remotewaterlevelmaximumsmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.SmoothParEvaporation(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from ToleranceEvaporation for smoothing kernel smooth_logistic1() [m].

Required by the methods:
Calc_ActualEvaporation_V1 Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> toleranceevaporation(0.0)
>>> derived.smoothparevaporation.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1, derived.smoothparevaporation))
1.0
>>> toleranceevaporation(2.5)
>>> derived.smoothparevaporation.update()
>>> round_(smooth_logistic1(2.5, derived.smoothparevaporation))
0.99

name: str = 'smoothparevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.WaterLevelMinimumRemoteSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from WaterLevelMinimumRemoteTolerance [m].

Required by the method:: Calc_ActualRemoteRelease_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevelminimumremotetolerance(0.0)
>>> derived.waterlevelminimumremotesmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1,
...        derived.waterlevelminimumremotesmoothpar))
1.0
>>> waterlevelminimumremotetolerance(2.5)
>>> derived.waterlevelminimumremotesmoothpar.update()
>>> round_(smooth_logistic1(2.5, derived.waterlevelminimumremotesmoothpar))
0.99

name: str = 'waterlevelminimumremotesmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.WaterLevelReliefSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from WaterLevelReliefTolerance for smoothing kernel smooth_logistic1() [m³/s].

Required by the method:
Calc_AllowedRemoteRelief_V2

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter values.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy import pub
>>> pub.timegrids = "2000.01.01", "2000.01.03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevelrelieftolerance(0.0)
>>> waterlevelrelieftolerance.values[1] = 2.5
>>> derived.waterlevelreliefsmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(1.0, derived.waterlevelreliefsmoothpar[0]))
1.0
>>> round_(smooth_logistic1(2.5, derived.waterlevelreliefsmoothpar[1]))
0.99

name: str = 'waterlevelreliefsmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.WaterLevelSupplySmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from WaterLevelSupplyTolerance for smoothing kernel smooth_logistic1() [m³/s].

Required by the method:
Calc_RequiredRemoteSupply_V1

NDIM: int = 1¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter values.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy import pub
>>> pub.timegrids = "2000.01.01", "2000.01.03", "1d"
>>> from hydpy.models.dam import *
>>> parameterstep()
>>> waterlevelsupplytolerance(0.0)
>>> waterlevelsupplytolerance.values[1] = 2.5
>>> derived.waterlevelsupplysmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(1.0, derived.waterlevelsupplysmoothpar[0]))
1.0
>>> round_(smooth_logistic1(2.5, derived.waterlevelsupplysmoothpar[1]))
0.99

name: str = 'waterlevelsupplysmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.HighestRemoteSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from HighestRemoteTolerance for smoothing kernel smooth_min1() [m³/s].

Required by the methods:
Update_ActualRemoteRelease_V1 Update_ActualRemoteRelief_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> highestremotedischarge(1.0)
>>> highestremotetolerance(0.0)
>>> derived.highestremotesmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_min1
>>> from hydpy import round_
>>> round_(smooth_min1(-4.0, 1.5, derived.highestremotesmoothpar))
-4.0
>>> highestremotetolerance(2.5)
>>> derived.highestremotesmoothpar.update()
>>> round_(smooth_min1(-4.0, -1.5, derived.highestremotesmoothpar))
-4.01

Note that the example above corresponds to the one on function calc_smoothpar_min1() due to the value of parameter HighestRemoteDischarge being 1 m³/s. Doubling HighestRemoteDischarge also doubles HighestRemoteSmoothPar, leading to the following result:

>>> highestremotedischarge(2.0)
>>> derived.highestremotesmoothpar.update()
>>> round_(smooth_min1(-4.0, 1.0, derived.highestremotesmoothpar))
-4.02

This relationship between HighestRemoteDischarge and HighestRemoteSmoothPar prevents any smoothing when the value of HighestRemoteDischarge is zero:

>>> highestremotedischarge(0.0)
>>> derived.highestremotesmoothpar.update()
>>> round_(smooth_min1(1.0, 1.0, derived.highestremotesmoothpar))
1.0

In addition, method update() sets the value of parameter HighestRemoteSmoothPar to zero if HighestRemoteDischarge is inf (no actual value will ever reach vicinity of infinity, hence smoothing would never apply anyway):

>>> highestremotedischarge(inf)
>>> derived.highestremotesmoothpar.update()
>>> round_(smooth_min1(1.0, 1.0, derived.highestremotesmoothpar))
1.0

name: str = 'highestremotesmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.VolumeSmoothParLog1(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from VolumeTolerance for smoothing kernel smooth_logistic1() [million m³].

Required by the method:
Calc_ActualRelease_V3

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> volumetolerance(0.0)
>>> derived.volumesmoothparlog1.update()
>>> from hydpy.cythons.smoothutils import smooth_logistic1
>>> from hydpy import round_
>>> round_(smooth_logistic1(0.1, derived.volumesmoothparlog1))
1.0
>>> volumetolerance(2.5)
>>> derived.volumesmoothparlog1.update()
>>> round_(smooth_logistic1(2.5, derived.volumesmoothparlog1))
0.99

name: str = 'volumesmoothparlog1'¶: Name of the variable in lowercase letters.

unit: str = 'million m³'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.VolumeSmoothParLog2(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from VolumeTolerance for smoothing kernel smooth_logistic2() [million m³].

Required by the method:
Calc_ActualRelease_V3

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> from hydpy.cythons.smoothutils import smooth_logistic2
>>> from hydpy import round_
>>> volumetolerance(0.0)
>>> derived.volumesmoothparlog2.update()
>>> round_(smooth_logistic2(0.0, derived.volumesmoothparlog2))
0.0
>>> volumetolerance(2.5)
>>> derived.volumesmoothparlog2.update()
>>> round_(smooth_logistic2(2.5, derived.volumesmoothparlog2))
2.51

name: str = 'volumesmoothparlog2'¶: Name of the variable in lowercase letters.

unit: str = 'million m³'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.DischargeSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from DischargeTolerance for smoothing kernels smooth_logistic2(), smooth_min1(), and smooth_max1() [m³/s].

Required by the methods:
Calc_ActualRelease_V3 Calc_AllowedDischarge_V2 Calc_FreeDischarge_V1 Calc_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, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> dischargetolerance(0.0)
>>> derived.dischargesmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_max1, smooth_min1
>>> from hydpy import round_
>>> round_(smooth_max1(4.0, 1.5, derived.dischargesmoothpar))
4.0
>>> round_(smooth_min1(4.0, 1.5, derived.dischargesmoothpar))
1.5
>>> dischargetolerance(2.5)
>>> derived.dischargesmoothpar.update()
>>> round_(smooth_max1(4.0, 1.5, derived.dischargesmoothpar))
4.01
>>> round_(smooth_min1(4.0, 1.5, derived.dischargesmoothpar))
1.49

name: str = 'dischargesmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_derived.CrestLevelSmoothPar(subvars: SubParameters)[source]¶

Bases: Parameter

Smoothing parameter to be derived from CrestLevelTolerance for smoothing kernel smooth_max1() [m].

Required by the method:
Calc_EffectiveWaterLevelDifference_V1

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

update()[source]¶

Calculate the smoothing parameter value.

The documentation on module smoothtools explains the following example in some detail:

>>> from hydpy.models.dam import *
>>> parameterstep()
>>> crestleveltolerance(0.0)
>>> derived.crestlevelsmoothpar.update()
>>> from hydpy.cythons.smoothutils import smooth_max1, smooth_min1
>>> from hydpy import round_
>>> round_(smooth_max1(4.0, 1.5, derived.crestlevelsmoothpar))
4.0
>>> round_(smooth_min1(4.0, 1.5, derived.crestlevelsmoothpar))
1.5
>>> crestleveltolerance(2.5)
>>> derived.crestlevelsmoothpar.update()
>>> round_(smooth_max1(4.0, 1.5, derived.crestlevelsmoothpar))
4.01
>>> round_(smooth_min1(4.0, 1.5, derived.crestlevelsmoothpar))
1.49

name: str = 'crestlevelsmoothpar'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

Solver parameters¶

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

Bases: SubParameters

Solver parameters of model dam.

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.dam_solver.AbsErrorMax(subvars)[source]¶

Bases: SolverParameter

Absolute numerical error tolerance [m³/s].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

INIT: int | float | bool = 0.0001¶

modify_init() → float[source]¶

Adjust and return the value of class constant INIT.

Note that the default initial value 0.0001 refers to mm/T. Hence the actual default initial value in m³/s is:

\(AbsErrorMax = 0.0001 \cdot CatchmentArea \cdot 1000 / Seconds\)

>>> from hydpy.models.dam import *
>>> simulationstep("1h")
>>> parameterstep("1d")
>>> solver.abserrormax.INIT
0.0001
>>> catchmentarea(2.0)
>>> derived.seconds.update()
>>> from hydpy import round_
>>> round_(solver.abserrormax.modify_init())
0.000056

name: str = 'abserrormax'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_solver.RelErrorMax(subvars)[source]¶

Bases: SolverParameter

Relative numerical error tolerance [1/T].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)¶

INIT: int | float | bool = nan¶

name: str = 'relerrormax'¶: Name of the variable in lowercase letters.

unit: str = '1/T'¶: Unit of the variable.

class hydpy.models.dam.dam_solver.RelDTMin(subvars)[source]¶

Bases: SolverParameter

Smallest relative integration time step size allowed [-].

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)¶

INIT: int | float | bool = 0.001¶

name: str = 'reldtmin'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_solver.RelDTMax(subvars)[source]¶

Bases: SolverParameter

Largest relative integration time step size allowed [-].

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)¶

INIT: int | float | bool = 1.0¶

name: str = 'reldtmax'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_solver.MaxEval(subvars)[source]¶

Bases: SolverParameter

Maximum number of function evaluations before stopping the Explicit Labatto Sequence [-].

NDIM: int = 0¶

TYPE¶: alias of int

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)¶

INIT: int | float | bool = 1000000¶

name: str = 'maxeval'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

class hydpy.models.dam.dam_solver.MaxCFL(subvars)[source]¶

Bases: SolverParameter

Maximum Caurant-Friedrichs-Lewy number for using the Explicit Labatto Sequence [-].

NDIM: int = 0¶

TYPE¶: alias of float

TIME: bool | None = None¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, inf)¶

INIT: int | float | bool = inf¶

name: str = 'maxcfl'¶: Name of the variable in lowercase letters.

unit: str = '-'¶: Unit of the variable.

Sequence Features¶

Factor sequences¶

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

Bases: FactorSequences

Factor sequences of model dam.

The following classes are selected:

WaterLevel() Water level [m].
OuterWaterLevel() The water level directly below the dam [m].
RemoteWaterLevel() The water level at a remote location [m].
WaterLevelDifference() Difference between the inner and the outer water level [m].
EffectiveWaterLevelDifference() Effective difference between the inner and the outer water level [m].

class hydpy.models.dam.dam_factors.WaterLevel(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FactorSequence

Water level [m].

Calculated by the method:
Calc_WaterLevel_V1

Required by the methods:
Calc_ActualEvaporation_V1 Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3 Calc_ActualRelease_V1 Calc_ActualRelease_V2 Calc_ActualRemoteRelease_V1 Calc_AllowedRemoteRelief_V2 Calc_EffectiveWaterLevelDifference_V1 Calc_FloodDischarge_V1 Calc_ForcedDischarge_V1 Calc_PossibleRemoteRelief_V1 Calc_RequiredRemoteSupply_V1 Calc_WaterLevelDifference_V1

After each simulation step, the value of WaterLevel corresponds to the value of the state sequence WaterVolume for the end of the simulation step.

NDIM: int = 0¶

name: str = 'waterlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_factors.OuterWaterLevel(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FactorSequence

The water level directly below the dam [m].

Calculated by the method:: Calc_OuterWaterLevel_V1
Required by the methods:: Calc_EffectiveWaterLevelDifference_V1 Calc_WaterLevelDifference_V1

NDIM: int = 0¶

name: str = 'outerwaterlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_factors.RemoteWaterLevel(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FactorSequence

The water level at a remote location [m].

Calculated by the method:: Calc_RemoteWaterLevel_V1
Required by the methods:: Calc_ForcedDischarge_V1 Calc_FreeDischarge_V1

NDIM: int = 0¶

name: str = 'remotewaterlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_factors.WaterLevelDifference(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FactorSequence

Difference between the inner and the outer water level [m].

Calculated by the method:
Calc_WaterLevelDifference_V1

Required by the method:
Calc_MaxForcedDischarge_V1

The inner water level is above the outer water level for positive values.

NDIM: int = 0¶

name: str = 'waterleveldifference'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_factors.EffectiveWaterLevelDifference(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FactorSequence

Effective difference between the inner and the outer water level [m].

Calculated by the method:
Calc_EffectiveWaterLevelDifference_V1

Required by the method:
Calc_MaxFreeDischarge_V1

“Effective” could mean, for example, the water level difference above a weir crest (where the actual water exchange takes place).

NDIM: int = 0¶

name: str = 'effectivewaterleveldifference'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

Flux sequences¶

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

Bases: FluxSequences

Flux sequences of model dam.

The following classes are selected:

Precipitation() Precipitation [mm].
AdjustedPrecipitation() Adjusted precipitation [m³/s].
PotentialEvaporation() Potential evaporation [mm/T].
AdjustedEvaporation() Adjusted evaporation [m³/s].
ActualEvaporation() Actual evaporation [m³/s].
Inflow() Total inflow [m³/s].
Exchange() Water exchange with another location [m³/s].
TotalRemoteDischarge() Total discharge at a cross-section far downstream [m³/s].
NaturalRemoteDischarge() Natural discharge at a cross-section far downstream [m³/s].
RemoteDemand() Discharge demand at a cross-section far downstream [m³/s].
RemoteFailure() Difference between the actual and the required discharge at a cross-section far downstream [m³/s].
RequiredRemoteRelease() Water release considered appropriate to reduce drought events at cross-sections far downstream [m³/s].
AllowedRemoteRelief() Allowed discharge to relieve a dam during high flow conditions [m³/s].
RequiredRemoteSupply() Required water supply, for example, to fill a dam during low water conditions [m³/s].
PossibleRemoteRelief() Maximum possible water release to a remote location to relieve the dam during high flow conditions [m³/s].
ActualRemoteRelief() Actual water release to a remote location to relieve the dam during high flow conditions [m³/s].
RequiredRelease() Required water release for reducing drought events downstream [m³/s].
TargetedRelease() The targeted water release for reducing drought events downstream after taking both the required release and additional low flow regulations into account [m³/s].
ActualRelease() Actual water release thought for reducing drought events downstream [m³/s].
MissingRemoteRelease() Amount of the required remote demand not met by the actual release [m³/s].
ActualRemoteRelease() Actual water release thought for arbitrary “remote” purposes [m³/s].
SafeRelease() Water release that is considered safe in terms of flood protection [m³/s].
AimedRelease() Ideal controlled water release [m³/s].
UnavoidableRelease() Water release that cannot be avoided due to limited storage capacity [m³/s].
FloodDischarge() Water release associated with flood events [m³/s].
FreeDischarge() Free water release through structures as flap sluice gates [m³/s].
MaxForcedDischarge() The currently highest possible forced water release through structures as pumps [m³/s].
MaxFreeDischarge() The currently highest possible free water release through structures as pumps [m³/s].
ForcedDischarge() Forced water release through structures as pumps [m³/s].
Outflow() Total outflow [m³/s].

class hydpy.models.dam.dam_fluxes.Precipitation(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Precipitation [mm].

Calculated by the method:: Calc_Precipitation_V1
Required by the method:: Calc_AdjustedPrecipitation_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'precipitation'¶: Name of the variable in lowercase letters.

unit: str = 'mm'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.AdjustedPrecipitation(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Adjusted precipitation [m³/s].

Calculated by the method:: Calc_AdjustedPrecipitation_V1
Required by the methods:: Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3 Calc_ActualEvaporation_WaterVolume_V1 Calc_AllowedDischarge_V1 Calc_AllowedDischarge_V3 Calc_Outflow_V2 Calc_Outflow_V7 Calc_UnavoidableRelease_WaterVolume_V1 Update_WaterVolume_V1 Update_WaterVolume_V2 Update_WaterVolume_V3 Update_WaterVolume_V4 Update_WaterVolume_V5

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'adjustedprecipitation'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.PotentialEvaporation(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Potential evaporation [mm/T].

Calculated by the method:: Calc_PotentialEvaporation_V1
Required by the method:: Calc_AdjustedEvaporation_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'potentialevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'mm/T'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.AdjustedEvaporation(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Adjusted evaporation [m³/s].

Calculated by the method:: Calc_AdjustedEvaporation_V1
Required by the methods:: Calc_ActualEvaporation_V1 Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3 Calc_ActualEvaporation_WaterVolume_V1 Calc_AllowedDischarge_V3

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'adjustedevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.ActualEvaporation(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Actual evaporation [m³/s].

Calculated by the methods:: Calc_ActualEvaporation_V1 Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3 Calc_ActualEvaporation_WaterVolume_V1
Required by the methods:: Calc_AllowedDischarge_V1 Calc_Outflow_V2 Calc_Outflow_V7 Calc_UnavoidableRelease_WaterVolume_V1 Update_WaterVolume_V1 Update_WaterVolume_V2 Update_WaterVolume_V3 Update_WaterVolume_V4

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'actualevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.Inflow(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Total inflow [m³/s].

Calculated by the methods:: Pick_Inflow_V1 Pick_Inflow_V2
Required by the methods:: Calc_ActualEvaporation_V2 Calc_ActualEvaporation_V3 Calc_ActualEvaporation_WaterVolume_V1 Calc_ActualRelease_V3 Calc_AllowedDischarge_V1 Calc_AllowedDischarge_V2 Calc_AllowedDischarge_V3 Calc_Outflow_V2 Calc_Outflow_V7 Calc_TargetedRelease_V1 Calc_UnavoidableRelease_WaterVolume_V1 Update_WaterVolume_V1 Update_WaterVolume_V2 Update_WaterVolume_V3 Update_WaterVolume_V4 Update_WaterVolume_V5

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'inflow'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.Exchange(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Water exchange with another location [m³/s].

Calculated by the method:: Pick_Exchange_V1
Required by the methods:: Calc_ActualEvaporation_V2 Calc_AllowedDischarge_V1 Calc_Outflow_V2 Update_WaterVolume_V4

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'exchange'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.TotalRemoteDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Total discharge at a cross-section far downstream [m³/s].

Calculated by the method:: Pick_TotalRemoteDischarge_V1
Required by the method:: Update_LoggedTotalRemoteDischarge_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'totalremotedischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.NaturalRemoteDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Natural discharge at a cross-section far downstream [m³/s].

Calculated by the method:
Calc_NaturalRemoteDischarge_V1

Required by the method:
Calc_RemoteDemand_V1

Natural means: without the water released by the dam.

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'naturalremotedischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.RemoteDemand(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Discharge demand at a cross-section far downstream [m³/s].

Calculated by the method:: Calc_RemoteDemand_V1
Required by the method:: Calc_RequiredRemoteRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'remotedemand'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.RemoteFailure(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Difference between the actual and the required discharge at a cross-section far downstream [m³/s].

Calculated by the method:
Calc_RemoteFailure_V1

Required by the method:
Calc_RequiredRemoteRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'remotefailure'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.RequiredRemoteRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Water release considered appropriate to reduce drought events at cross-sections far downstream [m³/s].

Calculated by the methods:
Calc_RequiredRemoteRelease_V1 Calc_RequiredRemoteRelease_V2

Required by the methods:
Calc_ActualRemoteRelease_V1 Calc_MissingRemoteRelease_V1 Calc_RequiredRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'requiredremoterelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.AllowedRemoteRelief(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Allowed discharge to relieve a dam during high flow conditions [m³/s].

Calculated by the methods:: Calc_AllowedRemoteRelief_V1 Calc_AllowedRemoteRelief_V2
Required by the methods:: Calc_ActualRemoteRelief_V1 Pass_AllowedRemoteRelief_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'allowedremoterelief'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.RequiredRemoteSupply(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Required water supply, for example, to fill a dam during low water conditions [m³/s].

Calculated by the method:
Calc_RequiredRemoteSupply_V1

Required by the method:
Pass_RequiredRemoteSupply_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'requiredremotesupply'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.PossibleRemoteRelief(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Maximum possible water release to a remote location to relieve the dam during high flow conditions [m³/s].

Calculated by the method:
Calc_PossibleRemoteRelief_V1

Required by the method:
Calc_ActualRemoteRelief_V1

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'possibleremoterelief'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.ActualRemoteRelief(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Actual water release to a remote location to relieve the dam during high flow conditions [m³/s].

Calculated by the method:
Calc_ActualRemoteRelief_V1

Updated by the method:
Update_ActualRemoteRelief_V1

Required by the methods:
Pass_ActualRemoteRelief_V1 Update_ActualRemoteRelease_V1 Update_WaterVolume_V3

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'actualremoterelief'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.RequiredRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Required water release for reducing drought events downstream [m³/s].

Calculated by the methods:: Calc_RequiredRelease_V1 Calc_RequiredRelease_V2
Required by the method:: Calc_TargetedRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'requiredrelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.TargetedRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

The targeted water release for reducing drought events downstream after taking both the required release and additional low flow regulations into account [m³/s].

Calculated by the method:
Calc_TargetedRelease_V1

Required by the method:
Calc_ActualRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'targetedrelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.ActualRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Actual water release thought for reducing drought events downstream [m³/s].

Calculated by the methods:: Calc_ActualRelease_V1 Calc_ActualRelease_V2 Calc_ActualRelease_V3
Required by the methods:: Calc_MissingRemoteRelease_V1 Calc_Outflow_V1 Calc_Outflow_V7

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'actualrelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.MissingRemoteRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Amount of the required remote demand not met by the actual release [m³/s].

Calculated by the method:: Calc_MissingRemoteRelease_V1
Required by the method:: Pass_MissingRemoteRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'missingremoterelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.ActualRemoteRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Actual water release thought for arbitrary “remote” purposes [m³/s].

Calculated by the method:: Calc_ActualRemoteRelease_V1
Updated by the method:: Update_ActualRemoteRelease_V1
Required by the methods:: Pass_ActualRemoteRelease_V1 Update_WaterVolume_V2 Update_WaterVolume_V3

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'actualremoterelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.SafeRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Water release that is considered safe in terms of flood protection [m³/s].

Calculated by the method:: Calc_SafeRelease_V1
Required by the method:: Calc_AimedRelease_WaterVolume_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'saferelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.AimedRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Ideal controlled water release [m³/s].

Calculated by the method:: Calc_AimedRelease_WaterVolume_V1
Required by the method:: Calc_Outflow_V6

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'aimedrelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.UnavoidableRelease(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Water release that cannot be avoided due to limited storage capacity [m³/s].

Calculated by the method:: Calc_UnavoidableRelease_WaterVolume_V1
Required by the method:: Calc_Outflow_V6

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'unavoidablerelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.FloodDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Water release associated with flood events [m³/s].

Calculated by the method:: Calc_FloodDischarge_V1
Required by the methods:: Calc_Outflow_V1 Calc_Outflow_V2 Calc_Outflow_V7

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'flooddischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.FreeDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Free water release through structures as flap sluice gates [m³/s].

Calculated by the method:: Calc_FreeDischarge_V1
Required by the methods:: Calc_Outflow_V4 Calc_Outflow_V5

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'freedischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.MaxForcedDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

The currently highest possible forced water release through structures as pumps [m³/s].

Calculated by the method:
Calc_MaxForcedDischarge_V1

Required by the method:
Calc_ForcedDischarge_V1

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'maxforceddischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.MaxFreeDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

The currently highest possible free water release through structures as pumps [m³/s].

Calculated by the method:
Calc_MaxFreeDischarge_V1

Required by the method:
Calc_FreeDischarge_V1

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'maxfreedischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.ForcedDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Forced water release through structures as pumps [m³/s].

Calculated by the method:: Calc_ForcedDischarge_V1
Required by the methods:: Calc_Outflow_V3 Calc_Outflow_V5

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'forceddischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_fluxes.Outflow(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: FluxSequence

Total outflow [m³/s].

Calculated by the methods:: Calc_Outflow_V1 Calc_Outflow_V2 Calc_Outflow_V3 Calc_Outflow_V4 Calc_Outflow_V5 Calc_Outflow_V7
Updated by the method:: Calc_Outflow_V6
Required by the methods:: Pass_Outflow_V1 Update_LoggedOutflow_V1 Update_WaterVolume_V1 Update_WaterVolume_V2 Update_WaterVolume_V3 Update_WaterVolume_V4

NDIM: int = 0¶

NUMERIC: bool = True¶

name: str = 'outflow'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

State sequences¶

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

Bases: StateSequences

State sequences of model dam.

The following classes are selected:

WaterVolume() Water volume [million m³].

class hydpy.models.dam.dam_states.WaterVolume(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: StateSequence

Water volume [million m³].

Updated by the methods:: Calc_ActualEvaporation_WaterVolume_V1 Calc_AimedRelease_WaterVolume_V1 Calc_UnavoidableRelease_WaterVolume_V1 Update_WaterVolume_V1 Update_WaterVolume_V2 Update_WaterVolume_V3 Update_WaterVolume_V4 Update_WaterVolume_V5
Required by the methods:: Calc_ActualRelease_V3 Calc_AllowedDischarge_V3 Calc_AllowedWaterLevel_V1 Calc_SurfaceArea_V1 Calc_WaterLevel_V1

NDIM: int = 0¶

NUMERIC: bool = True¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'watervolume'¶: Name of the variable in lowercase letters.

unit: str = 'million m³'¶: Unit of the variable.

Log sequences¶

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

Bases: LogSequences

Log sequences of model dam.

The following classes are selected:

LoggedTotalRemoteDischarge() Logged discharge values from somewhere else [m³/s].
LoggedOutflow() Logged discharge values from the dam itself [m³/s].
LoggedAdjustedEvaporation() Logged adjusted evaporation [m³/s].
LoggedRequiredRemoteRelease() Logged required discharge values computed by another model [m³/s].
LoggedAllowedRemoteRelief() Logged allowed discharge values computed by another model [m³/s].
LoggedOuterWaterLevel() Logged water level directly below the dam [m].
LoggedRemoteWaterLevel() Logged water level at a remote location [m].

class hydpy.models.dam.dam_logs.LoggedTotalRemoteDischarge(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequence

Logged discharge values from somewhere else [m³/s].

Updated by the method:: Update_LoggedTotalRemoteDischarge_V1
Required by the methods:: Calc_NaturalRemoteDischarge_V1 Calc_RemoteFailure_V1

NDIM: int = 1¶

NUMERIC: bool = False¶

name: str = 'loggedtotalremotedischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_logs.LoggedOutflow(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequence

Logged discharge values from the dam itself [m³/s].

Updated by the method:: Update_LoggedOutflow_V1
Required by the method:: Calc_NaturalRemoteDischarge_V1

NDIM: int = 1¶

NUMERIC: bool = False¶

name: str = 'loggedoutflow'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_logs.LoggedAdjustedEvaporation(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequenceFixed

Logged adjusted evaporation [m³/s].

Updated by the method:: Calc_AdjustedEvaporation_V1

NUMERIC: bool = False¶

SHAPE: int = 1¶

name: str = 'loggedadjustedevaporation'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_logs.LoggedRequiredRemoteRelease(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequenceFixed

Logged required discharge values computed by another model [m³/s].

Calculated by the methods:: Pick_LoggedRequiredRemoteRelease_V1 Pick_LoggedRequiredRemoteRelease_V2
Required by the method:: Calc_RequiredRemoteRelease_V2

NUMERIC: bool = False¶

SHAPE: int = 1¶

name: str = 'loggedrequiredremoterelease'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_logs.LoggedAllowedRemoteRelief(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequenceFixed

Logged allowed discharge values computed by another model [m³/s].

Calculated by the method:: Pick_LoggedAllowedRemoteRelief_V1
Required by the method:: Calc_AllowedRemoteRelief_V1

NUMERIC: bool = False¶

SHAPE: int = 1¶

name: str = 'loggedallowedremoterelief'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_logs.LoggedOuterWaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequenceFixed

Logged water level directly below the dam [m].

Calculated by the method:: Pick_LoggedOuterWaterLevel_V1
Required by the method:: Calc_OuterWaterLevel_V1

NUMERIC: bool = False¶

SHAPE: int = 1¶

name: str = 'loggedouterwaterlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_logs.LoggedRemoteWaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: LogSequenceFixed

Logged water level at a remote location [m].

Calculated by the method:: Pick_LoggedRemoteWaterLevel_V1
Required by the method:: Calc_RemoteWaterLevel_V1

NUMERIC: bool = False¶

SHAPE: int = 1¶

name: str = 'loggedremotewaterlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

Inlet sequences¶

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

Bases: InletSequences

Inlet sequences of model dam.

The following classes are selected:

Q() Inflow [m³/s].
S() Actual water supply [m³/s].
R() Actual water relief [m³/s].
E() Bidirectional water exchange [m³/s].

class hydpy.models.dam.dam_inlets.Q(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: InletSequence

Inflow [m³/s].

Required by the methods:: Pick_Inflow_V1 Pick_Inflow_V2

NDIM: int = 1¶

NUMERIC: bool = False¶

name: str = 'q'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_inlets.S(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: InletSequence

Actual water supply [m³/s].

Required by the method:: Pick_Inflow_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 's'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_inlets.R(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: InletSequence

Actual water relief [m³/s].

Required by the method:: Pick_Inflow_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'r'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_inlets.E(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: InletSequence

Bidirectional water exchange [m³/s].

Required by the method:: Pick_Exchange_V1

NDIM: int = 1¶

NUMERIC: bool = False¶

name: str = 'e'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

Outlet sequences¶

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

Bases: OutletSequences

Outlet sequences of model dam.

The following classes are selected:

Q() Outflow [m³/s].
S() Actual water supply [m³/s].
R() Actual water relief [m³/s].

class hydpy.models.dam.dam_outlets.Q(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: OutletSequence

Outflow [m³/s].

Calculated by the method:: Pass_Outflow_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'q'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_outlets.S(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: OutletSequence

Actual water supply [m³/s].

Calculated by the method:: Pass_ActualRemoteRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 's'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_outlets.R(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: OutletSequence

Actual water relief [m³/s].

Calculated by the method:: Pass_ActualRemoteRelief_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'r'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

Receiver sequences¶

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

Bases: ReceiverSequences

Receiver sequences of model dam.

The following classes are selected:

Q() Remote discharge [m³/s].
D() Water demand [m³/s].
S() Required water supply [m³/s].
R() Allowed water relief [m³/s].
OWL() The water level directly below the dam [m].
RWL() The water level at a remote location [m].

class hydpy.models.dam.dam_receivers.Q(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: ReceiverSequence

Remote discharge [m³/s].

Required by the method:: Pick_TotalRemoteDischarge_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'q'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_receivers.D(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: ReceiverSequence

Water demand [m³/s].

Required by the method:: Pick_LoggedRequiredRemoteRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'd'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_receivers.S(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: ReceiverSequence

Required water supply [m³/s].

Required by the method:: Pick_LoggedRequiredRemoteRelease_V2

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 's'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_receivers.R(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: ReceiverSequence

Allowed water relief [m³/s].

Required by the method:: Pick_LoggedAllowedRemoteRelief_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'r'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_receivers.OWL(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: ReceiverSequence

The water level directly below the dam [m].

Required by the method:: Pick_LoggedOuterWaterLevel_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'owl'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

class hydpy.models.dam.dam_receivers.RWL(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: ReceiverSequence

The water level at a remote location [m].

Required by the method:: Pick_LoggedRemoteWaterLevel_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'rwl'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

Sender sequences¶

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

Bases: SenderSequences

Sender sequences of model dam.

The following classes are selected:

D() Water demand [m³/s].
S() Required water supply [m³/s].
R() Required water relief [m³/s].

class hydpy.models.dam.dam_senders.D(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: SenderSequence

Water demand [m³/s].

Calculated by the method:: Pass_MissingRemoteRelease_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'd'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_senders.S(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: SenderSequence

Required water supply [m³/s].

Calculated by the method:: Pass_RequiredRemoteSupply_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 's'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_senders.R(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]¶

Bases: SenderSequence

Required water relief [m³/s].

Calculated by the method:: Pass_AllowedRemoteRelief_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'r'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

Aide sequences¶

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

Bases: AideSequences

Aide sequences of model dam.

The following classes are selected:

SurfaceArea() Surface area [km²].
AllowedDischarge() Discharge threshold that should not be overcut by the actual discharge [m³/s].
AllowedWaterLevel() The water level at the end of a simulation step that would follow from applying the allowed water level drop [m].

class hydpy.models.dam.dam_aides.SurfaceArea(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: AideSequence

Surface area [km²].

Calculated by the method:: Calc_SurfaceArea_V1
Required by the methods:: Calc_AllowedDischarge_V1 Calc_AllowedDischarge_V2

NDIM: int = 0¶

NUMERIC: bool = True¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'surfacearea'¶: Name of the variable in lowercase letters.

unit: str = 'km²'¶: Unit of the variable.

class hydpy.models.dam.dam_aides.AllowedDischarge(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: AideSequence

Discharge threshold that should not be overcut by the actual discharge [m³/s].

Calculated by the methods:
Calc_AllowedDischarge_V1 Calc_AllowedDischarge_V2 Calc_AllowedDischarge_V3

Required by the methods:
Calc_ActualRelease_V3 Calc_AimedRelease_WaterVolume_V1 Calc_Outflow_V2

NDIM: int = 0¶

NUMERIC: bool = True¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'alloweddischarge'¶: Name of the variable in lowercase letters.

unit: str = 'm³/s'¶: Unit of the variable.

class hydpy.models.dam.dam_aides.AllowedWaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶

Bases: AideSequence

The water level at the end of a simulation step that would follow from applying the allowed water level drop [m].

Calculated by the method:
Calc_AllowedWaterLevel_V1

Required by the methods:
Calc_AllowedDischarge_V3 Return_WaterLevelError_V1

NDIM: int = 0¶

NUMERIC: bool = True¶

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)¶

name: str = 'allowedwaterlevel'¶: Name of the variable in lowercase letters.

unit: str = 'm'¶: Unit of the variable.

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

Bases: AideSequences

Aide sequences of model dam.

The following classes are selected:

SurfaceArea() Surface area [km²].
AllowedDischarge() Discharge threshold that should not be overcut by the actual discharge [m³/s].
AllowedWaterLevel() The water level at the end of a simulation step that would follow from applying the allowed water level drop [m].

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

Bases: SubParameters

Control parameters of model dam.

The following classes are selected:

SurfaceArea() Average size of the water surface [km²].
CatchmentArea() Size of the catchment draining into the dam [km²].
NmbLogEntries() Number of log entries for certain variables [-].
CorrectionPrecipitation() Precipitation correction factor [-].
CorrectionEvaporation() Evaporation correction factor [-].
WeightEvaporation() Time weighting factor for evaporation [-].
RemoteDischargeMinimum() Discharge threshold of a cross-section far downstream not to be undercut by the actual discharge [m³/s].
RemoteDischargeSafety() Safety factor for reducing the risk of insufficient water release [m³/s].
WaterLevel2PossibleRemoteRelief() An interpolation function describing the relationship between water level and the highest possible water release used to relieve the dam during high flow conditions [-].
RemoteReliefTolerance() A tolerance value for PossibleRemoteRelief [m³/s].
NearDischargeMinimumThreshold() Discharge threshold of a cross-section near the dam not to be undercut by the actual discharge [m³/s].
NearDischargeMinimumTolerance() A tolerance value for the “near discharge minimum” [m³/s].
MinimumRelease() Minimum water release [m³/s].
RestrictTargetedRelease() A flag indicating whether low flow variability has to be preserved or not [-].
WaterVolumeMinimumThreshold() The minimum operating water volume of the dam [million m³].
WaterLevelMinimumThreshold() The minimum operating water level of the dam [m].
WaterLevelMinimumTolerance() A tolerance value for the minimum operating water level [m].
WaterLevelMaximumThreshold() The water level not to be exceeded [m].
WaterLevelMaximumTolerance() A tolerance value for the water level maximum [m].
RemoteWaterLevelMaximumThreshold() The remote water level not to be exceeded [m].
RemoteWaterLevelMaximumTolerance() Tolerance value for the remote water level maximum [m].
ThresholdEvaporation() The water level at which actual evaporation is 50 % of potential evaporation [m].
ToleranceEvaporation() A tolerance value defining the steepness of the transition of actual evaporation between zero and potential evaporation [m].
WaterLevelMinimumRemoteThreshold() The minimum operating water level of the dam regarding remote water supply [m].
WaterLevelMinimumRemoteTolerance() A tolerance value for the minimum operating water level regarding remote water supply [m].
HighestRemoteRelief() The highest possible relief discharge from another location [m³/s].
WaterLevelReliefThreshold() The threshold water level of the dam regarding the allowed relief discharge from another location [m].
WaterLevelReliefTolerance() A tolerance value for parameter WaterLevelReliefThreshold [m].
HighestRemoteSupply() The highest possible supply discharge from another location [m³/s].
WaterLevelSupplyThreshold() The threshold water level of the dam regarding the required supply discharge from another location [m].
WaterLevelSupplyTolerance() A tolerance value for parameter WaterLevelSupplyThreshold [m].
HighestRemoteDischarge() The highest possible discharge between two remote locations [m³/s].
HighestRemoteTolerance() Smoothing parameter associated with HighestRemoteDischarge [m³/s].
WaterVolume2WaterLevel() An interpolation function that describes the relationship between water level and water volume [-].
WaterLevel2FloodDischarge() An interpolation function that describesg the relationship between flood discharge and water volume [-].
WaterLevelDifference2MaxForcedDischarge() An interpolation function that describes the relationship between the highest possible forced discharge and the water level difference [-].
WaterLevelDifference2MaxFreeDischarge() An interpolation function that describes the relationship between the highest possible free discharge and the water level difference [-].
AllowedWaterLevelDrop() The highest allowed water level decrease [m/T].
AllowedRelease() The maximum water release not causing any harm downstream [m³/s].
TargetVolume() The desired volume of water required within the dam at specific times of the year [Mio. m³].
TargetRangeAbsolute() The absolute interpolation range related to parameter TargetVolume [Mio. m³].
TargetRangeRelative() The relative interpolation range related to parameter TargetVolume [-].
MaximumVolume() Maximum storable volume of water where uncontrolled discharge can be prevented [Mio. m³].
VolumeTolerance() Smoothing parameter for volume-related smoothing operations [Mio. m³].
DischargeTolerance() Smoothing parameter for discharge-related smoothing operations [m³/s].
CrestLevel() The crest level of a weir [m].
CrestLevelTolerance() A tolerance value for the crest level of a weir [m].
NmbSafeReleaseModels() The number of submodels that suggest release values that serve for flood protection at remote locations [-].
Commission() Commission date [-].

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

Bases: SubParameters

Derived parameters of model dam.

The following classes are selected:

TOY() References the timeofyear index array provided by the instance of class Indexer available in module pub [-].
Seconds() Length of the actual simulation step size [s].
InputFactor() Factor for converting meteorological input from mm/T to million m³/s.
RemoteDischargeSmoothPar() Smoothing parameter to be derived from RemoteDischargeSafety [m³/s].
NearDischargeMinimumSmoothPar1() Smoothing parameter to be derived from NearDischargeMinimumThreshold for smoothing kernel smooth_logistic1() [m³/s].
NearDischargeMinimumSmoothPar2() Smoothing parameter to be derived from NearDischargeMinimumThreshold for smoothing kernel smooth_logistic2() [m³/s].
WaterLevelMinimumSmoothPar() Smoothing parameter to be derived from WaterLevelMinimumTolerance for smoothing kernel smooth_logistic1() [m].
WaterLevelMaximumSmoothPar() Smoothing parameter to be derived from WaterLevelMaximumTolerance for smoothing kernel smooth_logistic1() [m].
RemoteWaterLevelMaximumSmoothPar() Smoothing parameter to be derived from RemoteWaterLevelMaximumTolerance for smoothing kernel smooth_logistic1() [m].
SmoothParEvaporation() Smoothing parameter to be derived from ToleranceEvaporation for smoothing kernel smooth_logistic1() [m].
WaterLevelMinimumRemoteSmoothPar() Smoothing parameter to be derived from WaterLevelMinimumRemoteTolerance [m].
WaterLevelReliefSmoothPar() Smoothing parameter to be derived from WaterLevelReliefTolerance for smoothing kernel smooth_logistic1() [m³/s].
WaterLevelSupplySmoothPar() Smoothing parameter to be derived from WaterLevelSupplyTolerance for smoothing kernel smooth_logistic1() [m³/s].
HighestRemoteSmoothPar() Smoothing parameter to be derived from HighestRemoteTolerance for smoothing kernel smooth_min1() [m³/s].
VolumeSmoothParLog1() Smoothing parameter to be derived from VolumeTolerance for smoothing kernel smooth_logistic1() [million m³].
VolumeSmoothParLog2() Smoothing parameter to be derived from VolumeTolerance for smoothing kernel smooth_logistic2() [million m³].
DischargeSmoothPar() Smoothing parameter to be derived from DischargeTolerance for smoothing kernels smooth_logistic2(), smooth_min1(), and smooth_max1() [m³/s].
CrestLevelSmoothPar() Smoothing parameter to be derived from CrestLevelTolerance for smoothing kernel smooth_max1() [m].

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

Bases: FactorSequences

Factor sequences of model dam.

The following classes are selected:

WaterLevel() Water level [m].
OuterWaterLevel() The water level directly below the dam [m].
RemoteWaterLevel() The water level at a remote location [m].
WaterLevelDifference() Difference between the inner and the outer water level [m].
EffectiveWaterLevelDifference() Effective difference between the inner and the outer water level [m].

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

Bases: FluxSequences

Flux sequences of model dam.

The following classes are selected:

Precipitation() Precipitation [mm].
AdjustedPrecipitation() Adjusted precipitation [m³/s].
PotentialEvaporation() Potential evaporation [mm/T].
AdjustedEvaporation() Adjusted evaporation [m³/s].
ActualEvaporation() Actual evaporation [m³/s].
Inflow() Total inflow [m³/s].
Exchange() Water exchange with another location [m³/s].
TotalRemoteDischarge() Total discharge at a cross-section far downstream [m³/s].
NaturalRemoteDischarge() Natural discharge at a cross-section far downstream [m³/s].
RemoteDemand() Discharge demand at a cross-section far downstream [m³/s].
RemoteFailure() Difference between the actual and the required discharge at a cross-section far downstream [m³/s].
RequiredRemoteRelease() Water release considered appropriate to reduce drought events at cross-sections far downstream [m³/s].
AllowedRemoteRelief() Allowed discharge to relieve a dam during high flow conditions [m³/s].
RequiredRemoteSupply() Required water supply, for example, to fill a dam during low water conditions [m³/s].
PossibleRemoteRelief() Maximum possible water release to a remote location to relieve the dam during high flow conditions [m³/s].
ActualRemoteRelief() Actual water release to a remote location to relieve the dam during high flow conditions [m³/s].
RequiredRelease() Required water release for reducing drought events downstream [m³/s].
TargetedRelease() The targeted water release for reducing drought events downstream after taking both the required release and additional low flow regulations into account [m³/s].
ActualRelease() Actual water release thought for reducing drought events downstream [m³/s].
MissingRemoteRelease() Amount of the required remote demand not met by the actual release [m³/s].
ActualRemoteRelease() Actual water release thought for arbitrary “remote” purposes [m³/s].
SafeRelease() Water release that is considered safe in terms of flood protection [m³/s].
AimedRelease() Ideal controlled water release [m³/s].
UnavoidableRelease() Water release that cannot be avoided due to limited storage capacity [m³/s].
FloodDischarge() Water release associated with flood events [m³/s].
FreeDischarge() Free water release through structures as flap sluice gates [m³/s].
MaxForcedDischarge() The currently highest possible forced water release through structures as pumps [m³/s].
MaxFreeDischarge() The currently highest possible free water release through structures as pumps [m³/s].
ForcedDischarge() Forced water release through structures as pumps [m³/s].
Outflow() Total outflow [m³/s].

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

Bases: InletSequences

Inlet sequences of model dam.

The following classes are selected:

Q() Inflow [m³/s].
S() Actual water supply [m³/s].
R() Actual water relief [m³/s].
E() Bidirectional water exchange [m³/s].

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

Bases: LogSequences

Log sequences of model dam.

The following classes are selected:

LoggedTotalRemoteDischarge() Logged discharge values from somewhere else [m³/s].
LoggedOutflow() Logged discharge values from the dam itself [m³/s].
LoggedAdjustedEvaporation() Logged adjusted evaporation [m³/s].
LoggedRequiredRemoteRelease() Logged required discharge values computed by another model [m³/s].
LoggedAllowedRemoteRelief() Logged allowed discharge values computed by another model [m³/s].
LoggedOuterWaterLevel() Logged water level directly below the dam [m].
LoggedRemoteWaterLevel() Logged water level at a remote location [m].

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

Bases: OutletSequences

Outlet sequences of model dam.

The following classes are selected:

Q() Outflow [m³/s].
S() Actual water supply [m³/s].
R() Actual water relief [m³/s].

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

Bases: ReceiverSequences

Receiver sequences of model dam.

The following classes are selected:

Q() Remote discharge [m³/s].
D() Water demand [m³/s].
S() Required water supply [m³/s].
R() Allowed water relief [m³/s].
OWL() The water level directly below the dam [m].
RWL() The water level at a remote location [m].

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

Bases: SenderSequences

Sender sequences of model dam.

The following classes are selected:

D() Water demand [m³/s].
S() Required water supply [m³/s].
R() Required water relief [m³/s].

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

Bases: SubParameters

Solver parameters of model dam.

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.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶

Bases: StateSequences

State sequences of model dam.

The following classes are selected:

WaterVolume() Water volume [million m³].

Table of Contents

Previous topic

Next topic

This Page

Versions

HydPy-Dam (base model)¶

Method Features¶

Parameter Features¶

Control parameters¶

Derived parameters¶

Solver parameters¶

Sequence Features¶

Factor sequences¶

Flux sequences¶

State sequences¶

Log sequences¶

Inlet sequences¶

Outlet sequences¶

Receiver sequences¶

Sender sequences¶

Aide sequences¶