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

Bases: AdHocModel

HydPy-Conv (base model).

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

• Pick_Inputs_V1 Pick the input from all inlet nodes.

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

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

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

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

• Calc_InputResiduals_V1 Determine the residuals at the input nodes.

• Calc_Outputs_V1 Perform a simple proximity-based interpolation.

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

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

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

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

• Pass_Outputs_V1 Pass the output to all outlet nodes.

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_Mean_V1 Return the arithmetic mean value for the given vector.

• Interpolate_InverseDistance_V1 Perform a simple inverse distance weighted interpolation.

DOCNAME: DocName = ('Conv', 'base model')

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()

class hydpy.models.conv.conv_model.Pick_Inputs_V1

Bases: Method

Pick the input from all inlet nodes.

Requires the derived parameter:

NmbInputs

Requires the inlet sequence:

Inputs

Calculates the flux sequence:

Inputs

class hydpy.models.conv.conv_model.Calc_Outputs_V1

Bases: Method

Perform a simple proximity-based interpolation.

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

Bases: Method

Return the arithmetic mean value for the given vector.

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

Bases: Method

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

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

Bases: Method

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

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

Bases: Method

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

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_InputResiduals_V1

Bases: Method

Determine the residuals at the input nodes.

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

Bases: Method

Perform a simple inverse distance weighted interpolation.

Required by the methods:

Calc_OutputResiduals_V1 Calc_Outputs_V2

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

Bases: Method

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

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

Bases: Method

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

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_Outputs_V3

Bases: Method

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

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

Bases: Method

Pass the output to all outlet nodes.

Requires the derived parameter:

NmbOutputs

Requires the flux sequence:

Outputs

Calculates the outlet sequence:

Outputs

class hydpy.models.conv.conv_model.BaseModel

Bases: AdHocModel

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

connect()

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 node 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: ClassVar[tuple[type[ReusableMethod], ...]] = ()

Parameter Features

Control parameters

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

Bases: SubParameters

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

• 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.Coordinates(subvars: SubParameters)

Bases: Parameter

Base class for InputCoordinates and OutputCoordinates [?].

We use the derived class InputCoordinates as an example:

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

Coordinates subclasses define 2-dimensional sequences. Hence, we must define their shape first:

>>> inputcoordinates
inputcoordinates(?)
>>> inputcoordinates.values
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: Shape information for variable `inputcoordinates` can only be retrieved after it has been defined.

However, you usually do this automatically when assigning new values. Use keyword arguments to define the names of the relevant input nodes as well as their coordinates:

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

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.values)
| 2.0, 4.0 |
| 3.0, 5.0 |
| 4.0, 6.0 |

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

>>> inputcoordinates.values[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"))

NDIM: int = 2

TYPE

alias of float

TIME: bool | None = None

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

nodes: tuple[Node, ...]

The relevant input or output nodes.

name: str = 'coordinates'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.InputCoordinates(subvars: SubParameters)

Bases: Coordinates

Coordinates of the inlet nodes [?].

name: str = 'inputcoordinates'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.OutputCoordinates(subvars: SubParameters)

Bases: Coordinates

Coordinates of the outlet nodes [?].

name: str = 'outputcoordinates'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.Heights(subvars: SubParameters)

Bases: Parameter

Base class for InputHeights and OutputHeights [?].

We use the derived class InputHeights as an example:

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

Heights subclasses define 1-dimensional sequences. Hence, we must define their shape first:

>>> inputheights
inputheights(?)
>>> inputheights.values
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: Shape information for variable `inputheights` can only be retrieved after it has been defined.

However, you usually do this automatically when assigning new values. Use keyword arguments to define the names of the relevant input nodes as well as their heights:

>>> from hydpy import print_vector
>>> inputheights(in1=1.0)
>>> inputheights
inputheights(in1=1.0)
>>> print_vector(inputheights.values)
1.0

Defining new heights removes the old ones:

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

You are free to change individual height values (the row order corresponds to the definition order when “calling” the parameter):

>>> inputheights.values[1] = 9.0
>>> inputheights
inputheights(in2=2.0,
             in0=9.0,
             in3=4.0)

The attribute nodes stores the correctly ordered nodes:

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

NDIM: int = 1

TYPE

alias of float

TIME: bool | None = None

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

nodes: tuple[Node, ...]

The relevant input or output nodes.

name: str = 'heights'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.InputHeights(subvars: SubParameters)

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

name: str = 'inputheights'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.OutputHeights(subvars: SubParameters)

Bases: Heights

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

Required by the method:

Calc_OutputPredictions_V1

name: str = 'outputheights'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.MaxNmbInputs(subvars: SubParameters)

Bases: Parameter

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

Required by the methods:

Calc_OutputResiduals_V1 Calc_Outputs_V1 Calc_Outputs_V2 Interpolate_InverseDistance_V1

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: int = 0

TYPE

alias of int

TIME: bool | None = None

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

trim(lower=None, upper=None) → bool

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: str = 'maxnmbinputs'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.conv.conv_control.MinNmbInputs(subvars: SubParameters)

Bases: Parameter

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

Required by the method:

Calc_ActualConstant_ActualFactor_V1

NDIM: int = 0

TYPE

alias of int

TIME: bool | None = None

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (2, None)

name: str = 'minnmbinputs'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.conv.conv_control.DefaultConstant(subvars: SubParameters)

Bases: Parameter

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

Required by the method:

Calc_ActualConstant_ActualFactor_V1

NDIM: int = 0

TYPE

alias of float

TIME: bool | None = None

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

name: str = 'defaultconstant'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.DefaultFactor(subvars: SubParameters)

Bases: Parameter

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

Required by the method:

Calc_ActualConstant_ActualFactor_V1

NDIM: int = 0

TYPE

alias of float

TIME: bool | None = None

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (-1.0, 1.0)

name: str = 'defaultfactor'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_control.Power(subvars: SubParameters)

Bases: Parameter

Power parameter for calculating inverse distance weights [-].

NDIM: int = 0

name: str = 'power'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

TYPE

alias of float

TIME: bool | None = None

SPAN: tuple[int | float | bool | None, int | float | bool | None] = (0, None)

Derived parameters

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

Bases: SubParameters

Derived parameters of model conv.

The following classes are selected:

• 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.NmbInputs(subvars: SubParameters)

Bases: Parameter

The number of inlet nodes [-]

Required by the methods:

Calc_ActualConstant_ActualFactor_V1 Calc_InputPredictions_V1 Calc_InputResiduals_V1 Pick_Inputs_V1

NDIM: int = 0

TYPE

alias of int

TIME: bool | None = None

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

update() → None

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

Note that invoking method update() like calling the parameter directly also sets the shape of flux sequence Inputs:

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

>>> derived.nmbinputs(3)
>>> derived.nmbinputs
nmbinputs(3)
>>> fluxes.inputs.shape
(3,)

name: str = 'nmbinputs'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.NmbOutputs(subvars: SubParameters)

Bases: Parameter

The number of outlet nodes [-]

Required by the methods:

Calc_OutputPredictions_V1 Calc_OutputResiduals_V1 Calc_Outputs_V1 Calc_Outputs_V2 Calc_Outputs_V3 Interpolate_InverseDistance_V1 Pass_Outputs_V1

NDIM: int = 0

TYPE

alias of int

TIME: bool | None = None

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

update() → None

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

Note that invoking method update() like calling the parameter directly also sets the shape of flux sequence Outputs:

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

>>> derived.nmboutputs(3)
>>> derived.nmboutputs
nmboutputs(3)
>>> fluxes.outputs.shape
(3,)

name: str = 'nmboutputs'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.Distances(subvars: SubParameters)

Bases: Parameter

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

NDIM: int = 2

TYPE

alias of float

TIME: bool | None = None

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

update() → None

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: str = 'distances'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_derived.ProximityOrder(subvars: SubParameters)

Bases: Parameter

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

Required by the methods:

Calc_OutputResiduals_V1 Calc_Outputs_V1 Calc_Outputs_V2 Interpolate_InverseDistance_V1

NDIM: int = 2

TYPE

alias of int

TIME: bool | None = None

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

update() → None

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: str = 'proximityorder'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

class hydpy.models.conv.conv_derived.Weights(subvars: SubParameters)

Bases: Parameter

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

Required by the methods:

Calc_OutputResiduals_V1 Calc_Outputs_V2 Interpolate_InverseDistance_V1

NDIM: int = 2

TYPE

alias of float

TIME: bool | None = None

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

update() → None

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: str = 'weights'

Name of the variable in lowercase letters.

unit: str = '-'

Unit of the variable.

Sequence Features

Flux sequences

class hydpy.models.conv.FluxSequences(master: Sequences, 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 [?].

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

class hydpy.models.conv.conv_fluxes.Inputs(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: 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_InputResiduals_V1 Calc_Outputs_V1 Calc_Outputs_V2

NDIM: int = 1

NUMERIC: bool = False

name: str = 'inputs'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.ActualConstant(subvars: ModelSequences[ModelSequence, FastAccess])

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

NDIM: int = 0

NUMERIC: bool = False

name: str = 'actualconstant'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.ActualFactor(subvars: ModelSequences[ModelSequence, FastAccess])

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

NDIM: int = 0

NUMERIC: bool = False

name: str = 'actualfactor'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.InputPredictions(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: 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

NDIM: int = 1

NUMERIC: bool = False

name: str = 'inputpredictions'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.OutputPredictions(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: 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

NDIM: int = 1

NUMERIC: bool = False

name: str = 'outputpredictions'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.InputResiduals(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: 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

NDIM: int = 1

NUMERIC: bool = False

name: str = 'inputresiduals'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.OutputResiduals(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: 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

NDIM: int = 1

NUMERIC: bool = False

name: str = 'outputresiduals'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

class hydpy.models.conv.conv_fluxes.Outputs(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: FluxSequence

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

Calculated by the methods:

Calc_Outputs_V1 Calc_Outputs_V2 Calc_Outputs_V3

Required by the method:

Pass_Outputs_V1

NDIM: int = 1

NUMERIC: bool = False

name: str = 'outputs'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

Inlet sequences

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

Bases: InletSequences

Inlet sequences of model conv.

The following classes are selected:

• Inputs() Inputs [?].

class hydpy.models.conv.conv_inlets.Inputs(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: InletSequence

Inputs [?].

Required by the method:

Pick_Inputs_V1

NDIM: int = 1

NUMERIC: bool = False

name: str = 'inputs'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

Outlet sequences

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

Bases: OutletSequences

Outlet sequences of model conv.

The following classes are selected:

• Outputs() Outputs [?].

class hydpy.models.conv.conv_outlets.Outputs(subvars: ModelSequences[ModelSequence, FastAccess])

Bases: OutletSequence

Outputs [?].

Calculated by the method:

Pass_Outputs_V1

NDIM: int = 1

NUMERIC: bool = False

name: str = 'outputs'

Name of the variable in lowercase letters.

unit: str = '?'

Unit of the variable.

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

Bases: SubParameters

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

• 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.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model conv.

The following classes are selected:

• 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.FluxSequences(master: Sequences, 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 [?].

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

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

Bases: InletSequences

Inlet sequences of model conv.

The following classes are selected:

• Inputs() Inputs [?].

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

Bases: OutletSequences

Outlet sequences of model conv.

The following classes are selected:

• Outputs() Outputs [?].