HydPy-Dam-V2 (dam model, version 2)¶
Application model dam_v002
is a simplification of dam_v001
. While most
functionalities are identical, dam_v002
does not calculate RequiredRemoteRelease
on
its own but picks this information from the simulation results of another model.
The following explanations focus on this difference. For further information on using
dam_v002
, please read the documentation on model dam_v001
.
Integration tests¶
Note
When new to HydPy, consider reading section Integration Tests first.
Each of the following examples repeats one example demonstrating a specific
functionality of application model dam_v001
. We define identical parameter values,
initial conditions, and input time series to achieve comparability. The sequence
RequiredRemoteRelease
requires special care. dam_v001
calculates its values based
on other information, but dam_v002
expects externally calculated values for it.
Hence, we use the tabulated results of the selected dam_v001
examples as the input
data of the node object demand, which passes this information to dam_v002
during
simulation. The limited precision of the copy-pasted RequiredRemoteRelease
values
causes tiny deviations between the results of both models.
The following time- and space-related setup is identical to the one of dam_v001
,
except we do not need to add other models to construct meaningful examples:
>>> from hydpy import pub
>>> pub.timegrids = "01.01.2000", "21.01.2000", "1d"
>>> from hydpy import Node
>>> inflow = Node("inflow")
>>> outflow = Node("outflow")
>>> demand = Node("demand", variable="D")
>>> from hydpy import Element
>>> dam = Element("dam", inlets=inflow, outlets=outflow, receivers=demand)
>>> from hydpy.models.dam_v002 import *
>>> parameterstep("1d")
>>> dam.model = model
We prepare an identical IntegrationTest
object:
>>> from hydpy import IntegrationTest
>>> test = IntegrationTest(dam)
>>> test.dateformat = "%d.%m."
>>> test.plotting_options.axis1 = fluxes.inflow, fluxes.outflow
>>> test.plotting_options.axis2 = states.watervolume
As initial conditions, dam_v002
requires logged values for the required remote
release instead of logged values for the total remote discharge and outflow. Following
the above reasoning, we copy-paste the first value of the “requiredremoterelease”
column that is identical for all drought-related calculations performed by dam_v001
:
>>> test.inits=((states.watervolume, 0.0),
... (logs.loggedadjustedevaporation, 0.0),
... (logs.loggedrequiredremoterelease, 0.005))
For a start, ihe inflow is constant again:
>>> inflow.sequences.sim.series = 1.0
dam_v002
implements fewer parameters than dam_v001
. Besides that, all parameter
settings are identical:
>>> watervolume2waterlevel(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 0.25]))
>>> waterlevel2flooddischarge(PPoly.from_data(xs=[0.0], ys=[0.0]))
>>> catchmentarea(86.4)
>>> neardischargeminimumthreshold(0.2)
>>> neardischargeminimumtolerance(0.2)
>>> waterlevelminimumthreshold(0.0)
>>> waterlevelminimumtolerance(0.0)
>>> restricttargetedrelease(True)
>>> surfacearea(1.44)
>>> correctionprecipitation(1.2)
>>> correctionevaporation(1.2)
>>> weightevaporation(0.8)
>>> thresholdevaporation(0.0)
>>> toleranceevaporation(0.001)
smooth near minimum¶
This example repeats the smooth near minimum example of application
model dam_v001
. We use the values of RequiredRemoteRelease
calculated by
dam_v001
, as explained above:
>>> demand.sequences.sim.series = [
... 0.008588, 0.010053, 0.013858, 0.027322, 0.064075, 0.235523, 0.470414,
... 0.735001, 0.891263, 0.696325, 0.349797, 0.105231, 0.111928, 0.240436,
... 0.229369, 0.058622, 0.016958, 0.008447, 0.004155, 0.0]
Note that the first tabulated value (0.005 m³/s) serves as an initial condition, and we have to assign the following nineteen values to the time series of the demand node. The last value of the node’s time series is of no importance. We arbitrarily set it to 0.0 m³/s.
The test results confirm that both models behave identically under low flow conditions for a “near” and a “remote” need for water supply:
>>> test("dam_v002_smooth_near_minimum")
Click to see the table
Click to see the graph
restriction enabled¶
This example repeats the restriction enabled example of application
model dam_v001
. We update the time series of the inflow and the required remote
release accordingly:
>>> inflow.sequences.sim.series[10:] = 0.1
>>> demand.sequences.sim.series = [
... 0.008746, 0.010632, 0.015099, 0.03006, 0.068641, 0.242578, 0.474285,
... 0.784512, 0.95036, 0.35, 0.034564, 0.299482, 0.585979, 0.557422,
... 0.229369, 0.142578, 0.068641, 0.029844, 0.012348, 0.0]
>>> neardischargeminimumtolerance(0.0)
The recalculation confirms that the restriction on releasing water when there is little
inflow works as explained for model dam_v001
:
>>> test("dam_v002_restriction_enabled")
Click to see the table
Click to see the graph
smooth stage minimum¶
This example repeats the smooth stage minimum example of application
model dam_v001
. We update parameters NearDischargeMinimumThreshold
,
WaterLevelMinimumThreshold
, and WaterLevelMinimumTolerance
, as well as the time
series of the inflow and the required remote release, accordingly:
>>> inflow.sequences.sim.series = numpy.linspace(0.2, 0.0, 20)
>>> neardischargeminimumthreshold(0.0)
>>> waterlevelminimumthreshold(0.005)
>>> waterlevelminimumtolerance(0.01)
>>> demand.sequences.sim.series = [
... 0.01232, 0.029323, 0.064084, 0.120198, 0.247367, 0.45567, 0.608464,
... 0.537314, 0.629775, 0.744091, 0.82219, 0.841916, 0.701812, 0.533258,
... 0.351863, 0.185207, 0.107697, 0.055458, 0.025948, 0.0]
dam_v002
deals with limited water availability, as already known from dam_v001
:
>>> test("dam_v002_smooth_stage_minimum")
Click to see the table
Click to see the graph
evaporation¶
This example repeats the evaporation example of application model
dam_v001
. We add an evap_ret_io
submodel and update the time series of the
required remote release time series accordingly:
>>> with model.add_pemodel_v1("evap_ret_io") as pemodel:
... evapotranspirationfactor(1.0)
>>> pemodel.prepare_inputseries()
>>> pemodel.sequences.inputs.referenceevapotranspiration.series = 10 * [1.0] + 10 * [5.0]
>>> demand.sequences.sim.series = [
... 0.012321, 0.029352, 0.064305, 0.120897, 0.248435, 0.453671, 0.585089,
... 0.550583, 0.694398, 0.784979, 0.81852, 0.840207, 0.72592, 0.575373,
... 0.386003, 0.198088, 0.113577, 0.05798, 0.026921, 0.0]
dam_v002
uses the evaporation values discussed for dam_v001
:
>>> test("dam_v002_evaporation")
Click to see the table
Click to see the graph
>>> del model.pemodel
flood retention¶
This example repeats the flood retention example of application model
dam_v001
. We use the same parameter and input time series configuration:
>>> neardischargeminimumthreshold(0.0)
>>> neardischargeminimumtolerance(0.0)
>>> waterlevelminimumthreshold(0.0)
>>> waterlevelminimumtolerance(0.0)
>>> waterlevel2flooddischarge(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 2.5]))
>>> neardischargeminimumthreshold(0.0)
>>> with model.add_precipmodel_v2("meteo_precip_io") as precipmodel:
... precipitationfactor(1.0)
>>> precipmodel.prepare_inputseries()
>>> precipmodel.sequences.inputs.precipitation.series = [
... 0.0, 50.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
... 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
>>> inflow.sequences.sim.series = [0.0, 0.0, 5.0, 9.0, 8.0, 5.0, 3.0, 2.0, 1.0, 0.0,
... 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
>>> demand.sequences.sim.series = 0.0
>>> test.inits.loggedrequiredremoterelease = 0.0
The recalculation results confirm the equality of both models for high-flow conditions:
>>> test("dam_v002_flood_retention")
Click to see the table
Click to see the graph
- class hydpy.models.dam_v002.Model[source]¶
Bases:
Main_PrecipModel_V2
,Main_PEModel_V1
HydPy-Dam-V2 (dam model, version 2).
- The following “receiver update methods” are called in the given sequence before performing a simulation step:
Pic_LoggedRequiredRemoteRelease_V1
Update the receiver sequenceLoggedRequiredRemoteRelease
.
- 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 thePrecipModel_V2
interface determine precipitation.Calc_PotentialEvaporation_V1
If available, let a submodel that complies with thePETModel_V1
interface determine potential evaporation.Calc_AdjustedEvaporation_V1
Adjust the given potential evaporation.Pic_Inflow_V1
Update the inlet sequenceInflow
.Calc_RequiredRemoteRelease_V2
Get the required remote release of the last simulation step.Calc_RequiredRelease_V1
Calculate the total water release (immediately and far 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):
Calc_AdjustedPrecipitation_V1
Adjust the given precipitation.Pic_Inflow_V1
Update the inlet sequenceInflow
.Calc_WaterLevel_V1
Determine the water level based on an interpolation approach approximating the relationship between water volume and water level.Calc_ActualEvaporation_V1
Calculate the actual evaporation.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_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_Outflow_V1
Calculate the total outflow of the dam.
- 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.
- The following “outlet update methods” are called in the given sequence at the end of each simulation step:
Calc_WaterLevel_V1
Determine the water level based on an interpolation approach approximating the relationship between water volume and water level.Pass_Outflow_V1
Update the outlet link sequenceQ
.
- Users can hook submodels into the defined main model if they satisfy one of the following interfaces:
PrecipModel_V2
Simple interface for determining precipitation in one step.PETModel_V1
Simple interface for calculating all potential evapotranspiration values in one step.
- precipmodel: modeltools.SubmodelProperty¶
Optional submodel that complies with the following interface: PrecipModel_V2.
- pemodel: modeltools.SubmodelProperty¶
Optional submodel that complies with the following interface: PETModel_V1.
- REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()¶
- class hydpy.models.dam_v002.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Control parameters of model dam_v002.
- The following classes are selected:
SurfaceArea()
Average size of the water surface [km²].CatchmentArea()
Size of the catchment draining into the dam [km²].CorrectionPrecipitation()
Precipitation correction factor [-].CorrectionEvaporation()
Evaporation correction factor [-].WeightEvaporation()
Time weighting factor for evaporation [-].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].RestrictTargetedRelease()
A flag indicating whether low flow variability has to be preserved or not [-].WaterLevelMinimumThreshold()
The minimum operating water level of the dam [m].WaterLevelMinimumTolerance()
A tolerance value for the minimum operating water level [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].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 [-].
- class hydpy.models.dam_v002.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Derived parameters of model dam_v002.
- The following classes are selected:
TOY()
References thetimeofyear
index array provided by the instance of classIndexer
available in modulepub
[-].Seconds()
Length of the actual simulation step size [s].InputFactor()
Factor for converting meteorological input from mm/T to million m³/s.NearDischargeMinimumSmoothPar1()
Smoothing parameter to be derived fromNearDischargeMinimumThreshold
for smoothing kernelsmooth_logistic1()
[m³/s].NearDischargeMinimumSmoothPar2()
Smoothing parameter to be derived fromNearDischargeMinimumThreshold
for smoothing kernelsmooth_logistic2()
[m³/s].WaterLevelMinimumSmoothPar()
Smoothing parameter to be derived fromWaterLevelMinimumTolerance
for smoothing kernelsmooth_logistic1()
[m].SmoothParEvaporation()
Smoothing parameter to be derived fromToleranceEvaporation
for smoothing kernelsmooth_logistic1()
[m].
- class hydpy.models.dam_v002.FactorSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
FactorSequences
Factor sequences of model dam_v002.
- The following classes are selected:
WaterLevel()
Water level [m].
- class hydpy.models.dam_v002.FluxSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
FluxSequences
Flux sequences of model dam_v002.
- The following classes are selected:
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].RequiredRemoteRelease()
Water release considered appropriate to reduce drought events at cross-sections far downstream [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].FloodDischarge()
Water release associated with flood events [m³/s].Outflow()
Total outflow [m³/s].
- class hydpy.models.dam_v002.InletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
InletSequences
Inlet sequences of model dam_v002.
- The following classes are selected:
Q()
Inflow [m³/s].
- class hydpy.models.dam_v002.LogSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
LogSequences
Log sequences of model dam_v002.
- The following classes are selected:
LoggedAdjustedEvaporation()
Logged adjusted evaporation [m³/s].LoggedRequiredRemoteRelease()
Logged required discharge values computed by another model [m³/s].
- class hydpy.models.dam_v002.OutletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
OutletSequences
Outlet sequences of model dam_v002.
- The following classes are selected:
Q()
Outflow [m³/s].
- class hydpy.models.dam_v002.ReceiverSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
ReceiverSequences
Receiver sequences of model dam_v002.
- The following classes are selected:
D()
Water demand [m³/s].
- class hydpy.models.dam_v002.SolverParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Solver parameters of model dam_v002.
- The following classes are selected:
AbsErrorMax()
Absolute numerical error tolerance [m³/s].RelErrorMax()
Relative numerical error tolerance [1/T].RelDTMin()
Smallest relative integration time step size allowed [-].RelDTMax()
Largest relative integration time step size allowed [-].
- class hydpy.models.dam_v002.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
StateSequences
State sequences of model dam_v002.
- The following classes are selected:
WaterVolume()
Water volume [million m³].