HydPy-Conv (base model)

The HydPy-Conv (base model) model family allows connecting different kinds of models providing output and requiring input that does not fit immediately.

Method features

class hydpy.models.conv.conv_model.Model[source]

Bases: AdHocModel

HydPy-Conv (base model).

The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:
The following “run methods” are called in the given sequence during each simulation step:
The following “outlet update methods” are called in the given sequence at the end of each simulation step:
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:
DOCNAME = ('Conv', 'base model')
REUSABLE_METHODS = ()
class hydpy.models.conv.conv_model.Pick_Inputs_V1[source]

Bases: Method

Pick the input from all inlet nodes.

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

Requires the derived parameter:

NmbInputs

Requires the inlet sequence:

Inputs

Calculates the flux sequence:

Inputs

Example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmbinputs(2)
>>> inlets.inputs.shape = 2
>>> inlets.inputs = 2.0, 4.0
>>> model.pick_inputs_v1()
>>> fluxes.inputs
inputs(2.0, 4.0)
class hydpy.models.conv.conv_model.Calc_Outputs_V1[source]

Bases: Method

Perform a simple proximity-based interpolation.

Used by the application model:

conv_nn

Requires the control parameter:

MaxNmbInputs

Requires the derived parameters:

NmbOutputs ProximityOrder

Requires the flux sequence:

Inputs

Calculates the flux sequence:

Outputs

Examples:

With complete input data, method Calc_Outputs_V1 performs the most simple nearest-neighbour approach:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> maxnmbinputs.value = 1
>>> derived.nmboutputs(3)
>>> derived.proximityorder.shape = (3, 1)
>>> derived.proximityorder([[0], [1], [0]])
>>> fluxes.inputs.shape = 2
>>> fluxes.inputs = 1.0, 2.0
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(1.0, 2.0, 1.0)

With incomplete data, it subsequently checks the second-nearest location, the third-nearest location, and so on, until it finds an actual value. Parameter MaxNmbInputs defines the maximum number of considered locations:

>>> fluxes.inputs = 1.0, nan
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(1.0, nan, 1.0)
>>> maxnmbinputs.value = 2
>>> derived.proximityorder.shape = (3, 2)
>>> derived.proximityorder([[0, 1], [1, 0], [0, 1]])
>>> model.calc_outputs_v1()
>>> fluxes.outputs
outputs(1.0, 1.0, 1.0)
class hydpy.models.conv.conv_model.Return_Mean_V1[source]

Bases: Method

Return the arithmetic mean value for the given vector.

Used by the application model:

conv_idw_ed

Examples:

Method Return_Mean_V1 requires two vectors and one integer value. The first vector (in the following examples: Inputs) handles the data to be averaged. The second vector (Outputs) serves as a mask. Method Return_Mean_V1 takes only those vector positions into account, where the value of the mask vector is not nan. The integer value defines the length of both vectors:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> fluxes.inputs.shape = 3
>>> fluxes.outputs.shape = 3
>>> fluxes.inputs = 0.0, 1.0, 5.0
>>> fluxes.outputs = 9.9, 9.9, 9.9
>>> from hydpy import round_
>>> round_(model.return_mean_v1(fluxes.inputs.values, fluxes.outputs.values, 3))
2.0
>>> fluxes.outputs = nan, 9.9, nan
>>> round_(model.return_mean_v1(fluxes.inputs.values, fluxes.outputs.values, 3))
1.0
>>> fluxes.outputs = nan, nan, nan
>>> round_(model.return_mean_v1(fluxes.inputs.values, fluxes.outputs.values, 3))
nan
class hydpy.models.conv.conv_model.Calc_ActualConstant_ActualFactor_V1[source]

Bases: Method

Calculate the linear regression coefficients ActualConstant and ActualFactor for modelling the relationship between Inputs (dependent variable) and Heights (independent variable).

Used by the application model:

conv_idw_ed

Requires the control parameters:

InputHeights MinNmbInputs DefaultConstant DefaultFactor

Requires the derived parameter:

NmbInputs

Requires the flux sequence:

Inputs

Calculates the flux sequences:

ActualConstant ActualFactor

Examples:

First, we calculate both regression coefficients for a small data set consisting of only three data points:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputheights.shape = 3
>>> inputheights.values = 1.0, 2.0, 3.0
>>> minnmbinputs(3)
>>> derived.nmbinputs(3)
>>> fluxes.inputs = 2.0, 3.0, 5.0
>>> model.calc_actualconstant_actualfactor_v1()
>>> fluxes.actualconstant
actualconstant(0.333333)
>>> fluxes.actualfactor
actualfactor(1.5)

In the last example, the required number of data points (MinNmbInputs) exactly agrees with the available number of data points. In the next example, we insert a nan value into the Inputs array to reduce the number of available data points to two. Then, Calc_ActualConstant_ActualFactor_V1 falls back to the default values provided by the control parameters DefaultConstant and DefaultFactor:

>>> fluxes.inputs = 2.0, nan, 5.0
>>> defaultconstant(0.0)
>>> defaultfactor(1.0)
>>> model.calc_actualconstant_actualfactor_v1()
>>> fluxes.actualconstant
actualconstant(0.0)
>>> fluxes.actualfactor
actualfactor(1.0)

If we lower our data requirements, method Calc_ActualConstant_ActualFactor_V1 uses the remaining two data points to calculate the coefficients:

>>> minnmbinputs(2)
>>> model.calc_actualconstant_actualfactor_v1()
>>> fluxes.actualconstant
actualconstant(0.5)
>>> fluxes.actualfactor
actualfactor(1.5)

The following two examples deal with a perfect and a non-existing linear relationship:

>>> fluxes.inputs = 2.0, 4.0, 6.0
>>> model.calc_actualconstant_actualfactor_v1()
>>> fluxes.actualconstant
actualconstant(0.0)
>>> fluxes.actualfactor
actualfactor(2.0)
>>> fluxes.inputs = 1.0, 4.0, 1.0
>>> model.calc_actualconstant_actualfactor_v1()
>>> fluxes.actualconstant
actualconstant(2.0)
>>> fluxes.actualfactor
actualfactor(0.0)

In case all values of the independent variable are the same, method Calc_ActualConstant_ActualFactor_V1 again uses the provided default values:

>>> inputheights.values = 1.0, 1.0, 1.0
>>> model.calc_actualconstant_actualfactor_v1()
>>> fluxes.actualconstant
actualconstant(0.0)
>>> fluxes.actualfactor
actualfactor(1.0)
class hydpy.models.conv.conv_model.Calc_InputPredictions_V1[source]

Bases: Method

Predict the values of the input nodes based on a linear model.

Used by the application model:

conv_idw_ed

Requires the control parameter:

InputHeights

Requires the derived parameter:

NmbInputs

Requires the flux sequences:

ActualConstant ActualFactor

Calculates the flux sequence:

InputPredictions

Basic equation:

\(InputPredictions = ActualConstant + ActualFactor \cdot InputHeights\)

Example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputheights.shape = 2
>>> inputheights.values = 1.0, 2.0
>>> derived.nmbinputs(2)
>>> fluxes.actualconstant(1.0)
>>> fluxes.actualfactor(2.0)
>>> model.calc_inputpredictions_v1()
>>> fluxes.inputpredictions
inputpredictions(3.0, 5.0)
class hydpy.models.conv.conv_model.Calc_OutputPredictions_V1[source]

Bases: Method

Predict the values of the output nodes based on a linear model.

Used by the application model:

conv_idw_ed

Requires the control parameter:

OutputHeights

Requires the derived parameter:

NmbOutputs

Requires the flux sequences:

ActualConstant ActualFactor

Calculates the flux sequence:

OutputPredictions

Basic equation:

\(OutputPredictions = ActualConstant + ActualFactor \cdot OutputHeights\)

Example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> outputheights.shape = 2
>>> outputheights.values = 1.0, 2.0
>>> derived.nmboutputs(2)
>>> fluxes.actualconstant(1.0)
>>> fluxes.actualfactor(2.0)
>>> model.calc_outputpredictions_v1()
>>> fluxes.outputpredictions
outputpredictions(3.0, 5.0)
class hydpy.models.conv.conv_model.Calc_CurrentInputAverages_V1[source]

Bases: Method

Take the long-term averages of the input nodes for the current month.

Used by the application model:

conv_idw_cm

Requires the control parameter:

InputAverages

Requires the derived parameters:

MOY NmbInputs

Calculates the flux sequence:

CurrentInputAverages

Basic equation:

\(CurrentInputAverages = InputAverages_{month}\)

Example:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-30", "2000-02-03", "1d"
>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmbinputs(2)
>>> inputaverages(5.0)
>>> inputaverages.values[0, :2] = 2.0, 1.0
>>> derived.moy.update()
>>> model.idx_sim = pub.timegrids.init["2000-01-31"]
>>> model.calc_currentinputaverages_v1()
>>> fluxes.currentinputaverages
currentinputaverages(2.0, 5.0)
>>> model.idx_sim = pub.timegrids.init["2000-02-01"]
>>> model.calc_currentinputaverages_v1()
>>> fluxes.currentinputaverages
currentinputaverages(1.0, 5.0)
class hydpy.models.conv.conv_model.Calc_CurrentOutputAverages_V1[source]

Bases: Method

Take the long-term averages of the output nodes for the current month.

Used by the application model:

conv_idw_cm

Requires the control parameter:

OutputAverages

Requires the derived parameters:

MOY NmbOutputs

Calculates the flux sequence:

CurrentOutputAverages

Basic equation:

\(CurrentOutputAverages = OutputAverages_{month}\)

Example:

>>> from hydpy import pub
>>> pub.timegrids = "2000-01-30", "2000-02-03", "1d"
>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmboutputs(2)
>>> outputaverages(5.0)
>>> outputaverages.values[0, :2] = 2.0, 1.0
>>> derived.moy.update()
>>> model.idx_sim = pub.timegrids.init["2000-01-31"]
>>> model.calc_currentoutputaverages_v1()
>>> fluxes.currentoutputaverages
currentoutputaverages(2.0, 5.0)
>>> model.idx_sim = pub.timegrids.init["2000-02-01"]
>>> model.calc_currentoutputaverages_v1()
>>> fluxes.currentoutputaverages
currentoutputaverages(1.0, 5.0)
class hydpy.models.conv.conv_model.Calc_InputRatios_V1[source]

Bases: Method

Calculate the ratios between the values of the input nodes and their long-term averages for the current month.

Used by the application model:

conv_idw_cm

Requires the derived parameter:

NmbInputs

Requires the flux sequences:

Inputs CurrentInputAverages

Calculates the flux sequence:

InputRatios

Basic equation:

\(InputRatios = \frac{Inputs}{CurrentInputAverages}\)

Examples:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmbinputs(3)
>>> fluxes.inputs = 3.0, 0.0, nan
>>> fluxes.currentinputaverages = 2.0
>>> model.calc_inputratios_v1()
>>> fluxes.inputratios
inputratios(1.5, 0.0, nan)

The ratios are undefined for averages of zero. Method Calc_InputRatios_V1 sets them to nan, which excludes the respective input nodes from the subsequent interpolation:

>>> fluxes.currentinputaverages = 0.0
>>> model.calc_inputratios_v1()
>>> fluxes.inputratios
inputratios(nan, nan, nan)

The same holds for missing averages:

>>> fluxes.currentinputaverages = nan
>>> model.calc_inputratios_v1()
>>> fluxes.inputratios
inputratios(nan, nan, nan)
class hydpy.models.conv.conv_model.Calc_InputResiduals_V1[source]

Bases: Method

Determine the residuals at the input nodes.

Used by the application model:

conv_idw_ed

Requires the derived parameter:

NmbInputs

Requires the flux sequences:

Inputs InputPredictions

Calculates the flux sequence:

InputResiduals

Basic equation:

\(InputResiduals = Inputs - InputPredictions\)

Example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmbinputs(2)
>>> fluxes.inputs = 1.0, 2.0
>>> fluxes.inputpredictions = 0.0, 4.0
>>> model.calc_inputresiduals_v1()
>>> fluxes.inputresiduals
inputresiduals(1.0, -2.0)
class hydpy.models.conv.conv_model.Interpolate_InverseDistance_V1[source]

Bases: Method

Perform a simple inverse distance weighted interpolation.

Required by the methods:

Calc_OutputRatios_V1 Calc_OutputResiduals_V1 Calc_Outputs_V2

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed

Requires the control parameter:

MaxNmbInputs

Requires the derived parameters:

NmbOutputs ProximityOrder Weights

See the documentation on method Calc_Outputs_V2 for further information.

class hydpy.models.conv.conv_model.Calc_Outputs_V2[source]

Bases: Method

Perform a simple inverse distance weighted interpolation based on the original data supplied by the input nodes.

Used by the application model:

conv_idw

Required submethod:

Interpolate_InverseDistance_V1

Requires the control parameter:

MaxNmbInputs

Requires the derived parameters:

NmbOutputs ProximityOrder Weights

Requires the flux sequence:

Inputs

Calculates the flux sequence:

Outputs

Examples:

With complete input data, method Calc_Outputs_V2 performs the most simple inverse distance weighted approach:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> maxnmbinputs.value = 4
>>> derived.nmboutputs(3)
>>> derived.proximityorder.shape = 3, 4
>>> derived.proximityorder([[0, 2, 1, 3],
...                         [1, 0, 2, 3],
...                         [0, 2, 1, 3]])
>>> derived.weights.shape = 3, 4
>>> derived.weights([[inf, inf, 0.05, 0.000053],
...                  [0.5, 0.029412, 0.029412, 0.000052],
...                  [0.5, 0.5, 0.1, 0.000053]])
>>> fluxes.inputs.shape = 4
>>> fluxes.inputs = 1.0, 5.0, 3.0, 6.0
>>> model.calc_outputs_v2()
>>> fluxes.outputs
outputs(2.0, 4.684331, 2.272907)

With incomplete data, it subsequently skips all missing values. Parameter MaxNmbInputs defines the maximum number of considered locations:

>>> fluxes.inputs = nan, 5.0, nan, 6.0
>>> model.calc_outputs_v2()
>>> fluxes.outputs
outputs(5.001059, 5.000104, 5.00053)

With just one considered location, method Calc_Outputs_V2 calculates the same results as the nearest-neighbour approach implemented by method Calc_Outputs_V1:

>>> maxnmbinputs.value = 1
>>> derived.proximityorder.shape = 3, 1
>>> derived.proximityorder([[0],
...                         [1],
...                         [0]])
>>> derived.weights.shape = 3, 1
>>> derived.weights([[inf],
...                  [0.5],
...                  [0.5]])
>>> model.calc_outputs_v2()
>>> fluxes.outputs
outputs(nan, 5.0, nan)
class hydpy.models.conv.conv_model.Calc_OutputResiduals_V1[source]

Bases: Method

Perform a simple inverse distance weighted interpolation based on the residuals previously determined for the input nodes.

Used by the application model:

conv_idw_ed

Required submethod:

Interpolate_InverseDistance_V1

Requires the control parameter:

MaxNmbInputs

Requires the derived parameters:

NmbOutputs ProximityOrder Weights

Requires the flux sequence:

InputResiduals

Calculates the flux sequence:

OutputResiduals

Example:

See the documentation on method Calc_Outputs_V2 for further information, from which we take the following (first) example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> maxnmbinputs.value = 4
>>> derived.nmboutputs(3)
>>> derived.proximityorder.shape = 3, 4
>>> derived.proximityorder([[0, 2, 1, 3],
...                         [1, 0, 2, 3],
...                         [0, 2, 1, 3]])
>>> derived.weights.shape = 3, 4
>>> derived.weights([[inf, inf, 0.05, 0.000053],
...                  [0.5, 0.029412, 0.029412, 0.000052],
...                  [0.5, 0.5, 0.1, 0.000053]])
>>> fluxes.inputresiduals.shape = 4
>>> fluxes.inputresiduals = 1.0, 5.0, 3.0, 6.0
>>> model.calc_outputresiduals_v1()
>>> fluxes.outputresiduals
outputresiduals(2.0, 4.684331, 2.272907)
class hydpy.models.conv.conv_model.Calc_OutputRatios_V1[source]

Bases: Method

Perform a simple inverse distance weighted interpolation based on the ratios previously determined for the input nodes.

Used by the application model:

conv_idw_cm

Required submethod:

Interpolate_InverseDistance_V1

Requires the control parameter:

MaxNmbInputs

Requires the derived parameters:

NmbOutputs ProximityOrder Weights

Requires the flux sequence:

InputRatios

Calculates the flux sequence:

OutputRatios

Example:

See the documentation on method Calc_Outputs_V2 for further information, from which we take the following (first) example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> maxnmbinputs.value = 4
>>> derived.nmboutputs(3)
>>> derived.proximityorder.shape = 3, 4
>>> derived.proximityorder([[0, 2, 1, 3],
...                         [1, 0, 2, 3],
...                         [0, 2, 1, 3]])
>>> derived.weights.shape = 3, 4
>>> derived.weights([[inf, inf, 0.05, 0.000053],
...                  [0.5, 0.029412, 0.029412, 0.000052],
...                  [0.5, 0.5, 0.1, 0.000053]])
>>> fluxes.inputratios.shape = 4
>>> fluxes.inputratios = 1.0, 5.0, 3.0, 6.0
>>> model.calc_outputratios_v1()
>>> fluxes.outputratios
outputratios(2.0, 4.684331, 2.272907)
class hydpy.models.conv.conv_model.Calc_Outputs_V3[source]

Bases: Method

Calculate the values of the output nodes by combining the initial predictions with the interpolated residuals.

Used by the application model:

conv_idw_ed

Requires the derived parameter:

NmbOutputs

Requires the flux sequences:

OutputPredictions OutputResiduals

Calculates the flux sequence:

Outputs

Basic equation:

\(Outputs = OutputPredictions + OutputResiduals\)

Examples:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmboutputs(2)
>>> fluxes.outputpredictions = 1.0, 2.0
>>> fluxes.outputresiduals = 3.0, -4.0
>>> model.calc_outputs_v3()
>>> fluxes.outputs
outputs(4.0, -2.0)
class hydpy.models.conv.conv_model.Calc_Outputs_V4[source]

Bases: Method

Calculate the values of the output nodes by multiplying their long-term averages for the current month with the interpolated ratios.

Used by the application model:

conv_idw_cm

Requires the derived parameter:

NmbOutputs

Requires the flux sequences:

CurrentOutputAverages OutputRatios

Calculates the flux sequence:

Outputs

Basic equation:

\(Outputs = CurrentOutputAverages \cdot OutputRatios\)

Example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmboutputs(4)
>>> fluxes.currentoutputaverages = 2.0, 3.0, 0.0, 4.0
>>> fluxes.outputratios = 1.5, 0.0, 2.0, nan
>>> model.calc_outputs_v4()
>>> fluxes.outputs
outputs(3.0, 0.0, 0.0, nan)
class hydpy.models.conv.conv_model.Pass_Outputs_V1[source]

Bases: Method

Pass the output to all outlet nodes.

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

Requires the derived parameter:

NmbOutputs

Requires the flux sequence:

Outputs

Calculates the outlet sequence:

Outputs

Example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmboutputs(2)
>>> fluxes.outputs = 2.0, 4.0
>>> outlets.outputs.shape = 2
>>> model.pass_outputs_v1()
>>> outlets.outputs
outputs(2.0, 4.0)
class hydpy.models.conv.conv_model.BaseModel[source]

Bases: AdHocModel

Base class for all HydPy-Conv (base model) application models.

connect() → None[source]

Connect the InletSequence and OutletSequence objects of the actual model to the NodeSequence objects handled by an arbitrary number of inlet and outlet nodes.

To application models derived from Model, you first need to define an Element connected with an arbitrary number of inlet and outlet nodes:

>>> from hydpy import Element
>>> conv = Element("conv",
...                inlets=["in1", "in2"],
...                outlets=["out1", "out2", "out3"])

Second, you must define the inlet and outlet nodes’ coordinates via parametera InputCoordinates and OutputCoordinates, respectively. In both cases, use the names of the Node objects as keyword arguments to pass the corresponding coordinates:

>>> from hydpy.models.conv_nn import *
>>> parameterstep()
>>> inputcoordinates(
...     in1=(0.0, 3.0),
...     in2=(2.0, -1.0))
>>> outputcoordinates(
...     out1=(0.0, 3.0),
...     out2=(3.0, -2.0),
...     out3=(1.0, 2.0))
>>> maxnmbinputs()
>>> parameters.update()

conv passes the current values of the inlet nodes correctly to the outlet nodes (note that node in1 works with simulated values while node in2 works with observed values, as we set its deploymode to obs):

>>> conv.model = model
>>> conv.inlets.in1.sequences.sim = 1.0
>>> conv.inlets.in2.deploymode = "obs"
>>> conv.inlets.in2.sequences.obs = 2.0
>>> model.simulate(0)
>>> conv.outlets.out1.sequences.sim
sim(1.0)
>>> conv.outlets.out2.sequences.sim
sim(2.0)
>>> conv.outlets.out3.sequences.sim
sim(1.0)

You get the following error message when you forget a node (or misspell its name):

>>> outputcoordinates(
...     out1=(0.0, 3.0),
...     out2=(3.0, -2.0))
>>> maxnmbinputs()
>>> parameters.update()
>>> conv.model = model
Traceback (most recent call last):
...
RuntimeError: While trying to connect model `conv_nn` of element `conv`, the following error occurred: The nodes handled by control parameter `outputcoordinates` (`out1` and `out2`) are not the same as the outlet nodes handled by element `conv` (`out1`, `out2`, and `out3`).
REUSABLE_METHODS = ()

Variable features

Variable tools

class hydpy.models.conv.conv_variables.MixinInputs(subvars: SubVariables[Any, Any, Any, Any])[source]

Bases: Variable, ABC

Mixin class for 1-dimensional sequences whose shape depends on the value of parameter NmbInputs.

We take the flux sequence Inputs as an example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmbinputs(2)
>>> fluxes.inputs.shape
(2,)

Redefining the same number does not delete the already available data, while changing it does:

>>> fluxes.inputs = 1.0, 2.0
>>> derived.nmbinputs(2)
>>> fluxes.inputs
inputs(1.0, 2.0)
>>> derived.nmbinputs(3)
>>> fluxes.inputs
inputs(nan, nan, nan)
name = 'mixininputs'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_variables.MixinOutputs(subvars: SubVariables[Any, Any, Any, Any])[source]

Bases: Variable, ABC

Mixin class for 1-dimensional sequences whose shape depends on the value of parameter NmbOutputs.

We take the flux sequence Outputs as an example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> derived.nmboutputs(2)
>>> fluxes.outputs.shape
(2,)

Redefining the same number does not delete the already available data, while changing it does:

>>> fluxes.outputs = 1.0, 2.0
>>> derived.nmboutputs(2)
>>> fluxes.outputs
outputs(1.0, 2.0)
>>> derived.nmboutputs(3)
>>> fluxes.outputs
outputs(nan, nan, nan)
name = 'mixinoutputs'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

Parameter features

Parameter tools

class hydpy.models.conv.conv_parameters.Coordinates(subvars: SubParameters[Model])[source]

Bases: SpecialParameter

Base class for InputCoordinates and OutputCoordinates [?].

Coordinates is a special parameter (see SpecialParameter) that handles the names of the relevant input or output nodes together with their coordinates. We use the derived class InputCoordinates as an example:

>>> from hydpy.models.conv import *
>>> parameterstep()

Initially, neither the nodes nor their coordinates are known:

>>> inputcoordinates
inputcoordinates(?)
>>> inputcoordinates.nodes
()
>>> len(inputcoordinates)
0
>>> inputcoordinates.coordinates
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: The coordinates of parameter `inputcoordinates` of element `?` have not been defined so far.
>>> inputcoordinates.verify()
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: The coordinates of parameter `inputcoordinates` of element `?` have not been defined so far.

Use keyword arguments to define the names of the relevant input nodes as well as their coordinates:

>>> inputcoordinates(in1=(1.0, 3.0))
>>> inputcoordinates
inputcoordinates(in1=(1.0, 3.0))
>>> from hydpy import print_matrix
>>> print_matrix(inputcoordinates.coordinates)
| 1.0, 3.0 |
>>> inputcoordinates.verify()

Defining new coordinates removes the old ones:

>>> inputcoordinates(in2=(2.0, 4.0),
...                  in0=(3.0, 5.0),
...                  in3=(4.0, 6.0))
>>> inputcoordinates
inputcoordinates(in2=(2.0, 4.0),
                 in0=(3.0, 5.0),
                 in3=(4.0, 6.0))
>>> print_matrix(inputcoordinates.coordinates)
| 2.0, 4.0 |
| 3.0, 5.0 |
| 4.0, 6.0 |
>>> len(inputcoordinates)
3

You are free to change individual coordinate values (the rows of the matrix contain the different value pairs; the row order corresponds to the definition order when “calling” the parameter):

>>> inputcoordinates.coordinates[1, 0] = 9.0
>>> inputcoordinates
inputcoordinates(in2=(2.0, 4.0),
                 in0=(9.0, 5.0),
                 in3=(4.0, 6.0))

The attribute nodes stores the correctly ordered nodes:

>>> inputcoordinates.nodes
(Node("in2", variable="Q"), Node("in0", variable="Q"), Node("in3", variable="Q"))

You must define the coordinates of at least one node, and each node requires exactly two coordinates. In case of errors, the previous definitions remain unchanged:

>>> inputcoordinates()
Traceback (most recent call last):
...
ValueError: Parameter `inputcoordinates` of element `?` requires the coordinates of at least one node, but none are given.
>>> inputcoordinates(in1=(1.0, 3.0), in2=(1.0, 2.0, 3.0))
Traceback (most recent call last):
...
ValueError: Parameter `inputcoordinates` of element `?` requires exactly two coordinates for each node, but for node `in2`, `(1.0, 2.0, 3.0)` is given.
>>> inputcoordinates(in1="wrong")
Traceback (most recent call last):
...
ValueError: Parameter `inputcoordinates` of element `?` requires exactly two coordinates for each node, but for node `in1`, `wrong` is given.
>>> inputcoordinates
inputcoordinates(in2=(2.0, 4.0),
                 in0=(9.0, 5.0),
                 in3=(4.0, 6.0))

Positional arguments are not supported:

>>> inputcoordinates((1.0, 3.0))
Traceback (most recent call last):
...
TypeError: Coordinates.__call__() takes 1 positional argument but 2 were given
nodes: tuple[Node, ...]

The relevant input or output nodes.

property coordinates: ndarray[tuple[int, int], dtype[float64]]

The coordinates of all nodes (one row per node, in the order of nodes).

verify() → None[source]

Raise an AttributeNotReady error if the coordinates are still undefined.

name: str = 'coordinates'

Name of the variable in lowercase letters.

class hydpy.models.conv.conv_parameters.NodeParameter(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter, ABC

Base class for parameters with node-specific values.

See the documentation on the subclasses Heights and Averages for examples.

abstract property coordinates: Coordinates

The Coordinates parameter that defines the relevant nodes.

name = 'nodeparameter'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_parameters.Heights(subvars: SubParameters[modeltools.Model])[source]

Bases: NodeParameter, ABC

Base class for InputHeights and OutputHeights [?].

Heights subclasses are 1-dimensional parameters that provide one height value for each node defined by the corresponding Coordinates parameter. We use the derived class InputHeights as an example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputheights
inputheights(?)

Defining the input coordinates also sets the derived parameter NmbInputs and thereby determines the shape of InputHeights:

>>> inputcoordinates(in2=(2.0, 4.0),
...                  in0=(3.0, 5.0),
...                  in3=(4.0, 6.0))
>>> derived.nmbinputs
nmbinputs(3)
>>> inputheights.shape
(3,)

You can pass the heights in the order of the coordinates’ nodes, like the values of other 1-dimensional parameters:

>>> inputheights(2.0, 3.0, 4.0)
>>> from hydpy import print_vector
>>> print_vector(inputheights.values)
2.0, 3.0, 4.0

However, the string representation relies on the node names:

>>> inputheights
inputheights(in2=2.0,
             in0=3.0,
             in3=4.0)

Preferably, you should use the node names as keywords. Then, the order does not matter:

>>> inputheights(in3=6.0, in2=7.0, in0=8.0)
>>> print_vector(inputheights.values)
7.0, 8.0, 6.0

The given node names must agree with the ones defined via InputCoordinates:

>>> inputheights(in2=1.0, in0=2.0, in4=3.0)
Traceback (most recent call last):
...
ValueError: The keyword arguments of parameter `inputheights` of element `?` must agree with the node names defined by parameter `inputcoordinates`, but the name `in3` is missing and the name `in4` is unknown.
>>> inputheights(in2=1.0)
Traceback (most recent call last):
...
ValueError: The keyword arguments of parameter `inputheights` of element `?` must agree with the node names defined by parameter `inputcoordinates`, but the names `in0` and `in3` are missing.
>>> inputheights
inputheights(in2=7.0,
             in0=8.0,
             in3=6.0)

Mixing positional and keyword arguments is not allowed:

>>> inputheights(1.0, in0=2.0)
Traceback (most recent call last):
...
ValueError: For parameter `inputheights` of element `?` both positional and keyword arguments are given, which is ambiguous.

Reading the heights from auxiliary control files works as usual:

>>> from hydpy import TestIO
>>> with TestIO(clear_own=True):
...     with open("heights_aux.py", "w", encoding="utf-8") as file_:
...         for line in (
...             "from hydpy.models.conv import *",
...             "parameterstep()",
...             "inputheights(in3=1.0, in2=2.0, in0=3.0)",
...         ):
...             print(line, file=file_)
...     inputheights(auxfile="heights_aux")
>>> inputheights
inputheights(in2=2.0,
             in0=3.0,
             in3=1.0)
>>> inputheights(in3=6.0, in2=7.0, in0=8.0)

Redefining the coordinates of the same number of nodes keeps the heights, while changing the number of nodes discards them:

>>> inputcoordinates(a=(2.0, 4.0), b=(3.0, 5.0), c=(4.0, 6.0))
>>> inputheights
inputheights(a=7.0,
             b=8.0,
             c=6.0)
>>> inputcoordinates(a=(2.0, 4.0), b=(3.0, 5.0))
>>> inputheights
inputheights(?)

The string representation falls back to the usual format if the numbers of heights and nodes differ:

>>> inputheights.shape = 3
>>> inputheights(1.0, 2.0, 3.0)
>>> inputheights
inputheights(1.0, 2.0, 3.0)
NDIM: Final[Literal[1]] = 1
TYPE

alias of float

name = 'heights'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_parameters.Averages(subvars: SubParameters[modeltools.Model])[source]

Bases: NodeParameter, ABC

Base class for InputAverages and OutputAverages [?].

Averages subclasses are 2-dimensional parameters that provide twelve long-term average values (one for each month of the year) for each node defined by the corresponding Coordinates parameter. The values can have any unit as long as the input and the output averages agree in this regard, so that one can, for example, use annual sums, monthly sums, or daily means. We use the derived class InputAverages as an example:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputaverages
inputaverages(?)

Defining the input coordinates also sets the derived parameter NmbInputs and thereby determines the shape of InputAverages:

>>> inputcoordinates(in2=(2.0, 4.0),
...                  in0=(3.0, 5.0),
...                  in3=(4.0, 6.0))
>>> derived.nmbinputs
nmbinputs(3)
>>> inputaverages.shape
(3, 12)

The safest way to define the averages is to use the node names as keywords, where the order does not matter. One value is valid for all months of the year, while twelve values define individual averages for January to December. You can mix both options freely:

>>> inputaverages(in3=[1.0, 2.0, 3.0, 4.0, 5.0, 6.0,
...                    7.0, 8.0, 9.0, 10.0, 11.0, 12.0],
...               in2=800.0,
...               in0=600.0)
>>> inputaverages
inputaverages(in2=800.0,
              in0=600.0,
              in3=[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0,
                   12.0])
>>> from hydpy import print_vector
>>> print_vector(inputaverages.values[:, 0])
800.0, 600.0, 1.0
>>> print_vector(inputaverages.values[:, 11])
800.0, 600.0, 12.0

Any other number of values and values that are not numbers result in errors:

>>> inputaverages(in2=[800.0, 700.0], in0=600.0, in3=700.0)
Traceback (most recent call last):
...
ValueError: Parameter `inputaverages` of element `?` requires either one value or twelve values for each node, but for node `in2`, `[800.0, 700.0]` is given.
>>> inputaverages(in2="wrong", in0=600.0, in3=700.0)
Traceback (most recent call last):
...
TypeError: Parameter `inputaverages` of element `?` requires either one value or twelve values for each node, but for node `in2`, `wrong` is given.

The given node names must agree with the ones defined via InputCoordinates:

>>> inputaverages(in2=1.0, in0=2.0, in4=3.0)
Traceback (most recent call last):
...
ValueError: The keyword arguments of parameter `inputaverages` of element `?` must agree with the node names defined by parameter `inputcoordinates`, but the name `in3` is missing and the name `in4` is unknown.

Mixing positional and keyword arguments is not allowed:

>>> inputaverages(1.0, in0=2.0)
Traceback (most recent call last):
...
ValueError: For parameter `inputaverages` of element `?` both positional and keyword arguments are given, which is ambiguous.

Negative averages are not allowed, but zero averages are:

>>> inputaverages(in2=-1.0, in0=0.0, in3=1.0)
>>> inputaverages
inputaverages(in2=0.0,
              in0=0.0,
              in3=1.0)

A single scalar value applies to all nodes and months:

>>> inputaverages(5.0)
>>> inputaverages
inputaverages(in2=5.0,
              in0=5.0,
              in3=5.0)

A given matrix must contain one row per node and one column per month:

>>> import numpy
>>> inputaverages(numpy.arange(1.0, 37.0).reshape(3, 12))
>>> print_vector(inputaverages.values[:, 11])
12.0, 24.0, 36.0

Be careful with vectors. Their entries always relate to the months, not to the nodes, which is why vectors with a length other than twelve are invalid:

>>> inputaverages(1.0, 2.0, 3.0)
Traceback (most recent call last):
...
ValueError: While trying to set the value(s) of variable `inputaverages`, the following error occurred: While trying to convert the value(s) `[1. 2. 3.]` to a numpy ndarray with shape `(3, 12)` and type `float`, the following error occurred: could not broadcast input array from shape (3,) into shape (3,12)

Reading the averages from auxiliary control files works as usual:

>>> inputcoordinates(in2=(2.0, 4.0),
...                  in0=(3.0, 5.0),
...                  in3=(4.0, 6.0))
>>> from hydpy import TestIO
>>> with TestIO(clear_own=True):
...     with open("averages_aux.py", "w", encoding="utf-8") as file_:
...         for line in (
...             "from hydpy.models.conv import *",
...             "parameterstep()",
...             "inputaverages(in3=1.0, in2=2.0, in0=3.0)",
...         ):
...             print(line, file=file_)
...     inputaverages(auxfile="averages_aux")
>>> inputaverages
inputaverages(in2=2.0,
              in0=3.0,
              in3=1.0)

Redefining the coordinates of the same number of nodes keeps the averages, while changing the number of nodes discards them:

>>> inputcoordinates(a=(2.0, 4.0), b=(3.0, 5.0), c=(4.0, 6.0))
>>> inputaverages
inputaverages(a=2.0,
              b=3.0,
              c=1.0)

The string representation falls back to the usual format if the numbers of rows and nodes differ:

>>> inputaverages.shape = (1, 12)
>>> inputaverages(1.0)
>>> inputaverages
inputaverages(1.0)
name = 'averages'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

NDIM: Final[Literal[2]] = 2
TYPE

alias of float

SPAN = (0.0, None)

Control parameters

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

Bases: ControlParameters

Control parameters of model conv.

The following classes are selected:
  • InputCoordinates Coordinates of the inlet nodes [?].

  • OutputCoordinates Coordinates of the outlet nodes [?].

  • InputHeights The height (above sea level or anything else) of the input nodes [?].

  • OutputHeights The height (above sea level or anything else) of the output nodes [?].

  • InputAverages The long-term averages of the input nodes for each month of the year [?].

  • OutputAverages The long-term averages of the output nodes for each month of the year [?].

  • MaxNmbInputs The maximum number of input locations to be taken into account for interpolating the values of a specific output location [-].

  • MinNmbInputs The minimum number of inputs for performing a statistical analysis [-].

  • DefaultConstant Default or fallback value for the constant of the linear regression model [?].

  • DefaultFactor Default or fallback value for the factor of the linear regression model [?].

  • Power Power parameter for calculating inverse distance weights [-].

class hydpy.models.conv.conv_control.InputCoordinates(subvars: SubParameters[Model])[source]

Bases: Coordinates

Coordinates of the inlet nodes [?].

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

name: str = 'inputcoordinates'

Name of the variable in lowercase letters.

class hydpy.models.conv.conv_control.OutputCoordinates(subvars: SubParameters[Model])[source]

Bases: Coordinates

Coordinates of the outlet nodes [?].

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

name: str = 'outputcoordinates'

Name of the variable in lowercase letters.

class hydpy.models.conv.conv_control.InputHeights(subvars: SubParameters[modeltools.Model])[source]

Bases: Heights

The height (above sea level or anything else) of the input nodes [?].

Required by the methods:

Calc_ActualConstant_ActualFactor_V1 Calc_InputPredictions_V1

Used by the application model:

conv_idw_ed

property coordinates: InputCoordinates

The InputCoordinates parameter.

name = 'inputheights'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.OutputHeights(subvars: SubParameters[modeltools.Model])[source]

Bases: Heights

The height (above sea level or anything else) of the output nodes [?].

Required by the method:

Calc_OutputPredictions_V1

Used by the application model:

conv_idw_ed

property coordinates: OutputCoordinates

The OutputCoordinates parameter.

name = 'outputheights'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.InputAverages(subvars: SubParameters[modeltools.Model])[source]

Bases: Averages

The long-term averages of the input nodes for each month of the year [?].

Required by the method:

Calc_CurrentInputAverages_V1

Used by the application model:

conv_idw_cm

property coordinates: InputCoordinates

The InputCoordinates parameter.

name = 'inputaverages'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.OutputAverages(subvars: SubParameters[modeltools.Model])[source]

Bases: Averages

The long-term averages of the output nodes for each month of the year [?].

Required by the method:

Calc_CurrentOutputAverages_V1

Used by the application model:

conv_idw_cm

property coordinates: OutputCoordinates

The OutputCoordinates parameter.

name = 'outputaverages'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.MaxNmbInputs(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

The maximum number of input locations to be taken into account for interpolating the values of a specific output location [-].

When passing no value, parameter MaxNmbInputs queries it from the shape of parameter InputCoordinates:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputcoordinates(in2=(2.0, 4.0),
...                  in0=(3.0, 5.0),
...                  in3=(4.0, 6.0))
>>> maxnmbinputs()
>>> maxnmbinputs
maxnmbinputs(3)

You can define alternative values manually:

>>> maxnmbinputs(2)
>>> maxnmbinputs
maxnmbinputs(2)
NDIM: Final[Literal[0]] = 0
TYPE

alias of int

SPAN = (1, None)
trim(lower: float | floating[Any] | integer[Any] | bool | Sequence[float | floating[Any] | integer[Any] | bool] | ndarray[tuple[int], dtype[floating[Any] | integer[Any] | bool]] | Sequence[Sequence[float | floating[Any] | integer[Any] | bool] | ndarray[tuple[int], dtype[floating[Any] | integer[Any] | bool]]] | ndarray[tuple[int, int], dtype[floating[Any] | integer[Any] | bool]] | Sequence[Sequence[Sequence[float | floating[Any] | integer[Any] | bool] | ndarray[tuple[int], dtype[floating[Any] | integer[Any] | bool]]] | ndarray[tuple[int, int], dtype[floating[Any] | integer[Any] | bool]]] | ndarray[tuple[int, int, int], dtype[floating[Any] | integer[Any] | bool]] | None = None, upper: float | floating[Any] | integer[Any] | bool | Sequence[float | floating[Any] | integer[Any] | bool] | ndarray[tuple[int], dtype[floating[Any] | integer[Any] | bool]] | Sequence[Sequence[float | floating[Any] | integer[Any] | bool] | ndarray[tuple[int], dtype[floating[Any] | integer[Any] | bool]]] | ndarray[tuple[int, int], dtype[floating[Any] | integer[Any] | bool]] | Sequence[Sequence[Sequence[float | floating[Any] | integer[Any] | bool] | ndarray[tuple[int], dtype[floating[Any] | integer[Any] | bool]]] | ndarray[tuple[int, int], dtype[floating[Any] | integer[Any] | bool]]] | ndarray[tuple[int, int, int], dtype[floating[Any] | integer[Any] | bool]] | None = None) → bool[source]

Assure that the value of MaxNmbInputs does not exceed the number of available input locations.

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputcoordinates(in2=(2.0, 4.0),
...                  in0=(3.0, 5.0),
...                  in3=(4.0, 6.0))
>>> maxnmbinputs(0)
Traceback (most recent call last):
...
ValueError: The value `0` of parameter `maxnmbinputs` of element `?` is not valid.
>>> maxnmbinputs(4)
Traceback (most recent call last):
...
ValueError: The value `4` of parameter `maxnmbinputs` of element `?` is not valid.
name = 'maxnmbinputs'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_control.MinNmbInputs(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

The minimum number of inputs for performing a statistical analysis [-].

Required by the method:

Calc_ActualConstant_ActualFactor_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[0]] = 0
TYPE

alias of int

SPAN = (2, None)
name = 'minnmbinputs'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_control.DefaultConstant(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

Default or fallback value for the constant of the linear regression model [?].

Required by the method:

Calc_ActualConstant_ActualFactor_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[0]] = 0
TYPE

alias of float

name = 'defaultconstant'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.DefaultFactor(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

Default or fallback value for the factor of the linear regression model [?].

Required by the method:

Calc_ActualConstant_ActualFactor_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[0]] = 0
TYPE

alias of float

SPAN = (-1.0, 1.0)
name = 'defaultfactor'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.Power(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

Power parameter for calculating inverse distance weights [-].

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed

NDIM: Final[Literal[0]] = 0
TYPE

alias of float

name = 'power'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

SPAN = (0, None)

Derived parameters

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

Bases: DerivedParameters

Derived parameters of model conv.

The following classes are selected:
  • MOY References the “global” month of the year index array [-].

  • NmbInputs The number of inlet nodes [-]

  • NmbOutputs The number of outlet nodes [-]

  • Distances Distances of the inlet nodes to each outlet node [?].

  • ProximityOrder Indices of the inlet nodes in the order of their proximity to each outlet node [-].

  • Weights Weighting coefficients of the inlet nodes corresponding to their proximity to each outlet node and parameter Power [-].

class hydpy.models.conv.conv_derived.MOY(subvars: SubParameters[modeltools.Model])[source]

Bases: MOYParameter

References the “global” month of the year index array [-].

Required by the methods:

Calc_CurrentInputAverages_V1 Calc_CurrentOutputAverages_V1

Used by the application model:

conv_idw_cm

name = 'moy'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.NmbInputs(subvars: SubParameters[modeltools.Model])[source]

Bases: NmbParameter

The number of inlet nodes [-]

Required by the methods:

Calc_ActualConstant_ActualFactor_V1 Calc_CurrentInputAverages_V1 Calc_InputPredictions_V1 Calc_InputRatios_V1 Calc_InputResiduals_V1 Pick_Inputs_V1

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

SPAN = (1, None)
update() → None[source]

Determine the number of inlet nodes via inspecting control parameter InputCoordinates.

Calling InputCoordinates sets NmbInputs immediately. Method update() determines the same value:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputcoordinates(
...     in1=(0.0, 3.0),
...     in2=(2.0, -1.0))
>>> derived.nmbinputs
nmbinputs(2)
>>> derived.nmbinputs(1)
>>> derived.nmbinputs.update()
>>> derived.nmbinputs
nmbinputs(2)
name = 'nmbinputs'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.NmbOutputs(subvars: SubParameters[modeltools.Model])[source]

Bases: NmbParameter

The number of outlet nodes [-]

Required by the methods:

Calc_CurrentOutputAverages_V1 Calc_OutputPredictions_V1 Calc_OutputRatios_V1 Calc_OutputResiduals_V1 Calc_Outputs_V1 Calc_Outputs_V2 Calc_Outputs_V3 Calc_Outputs_V4 Interpolate_InverseDistance_V1 Pass_Outputs_V1

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

SPAN = (1, None)
update() → None[source]

Determine the number of outlet nodes via inspecting control parameter OutputCoordinates.

Calling OutputCoordinates sets NmbOutputs immediately. Method update() determines the same value:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> outputcoordinates(
...     out1=(0.0, 3.0),
...     out2=(2.0, -1.0))
>>> derived.nmboutputs
nmboutputs(2)
>>> derived.nmboutputs(1)
>>> derived.nmboutputs.update()
>>> derived.nmboutputs
nmboutputs(2)
name = 'nmboutputs'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.Distances(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

Distances of the inlet nodes to each outlet node [?].

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

NDIM: Final[Literal[2]] = 2
TYPE

alias of float

update() → None[source]

Determine the distances.

The individual rows of parameter Distances correspond to the outlet nodes; the columns contain the inlet nodes’ indices:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputcoordinates(
...     in1=(0.0, 3.0),
...     in2=(2.0, -1.0))
>>> outputcoordinates(
...     out1=(0.0, 3.0),
...     out2=(3.0, -2.0),
...     out3=(1.0, 2.0))
>>> derived.distances.update()
>>> derived.distances
distances([[0.0, 4.472136],
           [5.830952, 1.414214],
           [1.414214, 3.162278]])
name = 'distances'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_derived.ProximityOrder(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

Indices of the inlet nodes in the order of their proximity to each outlet node [-].

NDIM: Final[Literal[2]] = 2
TYPE

alias of int

update() → None[source]

Determine the proximity-order of the inlet and outlet nodes.

The individual rows of parameter ProximityOrder correspond to the outlet nodes; the columns contain the inlet nodes’ indices:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputcoordinates(
...     in1=(0.0, 3.0),
...     in2=(2.0, -1.0))
>>> outputcoordinates(
...     out1=(0.0, 3.0),
...     out2=(3.0, -2.0),
...     out3=(1.0, 2.0))
>>> maxnmbinputs()
>>> derived.distances.update()
>>> derived.proximityorder.update()
>>> derived.proximityorder
proximityorder([[0, 1],
                [1, 0],
                [0, 1]])

Set the value of parameter MaxNmbInputs to one,if you want to consider the respective nearest input node only:

>>> maxnmbinputs(1)
>>> derived.proximityorder.update()
>>> derived.proximityorder
proximityorder([[0],
                [1],
                [0]])
name = 'proximityorder'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.Weights(subvars: SubParameters[modeltools.Model])[source]

Bases: Parameter

Weighting coefficients of the inlet nodes corresponding to their proximity to each outlet node and parameter Power [-].

NDIM: Final[Literal[2]] = 2
TYPE

alias of float

update() → None[source]

Determine the weighting coefficients.

The individual rows of parameter Weights correspond to the outlet nodes; the rows contain the weights of the inlet nodes:

>>> from hydpy.models.conv import *
>>> parameterstep()
>>> inputcoordinates(
...     in1=(0.0, 3.0),
...     in2=(2.0, -1.0),
...     in3=(0.0, 3.0),
...     in4=(99.0, 99.0))
>>> outputcoordinates(
...     out1=(0.0, 3.0),
...     out2=(3.0, -2.0),
...     out3=(1.0, 2.0))
>>> maxnmbinputs()
>>> power(2.0)
>>> derived.distances.update()
>>> derived.proximityorder.update()
>>> derived.weights.update()
>>> derived.weights
weights([[inf, inf, 0.05, 0.000053],
         [0.5, 0.029412, 0.029412, 0.000052],
         [0.5, 0.5, 0.1, 0.000053]])

You can restrict the number of inlet nodes used for each outlet node via parameter MaxNmbInputs. In the following example, it seems reasonable to set its value to three to ignore the far-distant inlet node in4:

>>> maxnmbinputs(3)
>>> derived.distances.update()
>>> derived.proximityorder.update()
>>> derived.weights.update()
>>> derived.weights
weights([[inf, inf, 0.05],
         [0.5, 0.029412, 0.029412],
         [0.5, 0.5, 0.1]])
name = 'weights'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

Sequence features

Flux sequences

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

Bases: FluxSequences

Flux sequences of model conv.

The following classes are selected:
  • Inputs The (unmodified) values supplied by the input nodes [?].

  • ActualConstant The actual value for the constant of the linear regression model [?].

  • ActualFactor The actual value for the factor of the linear regression model [?].

  • InputPredictions The values of the input nodes predicted by a regression model [?].

  • OutputPredictions The values of the output nodes predicted by a regression model [?].

  • InputResiduals The exact residuals of a regression model calculated for the input nodes [?].

  • OutputResiduals The guessed residuals of a regression model interpolated for the input nodes [?].

  • CurrentInputAverages The long-term averages of the input nodes for the current month [?].

  • CurrentOutputAverages The long-term averages of the output nodes for the current month [?].

  • InputRatios The ratios between the current values supplied by the input nodes and their long-term averages for the current month [-].

  • OutputRatios The ratios between the final results and the long-term averages for the current month, interpolated for the output nodes [-].

  • Outputs The final interpolation results estimated for the output nodes [?].

class hydpy.models.conv.conv_fluxes.Inputs(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinInputs, FluxSequence

The (unmodified) values supplied by the input nodes [?].

Calculated by the method:

Pick_Inputs_V1

Required by the methods:

Calc_ActualConstant_ActualFactor_V1 Calc_InputRatios_V1 Calc_InputResiduals_V1 Calc_Outputs_V1 Calc_Outputs_V2

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

NDIM: Final[Literal[1]] = 1
name = 'inputs'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.ActualConstant(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: FluxSequence

The actual value for the constant of the linear regression model [?].

Calculated by the method:

Calc_ActualConstant_ActualFactor_V1

Required by the methods:

Calc_InputPredictions_V1 Calc_OutputPredictions_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[0]] = 0
name = 'actualconstant'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.ActualFactor(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: FluxSequence

The actual value for the factor of the linear regression model [?].

Calculated by the method:

Calc_ActualConstant_ActualFactor_V1

Required by the methods:

Calc_InputPredictions_V1 Calc_OutputPredictions_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[0]] = 0
name = 'actualfactor'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.InputPredictions(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinInputs, FluxSequence

The values of the input nodes predicted by a regression model [?].

Calculated by the method:

Calc_InputPredictions_V1

Required by the method:

Calc_InputResiduals_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[1]] = 1
name = 'inputpredictions'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.OutputPredictions(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinOutputs, FluxSequence

The values of the output nodes predicted by a regression model [?].

Calculated by the method:

Calc_OutputPredictions_V1

Required by the method:

Calc_Outputs_V3

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[1]] = 1
name = 'outputpredictions'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.InputResiduals(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinInputs, FluxSequence

The exact residuals of a regression model calculated for the input nodes [?].

Calculated by the method:

Calc_InputResiduals_V1

Required by the method:

Calc_OutputResiduals_V1

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[1]] = 1
name = 'inputresiduals'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.OutputResiduals(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinOutputs, FluxSequence

The guessed residuals of a regression model interpolated for the input nodes [?].

Calculated by the method:

Calc_OutputResiduals_V1

Required by the method:

Calc_Outputs_V3

Used by the application model:

conv_idw_ed

NDIM: Final[Literal[1]] = 1
name = 'outputresiduals'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.CurrentInputAverages(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinInputs, FluxSequence

The long-term averages of the input nodes for the current month [?].

Calculated by the method:

Calc_CurrentInputAverages_V1

Required by the method:

Calc_InputRatios_V1

Used by the application model:

conv_idw_cm

NDIM: Final[Literal[1]] = 1
name = 'currentinputaverages'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.CurrentOutputAverages(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinOutputs, FluxSequence

The long-term averages of the output nodes for the current month [?].

Calculated by the method:

Calc_CurrentOutputAverages_V1

Required by the method:

Calc_Outputs_V4

Used by the application model:

conv_idw_cm

NDIM: Final[Literal[1]] = 1
name = 'currentoutputaverages'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.InputRatios(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinInputs, FluxSequence

The ratios between the current values supplied by the input nodes and their long-term averages for the current month [-].

Calculated by the method:

Calc_InputRatios_V1

Required by the method:

Calc_OutputRatios_V1

Used by the application model:

conv_idw_cm

NDIM: Final[Literal[1]] = 1
name = 'inputratios'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.OutputRatios(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinOutputs, FluxSequence

The ratios between the final results and the long-term averages for the current month, interpolated for the output nodes [-].

Calculated by the method:

Calc_OutputRatios_V1

Required by the method:

Calc_Outputs_V4

Used by the application model:

conv_idw_cm

NDIM: Final[Literal[1]] = 1
name = 'outputratios'

Name of the variable in lowercase letters.

unit = '-'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.Outputs(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: MixinOutputs, FluxSequence

The final interpolation results estimated for the output nodes [?].

Calculated by the methods:

Calc_Outputs_V1 Calc_Outputs_V2 Calc_Outputs_V3 Calc_Outputs_V4

Required by the method:

Pass_Outputs_V1

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

NDIM: Final[Literal[1]] = 1
name = 'outputs'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

Inlet sequences

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

Bases: InletSequences

Inlet sequences of model conv.

The following classes are selected:
class hydpy.models.conv.conv_inlets.Inputs(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: InletSequence

Inputs [?].

Required by the method:

Pick_Inputs_V1

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

NDIM: Final[Literal[1]] = 1
name = 'inputs'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.

Outlet sequences

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

Bases: OutletSequences

Outlet sequences of model conv.

The following classes are selected:
class hydpy.models.conv.conv_outlets.Outputs(subvars: ModelIOSequences[TM_co, ModelIOSequence, FastAccessIOSequence])[source]

Bases: OutletSequence

Outputs [?].

Calculated by the method:

Pass_Outputs_V1

Used by the application models:

conv_idw conv_idw_cm conv_idw_ed conv_nn

NDIM: Final[Literal[1]] = 1
name = 'outputs'

Name of the variable in lowercase letters.

unit = '?'

Unit of the variable.