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: hydpy.core.modeltools.AdHocModel

The HydPy-H-Branch model.

The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:

Pick_Input_V1 Updates Input based on Total.

The following “run methods” are called in the given sequence during each simulation step:

Calc_Outputs_V1 Performs the actual interpolation or extrapolation.

The following “outlet update methods” are called in the given sequence at the end of each simulation step:

Pass_Outputs_V1 Updates Branched based on Outputs.

connect()[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
>>> branch = Element("branch",
...                  inlets=["inflow1", "inflow2"],
...                  outlets=["outflow1", "outflow2"])

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

>>> from hydpy.models.hbranch import *
>>> parameterstep()
>>> 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`.

class hydpy.models.hbranch.hbranch_model.Calc_Outputs_V1[source]¶

Bases: hydpy.core.modeltools.Method

Performs the actual interpolation or extrapolation.

Requires the control parameters:: XPoints YPoints
Requires the derived parameters:: NmbPoints NmbBranches
Requires the flux sequence:: Input
Calculates the flux sequence:: Outputs

Examples:

As a simple example, assume a weir directing all discharge into branch1 until the capacity limit of 2 m³/s is reached. The discharge exceeding this threshold is directed into branch2:
>>> from hydpy.models.hbranch import *
>>> parameterstep()
>>> xpoints(0., 2., 4.)
>>> ypoints(branch1=[0., 2., 2.],
...         branch2=[0., 0., 2.])
>>> model.parameters.update()
Low discharge example (linear interpolation between the first two supporting point pairs):
>>> fluxes.input = 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.input = 3.
>>> 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.input = 5.
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(branch1=2.0,
        branch2=3.0)
Non-monotonous relationships and balance violations are allowed, e.g.:
>>> xpoints(0., 2., 4., 6.)
>>> ypoints(branch1=[0., 2., 0., 0.],
...         branch2=[0., 0., 2., 4.])
>>> model.parameters.update()
>>> fluxes.input = 7.
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(branch1=0.0,
        branch2=5.0)

ToDo Technical checks:

Note that method the name of sequence Input causes a false alarm here. It would be best to use a name not in conflict with Pythons’s input() statement:
>>> from hydpy.core.testtools import check_selectedvariables
>>> from hydpy.models.hbranch.hbranch_model import Calc_Outputs_V1
>>> print(check_selectedvariables(Calc_Outputs_V1))
Possibly erroneously selected (REQUIREDSEQUENCES): Input

class hydpy.models.hbranch.hbranch_model.Pick_Input_V1[source]¶

Bases: hydpy.core.modeltools.Method

Updates Input based on Total.

Requires the inlet sequence:: Total
Calculates the flux sequence:: Input
Basic equation:: \(Input = \sum Total\)

ToDo Technical checks:

Note that method the name of sequence Input causes a false alarm here. It would be best to use a name not in conflict with Pythons’s input() statement:
>>> from hydpy.core.testtools import check_selectedvariables
>>> from hydpy.models.hbranch.hbranch_model import Pick_Input_V1
>>> print(check_selectedvariables(Pick_Input_V1))
Possibly erroneously selected (RESULTSEQUENCES): Input

class hydpy.models.hbranch.hbranch_model.Pass_Outputs_V1[source]¶

Bases: hydpy.core.modeltools.Method

Updates 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: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Control parameters of model hbranch.

The following classes are selected:

XPoints() Supporting points for the independent input variable [eg. m³/s].
YPoints() Supporting points for the dependent output variables [eg. m³/s].

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

Bases: hydpy.core.variabletools.Variable[hydpy.core.parametertools.SubParameters, hydpy.core.parametertools.FastAccessParameter]

Supporting points for the independent input variable [eg. 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, the following errors are raised:

>>> 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¶

TIME: Optional[bool] = None¶

SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (None, None)¶

name: str = 'xpoints'¶

unit: str = 'eg. m³/s'¶

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

Bases: hydpy.core.variabletools.Variable[hydpy.core.parametertools.SubParameters, hydpy.core.parametertools.FastAccessParameter]

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

Required by the method:: Calc_Outputs_V1

Setting the values of parameter YPoints correctly requires consistency both with the values of parameter XPoints and the currently available Node objects. Read two following error messages to see what can go wrong, and how to prepare parameter YPoints correctly.

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

Parameter XPoints must be prepared 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)

The names of the Node objects the hbranch model is supposed to branch to must be supplied 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 an actual project (indicated by an 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.

A 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¶

TIME: Optional[bool] = None¶

SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (None, None)¶

name: str = 'ypoints'¶

unit: str = 'eg. m³/s'¶

Derived parameters¶

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

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Derived parameters of model hbranch.

The following classes are selected:

NmbBranches() Number of branches [-].
NmbPoints() Number of supporting points for linear interpolation [-].

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

Bases: hydpy.core.variabletools.Variable[hydpy.core.parametertools.SubParameters, hydpy.core.parametertools.FastAccessParameter]

Number of branches [-].

Required by the methods:: Calc_Outputs_V1 Pass_Outputs_V1

NDIM: int = 0¶

TYPE¶

TIME: Optional[bool] = None¶

SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (1, None)¶

update()[source]¶: Determine the number of branches

name: str = 'nmbbranches'¶

unit: str = '-'¶

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

Bases: hydpy.core.variabletools.Variable[hydpy.core.parametertools.SubParameters, hydpy.core.parametertools.FastAccessParameter]

Number of supporting points for linear interpolation [-].

Required by the method:: Calc_Outputs_V1

NDIM: int = 0¶

TYPE¶

TIME: Optional[bool] = None¶

SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (2, None)¶

update()[source]¶: Determine the number of points.

name: str = 'nmbpoints'¶

unit: str = '-'¶

Sequence Features¶

Flux sequences¶

class hydpy.models.hbranch.FluxSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.OutputSequences[FluxSequence]

Flux sequences of model hbranch.

The following classes are selected:

Input() Total input [e.g. m³/s].
Outputs() Branched outputs [e.g. m³/s].

class hydpy.models.hbranch.hbranch_fluxes.Input(subvars: SubVariablesType)[source]¶

Bases: hydpy.core.sequencetools.OutputSequence[hydpy.core.sequencetools.FluxSequences]

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

Calculated by the method:: Pick_Input_V1
Required by the method:: Calc_Outputs_V1

NDIM: int = 0¶

NUMERIC: bool = False¶

name: str = 'input'¶

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

class hydpy.models.hbranch.hbranch_fluxes.Outputs(subvars: SubVariablesType)[source]¶

Bases: hydpy.core.sequencetools.OutputSequence[hydpy.core.sequencetools.FluxSequences]

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'¶

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

Inlet sequences¶

class hydpy.models.hbranch.InletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.LinkSequences[InletSequence]

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: SubVariablesType)[source]¶

Bases: hydpy.core.sequencetools.LinkSequence[hydpy.core.sequencetools.InletSequences]

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

Required by the method:: Pick_Input_V1

NDIM: int = 1¶

NUMERIC: bool = False¶

name: str = 'total'¶

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

Outlet sequences¶

class hydpy.models.hbranch.OutletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.LinkSequences[OutletSequence]

Outlet sequences of model hbranch.

The following classes are selected:

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

class hydpy.models.hbranch.hbranch_outlets.Branched(subvars: SubVariablesType)[source]¶

Bases: hydpy.core.sequencetools.LinkSequence[hydpy.core.sequencetools.OutletSequences]

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

Calculated by the method:: Pass_Outputs_V1

NDIM: int = 1¶

NUMERIC: bool = False¶

name: str = 'branched'¶

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

class hydpy.models.hbranch.ControlParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)¶

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Control parameters of model hbranch.

The following classes are selected:

XPoints() Supporting points for the independent input variable [eg. m³/s].
YPoints() Supporting points for the dependent output variables [eg. m³/s].

class hydpy.models.hbranch.DerivedParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)¶

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Derived parameters of model hbranch.

The following classes are selected:

NmbBranches() Number of branches [-].
NmbPoints() Number of supporting points for linear interpolation [-].

class hydpy.models.hbranch.FluxSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)¶

Bases: hydpy.core.sequencetools.OutputSequences[FluxSequence]

Flux sequences of model hbranch.

The following classes are selected:

Input() Total input [e.g. m³/s].
Outputs() Branched outputs [e.g. m³/s].

class hydpy.models.hbranch.InletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)¶

Bases: hydpy.core.sequencetools.LinkSequences[InletSequence]

Inlet sequences of model hbranch.

The following classes are selected:

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

class hydpy.models.hbranch.OutletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)¶

Bases: hydpy.core.sequencetools.LinkSequences[OutletSequence]

Outlet sequences of model hbranch.

The following classes are selected:

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

hbranch¶

Method Features¶

Parameter Features¶

Control parameters¶

Derived parameters¶

Sequence Features¶

Flux sequences¶

Inlet sequences¶

Outlet sequences¶

Table of Contents

Previous topic

Next topic

This Page

Versions