Quick Start¶
This documentation includes a considerable number of doctest examples,
which you can easily repeat via copy-paste, and thus serves you as a very
comprehensive tutorial. At first, it might be a little overwhelming,
so you might need to spend some time to get adjusted and to find the
relevant starting points, matching your skills and aims. If you are
already familiar with Python, we recommend to start with reading and
repeating the examples of the documentation on the central HydPy
class,
and then to follow the links mentioned therein pointing to more detailed
explanations. Without Python knowledge, you should work through the
following paragraphs beforehand. If you are primarily interested in
executing standard workflows, for example in the context of flood
forecasting, you might prefer reading the documentation on modules
hyd
, commandtools
, and xmltools
first.
Starting Python¶
Best first experience comes with using HydPy interactively. Therefore, we first need to start the Interactive Python Interpreter or similar tools like IPython. Such tools come with complete integrated development environments like Spyder. Additionally, any HydPy installation allows you to start an interactive shell by typing the following line in your command-line prompt:
hyd.py start_shell
Using Python¶
The >>> symbol tells you that Python is expecting your first statement. First, try to do some math and see if you get the correct result:
>>> 1+2
3
Understanding the functioning of HydPy requires only basic Python
knowledge. For example, you should be able to use functions like
print()
both with positional and keyword arguments:
>>> print(1, "<", 2)
1 < 2
>>> print(1, "<", 2, end=" is True")
1 < 2 is True
Realise that Python uses colons and indentations instead of brackets for defining control flow structures like if-else clauses and loops:
>>> if 1 < 2:
... print("yes")
... else:
... print("no")
yes
>>> for i in [1, 2, 3]:
... j = i**2
... print(j)
1
4
9
In Python, everything is an object, and every object allows you to inspect it interactively to find out about its features:
>>> obj = "test"
>>> type(obj) is str
True
>>> dir(obj)
[..., 'title', 'translate', 'upper', 'zfill']
>>> print(obj.upper())
TEST
>>> print(obj.title())
Test
Using HydPy¶
Now that you are familiar with nearly all details of Python (just kidding), we introduce you to HydPy. HydPy is a so-called “site-package”, supplementing the standard Python features. Make these objects available by importing them. For example, write:
>>> from hydpy.examples import prepare_full_example_2
Now the additional function prepare_full_example_2()
lives in your shell.
Executing this function prepares the LahnH example project and returns
three further HydPy objects:
>>> hp, pub, TestIO = prepare_full_example_2()
Module pub
, for example, keeps among other things the information about
the simulation period defined by function prepare_full_example_2()
.
The start and end date and the simulation step size are:
>>> print(pub.timegrids.sim.firstdate)
1996-01-01 00:00:00
>>> print(pub.timegrids.sim.lastdate)
1996-01-05 00:00:00
>>> print(pub.timegrids.sim.stepsize)
1d
The catchment outlet of the LahnH example project is named “lahn_3”. The following example demonstrates how to query the discharge values simulated for this outlet:
>>> from hydpy import round_
>>> round_(hp.nodes.lahn_3.sequences.sim.series)
nan, nan, nan, nan
nan
stands for “not a number”, which we use to indicate missing
values. Here, the nan
values tell us we did not perform a simulation
run so far. We catch up on this by calling the method simulate()
:
>>> hp.simulate()
Now, we can inspect the freshly calculated discharge values:
>>> round_(hp.nodes.lahn_3.sequences.sim.series)
54.043745, 37.320814, 31.922053, 28.413644
You could now write the results to file, print them into a figure, evaluate them statistically, or – if you don’t like them – change some configurations and calculate different ones.
As you can see, a few lines of code are often enough to let HydPy execute
complex tasks in a standard-manner. However, HydPy offers a fine level
of control, allowing you to define specific workflows solving individual
problems. Take your time to understand these first examples fully and
then follow the more detailed explanations in the documentation on the
HydPy
class.