exch

The HydPy-Exch base model provides features to implement helper models that enable other models to exchange data more freely.

Method Features

class hydpy.models.exch.exch_model.Model[source]

Bases: AdHocModel

HydPy-Exch base model.

The following “receiver update methods” are called in the given sequence before performing a simulation step:
The following “run methods” are called in the given sequence during each simulation step:
The following “outlet update methods” are called in the given sequence at the end of each simulation step:
class hydpy.models.exch.exch_model.Pic_LoggedWaterLevel_V1[source]

Bases: Method

Pic the logged water level from a receiver node.

Requires the receiver sequence:

L

Calculates the log sequence:

LoggedWaterLevel

Basic equation:

\(LoggedWaterLevel = L\)

class hydpy.models.exch.exch_model.Update_WaterLevel_V1[source]

Bases: Method

Update the factor sequence WaterLevel.

Requires the log sequence:

LoggedWaterLevel

Calculates the factor sequence:

WaterLevel

Basic equation:

\(WaterLevel = LoggedWaterLevel\)

Example:

>>> from hydpy.models.exch import *
>>> parameterstep()
>>> logs.loggedwaterlevel = 2.0, 4.0
>>> model.update_waterlevel_v1()
>>> factors.waterlevel
waterlevel(2.0, 4.0)
class hydpy.models.exch.exch_model.Calc_DeltaWaterLevel_V1[source]

Bases: Method

Calculate the effective difference of both water levels.

Requires the control parameter:

CrestHeight

Requires the factor sequence:

WaterLevel

Calculates the factor sequence:

DeltaWaterLevel

Basic equation:

\(DeltaWaterLevel = max(WaterLevel_0, CrestHeight) - max(WaterLevel_1, CrestHeight)\)

Examples:

“Effective difference” means that only the height above the crest counts. The first example illustrates this for fixed water levels and a variable crest height:

>>> from hydpy.models.exch import *
>>> parameterstep()
>>> from hydpy import UnitTest
>>> test = UnitTest(model=model,
...                 method=model.calc_deltawaterlevel_v1,
...                 last_example=5,
...                 parseqs=(control.crestheight, factors.deltawaterlevel))
>>> test.nexts.crestheight = 1.0, 2.0, 3.0, 4.0, 5.0
>>> factors.waterlevel = 4.0, 2.0
>>> test()
| ex. | crestheight | deltawaterlevel |
---------------------------------------
|   1 |         1.0 |             2.0 |
|   2 |         2.0 |             2.0 |
|   3 |         3.0 |             1.0 |
|   4 |         4.0 |             0.0 |
|   5 |         5.0 |             0.0 |

Method Calc_DeltaWaterLevel_V1 modifies the basic equation given above to also work for an inverse gradient:

>>> factors.waterlevel = 2.0, 4.0
>>> test()
| ex. | crestheight | deltawaterlevel |
---------------------------------------
|   1 |         1.0 |            -2.0 |
|   2 |         2.0 |            -2.0 |
|   3 |         3.0 |            -1.0 |
|   4 |         4.0 |             0.0 |
|   5 |         5.0 |             0.0 |
class hydpy.models.exch.exch_model.Calc_PotentialExchange_V1[source]

Bases: Method

Calculate the potential exchange that strictly follows the weir formula without taking any other limitations into account.

Requires the control parameters:

CrestWidth FlowCoefficient FlowExponent

Requires the factor sequence:

DeltaWaterLevel

Calculates the flux sequence:

PotentialExchange

Basic equation:

\(PotentialExchange = FlowCoefficient \cdot CrestWidth \cdot DeltaWaterLevel ^ {FlowExponent}\)

Examples:

Method Calc_PotentialExchange_V1 modifies the given basic equation to work for positive and negative gradients:

>>> from hydpy.models.exch import *
>>> parameterstep()
>>> crestwidth(3.0)
>>> flowcoefficient(0.5)
>>> flowexponent(2.0)
>>> factors.deltawaterlevel = 2.0
>>> model.calc_potentialexchange_v1()
>>> fluxes.potentialexchange
potentialexchange(6.0)

>>> factors.deltawaterlevel = -2.0
>>> model.calc_potentialexchange_v1()
>>> fluxes.potentialexchange
potentialexchange(-6.0)
class hydpy.models.exch.exch_model.Calc_ActualExchange_V1[source]

Bases: Method

Calculate the actual exchange.

Requires the control parameter:

AllowedExchange

Requires the flux sequence:

PotentialExchange

Calculates the flux sequence:

ActualExchange

Basic equation:

\(ActualExchange = min(PotentialExchange, AllowedExchange)\)

Examples:

Method Calc_ActualExchange_V1 modifies the given basic equation to work for positive and negative gradients:

>>> from hydpy.models.exch import *
>>> parameterstep()
>>> allowedexchange(2.0)
>>> fluxes.potentialexchange = 1.0
>>> model.calc_actualexchange_v1()
>>> fluxes.actualexchange
actualexchange(1.0)

>>> fluxes.potentialexchange = 3.0
>>> model.calc_actualexchange_v1()
>>> fluxes.actualexchange
actualexchange(2.0)

>>> fluxes.potentialexchange = -1.0
>>> model.calc_actualexchange_v1()
>>> fluxes.actualexchange
actualexchange(-1.0)

>>> fluxes.potentialexchange = -3.0
>>> model.calc_actualexchange_v1()
>>> fluxes.actualexchange
actualexchange(-2.0)
class hydpy.models.exch.exch_model.Pass_ActualExchange_V1[source]

Bases: Method

Pass the actual exchange to an outlet node.

Requires the flux sequence:

ActualExchange

Calculates the outlet sequence:

E

Basic equation:

\(E = ActualExchange\)

Parameter Features

Control parameters

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

Bases: SubParameters

Control parameters of model exch.

The following classes are selected:
class hydpy.models.exch.exch_control.CrestHeight(subvars: SubParameters)[source]

Bases: Parameter

Crest height [m].

Required by the method:

Calc_DeltaWaterLevel_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'crestheight'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.exch.exch_control.CrestWidth(subvars: SubParameters)[source]

Bases: Parameter

Crest width [m].

Required by the method:

Calc_PotentialExchange_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'crestwidth'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.exch.exch_control.FlowCoefficient(subvars: SubParameters)[source]

Bases: Parameter

Flow coefficient [-].

Required by the method:

Calc_PotentialExchange_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 0.62
name: str = 'flowcoefficient'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.exch.exch_control.FlowExponent(subvars: SubParameters)[source]

Bases: Parameter

Flow exponent [-].

Required by the method:

Calc_PotentialExchange_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.5
name: str = 'flowexponent'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.exch.exch_control.AllowedExchange(subvars: SubParameters)[source]

Bases: Parameter

The highest water exchange allowed [m³/s].

Required by the method:

Calc_ActualExchange_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
INIT: int | float | bool | None = 1.5
name: str = 'allowedexchange'

Name of the variable in lower case letters.

unit: str = 'm³/s'

Unit of the variable.

Sequence Features

Factor sequences

class hydpy.models.exch.FactorSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FactorSequences

Factor sequences of model exch.

The following classes are selected:
class hydpy.models.exch.exch_factors.WaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: MixinFixedShape, FactorSequence

Water level [m].

Calculated by the method:

Update_WaterLevel_V1

Required by the method:

Calc_DeltaWaterLevel_V1

After each simulation step, the value of WaterLevel corresponds to the value of the LoggedWaterLevel of the previous simulation step.

NDIM: int = 1
SHAPE: Tuple[int, ...] = (2,)
name: str = 'waterlevel'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.exch.exch_factors.DeltaWaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FactorSequence

Effective difference of the two water levels [m].

Calculated by the method:

Calc_DeltaWaterLevel_V1

Required by the method:

Calc_PotentialExchange_V1

After each simulation step, the value of DeltaWaterLevel corresponds to the value of the LoggedWaterLevel of the previous simulation step.

NDIM: int = 0
name: str = 'deltawaterlevel'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

Flux sequences

class hydpy.models.exch.FluxSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model exch.

The following classes are selected:
class hydpy.models.exch.exch_fluxes.PotentialExchange(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

The potential bidirectional water exchange [m³/s].

Calculated by the method:

Calc_PotentialExchange_V1

Required by the method:

Calc_ActualExchange_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'potentialexchange'

Name of the variable in lower case letters.

unit: str = 'm³/s'

Unit of the variable.

class hydpy.models.exch.exch_fluxes.ActualExchange(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

The actual bidirectional water exchange [m³/s].

Calculated by the method:

Calc_ActualExchange_V1

Required by the method:

Pass_ActualExchange_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'actualexchange'

Name of the variable in lower case letters.

unit: str = 'm³/s'

Unit of the variable.

Log sequences

class hydpy.models.exch.LogSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: LogSequences

Log sequences of model exch.

The following classes are selected:
class hydpy.models.exch.exch_logs.LoggedWaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: LogSequenceFixed

Logged water level [m].

Calculated by the method:

Pic_LoggedWaterLevel_V1

Required by the method:

Update_WaterLevel_V1

NUMERIC: bool = False
SHAPE: int = 2
name: str = 'loggedwaterlevel'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

Outlet sequences

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

Bases: OutletSequences

Outlet sequences of model exch.

The following classes are selected:

  • E() Bidirectional water exchange [m³].

class hydpy.models.exch.exch_outlets.E(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: OutletSequence

Bidirectional water exchange [m³].

Calculated by the method:

Pass_ActualExchange_V1

NDIM: int = 1
NUMERIC: bool = False
name: str = 'e'

Name of the variable in lower case letters.

unit: str = 'm³'

Unit of the variable.

Receiver sequences

class hydpy.models.exch.ReceiverSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: ReceiverSequences

Receiver sequences of model exch.

The following classes are selected:

  • L() Water level [m].

class hydpy.models.exch.exch_receivers.L(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: ReceiverSequence

Water level [m].

Required by the method:

Pic_LoggedWaterLevel_V1

NDIM: int = 1
NUMERIC: bool = False
name: str = 'l'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

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

Bases: SubParameters

Control parameters of model exch.

The following classes are selected:
class hydpy.models.exch.FactorSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FactorSequences

Factor sequences of model exch.

The following classes are selected:
class hydpy.models.exch.FluxSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model exch.

The following classes are selected:
class hydpy.models.exch.LogSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: LogSequences

Log sequences of model exch.

The following classes are selected:
class hydpy.models.exch.OutletSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: OutletSequences

Outlet sequences of model exch.

The following classes are selected:

  • E() Bidirectional water exchange [m³].

class hydpy.models.exch.ReceiverSequences(master: Sequences, cls_fastaccess: Type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: ReceiverSequences

Receiver sequences of model exch.

The following classes are selected:

  • L() Water level [m].