musk

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

Bases: SegmentModel

The HydPy-Musk model.

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

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

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

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

• Calc_Discharge_V1 Apply the routing equation with fixed coefficients.

• Calc_ReferenceDischarge_V1 Estimate the reference discharge according to Todini (2007).

• Calc_ReferenceWaterLevel_V1 Find the reference water level via Pegasus iteration.

• Calc_WettedArea_V1 Calculate the wetted area in a trapezoidal profile.

• Calc_WettedPerimeter_V1 Calculate the wetted perimeter in a trapezoidal profile.

• Calc_SurfaceWidth_V1 Calculate the surface width in a trapezoidal profile.

• Calc_Celerity_V1 Calculate the kinematic celerity in a trapezoidal profile.

• Calc_CorrectingFactor_V1 Calculate the correcting factor according to Todini (2007).

• Calc_CourantNumber_V1 Calculate the Courant number according to Todini (2007).

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

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

• Calc_Discharge_V2 Apply the routing equation with discharge-dependent coefficients.

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:

• Return_WettedArea_V1 Calculate and return the wetted area in a trapezoidal profile.

• Return_WettedPerimeter_V1 Calculate and return the wetted perimeter in a trapezoidal profile.

• Return_SurfaceWidth_V1 Calculate and return the surface width in a trapezoidal profile.

• Return_Discharge_V1 Calculate and return the discharge in a trapezoidal profile after the Gauckler-Manning-Strickler formula under the kinematic wave assumption.

• Return_ReferenceDischargeError_V1 Calculate the difference between the discharge corresponding to the given water level and the reference discharge.

• Return_Celerity_V1 Calculate and return the kinematic celerity in a trapezoidal profile.

The following “submodels” might be called by one or more of the implemented methods or are meant to be directly called by the user:

• PegasusReferenceWaterLevel Pegasus iterator for finding the correct reference water level.

class hydpy.models.musk.musk_model.Pick_Inflow_V1

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.Update_Discharge_V1

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

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

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)

class hydpy.models.musk.musk_model.Return_WettedArea_V1

Bases: Method

Calculate and return the wetted area in a trapezoidal profile.

Required by the methods:

Calc_WettedArea_V1 Return_Celerity_V1 Return_Discharge_V1 Return_ReferenceDischargeError_V1

Requires the control parameters:

BottomWidth SideSlope

Basic equation:

\(waterlevel \cdot (BottomWidth + SideSlope \cdot waterlevel)\)

Examples:

The first example deals with a rectangular profile:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomwidth(2.0)
>>> sideslope(0.0)
>>> from hydpy import round_
>>> round_(model.return_wettedarea_v1(3.0))
6.0

The second example deals with a triangular profile:

>>> bottomwidth(0.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_wettedarea_v1(3.0))
18.0

The third example combines the two profiles defined above into a trapezoidal profile:

>>> bottomwidth(2.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_wettedarea_v1(3.0))
24.0

class hydpy.models.musk.musk_model.Calc_WettedArea_V1

Bases: Method

Calculate the wetted area in a trapezoidal profile.

Required submethod:

Return_WettedArea_V1

Requires the control parameters:

BottomWidth SideSlope

Requires the factor sequence:

ReferenceWaterLevel

Calculates the factor sequence:

WettedArea

Examples:

Method Calc_WettedArea_V1 uses the submethod Return_WettedArea_V1 to calculate the wetted area, from which’s documentation we take the following examples:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> bottomwidth(2.0, 0.0, 2.0)
>>> sideslope(0.0, 2.0, 2.0)
>>> factors.referencewaterlevel = 3.0
>>> model.run_segments(model.calc_wettedarea_v1)
>>> factors.wettedarea
wettedarea(6.0, 18.0, 24.0)

class hydpy.models.musk.musk_model.Return_WettedPerimeter_V1

Bases: Method

Calculate and return the wetted perimeter in a trapezoidal profile.

Required by the methods:

Calc_WettedPerimeter_V1 Return_Celerity_V1 Return_Discharge_V1 Return_ReferenceDischargeError_V1

Requires the control parameters:

BottomWidth SideSlope

Basic equation:

\(BottomWidth + 2 \cdot waterlevel \cdot \sqrt{1 + SideSlope^2}\)

Examples:

The first example deals with a rectangular profile:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomwidth(2.0)
>>> sideslope(0.0)
>>> from hydpy import round_
>>> round_(model.return_wettedperimeter_v1(3.0))
8.0

The second example deals with a triangular profile:

>>> bottomwidth(0.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_wettedperimeter_v1(3.0))
13.416408

The third example combines the two profiles defined above into a trapezoidal profile:

>>> bottomwidth(2.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_wettedperimeter_v1(3.0))
15.416408

class hydpy.models.musk.musk_model.Calc_WettedPerimeter_V1

Bases: Method

Calculate the wetted perimeter in a trapezoidal profile.

Required submethod:

Return_WettedPerimeter_V1

Requires the control parameters:

BottomWidth SideSlope

Requires the factor sequence:

ReferenceWaterLevel

Calculates the factor sequence:

WettedPerimeter

Examples:

Method Calc_WettedPerimeter_V1 uses the submethod Return_WettedPerimeter_V1 to calculate the wetted perimeter, from which’s documentation we take the following examples:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> bottomwidth(2.0, 0.0, 2.0)
>>> sideslope(0.0, 2.0, 2.0)
>>> factors.referencewaterlevel = 3.0
>>> model.run_segments(model.calc_wettedperimeter_v1)
>>> factors.wettedperimeter
wettedperimeter(8.0, 13.416408, 15.416408)

class hydpy.models.musk.musk_model.Return_SurfaceWidth_V1

Bases: Method

Calculate and return the surface width in a trapezoidal profile.

Required by the methods:

Calc_SurfaceWidth_V1 Return_Celerity_V1

Requires the control parameters:

BottomWidth SideSlope

Basic equation:

\(BottomWidth + 2 \cdot SideSlope \cdot waterlevel\)

Examples:

The first example deals with a rectangular profile:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomwidth(2.0)
>>> sideslope(0.0)
>>> from hydpy import round_
>>> round_(model.return_surfacewidth_v1(3.0))
2.0

The second example deals with a triangular profile:

>>> bottomwidth(0.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_surfacewidth_v1(3.0))
12.0

The third example combines the two profiles defined above into a trapezoidal profile:

>>> bottomwidth(2.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_surfacewidth_v1(3.0))
14.0

class hydpy.models.musk.musk_model.Calc_SurfaceWidth_V1

Bases: Method

Calculate the surface width in a trapezoidal profile.

Required submethod:

Return_SurfaceWidth_V1

Requires the control parameters:

BottomWidth SideSlope

Requires the factor sequence:

ReferenceWaterLevel

Calculates the factor sequence:

SurfaceWidth

Examples:

Method Calc_SurfaceWidth_V1 uses the submethod Return_SurfaceWidth_V1 to calculate the surface width, from which’s documentation we take the following examples:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> bottomwidth(2.0, 0.0, 2.0)
>>> sideslope(0.0, 2.0, 2.0)
>>> factors.referencewaterlevel = 3.0
>>> model.run_segments(model.calc_surfacewidth_v1)
>>> factors.surfacewidth
surfacewidth(2.0, 12.0, 14.0)

class hydpy.models.musk.musk_model.Return_Discharge_V1

Bases: Method

Calculate and return the discharge in a trapezoidal profile after the Gauckler-Manning-Strickler formula under the kinematic wave assumption.

Required by the method:

Return_ReferenceDischargeError_V1

Required submethods:

Return_WettedArea_V1 Return_WettedPerimeter_V1

Requires the control parameters:

StricklerCoefficient BottomWidth SideSlope BottomSlope

Basic equation:

:math:` StricklerCoefficient cdot sqrt{BottomSlope} cdot frac{A^{5/3}}{P^{2/3}}`

\(A = Return\_WettedArea(waterlevel)\_V1\)

\(P = Return\_WettedPerimeter(waterlevel)\_V1\)

Examples:

We hold the bottom slope and Strickler coefficient constant in all examples:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomslope(0.01)
>>> stricklercoefficient(20.0)

The first example deals with a rectangular profile:

>>> bottomwidth(2.0)
>>> sideslope(0.0)
>>> from hydpy import round_
>>> round_(model.return_discharge_v1(3.0))
9.905782

The second example deals with a triangular profile:

>>> bottomwidth(0.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_discharge_v1(3.0))
43.791854

In an empty triangular profile, the wetted perimeter is zero. To prevent zero division errors, Return_Discharge_V1 generally returns zero in such cases:

>>> round_(model.return_discharge_v1(0.0))
0.0

The third example combines the two profiles defined above into a trapezoidal profile:

>>> bottomwidth(2.0)
>>> sideslope(2.0)
>>> from hydpy import round_
>>> round_(model.return_discharge_v1(3.0))
64.475285

class hydpy.models.musk.musk_model.Return_ReferenceDischargeError_V1

Bases: Method

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

Required by the method:

Calc_ReferenceWaterLevel_V1

Required submethods:

Return_Discharge_V1 Return_WettedArea_V1 Return_WettedPerimeter_V1

Requires the control parameters:

BottomWidth SideSlope BottomSlope StricklerCoefficient

Requires the flux sequence:

ReferenceDischarge

Basic equation:

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

Example:

The following test calculation extends the trapezoidal profile example of the documentation on method Return_Discharge_V1:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomslope(0.01)
>>> stricklercoefficient(20.0)
>>> bottomwidth(2.0)
>>> sideslope(2.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_ReferenceWaterLevel_V1

Bases: Method

Find the reference water level via Pegasus iteration.

Required submethod:

Return_ReferenceDischargeError_V1

Requires the control parameters:

BottomWidth SideSlope BottomSlope StricklerCoefficient

Requires the solver parameters:

ToleranceWaterLevel ToleranceDischarge

Requires the flux sequence:

ReferenceDischarge

Calculates the factor sequence:

ReferenceWaterLevel

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_ReferenceWaterLevel_V1 restricts the Pegasus search to the lowest water level of 0 m and the highest water level of 1000 m:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> catchmentarea(100.0)
>>> nmbsegments(5)
>>> bottomslope(0.01)
>>> stricklercoefficient(20.0)
>>> bottomwidth(2.0)
>>> sideslope(2.0)
>>> solver.tolerancewaterlevel.update()
>>> solver.tolerancedischarge.update()
>>> fluxes.referencedischarge = -10.0, 0.0, 64.475285, 1000.0, 1000000000.0
>>> model.run_segments(model.calc_referencewaterlevel_v1)
>>> factors.referencewaterlevel
referencewaterlevel(0.0, 0.0, 3.0, 9.199035, 1000.0)

Repeated applications of Calc_ReferenceWaterLevel_V1 should always yield the same results but be often more efficient than the initial calculation due to using old reference water level estimates to gain more precise initial search intervals:

>>> model.run_segments(model.calc_referencewaterlevel_v1)
>>> factors.referencewaterlevel
referencewaterlevel(0.0, 0.0, 3.0, 9.199035, 1000.0)

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

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

Increase at least one parameter to reduce computation time:

>>> solver.tolerancewaterlevel(0.1)
>>> factors.referencewaterlevel = nan
>>> model.run_segments(model.calc_referencewaterlevel_v1)
>>> factors.referencewaterlevel
referencewaterlevel(0.0, 0.0, 3.000295, 9.196508, 1000.0)

class hydpy.models.musk.musk_model.Return_Celerity_V1

Bases: Method

Calculate and return the kinematic celerity in a trapezoidal profile.

Required by the method:

Calc_Celerity_V1

Required submethods:

Return_WettedArea_V1 Return_WettedPerimeter_V1 Return_SurfaceWidth_V1

Requires the control parameters:

BottomWidth SideSlope BottomSlope StricklerCoefficient

Requires the derived parameter:

PerimeterIncrease

Requires the factor sequences:

WettedArea WettedPerimeter SurfaceWidth

Basic equation:

\(StricklerCoefficient \cdot \sqrt{BottomSlope} \cdot \left( \frac{WettedArea}{WettedPerimeter} \right)^{\frac{2}{3}} \cdot \left( \frac{5}{3} - \frac{2 \cdot WettedArea \cdot PerimeterIncrease}{3 \cdot WettedPerimeter \cdot SurfaceWidth} \right)\)

Examples:

We hold the bottom slope and Strickler coefficient constant in all examples:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(1)
>>> bottomslope(0.01)
>>> stricklercoefficient(20.0)

The first example deals with a rectangular profile:

>>> bottomwidth(2.0)
>>> sideslope(0.0)
>>> derived.perimeterincrease.update()
>>> factors.wettedarea = model.return_wettedarea_v1(3.0)
>>> factors.wettedperimeter = model.return_wettedperimeter_v1(3.0)
>>> factors.surfacewidth = model.return_surfacewidth_v1(3.0)
>>> from hydpy import round_
>>> round_(model.return_celerity_v1())
1.926124

The returned celerity relies on the analytical solution of the following differential equation:

\(\frac{\mathrm{d}}{\mathrm{d} h} \frac{Q(h)}{A(h)}\)

We define a test function to check the returned celerity via a numerical approximation:

>>> def check_celerity():
...     q0 = model.return_discharge_v1(3.0-1e-6)
...     q1 = model.return_discharge_v1(3.0+1e-6)
...     a0 = model.return_wettedarea_v1(3.0-1e-6)
...     a1 = model.return_wettedarea_v1(3.0+1e-6)
...     round_((q1 - q0) / (a1 - a0))

>>> check_celerity()
1.926124

The second example deals with a triangular profile:

>>> bottomwidth(0.0)
>>> sideslope(2.0)
>>> derived.perimeterincrease.update()
>>> factors.wettedarea = model.return_wettedarea_v1(3.0)
>>> factors.wettedperimeter = model.return_wettedperimeter_v1(3.0)
>>> factors.surfacewidth = model.return_surfacewidth_v1(3.0)
>>> round_(model.return_celerity_v1())
3.243841
>>> check_celerity()
3.243841

In an empty triangular profile, the wetted perimeter is zero. To prevent zero division errors, Return_Celerity_V1 generally returns zero in such cases:

>>> factors.wettedarea = model.return_wettedarea_v1(0.0)
>>> round_(model.return_celerity_v1())
0.0

The third example combines the two profiles defined above into a trapezoidal profile:

>>> bottomwidth(2.0)
>>> sideslope(2.0)
>>> derived.perimeterincrease.update()
>>> factors.wettedarea = model.return_wettedarea_v1(3.0)
>>> factors.wettedperimeter = model.return_wettedperimeter_v1(3.0)
>>> factors.surfacewidth = model.return_surfacewidth_v1(3.0)
>>> round_(model.return_celerity_v1())
3.586803
>>> check_celerity()
3.586803

class hydpy.models.musk.musk_model.Calc_Celerity_V1

Bases: Method

Calculate the kinematic celerity in a trapezoidal profile.

Required submethod:

Return_Celerity_V1

Requires the control parameters:

BottomWidth SideSlope BottomSlope StricklerCoefficient

Requires the derived parameter:

PerimeterIncrease

Requires the factor sequences:

WettedArea WettedPerimeter SurfaceWidth

Calculates the factor sequence:

Celerity

Examples:

Method Calc_SurfaceWidth_V1 uses the submethod Return_SurfaceWidth_V1 to calculate the kinematic celerity, from which’s documentation we take the following examples:

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> bottomslope(0.01)
>>> stricklercoefficient(20.0)
>>> bottomwidth(2.0, 0.0, 2.0)
>>> sideslope(0.0, 2.0, 2.0)
>>> derived.perimeterincrease.update()
>>> factors.referencewaterlevel = 3.0
>>> model.run_segments(model.calc_wettedarea_v1)
>>> model.run_segments(model.calc_wettedperimeter_v1)
>>> model.run_segments(model.calc_surfacewidth_v1)
>>> model.run_segments(model.calc_celerity_v1)
>>> factors.celerity
celerity(1.926124, 3.243841, 3.586803)

class hydpy.models.musk.musk_model.Calc_CorrectingFactor_V1

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

Bases: Method

Calculate the Courant number according to Todini (2007).

Requires the control parameter:

Length

Requires the derived parameter:

Seconds

Requires the factor sequences:

Celerity CorrectingFactor

Calculates the state sequence:

CourantNumber

Basic equation (equation 50):

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

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)
>>> length(4.0)
>>> derived.seconds(1000.0)
>>> factors.celerity = 2.0
>>> factors.correctingfactor = 0.0, 0.5, 1.0, 2.0, inf
>>> 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

Bases: Method

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

Requires the control parameters:

Length BottomSlope

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 Length}\)

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)
>>> length(4.0)
>>> bottomslope(0.01)
>>> factors.surfacewidth = 5.0
>>> factors.celerity = 2.0
>>> factors.correctingfactor = 0.0, 0.5, 1.0, 2.0, inf
>>> fluxes.referencedischarge = 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

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(5)
>>> length(4.0)
>>> bottomslope(0.01)
>>> derived.seconds(1000.0)
>>> factors.celerity = 2.0
>>> factors.surfacewidth = 5.0
>>> factors.correctingfactor = 0.0, 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(-1.0, 0.026764, -0.309329, -0.582591, -1.0)
>>> factors.coefficient2
coefficient2(1.0, 0.948905, 0.96563, 0.979228, 1.0)
>>> factors.coefficient3
coefficient3(1.0, 0.024331, 0.343699, 0.603363, 1.0)
>>> from hydpy import print_values
>>> print_values(
...     factors.coefficient1 + factors.coefficient2 + factors.coefficient3)
1.0, 1.0, 1.0, 1.0, 1.0

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

>>> print_values(states.courantnumber.old)
0.0, 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

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

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

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.PegasusReferenceWaterLevel(model: Model)

Bases: Pegasus

Pegasus iterator for finding the correct reference water level.

METHODS: ClassVar[Tuple[Type[Method], ...]] = (<class 'hydpy.models.musk.musk_model.Return_ReferenceDischargeError_V1'>,)

name = 'pegasusreferencewaterlevel'

Parameter Features

Parameter tools

class hydpy.models.musk.musk_parameters.Parameter1D(subvars: SubParameters)

Bases: Parameter

Base class for the 1-dimensional parameters.

NDIM: int = 1

property refweights: ndarray[Any, dtype[float64]]

The relative length of all channel segments.

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> length(4.0, 1.0, 3.0)
>>> bottomwidth.refweights
array([0.5  , 0.125, 0.375])

name: str = 'parameter1d'

Name of the variable in lower case letters.

unit: str = '?'

Unit of the variable.

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:

• CatchmentArea() Size of the catchment draining into the channel [km²].

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

• Coefficients() Coefficients of the Muskingum working formula [-].

• Length() Segment length [km].

• BottomSlope() Bottom slope [-].

• BottomWidth() Bottom width [m].

• SideSlope() Side slope [-].

• StricklerCoefficient() Gauckler-Manning-Strickler coefficient [m^(1/3)/s].

class hydpy.models.musk.musk_control.CatchmentArea(subvars: SubParameters)

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 lower case letters.

unit: str = 'km²'

Unit of the variable.

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

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:

>>> length.shape
(2,)
>>> derived.perimeterincrease.shape
(2,)
>>> factors.referencewaterlevel.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 lower case letters.

unit: str = '-'

Unit of the variable.

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

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_values
>>> coefficients(damp=0.0)
>>> coefficients
coefficients(damp=0.0)
>>> print_values(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_values(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_values(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_values(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_values(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_values(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_values(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_values(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_values(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_values(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 lower case letters.

unit: str = '-'

Unit of the variable.

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

Bases: Parameter

Segment length [km].

Required by the methods:

Calc_CourantNumber_V1 Calc_ReynoldsNumber_V1

NDIM: int = 1

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 lower case letters.

unit: str = 'km'

Unit of the variable.

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

Bases: Parameter1D

Bottom slope [-].

Required by the methods:

Calc_Celerity_V1 Calc_ReferenceWaterLevel_V1 Calc_ReynoldsNumber_V1 Return_Celerity_V1 Return_Discharge_V1 Return_ReferenceDischargeError_V1

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

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 lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_control.BottomWidth(subvars: SubParameters)

Bases: Parameter1D

Bottom width [m].

Required by the methods:

Calc_Celerity_V1 Calc_ReferenceWaterLevel_V1 Calc_SurfaceWidth_V1 Calc_WettedArea_V1 Calc_WettedPerimeter_V1 Return_Celerity_V1 Return_Discharge_V1 Return_ReferenceDischargeError_V1 Return_SurfaceWidth_V1 Return_WettedArea_V1 Return_WettedPerimeter_V1

TYPE

alias of float

TIME: bool | None = None

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'bottomwidth'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_control.SideSlope(subvars: SubParameters)

Bases: Parameter1D

Side slope [-].

Required by the methods:

Calc_Celerity_V1 Calc_ReferenceWaterLevel_V1 Calc_SurfaceWidth_V1 Calc_WettedArea_V1 Calc_WettedPerimeter_V1 Return_Celerity_V1 Return_Discharge_V1 Return_ReferenceDischargeError_V1 Return_SurfaceWidth_V1 Return_WettedArea_V1 Return_WettedPerimeter_V1

A value of zero corresponds to a rectangular channel shape. A value of two corresponds to an increase of a half meter elevation for each additional meter distance from the channel.

TYPE

alias of float

TIME: bool | None = None

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'sideslope'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_control.StricklerCoefficient(subvars: SubParameters)

Bases: Parameter1D

Gauckler-Manning-Strickler coefficient [m^(1/3)/s].

Required by the methods:

Calc_Celerity_V1 Calc_ReferenceWaterLevel_V1 Return_Celerity_V1 Return_Discharge_V1 Return_ReferenceDischargeError_V1

The higher the coefficient’s value, the higher the calculated discharge. Typical values range from 20 to 80.

TYPE

alias of float

TIME: bool | None = None

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'stricklercoefficient'

Name of the variable in lower case letters.

unit: str = 'm^(1/3)/s'

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:

• Seconds() Length of the actual simulation step size [s].

• PerimeterIncrease() Increase of the (wetted) perimeter of a trapozoidal profile relative to a water level increase [-].

class hydpy.models.musk.musk_derived.Seconds(subvars: SubParameters)

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 lower case letters.

unit: str = 's'

Unit of the variable.

class hydpy.models.musk.musk_derived.PerimeterIncrease(subvars: SubParameters)

Bases: Parameter1D

Increase of the (wetted) perimeter of a trapozoidal profile relative to a water level increase [-].

Required by the methods:

Calc_Celerity_V1 Return_Celerity_V1

TYPE

alias of float

TIME: bool | None = None

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

update()

Update PerimeterIncrease based on SideSlope following \(2 \cdot \sqrt{1 + SideSlope^2}\).

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(2)
>>> sideslope(0.0, 2.0)
>>> derived.perimeterincrease.update()
>>> derived.perimeterincrease
perimeterincrease(2.0, 4.472136)

name: str = 'perimeterincrease'

Name of the variable in lower case letters.

unit: str = '-'

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 [-].

• ToleranceWaterLevel() Acceptable water level error for determining the reference water level [m].

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

class hydpy.models.musk.musk_solver.NmbRuns(subvars)

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

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

name: str = 'nmbruns'

Name of the variable in lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_solver.ToleranceWaterLevel(subvars)

Bases: SolverParameter

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

Required by the method:

Calc_ReferenceWaterLevel_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 = 'tolerancewaterlevel'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_solver.ToleranceDischarge(subvars)

Bases: SolverParameter

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

Required by the method:

Calc_ReferenceWaterLevel_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() → None

Adjust and return the value of class constant INIT.

Ideally, in the long term, the iterative search for the reference water level 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 lower case letters.

unit: str = 'm³/s'

Unit of the variable.

Sequence Features

Sequence tools

class hydpy.models.musk.musk_sequences.MixinSequence1D

Bases: object

Mixin class for the 1-dimensional sequences.

NDIM = 1

NUMERIC = False

property refweights: ndarray[Any, dtype[float64]]

The relative length of all channel segments.

>>> from hydpy.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> length(4.0, 1.0, 3.0)
>>> fluxes.referencedischarge.refweights
array([0.5  , 0.125, 0.375])

class hydpy.models.musk.musk_sequences.StateSequence1D(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.musk.musk_sequences.FactorSequence1D(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: MixinSequence1D, FactorSequence

Base class for the 1-dimensional factor sequences.

name: str = 'factorsequence1d'

Name of the variable in lower case letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.musk.musk_sequences.FluxSequence1D(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: MixinSequence1D, FluxSequence

Base class for the 1-dimensional flux sequences.

name: str = 'fluxsequence1d'

Name of the variable in lower case 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:

• ReferenceWaterLevel() Reference water level [m].

• WettedArea() Wetted area [m²].

• WettedPerimeter() Wetted perimeter [m].

• SurfaceWidth() Surface width [m].

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

• CorrectingFactor() Correcting factor [-].

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

• Coefficient2() Second coefficient of the Muskingum working formula [-].

• Coefficient3() Third coefficient of the Muskingum working formula [-].

class hydpy.models.musk.musk_factors.ReferenceWaterLevel(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FactorSequence1D

Reference water level [m].

Calculated by the method:

Calc_ReferenceWaterLevel_V1

Required by the methods:

Calc_SurfaceWidth_V1 Calc_WettedArea_V1 Calc_WettedPerimeter_V1

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'referencewaterlevel'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_factors.WettedArea(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FactorSequence1D

Wetted area [m²].

Calculated by the method:

Calc_WettedArea_V1

Required by the methods:

Calc_Celerity_V1 Calc_CorrectingFactor_V1 Return_Celerity_V1

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'wettedarea'

Name of the variable in lower case letters.

unit: str = 'm²'

Unit of the variable.

class hydpy.models.musk.musk_factors.WettedPerimeter(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FactorSequence1D

Wetted perimeter [m].

Calculated by the method:

Calc_WettedPerimeter_V1

Required by the methods:

Calc_Celerity_V1 Return_Celerity_V1

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'wettedperimeter'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_factors.SurfaceWidth(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FactorSequence1D

Surface width [m].

Calculated by the method:

Calc_SurfaceWidth_V1

Required by the methods:

Calc_Celerity_V1 Calc_ReynoldsNumber_V1 Return_Celerity_V1

SPAN: Tuple[int | float | bool | None, int | float | bool | None] = (0.0, None)

name: str = 'surfacewidth'

Name of the variable in lower case letters.

unit: str = 'm'

Unit of the variable.

class hydpy.models.musk.musk_factors.Celerity(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FactorSequence1D

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

Calculated by the method:

Calc_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 lower case letters.

unit: str = 'm/T'

Unit of the variable.

class hydpy.models.musk.musk_factors.CorrectingFactor(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_factors.Coefficient1(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_factors.Coefficient2(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_factors.Coefficient3(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case 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:

• Inflow() Inflow [m³/s].

• ReferenceDischarge() Reference discharge [m³/s].

• Outflow() Outflow [m³/s].

class hydpy.models.musk.musk_fluxes.Inflow(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FluxSequence

Inflow [m³/s].

Calculated by the method:

Pick_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 lower case letters.

unit: str = 'm³/s'

Unit of the variable.

class hydpy.models.musk.musk_fluxes.ReferenceDischarge(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FluxSequence1D

Reference discharge [m³/s].

Calculated by the method:

Calc_ReferenceDischarge_V1

Required by the methods:

Calc_CorrectingFactor_V1 Calc_ReferenceWaterLevel_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 lower case letters.

unit: str = 'm³/s'

Unit of the variable.

class hydpy.models.musk.musk_fluxes.Outflow(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case 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:

• CourantNumber() Courant number [-].

• ReynoldsNumber() Cell Reynolds number [-].

• Discharge() Current discharge at the segment endpoints [m³/s].

class hydpy.models.musk.musk_states.CourantNumber(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_states.ReynoldsNumber(subvars: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.musk.musk_states.Discharge(subvars: ModelSequences[ModelSequence, FastAccess])

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[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.models.musk import *
>>> parameterstep()
>>> nmbsegments(3)
>>> length(4.0, 1.0, 3.0)
>>> states.discharge.refweights
array([0.25  , 0.3125, 0.25  , 0.1875])

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

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

>>> nmbsegments(0)
>>> states.discharge.refweights
array([1.])

name: str = 'discharge'

Name of the variable in lower case 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: ModelSequences[ModelSequence, FastAccess])

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 lower case 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: ModelSequences[ModelSequence, FastAccess])

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 lower case letters.

unit: str = 'm³/s'

Unit of the variable.

Auxiliary Features

Masks

class hydpy.models.musk.Masks

Bases: Masks

Masks of base model musk.

The following classes are selected:

• Complete() Mask including all channel segments.

class hydpy.models.musk.musk_masks.Complete(variable: VariableProtocol | None = None, **kwargs)

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:

• CatchmentArea() Size of the catchment draining into the channel [km²].

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

• Coefficients() Coefficients of the Muskingum working formula [-].

• Length() Segment length [km].

• BottomSlope() Bottom slope [-].

• BottomWidth() Bottom width [m].

• SideSlope() Side slope [-].

• StricklerCoefficient() Gauckler-Manning-Strickler coefficient [m^(1/3)/s].

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:

• Seconds() Length of the actual simulation step size [s].

• PerimeterIncrease() Increase of the (wetted) perimeter of a trapozoidal profile relative to a water level increase [-].

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:

• ReferenceWaterLevel() Reference water level [m].

• WettedArea() Wetted area [m²].

• WettedPerimeter() Wetted perimeter [m].

• SurfaceWidth() Surface width [m].

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

• CorrectingFactor() Correcting factor [-].

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

• Coefficient2() Second coefficient of the Muskingum working formula [-].

• Coefficient3() Third coefficient of the Muskingum working formula [-].

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:

• Inflow() Inflow [m³/s].

• ReferenceDischarge() Reference discharge [m³/s].

• Outflow() Outflow [m³/s].

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 [-].

• ToleranceWaterLevel() Acceptable water level error for determining the reference water level [m].

• ToleranceDischarge() Acceptable discharge error for determining the reference water level [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:

• CourantNumber() Courant number [-].

• ReynoldsNumber() Cell Reynolds number [-].

• Discharge() Current discharge at the segment endpoints [m³/s].