examples

This module provides functions for preparing tutorial projects and other test data.

Module examples implements the following members:

• prepare_io_example_1() Prepare an IO example configuration for testing purposes.

• prepare_full_example_1() Prepare the LahnH example project on disk.

• prepare_full_example_2() Prepare the LahnH project on disk and in RAM.

---

hydpy.examples.prepare_io_example_1() → Tuple[Nodes, Elements]

Prepare an IO example configuration for testing purposes.

Function prepare_io_example_1() is thought for testing the functioning of HydPy and thus should be of interest for framework developers only. It uses the application models lland_v1, lland_v2, and hland_v1. Here, we apply prepare_io_example_1() and shortly discuss different aspects of its generated data.

>>> from hydpy.examples import prepare_io_example_1
>>> nodes, elements = prepare_io_example_1()

1. It defines a short initialisation period of five days:

>>> from hydpy import pub
>>> pub.timegrids
Timegrids("2000-01-01 00:00:00",
          "2000-01-05 00:00:00",
          "1d")

2. It prepares an empty directory for IO testing:

>>> import os
>>> from hydpy import repr_, TestIO
>>> with TestIO():  
...     repr_(pub.sequencemanager.currentpath)
...     os.listdir("project/series/default")
'...iotesting/project/series/default'
[]

(3) It returns four Element objects handling either application model lland_v1 lland_v2, or hland_v1, and two Node objects handling variables Q and T:

>>> for element in elements:
...     print(element.name, element.model)
element1 lland_v1
element2 lland_v1
element3 lland_v2
element4 hland_v1
>>> for node in nodes:
...     print(node.name, node.variable)
node1 Q
node2 T

(4) It generates artificial time series data for the input sequence Nied, the flux sequence NKor, and the state sequence BoWa of each lland model instance, the state sequence SP of the hland_v1 model instance, and the Sim sequence of each node instance. For precise test results, all generated values are unique:

>>> nied1 = elements.element1.model.sequences.inputs.nied
>>> nied1.series
InfoArray([0., 1., 2., 3.])
>>> nkor1 = elements.element1.model.sequences.fluxes.nkor
>>> nkor1.series
InfoArray([[12.],
           [13.],
           [14.],
           [15.]])
>>> bowa3 = elements.element3.model.sequences.states.bowa
>>> bowa3.series
InfoArray([[48., 49., 50.],
           [51., 52., 53.],
           [54., 55., 56.],
           [57., 58., 59.]])
>>> sim2 = nodes.node2.sequences.sim
>>> sim2.series
InfoArray([64., 65., 66., 67.])
>>> sp4 = elements.element4.model.sequences.states.sp
>>> sp4.series
InfoArray([[[68., 69., 70.],
            [71., 72., 73.]],

           [[74., 75., 76.],
            [77., 78., 79.]],

           [[80., 81., 82.],
            [83., 84., 85.]],

           [[86., 87., 88.],
            [89., 90., 91.]]])

(5) All sequences carry ndarray objects with (deep) copies of the time-series data for testing:

>>> import numpy
>>> (numpy.all(nied1.series == nied1.testarray) and
...  numpy.all(nkor1.series == nkor1.testarray) and
...  numpy.all(bowa3.series == bowa3.testarray) and
...  numpy.all(sim2.series == sim2.testarray) and
...  numpy.all(sp4.series == sp4.testarray))
InfoArray(True)
>>> bowa3.series[1, 2] = -999.0
>>> numpy.all(bowa3.series == bowa3.testarray)
InfoArray(False)

hydpy.examples.prepare_full_example_1(dirpath: str | None = None) → None

Prepare the LahnH example project on disk.

HydPy comes with a complete project data set for the German river Lahn, provided by the German Federal Institute of Hydrology (BfG). The Lahn is a medium-sized tributary to the Rhine. The given project configuration agrees with the BfG’s forecasting model, using HBV96 to simulate the inflow of the Rhine’s tributaries. The catchment consists of four sub-catchments, each one with a river gauge (Marburg, Asslar, Leun, Kalkofen) at its outlet. The sub-catchments consists of a different number of zones.

By default, function prepare_full_example_1() copies the original project data into the iotesting directory, thought for performing automated tests on real-world data. The following doctest shows the generated folder structure:

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()
>>> from hydpy import TestIO
>>> import os
>>> with TestIO():
...     print("root:", *sorted(os.listdir(".")))
...     for folder in ("control", "conditions", "series"):
...         print(f"LahnH/{folder}:",
...               *sorted(os.listdir(f"LahnH/{folder}")))
root: LahnH __init__.py
LahnH/control: default
LahnH/conditions: init_1996_01_01_00_00_00
LahnH/series: default

Pass an alternative path if you prefer to work in another directory:

>>> prepare_full_example_1(dirpath=".")

hydpy.examples.prepare_full_example_2(lastdate: timetools.DateConstrArg = '1996-01-05') → Tuple[hydpytools.HydPy, pubtools.Pub, Type[testtools.TestIO]]

Prepare the LahnH project on disk and in RAM.

Function prepare_full_example_2() is an extensions of function prepare_full_example_1(). Besides preparing the project data of the LahnH example project, it performs all necessary steps to start a simulation run. Therefore, it returns a readily prepared HydPy instance, as well as, for convenience, module pub and class TestIO:

>>> from hydpy.examples import prepare_full_example_2
>>> hp, pub, TestIO = prepare_full_example_2()
>>> hp.nodes
Nodes("dill", "lahn_1", "lahn_2", "lahn_3")
>>> hp.elements
Elements("land_dill", "land_lahn_1", "land_lahn_2", "land_lahn_3",
         "stream_dill_lahn_2", "stream_lahn_1_lahn_2",
         "stream_lahn_2_lahn_3")
>>> pub.timegrids
Timegrids("1996-01-01 00:00:00",
          "1996-01-05 00:00:00",
          "1d")
>>> from hydpy import classname
>>> classname(TestIO)
'TestIO'

Function prepare_full_example_2() is primarily thought for testing and thus does not allow for many configurations except changing the end date of the initialisation period:

>>> hp, pub, TestIO = prepare_full_example_2("1996-02-01")
>>> pub.timegrids
Timegrids("1996-01-01 00:00:00",
          "1996-02-01 00:00:00",
          "1d")