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:
The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:
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 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_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):
The following “outlet update methods” are called in the given sequence at the end of each simulation step:
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.

DOCNAME: DocName = ('Dam-Pump-Sluice', 'pumping station with sluice model')
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[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_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:
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:
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:
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:
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:
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.

The following classes are selected:

  • OWL() The water level directly below the dam [m].

  • RWL() The water level at a remote location [m].

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: