hstream

The HydPy-H-Stream model is an very simple routing approach. More precisely, it is a simplification of the Muskingum approach, which itself can be seen as a very simple finite difference solution of the routing problem.

Method Features

class hydpy.models.hstream.hstream_model.Model[source]

Bases: hydpy.core.modeltools.AdHocModel

The HydPy-H-Stream model.

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

  • Pick_Q_V1 Assign the actual value of the inlet sequence to the upper joint of the subreach upstream.

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:

  • Pass_Q_V1 Assing the actual value of the lower joint of of the subreach downstream to the outlet sequence.

class hydpy.models.hstream.hstream_model.Calc_QJoints_V1[source]

Bases: hydpy.core.modeltools.Method

Apply the routing equation.

Requires the derived parameters:

NmbSegments C1 C2 C3

Updates the state sequence:

QJoints

Basic equation:

\(Q_{space+1,time+1} = c1 \cdot Q_{space,time+1} + c2 \cdot Q_{space,time} + c3 \cdot Q_{space+1,time}\)

Examples:

Firstly, define a reach divided into four segments:

>>> from hydpy.models.hstream import *
>>> parameterstep("1d")
>>> derived.nmbsegments(4)
>>> states.qjoints.shape = 5

Zero damping is achieved through the following coefficients:

>>> derived.c1(0.0)
>>> derived.c2(1.0)
>>> derived.c3(0.0)

For initialization, assume a base flow of 2m³/s:

>>> states.qjoints.old = 2.0
>>> states.qjoints.new = 2.0

Through successive assignements of different discharge values to the upper junction one can see that these discharge values are simply shifted from each junction to the respective lower junction at each time step:

>>> states.qjoints[0] = 5.0
>>> model.calc_qjoints_v1()
>>> model.new2old()
>>> states.qjoints
qjoints(5.0, 2.0, 2.0, 2.0, 2.0)
>>> states.qjoints[0] = 8.0
>>> model.calc_qjoints_v1()
>>> model.new2old()
>>> states.qjoints
qjoints(8.0, 5.0, 2.0, 2.0, 2.0)
>>> states.qjoints[0] = 6.0
>>> model.calc_qjoints_v1()
>>> model.new2old()
>>> states.qjoints
qjoints(6.0, 8.0, 5.0, 2.0, 2.0)

With the maximum damping allowed, the values of the derived parameters are:

>>> derived.c1(0.5)
>>> derived.c2(0.0)
>>> derived.c3(0.5)

Assuming again a base flow of 2m³/s and the same input values results in:

>>> states.qjoints.old = 2.0
>>> states.qjoints.new = 2.0

>>> states.qjoints[0] = 5.0
>>> model.calc_qjoints_v1()
>>> model.new2old()
>>> states.qjoints
qjoints(5.0, 3.5, 2.75, 2.375, 2.1875)
>>> states.qjoints[0] = 8.0
>>> model.calc_qjoints_v1()
>>> model.new2old()
>>> states.qjoints
qjoints(8.0, 5.75, 4.25, 3.3125, 2.75)
>>> states.qjoints[0] = 6.0
>>> model.calc_qjoints_v1()
>>> model.new2old()
>>> states.qjoints
qjoints(6.0, 5.875, 5.0625, 4.1875, 3.46875)
class hydpy.models.hstream.hstream_model.Pick_Q_V1[source]

Bases: hydpy.core.modeltools.Method

Assign the actual value of the inlet sequence to the upper joint of the subreach upstream.

Requires the inlet sequence:

Q

Calculates the state sequence:

QJoints

class hydpy.models.hstream.hstream_model.Pass_Q_V1[source]

Bases: hydpy.core.modeltools.Method

Assing the actual value of the lower joint of of the subreach downstream to the outlet sequence.

Requires the derived parameter:

NmbSegments

Requires the state sequence:

QJoints

Calculates the outlet sequence:

Q

Parameter Features

Control parameters

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • Lag() Time lag between inflow and outflow [T].

  • Damp() Damping of the hydrograph [-].

class hydpy.models.hstream.hstream_control.Lag(subvars: SubVariablesType)[source]

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

Time lag between inflow and outflow [T].

NDIM: int = 0
TYPE
TIME: Optional[bool] = False
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0.0, None)
name: str = 'lag'
unit: str = 'T'
class hydpy.models.hstream.hstream_control.Damp(subvars: SubVariablesType)[source]

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

Damping of the hydrograph [-].

NDIM: int = 0
TYPE
TIME: Optional[bool] = None
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0.0, 1.0)
name: str = 'damp'
unit: str = '-'

Derived parameters

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • NmbSegments() Number of river segments [-].

  • C1() First coefficient of the Muskingum working formula [-].

  • C3() Third coefficient of the muskingum working formula [-].

  • C2() Second coefficient of the muskingum working formula [-].

class hydpy.models.hstream.hstream_derived.NmbSegments(subvars: SubVariablesType)[source]

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

Number of river segments [-].

Required by the methods:

Calc_QJoints_V1 Pass_Q_V1

NDIM: int = 0
TYPE
TIME: Optional[bool] = None
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0, None)
update()[source]

Determines in how many segments the whole reach needs to be divided to approximate the desired lag time via integer rounding. Adjusts the shape of sequence QJoints additionally.

Required control parameters:

Lag

Calculated derived parameters:

NmbSegments

Prepared state sequence:

QJoints

Examples:

Define a lag time of 1.4 days and a simulation step size of 12 hours:

>>> from hydpy.models.hstream import *
>>> parameterstep("1d")
>>> simulationstep("12h")
>>> lag(1.4)

Then the actual lag value for the simulation step size is 2.8

>>> lag
lag(1.4)
>>> lag.value
2.8

Through rounding the number of segments is determined:

>>> derived.nmbsegments.update()
>>> derived.nmbsegments
nmbsegments(3)

The number of joints is always the number of segments plus one:

>>> states.qjoints.shape
(4,)
name: str = 'nmbsegments'
unit: str = '-'
class hydpy.models.hstream.hstream_derived.C1(subvars: SubVariablesType)[source]

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

First coefficient of the Muskingum working formula [-].

Required by the method:

Calc_QJoints_V1

NDIM: int = 0
TYPE
TIME: Optional[bool] = None
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0.0, 0.5)
update()[source]

Update C1 based on \(c_1 = \frac{Damp}{1+Damp}\).

Examples:

The first examples show the calculated value of C1 for the lowest possible value of Lag, the lowest possible value, and an intermediate value:

>>> from hydpy.models.hstream import *
>>> parameterstep("1d")
>>> damp(0.0)
>>> derived.c1.update()
>>> derived.c1
c1(0.0)
>>> damp(1.0)
>>> derived.c1.update()
>>> derived.c1
c1(0.5)
>>> damp(0.25)
>>> derived.c1.update()
>>> derived.c1
c1(0.2)

For to low and to high values of Lag, clipping is performed: >>> damp.value = -0.1 >>> derived.c1.update() >>> derived.c1 c1(0.0) >>> damp.value = 1.1 >>> derived.c1.update() >>> derived.c1 c1(0.5)

name: str = 'c1'
unit: str = '-'
class hydpy.models.hstream.hstream_derived.C3(subvars: SubVariablesType)[source]

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

Third coefficient of the muskingum working formula [-].

Required by the method:

Calc_QJoints_V1

NDIM: int = 0
TYPE
TIME: Optional[bool] = None
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0.0, 0.5)
update()[source]

Update C3 based on \(c_1 = c_3\).

Example:

>>> from hydpy.models.hstream import *
>>> parameterstep("1d")
>>> derived.c1 = 0.5
>>> derived.c3.update()
>>> derived.c3
c3(0.5)
name: str = 'c3'
unit: str = '-'
class hydpy.models.hstream.hstream_derived.C2(subvars: SubVariablesType)[source]

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

Second coefficient of the muskingum working formula [-].

Required by the method:

Calc_QJoints_V1

NDIM: int = 0
TYPE
TIME: Optional[bool] = None
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0.0, 1.0)
update()[source]

Update C2 based on \(c_2 = 1.-c_1-c_3\).

Examples:

The following examples show the calculated value of C2 are clipped when to low or to high:

>>> from hydpy.models.hstream import *
>>> parameterstep("1d")
>>> derived.c1 = 0.6
>>> derived.c3 = 0.1
>>> derived.c2.update()
>>> derived.c2
c2(0.3)
>>> derived.c1 = 1.6
>>> derived.c2.update()
>>> derived.c2
c2(0.0)
>>> derived.c1 = -1.6
>>> derived.c2.update()
>>> derived.c2
c2(1.0)
name: str = 'c2'
unit: str = '-'

Sequence Features

State sequences

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

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

State sequences of model hstream.

The following classes are selected:

  • QJoints() Runoff at the segment junctions [m³/s].

class hydpy.models.hstream.hstream_states.QJoints(subvars: SubVariablesType)[source]

Bases: hydpy.core.sequencetools.OutputSequence[hydpy.core.sequencetools.StateSequences], hydpy.core.sequencetools.ConditionSequence[hydpy.core.sequencetools.StateSequences, hydpy.core.sequencetools.FastAccessOutputSequence]

Runoff at the segment junctions [m³/s].

Calculated by the method:

Pick_Q_V1

Updated by the method:

Calc_QJoints_V1

Required by the method:

Pass_Q_V1

When a wrong number of input values is given, QJoints uses their average and emits the following warning:

>>> from hydpy.models.hstream import *
>>> parameterstep("1h")
>>> simulationstep("1h")
>>> lag(2.0)
>>> derived.nmbsegments.update()
>>> states.qjoints(1.0, 2.0)
Traceback (most recent call last):
...
UserWarning: Due to the following problem, state sequence `qjoints` of element `?` handling model `hstream` could be  initialised with an averaged value only: While trying to set the value(s) of variable `qjoints`, the following error occurred: While trying to convert the value(s) `(1.0, 2.0)` to a numpy ndarray with shape `(3,)` and type `float`, the following error occurred: could not broadcast input array from shape (2,) into shape (3,)

>>> states.qjoints
qjoints(1.5, 1.5, 1.5)

>>> states.qjoints(1.0, 2.0, 3.0)
>>> states.qjoints
qjoints(1.0, 2.0, 3.0)
NDIM: int = 1
NUMERIC: bool = False
SPAN: Tuple[Union[int, float, bool, None], Union[int, float, bool, None]] = (0.0, None)
property refweights

A numpy ndarray with equal weights for all segment junctions..

>>> from hydpy.models.hstream import *
>>> parameterstep("1d")
>>> states.qjoints.shape = 5
>>> states.qjoints.refweights
array([ 0.2,  0.2,  0.2,  0.2,  0.2])
name: str = 'qjoints'
unit: str = 'm³/s'

Inlet sequences

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • Q() Runoff [m³/s].

class hydpy.models.hstream.hstream_inlets.Q(subvars: SubVariablesType)[source]

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

Runoff [m³/s].

Required by the method:

Pick_Q_V1

NDIM: int = 1
NUMERIC: bool = False
name: str = 'q'
unit: str = 'm³/s'

Outlet sequences

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • Q() Runoff [m³/s].

class hydpy.models.hstream.hstream_outlets.Q(subvars: SubVariablesType)[source]

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

Runoff [m³/s].

Calculated by the method:

Pass_Q_V1

NDIM: int = 0
NUMERIC: bool = False
name: str = 'q'
unit: str = 'm³/s'

Auxiliary Features

Masks

class hydpy.models.hstream.Masks[source]

Bases: hydpy.core.masktools.Masks

Masks of base model hstream.

The following classes are selected:
class hydpy.models.hstream.hstream_masks.Complete(variable: Optional[hydpy.core.typingtools.VariableProtocol] = None, **kwargs)[source]

Bases: hydpy.core.masktools.DefaultMask

Mask including a stream segments.

name: str = 'complete'
variable: hydpy.core.typingtools.VariableProtocol
class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • Lag() Time lag between inflow and outflow [T].

  • Damp() Damping of the hydrograph [-].

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • NmbSegments() Number of river segments [-].

  • C1() First coefficient of the Muskingum working formula [-].

  • C3() Third coefficient of the muskingum working formula [-].

  • C2() Second coefficient of the muskingum working formula [-].

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • Q() Runoff [m³/s].

class hydpy.models.hstream.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 hstream.

The following classes are selected:

  • Q() Runoff [m³/s].

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

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

State sequences of model hstream.

The following classes are selected:

  • QJoints() Runoff at the segment junctions [m³/s].