HydPy-Dam-Sluice (sluice model)¶
dam_sluice
is similar to dam_pump
but is thought for modelling free flow through
sluices driven by differences between inner and outer water levels. Principally, users
can define arbitrary relationships via WaterLevelDifference2MaxFreeDischarge
,
including ones that allow for “negative outflow” so that dam_sluice
takes water from
the downstream model. However, be careful with that because, depending on the
downstream model’s type and the current conditions, negative inflows can cause
problems.
By default, dam_sluice
neither takes precipitation nor evaporation into account, but
you can add submodels that comply with the PrecipModel_V2
or PETModel_V1
interface
that supply this information.
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 model
dam_pump
:
>>> 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_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]))
>>> remotewaterlevelmaximumthreshold(2.0)
>>> remotewaterlevelmaximumtolerance(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)
The remaining parameters are specific to dam_sluice
.
We define a one-to-one relationship between the effective water level difference and the highest possible free discharge values:
>>> waterleveldifference2maxfreedischarge(PPoly.from_data(xs=[0.0, 1.0], ys=[0.0, 1.0]))
By setting the crest level to 1 m, only inner and outer water levels higher than one meter are “effective” (can cause inflow or outflow through the hydraulic structure):
>>> crestlevel(1.0)
>>> crestleveltolerance(0.1)
The smoothing parameter DischargeTolerance
is only relevant when the outflow must be
suppressed to not further increase to high water levels at a remote location (see
Calc_FreeDischarge_V1
):
>>> dischargetolerance(0.1)
drainage¶
The results of the following test run are pretty similar to those of the drainage example. Outflow starts again when the inner water level reaches 1 m, which is the crest level in this example. Afterwards, however, the outflow increases approximately linearly with the further rising water level, but this is more a (useful) difference in parameterisation than of the underlying equations. The implemented flood protection mechanism suppresses the outflow quite similarly in both examples:
>>> test("dam_sluice_drainage")
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
irrigation¶
The flow through the hydraulic structure can be negative, corresponding to irrigation instead of land drainage. We set the dam’s “normal” inflow (from upstream areas) to 0 m³/s and increase the outer water level to 2 m, which reverses the water level gradient:
>>> inflow.sequences.sim.series = 0.0
>>> outer.sequences.sim.series = 2.0
Now, the inner water level rises because of inflow from the area downstream. The remote water level still overshoots the threshold of 2 m, but this does not suppress the inflow, as water losses should never increase flood risks:
>>> test("dam_sluice_irrigation")
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
mixed¶
Finally, we reset the “normal” inflow to 2 m³/s but leave the outer water level at 2 m:
>>> inflow.sequences.sim.series = 2.0
This setting results in a “mixed” situation where initial inflow from downstream turns into outflow as soon as the inner water level exceeds the outer one:
>>> test("dam_sluice_mixed")
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
- class hydpy.models.dam_sluice.Model[source]¶
Bases:
Main_PrecipModel_V2
,Main_PEModel_V1
HydPy-Dam-Sluice (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_EffectiveWaterLevelDifference_V1
Calculate the “effective” difference between the inner and the outer water level above a threshold level.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_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_V4
Take the free discharge as the only outflow.
- 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_sluice.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Control parameters of model dam_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 [-].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 [-].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_sluice.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Derived parameters of model dam_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.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_sluice.FactorSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
FactorSequences
Factor sequences of model dam_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].EffectiveWaterLevelDifference()
Effective difference between the inner and the outer water level [m].
- class hydpy.models.dam_sluice.FluxSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
FluxSequences
Flux sequences of model dam_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].MaxFreeDischarge()
The currently highest possible free water release through structures as pumps [m³/s].Outflow()
Total outflow [m³/s].
- class hydpy.models.dam_sluice.InletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
InletSequences
Inlet sequences of model dam_sluice.
- The following classes are selected:
Q()
Inflow [m³/s].
- class hydpy.models.dam_sluice.LogSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
LogSequences
Log sequences of model dam_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_sluice.OutletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
OutletSequences
Outlet sequences of model dam_sluice.
- The following classes are selected:
Q()
Outflow [m³/s].
- class hydpy.models.dam_sluice.ReceiverSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
ReceiverSequences
Receiver sequences of model dam_sluice.
- class hydpy.models.dam_sluice.SolverParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
SubParameters
Solver parameters of model dam_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_sluice.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)¶
Bases:
StateSequences
State sequences of model dam_sluice.
- The following classes are selected:
WaterVolume()
Water volume [million m³].