lstream_v002

Version 2 of HydPy-L-Stream is a computationally more efficient alternative to application model lstream_v001. The higher efficiency is due to not calculating discharges based on channel geometries but based on preprocessed relationships between discharge and storage, similar to the “V/Q-BEZIEHUNG EXTERN” option of LARSIM. An artificial neural network, available as “parameter” VG2QG, serves to describe this relationship. Principally, the neural network can fit any relationship provided by lstream_v001 very accurately. However, high accuracy might require a considerable number of neurons, which also can come with a relevant performance cost.

Integration tests

Note

When new to HydPy, consider reading section How to understand integration tests? first.

main channel flow

The following integration test repeats the main channel flow example of the documentation on application model lstream_v001. The spatial end temporal settings are identical:

>>> from hydpy import pub, Nodes, Element
>>> pub.timegrids = "2000-01-01", "2000-01-05", "30m"
>>> from hydpy.models.lstream_v002 import *
>>> parameterstep("1d")
>>> nodes = Nodes("input1", "input2", "output")
>>> stream = Element("stream",
...                  inlets=["input1", "input2"],
...                  outlets="output")
>>> stream.model = model

We again divide the channel into eight subsections:

>>> gts(8)

Next, we define a relatively small neural network consisting of three neurons in a single hidden layer. This network roughly approximates the discharge calculated by the Gauckler-Manning-Strickler equation on the triple trapezoid profile defined in the main channel flow example:

>>> vg2qg(nmb_inputs=1,
...       nmb_neurons=(3,),
...       nmb_outputs=1,
...       weights_input=[[0.610346, 1.360399, 0.35465]],
...       weights_output=[[432.958081],
...                       [94.674914],
...                       [1778.576841]],
...       intercepts_hidden=[[-2.681908, -2.237483, -3.790469]],
...       intercepts_output=[-78.006394])

In contrast to application model lstream_v001, lstream_v002 uses the stored water volume (VG) as its state variable instead of the water stage (H). Hence, we now must set VG to a value resulting in an initial outflow of 100 m³/s for the defined parameterisation of VG2QG, which holds for 1.570929405 million m³:

>>> from hydpy.core.testtools import IntegrationTest
>>> IntegrationTest.plotting_options.activated = fluxes.qz, fluxes.qa
>>> test = IntegrationTest(stream, inits=[[states.vg, 1.570929405]])

Finally, we define two identical inflow time series:

>>> import numpy
>>> q_base = 100.0
>>> q_peak = 900.0
>>> t_peak = 24.0
>>> β = 16.0
>>> ts = pub.timegrids.init.to_timepoints()
>>> nodes.input1.sequences.sim.series = q_base
>>> nodes.input2.sequences.sim.series = (
...     (q_peak-q_base)*((ts/t_peak)*numpy.exp(1.0-ts/t_peak))**β)

Our approximation of the discharge-storage relationship is far from perfect. Still, it is, at least in the range relevant for the selected event, sufficient to reproduce the original results of application model lstream_v001 with reasonable accuracy (for example, peak flow is 660 m³/s instead of 659 m³/s):

>>> test("lstream_v002_main_channel_flow")
Click to see the table
Click to see the graph
class hydpy.models.lstream_v002.Model[source]

Bases: hydpy.models.lstream.lstream_model.Model

Version 3 of HydPy-L-Stream.

The following “inlet update methods” are called in the given sequence at the beginning of each simulation step:
  • Pick_Q_V1 Query the current inflow from all inlet nodes.

The following methods define the relevant components of a system of ODE equations (e.g. direct runoff):
  • Calc_QZA_V1 Calculate the current inflow into the channel.

  • Calc_QG_V2 Determine the discharge of each the total cross-section based on an artificial neural network describing the relationship between water storage in the total channel and discharge.

  • Calc_QA_V1 Query the actual outflow.

The following methods define the complete equations of an ODE system (e.g. change in storage of fast water due to effective precipitation and direct runoff):
The following “outlet update methods” are called in the given sequence at the end of each simulation step:
  • Pass_Q_V1 Pass the outflow to the outlet node.

numconsts: hydpy.core.modeltools.NumConstsELS
numvars: hydpy.core.modeltools.NumVarsELS
element: Optional[‘devicetools.Element’]
cymodel: Optional[typingtools.CyModelProtocol]
parameters: parametertools.Parameters
sequences: sequencetools.Sequences
masks: masktools.Masks
class hydpy.models.lstream_v002.ControlParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Control parameters of model lstream_v002.

The following classes are selected:
  • GTS() Anzahl Gewässerteilstrecken (number of channel subsections) [-].

  • VG2QG() Künstliches Neuronales Netz zur Abbildung der Abhängigkeit des Abflusses einer Gewässerteilstrecke von deren aktuller Wasserspeicherung (artificial neural network describing the relationship between total discharge and water storage of individual channel subsections [-].

class hydpy.models.lstream_v002.DerivedParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Derived parameters of model lstream_v002.

The following classes are selected:
  • Sek() Sekunden im Simulationszeitschritt (Number of seconds of the selected simulation time step) [s].

class hydpy.models.lstream_v002.FluxSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.OutputSequences[FluxSequence]

Flux sequences of model lstream_v002.

The following classes are selected:
  • QZ() Mittlerer Zufluss in Gerinnestrecke (average inflow into the channel) [m³/s].

  • QZA() Aktueller Zufluss in Gerinnestrecke (current inflow into the channel) [m³/s].

  • QG() Durchfluss gesamt (total discharge) [m³/s].

  • QA() Abfluss aus Gerinnestrecke (outflow out of the channel) [m³/s].

class hydpy.models.lstream_v002.InletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.LinkSequences[InletSequence]

Inlet sequences of model lstream_v002.

The following classes are selected:
  • Q() Abfluss (runoff) [m³/s].

class hydpy.models.lstream_v002.OutletSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.LinkSequences[OutletSequence]

Outlet sequences of model lstream_v002.

The following classes are selected:
  • Q() Abfluss (runoff) [m³/s].

class hydpy.models.lstream_v002.SolverParameters(master: hydpy.core.parametertools.Parameters, cls_fastaccess: Optional[Type[hydpy.core.parametertools.FastAccessParameter]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.variabletools.SubVariables[hydpy.core.parametertools.Parameters, Parameter, hydpy.core.parametertools.FastAccessParameter]

Solver parameters of model lstream_v002.

The following classes are selected:
  • AbsErrorMax() Absolute numerical error tolerance [m3/s].

  • RelErrorMax() Relative numerical error tolerance [-].

  • RelDTMin() Smallest relative integration time step size allowed [-].

  • RelDTMax() Largest relative integration time step size allowed [-].

class hydpy.models.lstream_v002.StateSequences(master: hydpy.core.sequencetools.Sequences, cls_fastaccess: Optional[Type[FastAccessType]] = None, cymodel: Optional[hydpy.core.typingtools.CyModelProtocol] = None)

Bases: hydpy.core.sequencetools.OutputSequences[StateSequence]

State sequences of model lstream_v002.

The following classes are selected:
  • VG() Wasservolumen (water volume) [million m³].