hbranch

The HydPy-H-Branch defines methods for branching single inflow values into multiple outflow values.

Method Features

class hydpy.models.hbranch.hbranch_model.Model[source]

Bases: AdHocModel

The HydPy-H-Branch model.

The following “inlet update methods” are called in the given sequence at the beginning of each 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:
nodenames: List[str]

Names of the output nodes.

connect() → None[source]

Connect the LinkSequence instances handled by the actual model to the NodeSequence instances handled by one inlet node and multiple oulet nodes.

The HydPy-H-Branch model passes multiple output values to different outlet nodes. This requires additional information regarding the direction of each output value. Therefore, node names are used as keywords. Assume the discharge values of both nodes inflow1 and inflow2 shall be branched to nodes outflow1 and outflow2 via element branch:

>>> from hydpy import Element, pub
>>> branch = Element("branch",
...                  inlets=["inflow1", "inflow2"],
...                  outlets=["outflow1", "outflow2"])

Then parameter YPoints relates different supporting points via its keyword arguments to the respective nodes:

>>> pub.timegrids = "2000-01-01", "2000-01-02", "1d"
>>> from hydpy.models.hbranch import *
>>> parameterstep()
>>> delta(0.0)
>>> xpoints(0.0, 3.0)
>>> ypoints(outflow1=[0.0, 1.0], outflow2=[0.0, 2.0])
>>> parameters.update()

After connecting the model with its element the total discharge value of nodes inflow1 and inflow2 can be properly divided:

>>> branch.model = model
>>> branch.inlets.inflow1.sequences.sim = 1.0
>>> branch.inlets.inflow2.sequences.sim = 5.0
>>> model.simulate(0)
>>> branch.outlets.outflow1.sequences.sim
sim(2.0)
>>> branch.outlets.outflow2.sequences.sim
sim(4.0)

In case of missing (or misspelled) outlet nodes, the following error is raised:

>>> branch.outlets.mutable = True
>>> del branch.outlets.outflow1
>>> parameters.update()
>>> model.connect()
Traceback (most recent call last):
...
RuntimeError: Model `hbranch` of element `branch` tried to connect to an outlet node named `outflow1`, which is not an available outlet node of element `branch`.

A missing reference to the corresponding element results in the following error message:

>>> model.element = None
>>> model.connect()
Traceback (most recent call last):
...
RuntimeError: Model  hbranch does not know the element it shall connect with so far.
class hydpy.models.hbranch.hbranch_model.Pick_OriginalInput_V1[source]

Bases: Method

Update OriginalInput based on Total.

Requires the inlet sequence:

Total

Calculates the flux sequence:

OriginalInput

Basic equation:

\(OriginalInput = \sum Total\)

class hydpy.models.hbranch.hbranch_model.Calc_AdjustedInput_V1[source]

Bases: Method

Adjust the original input data.

Requires the control parameters:

Delta Minimum

Requires the derived parameter:

MOY

Requires the flux sequence:

OriginalInput

Calculates the flux sequence:

AdjustedInput

Basic equation:

\(AdjustedInput = max(OriginalInput + Delta, Minimum)\)

Examples:

The degree of the input adjustment may vary monthly. Hence, we need to define a concrete initialisation period for the following examples:

>>> from hydpy import pub
>>> pub.timegrids = "2000-03-30", "2000-04-03", "1d"
>>> from hydpy.models.hbranch import *
>>> parameterstep()
>>> derived.moy.update()

Negative Delta values correspond to decreasing input:

>>> delta.mar = -1.0
>>> minimum(0.0)
>>> model.idx_sim = pub.timegrids.init["2000-03-31"]
>>> fluxes.originalinput = 1.5
>>> model.calc_adjustedinput_v1()
>>> fluxes.adjustedinput
adjustedinput(0.5)

The adjusted input values are never smaller than the threshold value defined by parameter Minimum:

>>> minimum(1.0)
>>> model.calc_adjustedinput_v1()
>>> fluxes.adjustedinput
adjustedinput(1.0)

Positive Delta values correspond to increasing input:

>>> model.idx_sim = pub.timegrids.init["2000-04-01"]
>>> delta.apr = 1.0
>>> fluxes.originalinput = 0.5
>>> model.calc_adjustedinput_v1()
>>> fluxes.adjustedinput
adjustedinput(1.5)
class hydpy.models.hbranch.hbranch_model.Calc_Outputs_V1[source]

Bases: Method

Perform the actual interpolation or extrapolation.

Requires the control parameters:

XPoints YPoints

Requires the derived parameters:

NmbPoints NmbBranches

Requires the flux sequence:

AdjustedInput

Calculates the flux sequence:

Outputs

Examples:

As a simple example, assume a weir directing all discharge into branch1 until reaching the capacity limit of 2 m³/s. hbranch_v1 redirects the discharge exceeding this threshold to branch2:

>>> from hydpy.models.hbranch import *
>>> parameterstep()
>>> xpoints(0.0, 2.0, 4.0)
>>> ypoints(branch1=[0.0, 2.0, 2.0],
...         branch2=[0.0, 0.0, 2.0])
>>> derived.nmbbranches.update()
>>> derived.nmbpoints.update()

Low discharge example (linear interpolation between the first two supporting point pairs):

>>> fluxes.adjustedinput = 1.
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(branch1=1.0,
        branch2=0.0)

Medium discharge example (linear interpolation between the second two supporting point pairs):

>>> fluxes.adjustedinput = 3.0
>>> model.calc_outputs_v1()
>>> print(fluxes.outputs)
outputs(branch1=2.0,
        branch2=1.0)

High discharge example (linear extrapolation beyond the second two supporting point pairs):

>>> fluxes.adjustedinput = 5.0
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(branch1=2.0,
        branch2=3.0)

Non-monotonous relationships and balance violations are allowed:

>>> xpoints(0.0, 2.0, 4.0, 6.0)
>>> ypoints(branch1=[0.0, 2.0, 0.0, 0.0],
...         branch2=[0.0, 0.0, 2.0, 4.0])
>>> derived.nmbbranches.update()
>>> derived.nmbpoints.update()
>>> fluxes.adjustedinput = 7.0
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(branch1=0.0,
        branch2=5.0)
class hydpy.models.hbranch.hbranch_model.Pass_Outputs_V1[source]

Bases: Method

Update Branched based on Outputs.

Requires the derived parameter:

NmbBranches

Requires the flux sequence:

Outputs

Calculates the outlet sequence:

Branched

Basic equation:

\(Branched_i = Outputs_i\)

Parameter Features

Control parameters

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

Bases: SubParameters

Control parameters of model hbranch.

The following classes are selected:

  • Delta() Monthly varying difference for increasing or decreasing the input [e.g. m³/s].

  • Minimum() The allowed minimum value of the adjusted input [e.g. m³/s].

  • XPoints() Supporting points for the independent input variable [e.g. m³/s].

  • YPoints() Supporting points for the dependent output variables [e.g. m³/s].

class hydpy.models.hbranch.hbranch_control.Delta(subvars: SubParameters)[source]

Bases: MonthParameter

Monthly varying difference for increasing or decreasing the input [e.g. m³/s].

Required by the method:

Calc_AdjustedInput_V1

TYPE

alias of float

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

class hydpy.models.hbranch.hbranch_control.Minimum(subvars: SubParameters)[source]

Bases: Parameter

The allowed minimum value of the adjusted input [e.g. m³/s].

Required by the method:

Calc_AdjustedInput_V1

NDIM: int = 0
TYPE

alias of float

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

class hydpy.models.hbranch.hbranch_control.XPoints(subvars: SubParameters)[source]

Bases: Parameter

Supporting points for the independent input variable [e.g. m³/s].

Required by the method:

Calc_Outputs_V1

There must be at least two supporting points, and they must be strictly monotonous. If not, XPoints raises the following errors:

>>> from hydpy.models.hbranch import *
>>> parameterstep()
>>> xpoints(1.0, 2.0)
>>> xpoints
xpoints(1.0, 2.0)

>>> xpoints(1.0)
Traceback (most recent call last):
...
ValueError: Branching via linear interpolation requires at least two supporting points, but parameter `xpoints` of element `?` received 1 value(s).

>>> xpoints(1.0, 2.0, 2.0, 3.0)
Traceback (most recent call last):
...
ValueError: The values of parameter `xpoints` of element `?` must be arranged strictly monotonous, which is not the case for the given values `1.0, 2.0, 2.0, and 3.0`.
NDIM: int = 1
TYPE

alias of float

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

class hydpy.models.hbranch.hbranch_control.YPoints(subvars: SubParameters)[source]

Bases: Parameter

Supporting points for the dependent output variables [e.g. m³/s].

Required by the method:

Calc_Outputs_V1

Preparing parameter YPoints requires consistency with parameter XPoints and the currently available Node objects.

>>> from hydpy.models.hbranch import *
>>> parameterstep("1d")
>>> ypoints
ypoints(?)

You need to prepare the parameter XPoints first:

>>> ypoints(1.0, 2.0)
Traceback (most recent call last):
...
RuntimeError: The shape of parameter `ypoints` of element `?` depends on the shape of parameter `xpoints`, which has not been defined so far.

>>> xpoints(1.0, 2.0, 3.0)

You need to supply the names of the output Node objects as keyword arguments:

>>> ypoints(1.0, 2.0)
Traceback (most recent call last):
...
ValueError: For parameter `ypoints` of element `?` no branches are defined.  Do this via keyword arguments as explained in the documentation.

The number of x and y supporting points must agree for all branches:

>>> ypoints(branch1=[1.0, 2.0],
...         branch2=[2.0, 4.0])
Traceback (most recent call last):
...
ValueError: Each branch requires the same number of supporting points as given for parameter `xpoints`, which is 3, but for branch `branch1` of parameter `ypoints` of element `?` 2 values are given.

>>> xpoints(1.0, 2.0)

When working in on actual project (indicated by a predefined project name), each branch name must correspond to a Node name:

>>> from hydpy import pub, Nodes
>>> pub.projectname = "test"
>>> nodes = Nodes("branch1")
>>> ypoints(branch1=[1.0, 2.0],
...         branch2=[2.0, 4.0])
Traceback (most recent call last):
...
RuntimeError: Parameter `ypoints` of element `?` is supposed to branch to node `branch2`, but such a node is not available.

We use the following general exception message for some unexpected errors:

>>> nodes = Nodes("branch1", "branch2")
>>> ypoints(branch1=[1.0, 2.0],
...         branch2="xy")
Traceback (most recent call last):
...
ValueError: While trying to set the values for branch `branch2` of parameter `ypoints` of element `?`, the following error occurred: could not convert string to float: 'xy'

Changing the number of branches during runtime might result in erroneous connections to the Node objects:

>>> ypoints(branch1=[1.0, 2.0],
...         branch2=[2.0, 4.0])
>>> ypoints
ypoints(branch1=[1.0, 2.0],
        branch2=[2.0, 4.0])
>>> ypoints(branch1=[1.0, 2.0])
Traceback (most recent call last):
...
RuntimeError: The number of branches of the hbranch model should not be changed during run time.  If you really need to do this, first initialize a new `branched` sequence and connect it to the respective outlet nodes properly.
NDIM: int = 2
TYPE

alias of float

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

Derived parameters

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

Bases: SubParameters

Derived parameters of model hbranch.

The following classes are selected:

  • MOY() References the “global” month of the year index array [-].

  • NmbBranches() The number of branches [-].

  • NmbPoints() The number of supporting points for linear interpolation [-].

class hydpy.models.hbranch.hbranch_derived.MOY(subvars: SubParameters)[source]

Bases: MOYParameter

References the “global” month of the year index array [-].

Required by the method:

Calc_AdjustedInput_V1

name: str = 'moy'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hbranch.hbranch_derived.NmbBranches(subvars: SubParameters)[source]

Bases: Parameter

The number of branches [-].

Required by the methods:

Calc_Outputs_V1 Pass_Outputs_V1

NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (1, None)
update()[source]

Determine the number of branches.

name: str = 'nmbbranches'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.hbranch.hbranch_derived.NmbPoints(subvars: SubParameters)[source]

Bases: Parameter

The number of supporting points for linear interpolation [-].

Required by the method:

Calc_Outputs_V1

NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (2, None)
update()[source]

Determine the number of points.

name: str = 'nmbpoints'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

Sequence Features

Flux sequences

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

Bases: FluxSequences

Flux sequences of model hbranch.

The following classes are selected:
class hydpy.models.hbranch.hbranch_fluxes.OriginalInput(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Unadjusted total input [e.g. m³/s].

Calculated by the method:

Pick_OriginalInput_V1

Required by the method:

Calc_AdjustedInput_V1

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

class hydpy.models.hbranch.hbranch_fluxes.AdjustedInput(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Adjusted total input [e.g. m³/s].

Calculated by the method:

Calc_AdjustedInput_V1

Required by the method:

Calc_Outputs_V1

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

class hydpy.models.hbranch.hbranch_fluxes.Outputs(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: FluxSequence

Branched outputs [e.g. m³/s].

Calculated by the method:

Calc_Outputs_V1

Required by the method:

Pass_Outputs_V1

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

Inlet sequences

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

Bases: InletSequences

Inlet sequences of model hbranch.

The following classes are selected:

  • Total() Total input [e.g. m³/s].

class hydpy.models.hbranch.hbranch_inlets.Total(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: InletSequence

Total input [e.g. m³/s].

Required by the method:

Pick_OriginalInput_V1

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

Outlet sequences

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

Bases: OutletSequences

Outlet sequences of model hbranch.

The following classes are selected:
class hydpy.models.hbranch.hbranch_outlets.Branched(subvars: ModelSequences[ModelSequence, FastAccess])[source]

Bases: OutletSequence

Branched outputs [e.g. m³/s].

Calculated by the method:

Pass_Outputs_V1

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

Name of the variable in lower case letters.

unit: str = 'e.g. m³/s'

Unit of the variable.

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

Bases: SubParameters

Control parameters of model hbranch.

The following classes are selected:

  • Delta() Monthly varying difference for increasing or decreasing the input [e.g. m³/s].

  • Minimum() The allowed minimum value of the adjusted input [e.g. m³/s].

  • XPoints() Supporting points for the independent input variable [e.g. m³/s].

  • YPoints() Supporting points for the dependent output variables [e.g. m³/s].

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

Bases: SubParameters

Derived parameters of model hbranch.

The following classes are selected:

  • MOY() References the “global” month of the year index array [-].

  • NmbBranches() The number of branches [-].

  • NmbPoints() The number of supporting points for linear interpolation [-].

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

Bases: FluxSequences

Flux sequences of model hbranch.

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

Bases: InletSequences

Inlet sequences of model hbranch.

The following classes are selected:

  • Total() Total input [e.g. m³/s].

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

Bases: OutletSequences

Outlet sequences of model hbranch.

The following classes are selected: