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:
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.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_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.
- check_waterbalance(initial_conditions: dict[str, dict[str, dict[str, float | ndarray[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 modeldam_lreservoir
for some examples.
- REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()¶
- 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³].