HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/docs/rst/quickstart.rst

@@ -0,0 +1,304 @@
+
+.. _doctest: https://docs.python.org/library/doctest.html
+.. _Python Interpreter: https://docs.python.org/tutorial/interpreter.html
+.. _Python Launcher: https://docs.python.org/3/using/windows.html#launcher
+.. _IDLE: https://docs.python.org/3/library/idle.html
+.. _IPython: https://ipython.org/
+.. _PyCharm: https://www.jetbrains.com/pycharm
+
+.. role:: raw-html(raw)
+   :format: html
+
+
+.. _quickstart:
+
+Quick Start
+===========
+
+This documentation includes countless `doctest`_  examples, which you can easily repeat
+via copy-paste to gain insights into all the details of HydPy.  At first, it may be
+overwhelming, so you need to get adjusted and find the relevant starting points that
+match your skills and aims.  If you want to take advantage of HydPy's full flexibility
+by using it as a Python library and are already familiar with Python, go to the
+:ref:`Simulation > Python <simulation_python>` subsection.  Without Python experience,
+you should review the following paragraphs beforehand.  If you are, in contrast,
+primarily interested in executing standard workflows, for example, in the context of
+flood forecasting, you might prefer starting with the :ref:`Simulation > XML
+<simulation_xml>` subsection.
+
+
+Starting Python
+_______________
+
+The best first experience comes with using HydPy interactively.  Therefore, one first
+must start a Python shell.  The most basic choice is the `Python Interpreter`_.  With a
+default installation on Windows, you can type `py` into a console like the command
+prompt (cmd), which tells the `Python Launcher`_ to search for the interpreter of the
+currently preferable Python version installed on your computer (usually, the most
+recent one) and start it::
+
+  C:\>py
+  Python 3.13.1
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>>
+
+To start learning Python (and HydPy), a good choice is Python's Integrated Development
+and Learning Environment `IDLE`_, which also comes with regular Python distributions.
+Open its shell via the Windows menu or by writing::
+
+  py -m idlelib
+
+.. image:: IDLE-shell.png
+   :width: 700
+
+The two mentioned options require a regular Python installation on your computer. The
+following command also works with HydPy installed independently from a regular Python
+distribution via its Windows installer::
+
+  hyd.py start_shell
+  >>>
+
+You may want to save modified or freshly created examples in Python scripts.  For a
+start, `IDLE`_ does not only provide the (initially opened) shell window but can also
+open multiple editor windows (click on File :raw-html:`&rarr;` New File):
+
+.. image:: IDLE-editor.png
+   :width: 700
+
+When seriously starting to work with Python, consider using more capable shells like
+`IPython`_ or complex Integrated Development Environments like `Pycharm`_.
+
+
+Using Python
+____________
+
+Understanding the functioning of HydPy requires only basic Python knowledge, to which
+this subsection offers a brief introduction.
+
+In the shell, the `>>>` symbol tells you that Python is expecting your first action.
+First, do some math and see if you get the correct result:
+
+>>> 1 + 2
+3
+
+Assignments work with `=`:
+
+>>> x = 4
+>>> x
+4
+
+Checks for equality and identity rely on `==` and `is`:
+
+>>> y = 4.0
+>>> x == y
+True
+>>> x is y
+False
+
+`!=` and `is not` are their counterparts:
+
+>>> x != y
+False
+>>> x is not y
+True
+
+Many functions like |print| accept both positional and keyword arguments:
+
+>>> print(1, "<", 2)  # three positional arguments
+1 < 2
+
+>>> print(1, "<", 2, end=" is True")  # three positional and one keyword argument
+1 < 2 is True
+
+Python uses colons and indentations instead of brackets to define control flow
+structures, such as if-else clauses:
+
+>>> if 1 < 2:
+...     print("yes")
+... else:
+...     print("no")
+yes
+
+The most common way of defining loops is using `for ... in ...` expressions:
+
+>>> for i in [1, 3, 2]:
+...     (2 * i) ** 2
+4
+36
+16
+
+Write `import ...` to import another library completely or `import ... from ...` to
+load one or more of its members:
+
+>>> import hydpy
+>>> from hydpy import HydPy, pub
+
+`.` serves for member access:
+
+>>> hydpy.pub is pub
+True
+
+In `assert ...`, `assert` checks if `...` is true:
+
+>>> assert pub.options.utcoffset == 60  # right, so nothing happens
+>>> assert pub.options.utcoffset == -60  # wrong, hence an AssertionError
+Traceback (most recent call last):
+...
+AssertionError
+
+The `with` statement usually starts something and undoes it after finishing the
+following indented block:
+
+>>> with pub.options.utcoffset(-60):
+...     assert pub.options.utcoffset == -60
+>>> assert pub.options.utcoffset == 60
+
+In Python, everything is an object, and every object allows you to inspect it to find
+out about its features:
+
+>>> obj = "test"
+>>> assert type(obj) is str  # What type has `obj`?
+>>> dir(obj)[-4:]  # What are it's members?
+['title', 'translate', 'upper', 'zfill']
+>>> obj.upper()  # What does its method `upper` do?
+'TEST'
+
+Assigning an object to a variable does not involve copying it.  One merely gets another
+reference (or pointer) to the same object:
+
+>>> list1 = [1, 2]
+>>> list2 = list1
+>>> assert list1 is list2
+>>> list2.append(3)
+>>> assert list1 == [1, 2, 3]
+
+The same holds for passing objects to functions:
+
+>>> def append_value(list_, value):
+...     list_.append(value)
+...
+>>> append_value(list2, 4)
+>>> assert list1 == [1, 2, 3, 4]
+
+.. caution::
+
+    Python provides functions for making flat and deep copies of objects.  "Deep
+    copying" means that an object **and** its subobjects are copied.  This effort is
+    favourable in some situations but results in additional memory usage and
+    computation time.  HydPy's Cython-based extension classes, and thus HydPy in
+    general, do **not** support deep copying.
+
+
+.. _run_hydpy:
+
+Run HydPy
+_________
+
+After this first dive into Python's syntax, we introduce you to HydPy.  For an easy
+start, please download and unzip the :ref:`HydPy-H-Lahn` example project into a
+working directory of your choice.
+
+Now open, for example, the `IDLE` shell as explained above and activate the selected
+directory.  Let us, therefore, first define the working directory's path as a string.
+We take "C:/temp" as an example, but you can specify any other directory (on Windows,
+you could also write r"C:\\temp" for "C:\\\\temp"):
+
+>>> workingdir = "C:/temp"
+
+.. testsetup::
+
+    >>> from hydpy.core.testtools import prepare_full_example_1
+    >>> prepare_full_example_1()
+    >>> import os
+    >>> cwd = os.getcwd()
+    >>> from hydpy.tests import iotesting
+    >>> workingdir = iotesting.__path__[0]
+    >>> os.chdir(workingdir)
+
+Now, import Python's |os| module and use its `chdir` function to activate the
+preferred working directory:
+
+>>> import os
+>>> os.chdir(workingdir)
+
+The now-activated directory should contain a subdirectory named `HydPy-H-Lahn`
+containing, for example, the sub-subdirectory `network`.  The following code line
+checks this:
+
+>>> assert os.path.exists(os.path.join(workingdir, "HydPy-H-Lahn", "network"))
+
+After these preparatory steps, we finally get started with HydPy.  HydPy is a so-called
+"site package", and, in Python, site package names are by convention lowercase:
+
+>>> import hydpy
+
+The entry point to each project is the central |HydPy| class.  Initialise it by passing
+the project's name to it:
+
+>>> hp = hydpy.HydPy("HydPy-H-Lahn")
+
+Equally prominent throughout this documentation is the |pub| module, which allows for
+the specification of general information.  Here, we use it to define the first date,
+the last date, and the time step size of the considered simulation period in the
+simplest possible manner:
+
+>>> hydpy.pub.timegrids = "1996-01-01", "1997-01-01", "1d"
+
+Now, there are numerous ways to proceed.  We choose the most straightforward one
+(without deviating from a single default) and call method  |HydPy.prepare_everything|
+of class |HydPy|, which "prepares everything" so far as to leave the |HydPy| instance
+in a simulation-ready state:
+
+>>> hp.prepare_everything()
+
+The catchment outlet of the :ref:`HydPy-H-Lahn` example project is named `lahn_kalk`.
+The following example demonstrates how to query the discharge values simulated for this
+outlet:
+
+>>> from hydpy import print_vector
+>>> print_vector(hp.nodes.lahn_kalk.sequences.sim.series[:6])
+nan, nan, nan, nan, nan, nan
+
+|numpy.nan| means "not a number", indicating missing values.  In this example, the
+|numpy.nan| values tell us we have not performed a simulation run.  We catch up on this
+by calling method |HydPy.simulate|:
+
+>>> hp.simulate()
+
+Now, we can inspect the freshly calculated discharge values:
+
+>>> print_vector(hp.nodes.lahn_kalk.sequences.sim.series[:6])
+54.019337, 37.257561, 31.865308, 28.359542, 26.191386, 25.047099
+
+You could now write the results to file, print them into a figure, evaluate them
+statistically, or change some configurations and repeat the simulation if you don't
+like them.  As a last example, we compare the  complete simulated discharge time series
+with the available measurements of gauge Kalkofen by plotting them:
+
+>>> figure = hp.nodes.lahn_kalk.plot_allseries()
+
+.. testsetup::
+
+    >>> from hydpy.core.testtools import save_autofig
+    >>> save_autofig("Kalkofen_Qsim_vs_Qobs.png", figure)
+
+.. image:: Kalkofen_Qsim_vs_Qobs.png
+
+.. tip::
+
+    If the desired time series plot does not appear automatically (which depends on
+    your configuration of the |matplotlib| library), type the following commands:
+
+    >>> from matplotlib import pyplot  # doctest: +SKIP
+    >>> pyplot.show()  # doctest: +SKIP
+
+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 fine-grained control, allowing you to
+define specific workflows to solve individual problems.  Take your time to understand
+these first examples fully and then follow the more detailed explanations in the
+:ref:`Simulation > Python <simulation_python>` and :ref:`Simulation > XML
+<simulation_xml>` sections.
+
+.. testsetup::
+
+    >>> os.chdir(cwd)

hydpy/docs/rst/reference_manual.rst

@@ -0,0 +1,29 @@
+
+.. _reference_manual:
+
+Reference Manual
+================
+
+This reference manual provides in-depth information about all general :ref:`framework
+functionalities <framework_tools>` and :ref:`models <model_families>` HydPy offers.
+Also, it lists all :ref:`submodel interfaces <submodel_interfaces>`, which are
+standardised connections for coupling main models and submodels.
+
+HydPy has a so-called complete (line-based) test coverage, meaning automatised test
+bots analyse each HydPy build thoroughly.  We achieved this desirable goal by writing
+an extremely high number of doctests, which are "normal" unit or integration tests
+visible in the documentation.  As a result, reading this reference manual takes some
+time (and we advise not only to read but also repeat the tests in a Python shell), but
+it covers all details and edge cases we thought to be relevant (for example, tests of
+expected user errors).  Therefore, please refrain from reading this reference manual
+from front to back.  You will likely benefit more from working through the
+:ref:`quickstart` section and the :ref:`user_guide` and, afterwards, from searching
+for more specific information in this reference manual.
+
+
+.. toctree::
+   :hidden:
+
+   framework_tools
+   model_families
+   submodel_interfaces

hydpy/docs/rst/required_tools.rst

@@ -0,0 +1,50 @@
+.. _GitHub: https://github.com
+.. _hydpy repository: https://github.com/hydpy-dev/hydpy
+.. _CPython: https://www.python.org/
+.. _requirements.txt: https://github.com/hydpy-dev/hydpy/blob/master/requirements.txt
+.. _Cython: http://www.cython.org/
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _conf.py: https://github.com/hydpy-dev/hydpy/blob/master/hydpy/docs/sphinx/conf.py
+.. _Spyder: https://www.spyder-ide.org/
+.. _Anaconda distribution: https://www.anaconda.com/distribution/
+.. _PyCharm: https://www.jetbrains.com/pycharm/
+.. _type hints: https://docs.python.org/3/library/typing.html
+.. _mypy: http://mypy-lang.org/
+.. _Git: https://git-scm.com/
+
+.. _required_tools:
+
+Required tools
+______________
+
+For simple tasks like fixing typos, a web browser suffices to propose
+file changes directly via `GitHub`_ (see section :ref:`version_control`).
+Your "pull request" triggers a server-based process, employing all tools
+required to test, build, release, and document a new *HydPy* version (see
+section :ref:`continuous_integration`).  For an actual release, the
+maintainer of the `hydpy repository`_ only needs to accept your request
+and "tag" it. However, reaching for more complex goals requires to have
+these development tools runnable on your machine.
+
+First, you need the Python interpreter itself. We do our best to keep
+*HydPy* up-to-date with the development of Python, so please select the
+most recent stable `CPython`_ version.
+
+Second, install all required site-packages listed in `requirements.txt`_.
+These include tools like `Cython`_ for translating Python based model
+source code into computationally more efficient C code.  Additionally,
+you need `Sphinx`_ and its extensions listed in `conf.py`_ for generating
+the HTML documentation.
+
+Third, please use a modern Integrated Development Environment (IDE).
+Principally, you are free to select any IDE you like (one reasonable
+choice for beginners were `Spyder`_, already contained in the
+`Anaconda distribution`_), but at least for developers planning more
+substantial code contributions, we strongly recommend `PyCharm`_.
+We gradually introduce `type hints`_ into *HydPy's* source code and,
+so far, prefer `PyCharm`_'s internal type checker over `mypy`_, which
+is still not part of the standard library.  One must use `PyCharm`_
+specific comments to disable misleading type warnings (and other
+misleading warnings as well).
+
+Fourth, you need `Git`_ for version control, as described in the next section.