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:
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_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):
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-Sluice', '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[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_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:
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:
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:
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:
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:
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.

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_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: