HydPy-Dam-Pump-Sluice (pumping station with sluice model)¶
dam_pump_sluice
combines the “forced discharge” component of dam_pump
with the
“free discharge” component of dam_sluice
.
Integration tests¶
Note
When new to HydPy, consider reading section Integration Tests first.
We take all of the following settings from the documentation on the application models
dam_pump
and dam_sluice
:
>>> from hydpy import IntegrationTest, Element, Node, pub, round_
>>> pub.timegrids = "2000-01-01", "2000-01-21", "1d"
>>> from hydpy.aliases import dam_receivers_OWL, dam_receivers_RWL
>>> inflow = Node("inflow")
>>> outflow = Node("outflow")
>>> outer = Node("outer", variable=dam_receivers_OWL)
>>> remote = Node("remote", variable=dam_receivers_RWL)
>>> dam = Element("dam", inlets=inflow, outlets=outflow, receivers=(outer, remote))
>>> from hydpy.models.dam_pump_sluice import *
>>> parameterstep()
>>> dam.model = model
>>> surfacearea(1.44)
>>> catchmentarea(86.4)
>>> watervolume2waterlevel(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 1.0]))
>>> waterlevelmaximumthreshold(1.0)
>>> waterlevelmaximumtolerance(0.1)
>>> remotewaterlevelmaximumthreshold(2.0)
>>> remotewaterlevelmaximumtolerance(0.1)
>>> crestlevel(1.0)
>>> crestleveltolerance(0.1)
>>> correctionprecipitation(1.0)
>>> correctionevaporation(1.0)
>>> weightevaporation(0.8)
>>> thresholdevaporation(0.0)
>>> toleranceevaporation(0.001)
>>> with model.add_precipmodel_v2("meteo_precip_io"):
... precipitationfactor(1.0)
>>> with model.add_pemodel_v1("evap_ret_io"):
... evapotranspirationfactor(1.0)
>>> test = IntegrationTest(dam)
>>> test.dateformat = "%d.%m."
>>> test.plotting_options.axis1 = fluxes.inflow, fluxes.outflow
>>> test.plotting_options.axis2 = factors.waterlevel, factors.outerwaterlevel, factors.remotewaterlevel
>>> test.inits = [(states.watervolume, 0.0),
... (logs.loggedadjustedevaporation, 0.0),
... (logs.loggedouterwaterlevel, 0.0),
... (logs.loggedremotewaterlevel, 0.0)]
>>> test.reset_inits()
>>> conditions = model.conditions
>>> model.precipmodel.sequences.inputs.precipitation.series = 2.0
>>> model.pemodel.sequences.inputs.referenceevapotranspiration.series = 1.0
>>> inflow.sequences.sim.series = 2.0
>>> outer.sequences.sim.series = 0.0
>>> remote.sequences.sim.series = numpy.linspace(0.0, 3.0, 20)
pump only¶
First, we demonstrate the proper implementation of the “forced discharge” components by
enabling them, like in the drainage example of application model
dam_pump
, while turning off the “free discharge” component:
>>> waterleveldifference2maxforceddischarge(PPoly.from_data(xs=[0.0], ys=[1.0]))
>>> waterleveldifference2maxfreedischarge(PPoly.from_data(xs=[0.0], ys=[0.0]))
To reproduce the results of dam_pump
exactly, we must set DischargeTolerance
to
zero (see the critical remark at the end of the documentation on method
Calc_FreeDischarge_V1
):
>>> dischargetolerance(0.0)
The following results are identical to those of the drainage example:
>>> test("dam_pump_sluice_pump_only")
Click to see the table
Click to see the graph
There is no indication of an error in the water balance:
>>> round_(model.check_waterbalance(conditions))
0.0
sluice only¶
Next, we switch from pure “forced discharge” to pure “free discharge” according to the
drainage example on application model dam_sluice
:
>>> waterleveldifference2maxforceddischarge(PPoly.from_data(xs=[0.0], ys=[0.0]))
>>> waterleveldifference2maxfreedischarge(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 1.0]))
>>> dischargetolerance(0.1)
The following results are identical to those of the drainage example:
>>> test("dam_pump_sluice_sluice_only")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0
pump and sluice¶
The next example shows how dam_pump_sluice
calculates both discharge types
simultaneously:
>>> waterleveldifference2maxforceddischarge(PPoly.from_data(xs=[0.0], ys=[1.0]))
>>> test("dam_pump_sluice_pump_and_sluice")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0
irrigation and sluice¶
The last example shows how MaxForcedDischarge
calculates both discharge types
simultaneously but uses a negative value for maxforceddischarge (resulting in reverse flow direction,
e.g. to simulate irrigation processes):
>>> waterleveldifference2maxforceddischarge(PPoly.from_data(xs=[0.0], ys=[-1.0]))
>>> waterlevelmaximumthreshold(1.5)
>>> remotewaterlevelmaximumthreshold(0.5)
>>> test("dam_pump_sluice_irrigation_and_sluice")
Click to see the table
Click to see the graph
>>> round_(model.check_waterbalance(conditions))
0.0
- class hydpy.models.dam_pump_sluice.Model[source]¶
Bases:
ELSModel
,MixinSimpleWaterBalance
,Main_PrecipModel_V2
,Main_PEModel_V1
HydPy-Dam-Pump-Sluice (pumping station with sluice model).
- The following “receiver update methods” are called in the given sequence before performing a simulation step:
Pick_LoggedOuterWaterLevel_V1
Update the receiver sequenceLoggedOuterWaterLevel
.Pick_LoggedRemoteWaterLevel_V1
Update the receiver sequenceLoggedRemoteWaterLevel
.
- 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.
- The following methods define the relevant components of a system of ODE equations (e.g. direct runoff):
Calc_AdjustedPrecipitation_V1
Adjust the given precipitation.Pick_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_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_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_ActualEvaporation_V1
Calculate the actual evaporation.Calc_Outflow_V5
Calculate the total outflow as the sum of free and forced discharge.
- 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.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.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], ...]] = ()¶
- numconsts: NumConstsELS¶
- numvars: NumVarsELS¶
- class hydpy.models.dam_pump_sluice.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Control parameters of model dam_pump_sluice.
- 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 [-].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].WaterVolume2WaterLevel()
An interpolation function that describes the relationship between water level 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 [-].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].
- class hydpy.models.dam_pump_sluice.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Derived parameters of model dam_pump_sluice.
- 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.WaterLevelMaximumSmoothPar()
Smoothing parameter to be derived fromWaterLevelMaximumTolerance
for smoothing kernelsmooth_logistic1()
[m].RemoteWaterLevelMaximumSmoothPar()
Smoothing parameter to be derived fromRemoteWaterLevelMaximumTolerance
for smoothing kernelsmooth_logistic1()
[m].SmoothParEvaporation()
Smoothing parameter to be derived fromToleranceEvaporation
for smoothing kernelsmooth_logistic1()
[m].DischargeSmoothPar()
Smoothing parameter to be derived fromDischargeTolerance
for smoothing kernelssmooth_logistic2()
,smooth_min1()
, andsmooth_max1()
[m³/s].CrestLevelSmoothPar()
Smoothing parameter to be derived fromCrestLevelTolerance
for smoothing kernelsmooth_max1()
[m].
- class hydpy.models.dam_pump_sluice.FactorSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
FactorSequences
Factor sequences of model dam_pump_sluice.
- 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_pump_sluice.FluxSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
FluxSequences
Flux sequences of model dam_pump_sluice.
- 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].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_pump_sluice.InletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
InletSequences
Inlet sequences of model dam_pump_sluice.
- The following classes are selected:
Q()
Inflow [m³/s].
- class hydpy.models.dam_pump_sluice.LogSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
LogSequences
Log sequences of model dam_pump_sluice.
- The following classes are selected:
LoggedAdjustedEvaporation()
Logged adjusted evaporation [m³/s].LoggedOuterWaterLevel()
Logged water level directly below the dam [m].LoggedRemoteWaterLevel()
Logged water level at a remote location [m].
- class hydpy.models.dam_pump_sluice.OutletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
OutletSequences
Outlet sequences of model dam_pump_sluice.
- The following classes are selected:
Q()
Outflow [m³/s].
- class hydpy.models.dam_pump_sluice.ReceiverSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
ReceiverSequences
Receiver sequences of model dam_pump_sluice.
- class hydpy.models.dam_pump_sluice.SolverParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Solver parameters of model dam_pump_sluice.
- 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_pump_sluice.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
StateSequences
State sequences of model dam_pump_sluice.
- The following classes are selected:
WaterVolume()
Water volume [million m³].