HydPy-Exch-Water-Transfer-IO (submodel for transferring water based on external requests or volume-dependent rules)

exch_water_transfer_io is a submodel that adds a water transfer feature to “storage-type” main models like dam_llake and dam_lreservoir. These transfers can be positive (withdrawal from the storage) or negative (supply to the storage).

exch_water_transfer_io’s design agrees with LARSIM’s storage branching routine VSPE. It takes the requested transfer from the input sequence RequestedTransfer or, when no such external request is available (indicated preferably by inf or alternatively by nan), from volume-dependent interpolation rules defined by parameter VolTransferRules. All withdrawals, whether externally requested or rule-based, are restricted to a dynamically updated maximum discharge, which for dam_llake and dam_lreservoir follows from the allowed water level drop. Externally requested withdrawals and supplies are also limited by the water volume thresholds MinVol and MaxVol, respectively. VolTransferRules, MinVol, and MaxVol (and VolTol, see below) can vary seasonally.

exch_water_transfer_io connects to its own outlet node, to which it passes the determined water transfer. If parameter KeepWaterBalance is True, this water transfer always reflects the actual, storage-effective transfer. However, if KeepWaterBalance is False, exch_water_transfer_io passes available external requests unmodified, even if real withdrawal from or supply to the main model had to be reduced (justified by regarding them as measured and thus more certain than simulation results).

Note the tolerance parameters VolTol and QTol, which let exch_water_transfer_io react smoothly to the volume- and discharge-based restrictions mentioned above. This can make simulation results more realistic and the numerical solving of the main model’s ordinary differential equations more efficient (explained in more detail in the smooth near minimum example of dam_v001).

The water transfer example of dam_llake and the water transfer example of dam_lreservoir show how to apply exch_water_transfer_io.

class hydpy.models.exch_water_transfer_io.Model

Bases: AdHocModel, TransferModel_V1

HydPy-Exch-Water-Transfer-IO (submodel for transferring water based on external requests or volume-dependent rules).

The following interface methods are available to main models using the defined model as a submodel:

• Determine_Transfer_V1 Interface method for determining the water transfer based on the current water volume and the main model’s allowed discharge.

• Get_Transfer_V1 Interface method for querying the effective water transfer in m³/s.

• Set_Transfer_V1 Interface method to receive the final effective water transfer and pass the actual transfer to the outlet node.

The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:

• Return_AllowedTransfer_V1 Restrict withdrawals to the allowed discharge without turning them into supplies.

DOCNAME = ('Exch-Water-Transfer-IO', 'submodel for transferring water based on external requests or volume-dependent rules')

REUSABLE_METHODS = ()

class hydpy.models.exch_water_transfer_io.AideSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: AideSequences

Aide sequences of model exch_water_transfer_io.

The following classes are selected:

• EffectiveTransfer() Water transfer that affects the water balance of the main model [m³/s].

class hydpy.models.exch_water_transfer_io.ControlParameters(master: Parameters[TM_co], cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: ControlParameters

Control parameters of model exch_water_transfer_io.

The following classes are selected:

• KeepWaterBalance() Flag to indicate if too-high requested transfers should be reduced [-].

• MinVol() Minimum water volume that externally requested withdrawals should not undercut [million m³].

• MaxVol() Maximum water volume that externally requested supplies should not exceed [million m³].

• VolTol() Tolerance for smoothing the reduction of externally requested transfers at the water volume thresholds MinVol and MaxVol [million m³].

• QTol() Tolerance for smoothing the reduction of withdrawals to the main model’s allowed discharge [m³/s].

• VolTransferRules() Seasonally varying interpolation rules for calculating the water transfer based on the current water volume [m³/s].

class hydpy.models.exch_water_transfer_io.DerivedParameters(master: Parameters[TM_co], cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: DerivedParameters

Derived parameters of model exch_water_transfer_io.

The following classes are selected:

• TOY() References the timeofyear index array provided by the instance of class Indexer available in module pub [-].

• VolSmoothPar() Smoothing parameter to be derived from VolTol for smoothing kernel smooth_logistic1() [million m³].

• QSmoothPar() Smoothing parameter to be derived from QTol for smoothing kernels smooth_min1() and smooth_max1() [m³/s].

class hydpy.models.exch_water_transfer_io.InputSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: InputSequences

Input sequences of model exch_water_transfer_io.

The following classes are selected:

• RequestedTransfer() Externally requested water transfer [m³/s].

class hydpy.models.exch_water_transfer_io.OutletSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: OutletSequences

Outlet sequences of model exch_water_transfer_io.

The following classes are selected:

• ActualTransfer() Actual water transfer [m³/s].