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:
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_ReferenceWaterDepth_V1
Find the reference water depth viaPegasus
iteration.Calc_WettedArea_SurfaceWidth_Celerity_V1
Let a submodel that follows theCrossSectionModel_V1
interface calculate all its properties based on the current reference water level and query the wetted area, the surface width, and the celerity.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_Discharge_CrossSectionModel_V1
Let a submodel that follows theCrossSectionModel_V1
submodel interface calculate the discharge for the given water depth and return it.Return_ReferenceDischargeError_V1
Calculate the difference between the discharge corresponding to the given water depth and the reference discharge.Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1
Let a submodel that follows theCrossSectionModel_V1
interface calculate all its properties based on the current reference water level and query the wetted area, the surface width, and the celerity.
- The following “submodels” might be called by one or more of the implemented methods or are meant to be directly called by the user:
PegasusReferenceWaterDepth
Pegasus iterator for finding the correct reference water depth.
- 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.
- class hydpy.models.musk.musk_model.Update_Discharge_V1[source]¶
Bases:
Method
Assign the inflow to the start point of the first channel segment.
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:
- Updates the state sequence:
- 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:
- Calculates the flux sequence:
- 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 propertyIdx_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_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:
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:
- Required submethod:
- Requires the flux sequence:
- 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) >>> 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:
- Requires the solver parameters:
- Requires the flux sequence:
- Calculates the factor sequence:
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 methodCalc_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) >>> 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 theToleranceDischarge
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:
- Requires the factor sequence:
- Calculates the factor sequences:
- 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:
- Requires the factor sequence:
- Calculates the factor sequences:
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) >>> 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:
- Requires the flux sequence:
- Calculates the factor sequence:
- 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:
- Requires the factor sequences:
- Calculates the state sequence:
- 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 >>> 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:
- Requires the derived parameter:
- Requires the factor sequences:
- Requires the flux sequence:
- Calculates the state sequence:
- 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 = 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:
- Updates the factor sequences:
- 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) >>> bottomslope(0.01) >>> derived.seconds(1000.0) >>> derived.segmentlength(4.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_vector >>> print_vector( ... 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_vector(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[source]¶
Bases:
Method
Apply the routing equation with discharge-dependent coefficients.
- Requires the factor sequences:
- Updates the state sequence:
- 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:
- Requires the state sequence:
- Calculates the flux sequence:
- 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.
- class hydpy.models.musk.musk_model.PegasusReferenceWaterDepth(model: Model)[source]¶
Bases:
Pegasus
Pegasus iterator for finding the correct reference water depth.
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:
CatchmentArea()
Size of the catchment draining into the channel [km²].NmbSegments()
Number of channel segments [-].Coefficients()
Coefficients of the Muskingum working formula [-].Length()
The total length of channel [km].BottomSlope()
Bottom slope [-].
- class hydpy.models.musk.musk_control.CatchmentArea(subvars: SubParameters)[source]¶
Bases:
Parameter
Size of the catchment draining into the channel [km²].
- class hydpy.models.musk.musk_control.NmbSegments(subvars: SubParameters)[source]¶
Bases:
Parameter
Number of channel segments [-].
- Required by the method:
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)
- class hydpy.models.musk.musk_control.Coefficients(subvars: SubParameters)[source]¶
Bases:
MixinFixedShape
,Parameter
Coefficients of the Muskingum working formula [-].
- Required by the method:
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
- class hydpy.models.musk.musk_control.Length(subvars: SubParameters)[source]¶
Bases:
Parameter
The total length of channel [km].
- class hydpy.models.musk.musk_control.BottomSlope(subvars: SubParameters)[source]¶
Bases:
Parameter
Bottom slope [-].
- Required by the method:
\(BottomSlope = \frac{elevation_{start} - elevation_{end}}{Length}\)
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].SegmentLength()
The length of each channel segments [km].
- class hydpy.models.musk.musk_derived.Seconds(subvars: SubParameters)[source]¶
Bases:
SecondsParameter
Length of the actual simulation step size [s].
- Required by the method:
- class hydpy.models.musk.musk_derived.SegmentLength(subvars: SubParameters)[source]¶
Bases:
Parameter
The length of each channel segments [km].
- Required by the methods:
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 theRUN_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].
- 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.
- 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:
- 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:
- 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)
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¶
- class hydpy.models.musk.musk_sequences.StateSequence1D(subvars: ModelSequences[ModelSequence, FastAccess])[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)
- class hydpy.models.musk.musk_sequences.FactorSequence1D(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
MixinSequence1D
,FactorSequence
Base class for the 1-dimensional factor sequences.
- class hydpy.models.musk.musk_sequences.FluxSequence1D(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
MixinSequence1D
,FluxSequence
Base class for the 1-dimensional flux sequences.
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:
ReferenceWaterDepth()
Reference water depth [m].WettedArea()
Wetted area [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.ReferenceWaterDepth(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FactorSequence1D
Reference water depth [m].
- Calculated by the method:
- Required by the methods:
Calc_WettedArea_SurfaceWidth_Celerity_CrossSectionModel_V1
Calc_WettedArea_SurfaceWidth_Celerity_V1
- class hydpy.models.musk.musk_factors.WettedArea(subvars: ModelSequences[ModelSequence, FastAccess])[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:
- class hydpy.models.musk.musk_factors.SurfaceWidth(subvars: ModelSequences[ModelSequence, FastAccess])[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:
- class hydpy.models.musk.musk_factors.Celerity(subvars: ModelSequences[ModelSequence, FastAccess])[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
- class hydpy.models.musk.musk_factors.CorrectingFactor(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FactorSequence1D
Correcting factor [-].
- Calculated by the method:
- Required by the methods:
- class hydpy.models.musk.musk_factors.Coefficient1(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FactorSequence1D
First coefficient of the Muskingum working formula [-].
- Updated by the method:
- Required by the method:
- class hydpy.models.musk.musk_factors.Coefficient2(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FactorSequence1D
Second coefficient of the Muskingum working formula [-].
- Updated by the method:
- Required by the method:
- class hydpy.models.musk.musk_factors.Coefficient3(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FactorSequence1D
Third coefficient of the Muskingum working formula [-].
- Updated by the method:
- Required by the method:
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])[source]¶
Bases:
FluxSequence
Inflow [m³/s].
- Calculated by the method:
- Required by the method:
- class hydpy.models.musk.musk_fluxes.ReferenceDischarge(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FluxSequence1D
Reference discharge [m³/s].
- Calculated by the method:
- Required by the methods:
Calc_CorrectingFactor_V1
Calc_ReferenceWaterDepth_V1
Calc_ReynoldsNumber_V1
Return_ReferenceDischargeError_V1
- class hydpy.models.musk.musk_fluxes.Outflow(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
FluxSequence
Outflow [m³/s].
- Calculated by the method:
- Required by the method:
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])[source]¶
Bases:
StateSequence1D
Courant number [-].
- Calculated by the method:
- Required by the method:
- class hydpy.models.musk.musk_states.ReynoldsNumber(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
StateSequence1D
Cell Reynolds number [-].
- Calculated by the method:
- Required by the method:
- class hydpy.models.musk.musk_states.Discharge(subvars: ModelSequences[ModelSequence, FastAccess])[source]¶
Bases:
StateSequence1D
Current discharge at the segment endpoints [m³/s].
- Updated by the methods:
- Required by the methods:
- 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 likeaverage_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
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])[source]¶
Bases:
InletSequence
Runoff [m³/s].
- Required by the method:
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])[source]¶
Bases:
OutletSequence
Runoff [m³/s].
- Calculated by the method:
Auxiliary Features¶
Masks¶
- class hydpy.models.musk.Masks[source]
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: variabletools.Variable | None = None, doc: str | None = None, **kwargs)[source]¶
Bases:
DefaultMask
Mask including all channel segments.
- 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()
The total length of channel [km].BottomSlope()
Bottom slope [-].
- 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].SegmentLength()
The length of each channel segments [km].
- 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:
ReferenceWaterDepth()
Reference water depth [m].WettedArea()
Wetted area [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 theRUN_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].
- 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].