HydPy-Musk (base model)

HydPy-Musk provides features for implementing Muskingum-like routing methods, which are finite difference solutions of the routing problem.

Method Features

class hydpy.models.musk.musk_model.Model[source]

Bases: SegmentModel

HydPy-Musk (base 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:

  • Calc_Outflow_V1 Take the discharge at the last segment endpoint as the channel’s outflow.

  • Pass_Outflow_V1 Pass the channel’s outflow to the outlet sequence.

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:
The following “submodels” might be called by one or more of the implemented methods or are meant to be directly called by the user:
DOCNAME: DocName = ('Musk', 'base model')
OBSERVER_METHODS: ClassVar[tuple[type[Method], ...]] = ()
wqmodel

Required submodel that complies with the following interface: CrossSectionModel_V1.

wqmodel_is_mainmodel
wqmodel_typeid
REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.musk.musk_model.Pick_Inflow_V1[source]

Bases: Method

Assign the actual value of the inlet sequence to the inflow sequence.

Requires the inlet sequence:

Q

Calculates the flux sequence:

Inflow

class hydpy.models.musk.musk_model.Adjust_Inflow_V1[source]

Bases: Method

Protect against negative inflow.

Requires the solver parameter:

ToleranceNegativeInflow

Updates the flux sequence:

Inflow

Examples:

Models like musk_mct cannot handle negative inflow. Hence, Adjust_Inflow_V1 sets all such values to zero:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> fluxes.inflow = -0.1
>>> model.adjust_inflow_v1()
>>> fluxes.inflow
inflow(0.0)

This behaviour serves well in situations where numerical issues like rounding errors cause slightly negative inflow values but bears the risk of severely violating the water balance in case the upstream models produce strong negative inflow values on purpose. You can modify the solver parameter ToleranceNegativeInflow, below which negative inflows are set to nan instead of zero, to ensure such problems get noticed:

>>> fluxes.inflow = -0.1
>>> solver.tolerancenegativeinflow(-0.01)
>>> model.adjust_inflow_v1()
>>> fluxes.inflow
inflow(nan)
class hydpy.models.musk.musk_model.Update_Discharge_V1[source]

Bases: Method

Assign the inflow to the start point of the first channel segment.

Requires the flux sequence:

Inflow

Updates the state sequence:

Discharge

Example:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> fluxes.inflow = 2.0
>>> model.update_discharge_v1()
>>> states.discharge
discharge(2.0, nan, nan, nan)
class hydpy.models.musk.musk_model.Calc_Discharge_V1[source]

Bases: Method

Apply the routing equation with fixed coefficients.

Requires the control parameter:

Coefficients

Updates the state sequence:

Discharge

Basic equation:

\(Q_{space+1,time+1} = Coefficients_0 \cdot Discharge_{space,time+1} + Coefficients_1 \cdot Discharge_{space,time} + Coefficients_2 \cdot Discharge_{space+1,time}\)

Examples:

First, define a channel divided into four segments:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(4)

The following coefficients correspond to pure translation without diffusion:

>>> coefficients(0.0, 1.0, 0.0)

The initial flow is 2 m³/s:

>>> states.discharge.old = 2.0
>>> states.discharge.new = 2.0

Successive invocations of method Calc_Discharge_V1 shift the given inflows to the next lower endpoints at each time step:

>>> states.discharge[0] = 5.0
>>> model.run_segments(model.calc_discharge_v1)
>>> model.new2old()
>>> states.discharge
discharge(5.0, 2.0, 2.0, 2.0, 2.0)

>>> states.discharge[0] = 8.0
>>> model.run_segments(model.calc_discharge_v1)
>>> model.new2old()
>>> states.discharge
discharge(8.0, 5.0, 2.0, 2.0, 2.0)

>>> states.discharge[0] = 6.0
>>> model.run_segments(model.calc_discharge_v1)
>>> model.new2old()
>>> states.discharge
discharge(6.0, 8.0, 5.0, 2.0, 2.0)

We repeat the example with strong wave diffusion:

>>> coefficients(0.5, 0.0, 0.5)

>>> states.discharge.old = 2.0
>>> states.discharge.new = 2.0

>>> states.discharge[0] = 5.0
>>> model.run_segments(model.calc_discharge_v1)
>>> model.new2old()
>>> states.discharge
discharge(5.0, 3.5, 2.75, 2.375, 2.1875)

>>> states.discharge[0] = 8.0
>>> model.run_segments(model.calc_discharge_v1)
>>> model.new2old()
>>> states.discharge
discharge(8.0, 5.75, 4.25, 3.3125, 2.75)

>>> states.discharge[0] = 6.0
>>> model.run_segments(model.calc_discharge_v1)
>>> model.new2old()
>>> states.discharge
discharge(6.0, 5.875, 5.0625, 4.1875, 3.46875)
class hydpy.models.musk.musk_model.Calc_ReferenceDischarge_V1[source]

Bases: Method

Estimate the reference discharge according to Todini (2007).

Requires the state sequence:

Discharge

Calculates the flux sequence:

ReferenceDischarge

Basic equations (equations 45 and 46):

\(ReferenceDischarge_{next, new} = \frac{Discharge_{last, new} + Discharge^*_{next, new}}{2}\)

\(Discharge^*_{next, new} = Discharge_{next, old} + (Discharge_{last, new} - Discharge_{last, old})\)

Examples:

The Muskingum-Cunge-Todini method requires an initial guess for the new discharge value at the segment endpoint, which other methods have to improve later. However, the final discharge value will still depend on the initial estimate. Hence, Todini (2007) suggests an iterative refinement by repeating all relevant methods. Method Calc_ReferenceDischarge_V1 plays a significant role in controlling this refinement. It calculates the initial estimate as defined in the basic equationsDuring the first run (when the index property Idx_Run is zero):

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> states.discharge.old = 3.0, 2.0
>>> states.discharge.new = 4.0, 5.0
>>> model.idx_run = 0
>>> model.calc_referencedischarge_v1()
>>> fluxes.referencedischarge
referencedischarge(3.5)

However, subsequent runs use the already available estimate calculated in the last iteration.:

>>> model.idx_run = 1
>>> model.calc_referencedischarge_v1()
>>> fluxes.referencedischarge
referencedischarge(4.5)

The given basic equation can result in negative reference discharge estimates during severe low-flow conditions. Calc_ReferenceDischarge_V1 resets those to zero:

>>> model.idx_run = 0
>>> states.discharge.old = 0.6, 0.1
>>> states.discharge.new = 0.2, nan
>>> model.calc_referencedischarge_v1()
>>> fluxes.referencedischarge
referencedischarge(0.0)
class hydpy.models.musk.musk_model.Return_Discharge_CrossSectionModel_V1[source]

Bases: Method

Let a submodel that follows the CrossSectionModel_V1 submodel interface calculate the discharge for the given water depth and return it.

Required by the method:

Return_ReferenceDischargeError_V1

See the documentation on method Return_ReferenceDischargeError_V1 for an example.

class hydpy.models.musk.musk_model.Return_ReferenceDischargeError_V1[source]

Bases: Method

Calculate the difference between the discharge corresponding to the given water depth and the reference discharge.

Required by the method:

Calc_ReferenceWaterDepth_V1

Required submethod:

Return_Discharge_CrossSectionModel_V1

Requires the flux sequence:

ReferenceDischarge

Basic equation:

\(Return\_Discharge\_V1(waterdepth) - ReferenceDischarge\)

Example:

We use the submodel wq_trapeze_strickler as an example:

>>> from hydpy.models.musk_mct import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomslope(0.01)
>>> with model.add_wqmodel_v1("wq_trapeze_strickler"):
...     nmbtrapezes(1)
...     bottomlevels(0.0)
...     bottomwidths(2.0)
...     sideslopes(2.0)
...     stricklercoefficients(20.0)
...     calibrationfactors(1.0)
>>> fluxes.referencedischarge = 50.0
>>> from hydpy import round_
>>> round_(model.return_referencedischargeerror_v1(3.0))
14.475285
class hydpy.models.musk.musk_model.Calc_ReferenceWaterDepth_V1[source]

Bases: Method

Find the reference water depth via Pegasus iteration.

Required submethod:

Return_ReferenceDischargeError_V1

Requires the solver parameters:

ToleranceWaterDepth ToleranceDischarge

Requires the flux sequence:

ReferenceDischarge

Calculates the factor sequence:

ReferenceWaterDepth

Examples:

The following test calculation extends the example of the documentation on method Return_ReferenceDischargeError_V1. The first and the last channel segments demonstrate that method Calc_ReferenceWaterDepth_V1 restricts the Pegasus search to the lowest water depth of 0 m and the highest water depth of 1000 m:

>>> from hydpy.models.musk_mct import *
>>> parameterstep()
>>> catchmentarea(100.0)
>>> nmbsegments(5)
>>> bottomslope(0.01)
>>> with model.add_wqmodel_v1("wq_trapeze_strickler"):
...     nmbtrapezes(1)
...     bottomlevels(0.0)
...     bottomwidths(2.0)
...     sideslopes(2.0)
...     stricklercoefficients(20.0)
...     calibrationfactors(1.0)
>>> solver.tolerancewaterdepth.update()
>>> solver.tolerancedischarge.update()
>>> fluxes.referencedischarge = -10.0, 0.0, 64.475285, 1000.0, 1000000000.0
>>> model.run_segments(model.calc_referencewaterdepth_v1)
>>> factors.referencewaterdepth
referencewaterdepth(0.0, 0.0, 3.0, 9.199035, 1000.0)

Repeated applications of Calc_ReferenceWaterDepth_V1 should always yield the same results but are often more efficient than the initial calculation because they use old reference water depth estimates to gain more precise initial search intervals:

>>> model.run_segments(model.calc_referencewaterdepth_v1)
>>> factors.referencewaterdepth
referencewaterdepth(0.0, 0.0, 3.0, 9.199035, 1000.0)

The Pegasus algorithm stops when the search interval is smaller than the tolerance value defined by the ToleranceWaterDepth parameter or if the difference to the target discharge is less than the tolerance value defined by the ToleranceDischarge parameter. By default, the water depth-related tolerance is zero; hence, the discharge-related tolerance must stop the iteration:

>>> solver.tolerancewaterdepth
tolerancewaterdepth(0.0)
>>> solver.tolerancedischarge
tolerancedischarge(0.0001)

Increase at least one parameter to reduce computation time:

>>> solver.tolerancewaterdepth(0.1)
>>> factors.referencewaterdepth = nan
>>> model.run_segments(model.calc_referencewaterdepth_v1)
>>> factors.referencewaterdepth
referencewaterdepth(0.0, 0.0, 3.000295, 9.196508, 1000.0)
class hydpy.models.musk.musk_model.Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1[source]

Bases: Method

Let a submodel that follows the CrossSectionModel_V1 interface calculate all its properties based on the current reference water level and query the wetted area, the surface width, and the celerity.

Required by the method:

Calc_WettedArea_SurfaceWidth_Celerity_V1

Requires the factor sequence:

ReferenceWaterDepth

Calculates the factor sequences:

WettedArea SurfaceWidth Celerity

class hydpy.models.musk.musk_model.Calc_WettedArea_SurfaceWidth_Celerity_V1[source]

Bases: Method

Let a submodel that follows the CrossSectionModel_V1 interface calculate all its properties based on the current reference water level and query the wetted area, the surface width, and the celerity.

Required submethod:

Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1

Requires the factor sequence:

ReferenceWaterDepth

Calculates the factor sequences:

WettedArea SurfaceWidth Celerity

Example:

We use the submodel wq_trapeze_strickler as an example:

>>> from hydpy.models.musk_mct import *
>>> parameterstep()
>>> nmbsegments(3)
>>> bottomslope(0.01)
>>> with model.add_wqmodel_v1("wq_trapeze_strickler"):
...     nmbtrapezes(1)
...     bottomlevels(0.0)
...     bottomwidths(2.0)
...     sideslopes(0.0)
...     stricklercoefficients(20.0)
...     calibrationfactors(1.0)
>>> factors.referencewaterdepth = 1.0, 2.0, 3.0
>>> model.run_segments(model.calc_wettedarea_surfacewidth_celerity_v1)
>>> factors.wettedarea
wettedarea(2.0, 4.0, 6.0)
>>> factors.surfacewidth
surfacewidth(2.0, 2.0, 2.0)
>>> factors.celerity
celerity(1.679895, 1.86546, 1.926124)
class hydpy.models.musk.musk_model.Calc_CorrectingFactor_V1[source]

Bases: Method

Calculate the correcting factor according to Todini (2007).

Requires the factor sequences:

Celerity WettedArea

Requires the flux sequence:

ReferenceDischarge

Calculates the factor sequence:

CorrectingFactor

Basic equation (equation 49):

\(CorrectingFactor = \frac{Celerity \cdot WettedArea}{ReferenceDischarge}\)

Example:

The last segment shows that Calc_CorrectingFactor_V1 prevents zero divisions by setting the correcting factor to one when necessary:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> factors.celerity = 1.0
>>> factors.wettedarea = 2.0, 2.0, 2.0
>>> fluxes.referencedischarge = 4.0, 2.0, 0.0
>>> model.run_segments(model.calc_correctingfactor_v1)
>>> factors.correctingfactor
correctingfactor(0.5, 1.0, 1.0)
class hydpy.models.musk.musk_model.Calc_CourantNumber_V1[source]

Bases: Method

Calculate the Courant number according to Todini (2007).

Requires the derived parameters:

Seconds SegmentLength

Requires the factor sequences:

Celerity CorrectingFactor

Requires the flux sequence:

ReferenceDischarge

Calculates the state sequence:

CourantNumber

Basic equation (equation 50):

\(CourantNumber = \frac{Celerity \cdot Seconds}{CorrectingFactor \cdot 1000 \cdot SegmentLength}\)

Example:

The last segment shows that Calc_CourantNumber_V1 prevents zero divisions by setting the courant number to zero when necessary:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(5)
>>> derived.seconds(1000.0)
>>> derived.segmentlength(4.0)
>>> factors.celerity = 2.0
>>> factors.correctingfactor = 0.0, 0.5, 1.0, 2.0, inf
>>> fluxes.referencedischarge = 0.0, 1.0, 1.0, 1.0, 1.0
>>> model.run_segments(model.calc_courantnumber_v1)
>>> states.courantnumber
courantnumber(0.0, 1.0, 0.5, 0.25, 0.0)
class hydpy.models.musk.musk_model.Calc_ReynoldsNumber_V1[source]

Bases: Method

Calculate the cell Reynolds number according to Todini (2007).

Requires the control parameter:

BottomSlope

Requires the derived parameter:

SegmentLength

Requires the factor sequences:

CorrectingFactor SurfaceWidth Celerity

Requires the flux sequence:

ReferenceDischarge

Calculates the state sequence:

ReynoldsNumber

Basic equation (equation 51):

\(ReynoldsNumber = \frac{ReferenceDischarge}{CorrectingFactor \cdot SurfaceWidth \cdot BottomSlope \cdot Celerity \cdot 1000 \cdot SegmentLength}\)

Example:

The last segment shows that Calc_ReynoldsNumber_V1 prevents zero divisions by setting the cell reynolds number to zero when necessary:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(5)
>>> bottomslope(0.01)
>>> derived.segmentlength(4.0)
>>> factors.surfacewidth = 5.0
>>> factors.celerity = 2.0
>>> factors.correctingfactor = 0.0, 0.5, 1.0, 2.0, inf
>>> fluxes.referencedischarge = 0.0, 10.0, 10.0, 10.0, 10.0
>>> model.run_segments(model.calc_reynoldsnumber_v1)
>>> states.reynoldsnumber
reynoldsnumber(0.0, 0.05, 0.025, 0.0125, 0.0)
class hydpy.models.musk.musk_model.Calc_Coefficient1_Coefficient2_Coefficient3_V1[source]

Bases: Method

Calculate the coefficients of the Muskingum working formula according to Todini (2007).

Requires the state sequences:

CourantNumber ReynoldsNumber

Updates the factor sequences:

Coefficient1 Coefficient2 Coefficient3

Basic equations (equation 52, corrigendum):

\(Coefficient1 = \frac {-1 + CourantNumber_{new} + ReynoldsNumber_{new}} {1 + CourantNumber_{new} + ReynoldsNumber_{new}}\)

\(Coefficient2 = \frac {1 + CourantNumber_{old} - ReynoldsNumber_{old}} {1 + CourantNumber_{new} + ReynoldsNumber_{new}} \cdot \frac{CourantNumber_{new}}{CourantNumber_{old}}\)

\(Coefficient3 = \frac {1 - CourantNumber_{old} + ReynoldsNumber_{old}} {1 + CourantNumber_{new} + ReynoldsNumber_{new}} \cdot \frac{CourantNumber_{new}}{CourantNumber_{old}}\)

Examples:

We make some effort to calculate consistent “old” and “new” Courant and Reynolds numbers:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(4)
>>> bottomslope(0.01)
>>> derived.seconds(1000.0)
>>> derived.segmentlength(4.0)
>>> factors.celerity = 2.0
>>> factors.surfacewidth = 5.0
>>> factors.correctingfactor = 0.5, 1.0, 2.0, inf
>>> fluxes.referencedischarge = 10.0
>>> model.run_segments(model.calc_courantnumber_v1)
>>> model.run_segments(model.calc_reynoldsnumber_v1)
>>> states.courantnumber.new2old()
>>> states.reynoldsnumber.new2old()
>>> fluxes.referencedischarge = 11.0
>>> model.run_segments(model.calc_courantnumber_v1)
>>> model.run_segments(model.calc_reynoldsnumber_v1)

Due to the consistency of its input data, Calc_Coefficient1_Coefficient2_Coefficient3_V1 calculates the three working coefficients so that their sum is one:

>>> model.run_segments(model.calc_coefficient1_coefficient2_coefficient3_v1)
>>> factors.coefficient1
coefficient1(0.026764, -0.309329, -0.582591, -1.0)
>>> factors.coefficient2
coefficient2(0.948905, 0.96563, 0.979228, 1.0)
>>> factors.coefficient3
coefficient3(0.024331, 0.343699, 0.603363, 1.0)
>>> from hydpy import print_vector
>>> print_vector(
...     factors.coefficient1 + factors.coefficient2 + factors.coefficient3)
1.0, 1.0, 1.0, 1.0

Note that the “old” Courant numbers of the last segment are zero.

>>> print_vector(states.courantnumber.old)
1.0, 0.5, 0.25, 0.0

To prevent zero divisions, Calc_Coefficient1_Coefficient2_Coefficient3_V1 assumes the ratio between the new and the old Courant number to be one in such cases.

class hydpy.models.musk.musk_model.Calc_Discharge_V2[source]

Bases: Method

Apply the routing equation with discharge-dependent coefficients.

Requires the factor sequences:

Coefficient1 Coefficient2 Coefficient3

Updates the state sequence:

Discharge

Basic equation:

\(Discharge_{next, new} = Coefficient0 \cdot Discharge_{last, new} + Coefficient1 \cdot Discharge_{last, old} + Coefficient2 \cdot Discharge_{next, old}\)

Examples:

First, we define a channel divided into four segments:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(4)

The following coefficients correspond to pure translation without diffusion:

>>> factors.coefficient1 = 0.0
>>> factors.coefficient2 = 1.0
>>> factors.coefficient3 = 0.0

The initial flow is 2 m³/s:

>>> states.discharge.old = 2.0
>>> states.discharge.new = 2.0

Successive invocations of method Calc_Discharge_V2 shift the given inflows to the next lower endpoints at each time step:

>>> states.discharge[0] = 5.0
>>> model.run_segments(model.calc_discharge_v2)
>>> model.new2old()
>>> states.discharge
discharge(5.0, 2.0, 2.0, 2.0, 2.0)

>>> states.discharge[0] = 8.0
>>> model.run_segments(model.calc_discharge_v2)
>>> model.new2old()
>>> states.discharge
discharge(8.0, 5.0, 2.0, 2.0, 2.0)

>>> states.discharge[0] = 6.0
>>> model.run_segments(model.calc_discharge_v2)
>>> model.new2old()
>>> states.discharge
discharge(6.0, 8.0, 5.0, 2.0, 2.0)

We repeat the example with strong wave diffusion:

>>> factors.coefficient1 = 0.5
>>> factors.coefficient2 = 0.0
>>> factors.coefficient3 = 0.5

>>> states.discharge.old = 2.0
>>> states.discharge.new = 2.0

>>> states.discharge[0] = 5.0
>>> model.run_segments(model.calc_discharge_v2)
>>> model.new2old()
>>> states.discharge
discharge(5.0, 3.5, 2.75, 2.375, 2.1875)

>>> states.discharge[0] = 8.0
>>> model.run_segments(model.calc_discharge_v2)
>>> model.new2old()
>>> states.discharge
discharge(8.0, 5.75, 4.25, 3.3125, 2.75)

>>> states.discharge[0] = 6.0
>>> model.run_segments(model.calc_discharge_v2)
>>> model.new2old()
>>> states.discharge
discharge(6.0, 5.875, 5.0625, 4.1875, 3.46875)
class hydpy.models.musk.musk_model.Calc_Outflow_V1[source]

Bases: Method

Take the discharge at the last segment endpoint as the channel’s outflow.

Requires the control parameter:

NmbSegments

Requires the state sequence:

Discharge

Calculates the flux sequence:

Outflow

Basic equation:

\(Outflow = Discharge_{NmbSegments}\)

Example:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(2)
>>> states.discharge.new = 1.0, 2.0, 3.0
>>> model.calc_outflow_v1()
>>> fluxes.outflow
outflow(3.0)
class hydpy.models.musk.musk_model.Pass_Outflow_V1[source]

Bases: Method

Pass the channel’s outflow to the outlet sequence.

Requires the flux sequence:

Outflow

Calculates the outlet sequence:

Q

class hydpy.models.musk.musk_model.PegasusReferenceWaterDepth(model: Model)[source]

Bases: Pegasus

Pegasus iterator for finding the correct reference water depth.

METHODS: ClassVar[tuple[type[Method], ...]] = (<class 'hydpy.models.musk.musk_model.Return_ReferenceDischargeError_V1'>,)
name: ClassVar[str] = 'pegasusreferencewaterdepth'

Parameter Features

Control parameters

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

Bases: SubParameters

Control parameters of model musk.

The following classes are selected:
class hydpy.models.musk.musk_control.CatchmentArea(subvars: SubParameters)[source]

Bases: Parameter

Size of the catchment draining into the channel [km²].

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 = 'catchmentarea'

Name of the variable in lowercase letters.

unit: str = 'km²'

Unit of the variable.

class hydpy.models.musk.musk_control.NmbSegments(subvars: SubParameters)[source]

Bases: Parameter

Number of channel segments [-].

Required by the method:

Calc_Outflow_V1

You can set the number of segments directly:

>>> from hydpy.models.musk import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> nmbsegments(2)
>>> nmbsegments
nmbsegments(2)

NmbSegments prepares the shape of most 1-dimensional parameters and sequences automatically:

>>> factors.referencewaterdepth.shape
(2,)
>>> fluxes.referencedischarge.shape
(2,)
>>> states.discharge.shape
(3,)

If you prefer to configure musk in the style of HBV96 (Lindström et al., 1997), use the lag argument. NmbSegments calculates the number of segments so that one simulation step lag corresponds to one segment:

>>> nmbsegments(lag=2.5)
>>> nmbsegments
nmbsegments(lag=2.5)
>>> states.discharge.shape
(6,)

Negative lag values are trimmed to zero:

>>> from hydpy.core.testtools import warn_later
>>> with warn_later():
...     nmbsegments(lag=-1.0)
UserWarning: For parameter `nmbsegments` of element `?` the keyword argument `lag` with value `-1.0` needed to be trimmed to `0.0`.
>>> nmbsegments
nmbsegments(lag=0.0)
>>> states.discharge.shape
(1,)

Calculating an integer number of segments from a time lag defined as a floating-point number requires rounding:

>>> nmbsegments(lag=0.9)
>>> nmbsegments
nmbsegments(lag=0.9)
>>> states.discharge.shape
(3,)

NmbSegments preserves existing values if the number of segments does not change:

>>> states.discharge = 1.0, 2.0, 3.0
>>> nmbsegments(2)
>>> nmbsegments
nmbsegments(2)
>>> states.discharge
discharge(1.0, 2.0, 3.0)
NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)
KEYWORDS: Mapping[str, Keyword] = {'lag': ('lag', <class 'float'>, False, (None, None))}
name: str = 'nmbsegments'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_control.Coefficients(subvars: SubParameters)[source]

Bases: MixinFixedShape, Parameter

Coefficients of the Muskingum working formula [-].

Required by the method:

Calc_Discharge_V1

There are three options for defining the (fixed) coefficients of the Muskingum working formula. First, you can define them manually (see the documentation on method Calc_Discharge_V1 on how these coefficients are applied):

>>> from hydpy.models.musk import *
>>> simulationstep("12h")
>>> parameterstep("1d")
>>> coefficients(0.2, 0.5, 0.3)
>>> coefficients
coefficients(0.2, 0.5, 0.3)

Second, you can let parameter Coefficients calculate the coefficients according to HBV96 (Lindström et al., 1997). Therefore, use the damp argument. Its lowest possible value is zero and results in a pure translation process where a flood wave travels one segment per simulation step without modification of its shape:

>>> from hydpy import print_vector
>>> coefficients(damp=0.0)
>>> coefficients
coefficients(damp=0.0)
>>> print_vector(coefficients.values)
0.0, 1.0, 0.0

Negative damp values are trimmed to zero:

>>> from hydpy.core.testtools import warn_later
>>> with warn_later():
...     coefficients(damp=-1.0)
UserWarning: For parameter `coefficients` of element `?` the keyword argument `damp` with value `-1.0` needed to be trimmed to `0.0`.

Higher values do not change the translation time but increase wave attenuation. The highest possible value with non-negative coefficients is one:

>>> coefficients(damp=1.0)
>>> coefficients
coefficients(damp=1.0)
>>> print_vector(coefficients.values)
0.5, 0.0, 0.5

Higher values are allowed but result in highly skewed responses that are usually not desirable:

>>> coefficients(damp=3.0)
>>> coefficients
coefficients(damp=3.0)
>>> print_vector(coefficients.values)
0.75, -0.5, 0.75

The third option follows the original Muskingum method (McCarthy, 1940) and is more flexible as it offers two parameters. k is the translation time (defined with respect to the current parameter step size), and x is a weighting factor. Note that both parameters hold for a single channel segment, so that, for example, a k value of one day results in an efficient translation time of two days for a channel divided into two segments.

The calculation of the coefficients follows the classic Muskingum method:

\(c_1 = \frac{1 - 2 \cdot k \cdot x}{2 \cdot k (1 - x) + 1}\)

\(c_2 = \frac{1 + 2 \cdot k \cdot x}{2 \cdot k (1 - x) + 1}\)

\(c_3 = \frac{2 \cdot k (1 - x) - 1}{2 \cdot k (1 - x) + 1}\)

For a k value of zero, travel time and diffusion are zero:

>>> coefficients(k=0.0, x=0.0)
>>> coefficients
coefficients(k=0.0, x=0.0)
>>> print_vector(coefficients.values)
1.0, 1.0, -1.0

Negative k values are trimmed:

>>> with warn_later():
...     coefficients(k=-1.0, x=0.0)
UserWarning: For parameter `coefficients` of element `?` the keyword argument `k` with value `-1.0` needed to be trimmed to `0.0`.
>>> coefficients
coefficients(k=0.0, x=0.0)
>>> print_vector(coefficients.values)
1.0, 1.0, -1.0

The usual lowest value for x is zero:

>>> coefficients(k=0.5, x=0.0)
>>> coefficients
coefficients(k=0.5, x=0.0)
>>> print_vector(coefficients.values)
0.333333, 0.333333, 0.333333

However, negative x values do not always result in problematic wave transformations, so we allow them:

>>> coefficients(k=0.5, x=-1.0)
>>> coefficients
coefficients(k=0.5, x=-1.0)
>>> print_vector(coefficients.values)
0.6, -0.2, 0.6

As mentioned above, the value of k depends on the current parameter step size:

>>> from hydpy import pub
>>> with pub.options.parameterstep("12h"):
...     coefficients
coefficients(k=1.0, x=-1.0)

The highest possible value for x depends on the current value of k (but can never exceed 0.5):

\(x \leq min \left( \frac{1}{2 \cdot k}, 1 - \frac{1}{2 \cdot k} \right) \leq \frac{1}{2}\)

>>> with warn_later():
...     coefficients(k=0.5, x=1.0)
UserWarning: For parameter `coefficients` of element `?` the keyword argument `x` with value `1.0` needed to be trimmed to `0.5`.
>>> coefficients
coefficients(k=0.5, x=0.5)
>>> print_vector(coefficients.values)
0.0, 1.0, 0.0

>>> with warn_later():
...     coefficients(k=1.0, x=1.0)
UserWarning: For parameter `coefficients` of element `?` the keyword argument `x` with value `1.0` needed to be trimmed to `0.25`.
>>> coefficients
coefficients(k=1.0, x=0.25)
>>> print_vector(coefficients.values)
0.0, 0.5, 0.5

>>> with warn_later():
...     coefficients(k=0.25, x=1.0)
UserWarning: For parameter `coefficients` of element `?` the keyword argument `x` with value `1.0` needed to be trimmed to `0.0`.
>>> coefficients
coefficients(k=0.25, x=0.0)
>>> print_vector(coefficients.values)
0.5, 0.5, 0.0
NDIM: int = 1
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
SHAPE: tuple[int, ...] = (3,)
KEYWORDS: Mapping[str, Keyword] = {'damp': ('damp', <class 'float'>, None, (None, None)), 'k': ('k', <class 'float'>, False, (None, None)), 'x': ('x', <class 'float'>, None, (None, None))}
name: str = 'coefficients'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_control.Length(subvars: SubParameters)[source]

Bases: Parameter

The total length of channel [km].

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 = 'length'

Name of the variable in lowercase letters.

unit: str = 'km'

Unit of the variable.

class hydpy.models.musk.musk_control.BottomSlope(subvars: SubParameters)[source]

Bases: Parameter

Bottom slope [-].

Required by the method:

Calc_ReynoldsNumber_V1

\(BottomSlope = \frac{elevation_{start} - elevation_{end}}{Length}\)

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 = 'bottomslope'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

Derived parameters

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

Bases: SubParameters

Derived parameters of model musk.

The following classes are selected:
class hydpy.models.musk.musk_derived.Seconds(subvars: SubParameters)[source]

Bases: SecondsParameter

Length of the actual simulation step size [s].

Required by the method:

Calc_CourantNumber_V1

name: str = 'seconds'

Name of the variable in lowercase letters.

unit: str = 's'

Unit of the variable.

class hydpy.models.musk.musk_derived.SegmentLength(subvars: SubParameters)[source]

Bases: Parameter

The length of each channel segments [km].

Required by the methods:

Calc_CourantNumber_V1 Calc_ReynoldsNumber_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)
update()[source]

Update the segment length based on \(SegmentLength = Length / NmbSegments\).

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(2)
>>> length(8.0)
>>> derived.segmentlength.update()
>>> derived.segmentlength
segmentlength(4.0)
name: str = 'segmentlength'

Name of the variable in lowercase letters.

unit: str = 'km'

Unit of the variable.

Solver parameters

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

Bases: SubParameters

Solver parameters of model musk.

The following classes are selected:

  • NmbRuns() The number of (repeated) runs of the RUN_METHODS of the current application model per simulation step [-].

  • ToleranceWaterDepth() Acceptable water depth error for determining the reference water depth [m].

  • ToleranceDischarge() Acceptable discharge error for determining the reference water depth [m³/s].

  • ToleranceNegativeInflow() Threshold for setting negative inflow values to zero or nan [m³/s].

class hydpy.models.musk.musk_solver.NmbRuns(subvars)[source]

Bases: SolverParameter

The number of (repeated) runs of the RUN_METHODS of the current application model per simulation step [-].

Model developers need to subclass NmbRuns for each application model to define a suitable INIT value.

NDIM: int = 0
TYPE

alias of int

TIME: bool | None = None
name: str = 'nmbruns'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_solver.ToleranceWaterDepth(subvars)[source]

Bases: SolverParameter

Acceptable water depth error for determining the reference water depth [m].

Required by the method:

Calc_ReferenceWaterDepth_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 = 0.0
name: str = 'tolerancewaterdepth'

Name of the variable in lowercase letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_solver.ToleranceDischarge(subvars)[source]

Bases: SolverParameter

Acceptable discharge error for determining the reference water depth [m³/s].

Required by the method:

Calc_ReferenceWaterDepth_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 = 1e-06
modify_init() → float[source]

Adjust and return the value of class constant INIT.

Ideally, in the long term, the iterative search for the reference water depth takes comparable computation time and yields comparable relative accuracy for channels that pass different amounts of water. We use the catchment size as an indicator of the expected (average) amount of water. For central European conditions, the average specific discharge is usually (much) larger than 0.001 m³/s/km². The error tolerance must be much lower, especially for handling low-flow situations. Hence, the return value of method modify_init() is based on one per mille of this specific discharge value:

\(ToleranceDischarge = 0.001 / 1000 \cdot CatchmentArea\)

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> from hydpy import round_
>>> round_(solver.tolerancedischarge.INIT, 12)
0.000001
>>> catchmentarea(2000.0)
>>> solver.tolerancedischarge.update()
>>> solver.tolerancedischarge
tolerancedischarge(0.002)
name: str = 'tolerancedischarge'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

class hydpy.models.musk.musk_solver.ToleranceNegativeInflow(subvars)[source]

Bases: SolverParameter

Threshold for setting negative inflow values to zero or nan [m³/s].

Required by the method:

Adjust_Inflow_V1

NDIM: int = 0
TYPE

alias of float

TIME: bool | None = None
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, -inf)
INIT: int | float | bool = -inf
name: str = 'tolerancenegativeinflow'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

Sequence Features

Sequence tools

class hydpy.models.musk.musk_sequences.MixinSequence1D[source]

Bases: object

Mixin class for the 1-dimensional sequences.

NDIM = 1
NUMERIC = False
property refweights: ndarray[tuple[Any, ...], dtype[float64]]

The relative length of all channel segments.

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(4)
>>> from hydpy import print_vector
>>> print_vector(fluxes.referencedischarge.refweights)
0.25, 0.25, 0.25, 0.25
class hydpy.models.musk.musk_sequences.StateSequence1D(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinSequence1D, StateSequence

Base class for the 1-dimensional state sequences.

For a wrong number of input values, subclasses like Discharge use their average and emit the following warning:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(2)
>>> from hydpy.core.testtools import warn_later
>>> with warn_later():
...     states.discharge(1.0, 2.0)
UserWarning: Due to the following problem, state sequence `discharge` of element `?` handling model `musk` could be initialised with an averaged value only: While trying to set the value(s) of variable `discharge`, 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.discharge
discharge(1.5, 1.5, 1.5)

>>> states.discharge(1.0, 2.0, 3.0)
>>> states.discharge
discharge(1.0, 2.0, 3.0)
name: str = 'statesequence1d'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.musk.musk_sequences.FactorSequence1D(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinSequence1D, FactorSequence

Base class for the 1-dimensional factor sequences.

name: str = 'factorsequence1d'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.musk.musk_sequences.FluxSequence1D(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinSequence1D, FluxSequence

Base class for the 1-dimensional flux sequences.

name: str = 'fluxsequence1d'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

Factor sequences

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

Bases: FactorSequences

Factor sequences of model musk.

The following classes are selected:
class hydpy.models.musk.musk_factors.ReferenceWaterDepth(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Reference water depth [m].

Calculated by the method:

Calc_ReferenceWaterDepth_V1

Required by the methods:

Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1 Calc_WettedArea_SurfaceWidth_Celerity_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'referencewaterdepth'

Name of the variable in lowercase letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_factors.WettedArea(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Wetted area [m²].

Calculated by the methods:

Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1 Calc_WettedArea_SurfaceWidth_Celerity_V1

Required by the method:

Calc_CorrectingFactor_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'wettedarea'

Name of the variable in lowercase letters.

unit: str = 'm²'

Unit of the variable.

class hydpy.models.musk.musk_factors.SurfaceWidth(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Surface width [m].

Calculated by the methods:

Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1 Calc_WettedArea_SurfaceWidth_Celerity_V1

Required by the method:

Calc_ReynoldsNumber_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'surfacewidth'

Name of the variable in lowercase letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_factors.Celerity(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Kinematic celerity (wave speed) [m/T].

Calculated by the methods:

Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1 Calc_WettedArea_SurfaceWidth_Celerity_V1

Required by the methods:

Calc_CorrectingFactor_V1 Calc_CourantNumber_V1 Calc_ReynoldsNumber_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'celerity'

Name of the variable in lowercase letters.

unit: str = 'm/T'

Unit of the variable.

class hydpy.models.musk.musk_factors.CorrectingFactor(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Correcting factor [-].

Calculated by the method:

Calc_CorrectingFactor_V1

Required by the methods:

Calc_CourantNumber_V1 Calc_ReynoldsNumber_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'correctingfactor'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_factors.Coefficient1(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

First coefficient of the Muskingum working formula [-].

Updated by the method:

Calc_Coefficient1_Coefficient2_Coefficient3_V1

Required by the method:

Calc_Discharge_V2

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'coefficient1'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_factors.Coefficient2(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Second coefficient of the Muskingum working formula [-].

Updated by the method:

Calc_Coefficient1_Coefficient2_Coefficient3_V1

Required by the method:

Calc_Discharge_V2

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'coefficient2'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_factors.Coefficient3(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FactorSequence1D

Third coefficient of the Muskingum working formula [-].

Updated by the method:

Calc_Coefficient1_Coefficient2_Coefficient3_V1

Required by the method:

Calc_Discharge_V2

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'coefficient3'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

Flux sequences

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

Bases: FluxSequences

Flux sequences of model musk.

The following classes are selected:
class hydpy.models.musk.musk_fluxes.Inflow(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FluxSequence

Inflow [m³/s].

Calculated by the method:

Pick_Inflow_V1

Updated by the method:

Adjust_Inflow_V1

Required by the method:

Update_Discharge_V1

NDIM: int = 0
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'inflow'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

class hydpy.models.musk.musk_fluxes.ReferenceDischarge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FluxSequence1D

Reference discharge [m³/s].

Calculated by the method:

Calc_ReferenceDischarge_V1

Required by the methods:

Calc_CorrectingFactor_V1 Calc_CourantNumber_V1 Calc_ReferenceWaterDepth_V1 Calc_ReynoldsNumber_V1 Return_ReferenceDischargeError_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
name: str = 'referencedischarge'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

class hydpy.models.musk.musk_fluxes.Outflow(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: FluxSequence

Outflow [m³/s].

Calculated by the method:

Calc_Outflow_V1

Required by the method:

Pass_Outflow_V1

NDIM: int = 0
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'outflow'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

State sequences

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

Bases: StateSequences

State sequences of model musk.

The following classes are selected:
class hydpy.models.musk.musk_states.CourantNumber(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: StateSequence1D

Courant number [-].

Calculated by the method:

Calc_CourantNumber_V1

Required by the method:

Calc_Coefficient1_Coefficient2_Coefficient3_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'courantnumber'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_states.ReynoldsNumber(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: StateSequence1D

Cell Reynolds number [-].

Calculated by the method:

Calc_ReynoldsNumber_V1

Required by the method:

Calc_Coefficient1_Coefficient2_Coefficient3_V1

NDIM: int = 1
NUMERIC: bool = False
SPAN: tuple[int | float | bool | None, int | float | bool | None] = (None, None)
name: str = 'reynoldsnumber'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_states.Discharge(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: StateSequence1D

Current discharge at the segment endpoints [m³/s].

Updated by the methods:

Calc_Discharge_V1 Calc_Discharge_V2 Update_Discharge_V1

Required by the methods:

Calc_Outflow_V1 Calc_ReferenceDischarge_V1

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)
property refweights: ndarray[tuple[Any, ...], dtype[float64]]

Modified relative length of all channel segments.

Opposed to other 1-dimensional musk sequences, Discharge handles values that apply to the start and endpoint of each channel segment. refweights adjusts the returned relative lengths of all segments so that functions like average_values() calculate the weighted average of the mean values of all segments, each one gained by averaging the discharge value at the start and the endpoint:

>>> from hydpy import round_
>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> round_(states.discharge.refweights)
0.166667, 0.333333, 0.333333, 0.166667

>>> states.discharge = 1.0, 2.0, 3.0, 4.0
>>> round_(states.discharge.average_values())
2.5

For a (non-existing) channel with zero segments, refweights a single weight with the value one:

>>> nmbsegments(0)
>>> round_(states.discharge.refweights)
1.0
name: str = 'discharge'

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

Inlet sequences

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

Bases: InletSequences

Inlet sequences of model musk.

The following classes are selected:

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

class hydpy.models.musk.musk_inlets.Q(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: InletSequence

Runoff [m³/s].

Required by the method:

Pick_Inflow_V1

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

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

Outlet sequences

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

Bases: OutletSequences

Outlet sequences of model musk.

The following classes are selected:

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

class hydpy.models.musk.musk_outlets.Q(subvars: ModelIOSequences[ModelIOSequence, FastAccessIOSequence])[source]

Bases: OutletSequence

Runoff [m³/s].

Calculated by the method:

Pass_Outflow_V1

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

Name of the variable in lowercase letters.

unit: str = 'm³/s'

Unit of the variable.

Auxiliary Features

Masks

class hydpy.models.musk.Masks[source]

Bases: Masks

Masks of base model musk.

The following classes are selected:
class hydpy.models.musk.musk_masks.Complete(variable: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]

Bases: DefaultMask

Mask including all channel segments.

name: str = 'complete'
class hydpy.models.musk.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Control parameters of model musk.

The following classes are selected:
class hydpy.models.musk.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model musk.

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

Bases: FactorSequences

Factor sequences of model musk.

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

Bases: FluxSequences

Flux sequences of model musk.

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

Bases: InletSequences

Inlet sequences of model musk.

The following classes are selected:

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

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

Bases: OutletSequences

Outlet sequences of model musk.

The following classes are selected:

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

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

Bases: SubParameters

Solver parameters of model musk.

The following classes are selected:

  • NmbRuns() The number of (repeated) runs of the RUN_METHODS of the current application model per simulation step [-].

  • ToleranceWaterDepth() Acceptable water depth error for determining the reference water depth [m].

  • ToleranceDischarge() Acceptable discharge error for determining the reference water depth [m³/s].

  • ToleranceNegativeInflow() Threshold for setting negative inflow values to zero or nan [m³/s].

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

Bases: StateSequences

State sequences of model musk.

The following classes are selected: