HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/docs/rst/how_to_read_the_reference_manual.rst

@@ -0,0 +1,156 @@
+
+.. _how_to_read_the_reference_manual:
+
+How to read the Reference Manual
+================================
+
+When developing HydPy, we prefer flexibility over simplicity, and when writing the
+:ref:`reference_manual`, we prefer transparency over graphicness.  In both cases, we
+follow some software standards not regularly used within the hydrological community.
+Therefore, it may take some time before you profit from the full strengths of HydPy.
+This section offers some guides to ease navigation through the :ref:`reference_manual`
+and use its numerous Python code examples to understand the implemented models and
+improve your workflows.
+
+
+.. _integration_tests:
+
+Integration Tests
+_________________
+
+Nowdadays, most software developers test their basic source code via other
+source code.  Writing and maintaining this additional code is much work,
+but one can easily automatise its execution.  Hence, one profits from
+this strategy at the latest when a software project becomes too large for
+repeated manual testing.
+
+However, for reliable automatic testing, one needs to be sure that the
+test code covers the different vital aspects of the code base thoroughly
+enough.  One common strategy is to build two test suites, one including the
+so-called unit tests and the other one the so-called integration tests.
+Unit tests focus on specific software functionalities and often try to
+cover all possible cases.  They lay the ground for software products that
+yield correct results even under rare circumstances.  Integration tests, on the
+other hand, evaluate the interplay of different functionalities.  Due to
+increased complexity, they do not cover all possible cases but strive
+to show that we get correct results for some relevant anticipated situations.
+These "situations" are often workflows describing how we are expecting
+users to work with the software.  Therefore, well-written integration tests
+do not serve for testing only, but can be instructive for new developers
+and sometimes even for users.
+
+The documentation of *HydPy* follows the approach to embed all performed
+unit and integration tests.  This very transparent approach allows the user
+to read and quickly repeat the tests, and thereby to learn to use *HydPy*
+correctly.
+
+When speaking of integration tests, we often mean tests showing that the
+individual components of a hydrological model are combined correctly, so
+that the model can perform rational calculations.  Like *HydPy* standardises
+model implementation, it suggests a certain structure for such tests.
+
+We use the integration test on the application model |lland_dd| as an
+example.  After some "usual" introductory remarks, we start with the
+:ref:`lland_dd_integration_tests` section and prepare some general settings.
+As we want our model to perform "real" simulations, we first define a
+simulation period and step size via the |Timegrids| object available in
+module |pub|.
+
+Next, we prepare an object of the respective |Model| subclass (here,
+|lland_dd.Model| of |lland_dd|) as well as an |Element| and a |Node|
+object.  Through connecting these objects like in "real" projects, we check
+that |lland_dd| does not only calculate the correct outflow but passes it
+correctly to the downstream node (und thus potentially to other models
+downstream).  For routing models as |kinw_williams|, we need to define
+additional upstream nodes, to make sure the model also receives its inflow
+correctly.
+
+Eventually, we define some control parameters relevant for all integration
+test examples.  For |lland_dd|, we decide to set parameter
+|lland_control.NHRU| to one to focus only on one land-use type at a time.
+
+The last general step is to initialise an |IntegrationTest| object,
+which we use later for executing the individual integration test runs.
+Behind the scenes, our test object prepares an |HydPy| object and uses
+it very similar like we would do in a "real" *HydPy* project.
+
+In the first example (:ref:`lland_dd_acker_summer`), we decide to test
+|lland_dd| for the land-use type |lland_constants.ACKER| and set the
+land use parameter |lland_control.Lnk| accordingly.  After that, we
+prepare all remaining control parameters.  We can define the parameter
+values as we would do within the control files of "real" *HydPy* projects.
+
+Next, we define the initial conditions.  Principally, we could pass them
+to the relevant state sequences directly, as we would do within the
+condition files of a "real" *HydPy* project.  But then we need to reset
+them after each integration test example (each simulation run changes the
+model states, and each subsequent run starts with the lastly calculated
+states by default).  To avoid additional resetting work, class
+|IntegrationTest| offers the |Test.inits| property.  We pass pairs of
+|StateSequence| objects and initial values, which our test object memorises.
+Now it will reset each given state to the corresponding initial value
+before each test run.  Note that |Test.inits| also accepts |LogSequence|
+objects (see for example the documentation on application model |hland_96|,
+in which we define a single value for the unit hydrograph memory sequence
+|rconc_logs.QUH|).
+
+Finally, we define all model input series.  |lland_dd| receives external
+meteorological input only, which we make available via the |IOSequence.series|
+property of the relevant |InputSequence| objects (here we pass hard-coded
+values to, for example, the precipitation sequence |lland_inputs.Nied|).
+Routing models as |kinw_williams| usually do not receive external input
+but inflow from upstream models.  More concretely, they pick data from the
+|Sim| sequence(s) of their inlet |Node| object(s) (in the documentation on
+|kinw_williams|, we calculate a design flood-wave on-the-fly and assign it
+the simulation sequences of two inlet nodes).  In a "real" *HydPy* project,
+we usually would not provide any time-series data via Python source code
+but use more conventional file formats like NetCDF-CF (see |netcdftools|).
+
+After all these preparations, we let our |IntegrationTest| object execute
+the first test example.  It (re)sets the initial conditions, calls the
+|HydPy.simulate| method and tabulates the original data of all |InputSequence|
+and upstream |Sim| objects as well the result data of all |FluxSequence|,
+|StateSequence|, and downstream |Sim| objects for each simulation time step.
+This huge table is hard to read but should suffice to follow each relevant
+aspect of the internal model behaviour.
+
+Note that the tabulated date also exists hard-coded in the related source
+file for regression testing.  Each time when we or, for example, Travis CI
+(see section :ref:`tests_and_documentation`) execute our test suite,
+Python's |doctest| features compare the freshly calculated table with the
+hard-coded old table and report if they are not identical.  This sort of
+testing helps users to check if their *HydPy* installation works as
+documented and prevent developers from accidentally changing model features.
+
+The tabulated data is comprehensive and partly even redundant.  We only
+neglect the results of |AideSequence| objects (that usually handle temporary
+information not relevant for the user) and |LogSequence| objects (that
+typically provide access to data previously handled by other sequences).
+Redundancy is often due to testing both the "internal" and the "external"
+simulation results.  See for example the tabulated data of the integration
+tests of |kinw_williams|, where the values of flux sequence
+|kinw_fluxes.QA| and the outlet node sequence `output` are
+identical. |kinw_williams| first calculates the outflow values and then
+passes them to the downstream node.  Due to no other models being involved,
+the identity of both series gives us confidence  |kinw_williams| integrates
+correctly with all relevant *HydPy* functionalities.
+
+When passing a filename to our test object (in example
+:ref:`lland_dd_acker_summer`: "lland_dd_acker_summer") it also creates an
+interactive HTML plot, stores it in the `html_` subpackage, and embeds it
+into the documentation.  This mechanism ensures that each graph is always
+in-sync with the considered *HydPy* version.  The additional arguments
+`axis1` and `axis2` allow modifying the initial plot configuration.
+
+We then continue the :ref:`lland_dd_integration_tests` section with example
+:ref:`lland_dd_wasser`, dealing with one of the water types of |lland_dd|.
+We only need to assign the constant |lland_constants.WASSER| to parameter
+|lland_control.Lnk| and call our test object again to get the next results.
+
+As mentioned initially, we try to cover the fundamental aspects of each
+model but cannot expect to check everything.  So reading all of its
+integration tests is a good starting point to understand a model.  After
+that, you can perform alternative experiments yourself.  If you find your
+analysis adds add valuable information to the existing test suite or even
+reveals a shortcoming of the model, please do not hesitate to provide it
+to us (see section :ref:`version_control`).

hydpy/docs/rst/hydpydependencies.rst

@@ -0,0 +1,55 @@
+.. _Python Standard Library: https://docs.python.org/library/
+.. _setup.py: https://github.com/hydpy-dev/hydpy/blob/master/setup.py
+.. _NumPy: http://www.numpy.org/
+.. _SciPy: https://www.scipy.org/
+.. _wrapt: https://wrapt.readthedocs.io/en/latest/
+.. _netCDF4 module: http://unidata.github.io/netcdf4-python/
+.. _NetCDF-CF: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html
+.. _hydpy __init__.py file: https://github.com/hydpy-dev/hydpy/blob/master/hydpy/__init__.py
+.. _coverage library: https://coverage.readthedocs.io
+.. _requirements.txt: https://github.com/hydpy-dev/hydpy/blob/master/requirements.txt
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _conf.py: https://github.com/hydpy-dev/hydpy/blob/master/hydpy/docs/sphinx/conf.py
+
+.. _hydpydependencies:
+
+Dependencies
+____________
+
+As mentioned at the beginning of the :ref:`developer_guide` section, using
+multiple Python libraries without questioning their maturity and
+long-term stability can be a huge time-saver when compiling Python scripts
+as ad-hoc solutions for complex problems.  However, we have to be more
+cautious when including external libraries into our core code.  In general,
+we should keep the number of imported libraries low and avoid libraries
+with significant shortcomings or uncertain future support.  Otherwise,
+we risk the long-term stability of *HydPy* itself.  Whenever reasonable,
+import only packages of the `Python Standard Library`_, or at least
+restrict yourself to reliable, mature and stable site-packages.
+
+In the development of *HydPy*, we consider three groups of site-packages:
+**required** dependencies, **optional** dependencies, and dependencies
+only relevant for **development**.
+
+"Required dependencies" are site-packages being imported within
+each *HydPy* application by necessity.  See the "install_requires"
+argument within the `setup.py`_ file for the current list of required
+dependencies.  At the time of writing these are only the highly
+accepted and easily installable site-packages `NumPy`_, `SciPy`_, and
+`wrapt`_, providing essential features not available within the
+`Python Standard Library`_.
+
+"Optional dependencies" are site-packages needed for specific *HydPy*
+features only.  One good example is the `netCDF4 module`_.  The first
+reason for declaring this site-package optional is its limited scope for
+reading and writing `NetCDF-CF`_ time series files.  Users can choose other
+file formats as well.  The second reason is that its installation is not
+always working smoothly.  See the documentation on class |OptionalImport|
+on how to define optional imports.
+
+"Development dependencies" are site-packages relevant for framework or
+model developers only.  One example is the `coverage library`_, checking
+whether the available tests execute certain source code lines or not.  The
+`requirements.txt`_ file lists most development dependencies.  Additionally,
+we rely on `Sphinx`_ in conjunction with its extensions listed in `conf.py`_
+for generating the HTML documentation.

hydpy/docs/rst/index.rst

@@ -0,0 +1,125 @@
+.. _Python: http://www.python.org/
+.. _Cython: http://www.cython.org/
+.. _`Ruhr-University Bochum`: http://www.hydrology.ruhr-uni-bochum.de/index.html.en
+.. _`German Federal Institute of Hydrology`: https://www.bafg.de/EN
+.. _`Björnsen Consulting Engineers`: https://www.bjoernsen.de/en/bjoernsen-consulting-engineers
+.. _`GitHub repository`: https://github.com/hydpy-dev/hydpy
+.. _`GNU Lesser General Public License 3`: https://www.gnu.org/licenses/lgpl-3.0.en.html
+.. _`documentation test`: https://docs.python.org/3.6/library/doctest.html
+.. _`Travis CI`: https://travis-ci.com/hydpy-dev/hydpy/branches
+.. _`AppVeyor`: https://ci.appveyor.com/project/tyralla/hydpy/history
+.. _`example 13`: https://hydpy-dev.github.io/hydpy/master/dam_v001.html#dam-v001-ex13
+.. _Plotly: https://plotly.com/python/
+.. _`GitHub issue`: https://github.com/hydpy-dev/hydpy/issues
+.. _`Pull Request`: https://github.com/pulls
+
+.. _HydPy:
+
+Introduction
+============
+
+*HydPy* is an interactive framework for developing and applying
+different types of hydrological models, originally developed
+at the `Ruhr-University Bochum`_ for specific research purposes.
+Later it was extended on behalf of the `German Federal Institute of
+Hydrology`_ to be applicable in practical applications like runoff
+forecasting in large river basins.  Now it is being maintained by
+`Björnsen Consulting Engineers`_.
+
+*HydPy* is intended to be a modern open source software, based
+on the programming language `Python`_, commonly used in many scientific
+fields.  Through using different well-established `Python`_ libraries
+and design principles, we target high quality and transparency standards.
+To avoid writing model cores (like |lland_dd|) in a more native
+programming language, *HydPy* includes a `Cython`_ based mechanism
+to automatically translate Python code to C code and to compile it.
+
+*HydPy* has no graphical user interface. Instead, it is thought to
+be applied by executing Python scripts.  These scripts help to increase
+the reproducibility of studies performed with *HydPy* because
+they can be easily shared and repeatedly executed.  This approach facilitates
+discussing possible weaknesses of *HydPy* and its implemented
+models and comparing different methodical approaches (e. g. different
+strategies to calibrate model parameters).  However, if you are not an
+experienced hydrologist with basic programming skills, you may need
+some help to become acquainted with *HydPy*.
+
+We host *HydPy* in a `GitHub repository`_ and everyone
+is allowed to download, modify, and use it.  However, when passing the
+(possibly modified) code to third parties, one has to be aware that
+the selected `GNU Lesser General Public License 3`_ cannot be changed
+to a "less open source" license.  If you, for example, implement a new
+model into *HydPy*, you can be sure that all possible further
+developments of your model code are still open source and the mentioned
+third parties are allowed to pass this modified source code to you.
+
+*HydPy* offers many functionalities to make the implemented
+models as transparent and reliable as possible.  For this reason,
+the online documentation is automatically updated for each new
+*HydPy* version and includes different `documentation test`_
+mechanism ensuring that *HydPy* is working as expected and
+that the documentation is up-to-date with it.
+
+See for example the documentation of the (very simple) method
+|lland_model.Calc_NKor_V1|.  The text describes what the method does
+and what input data it requires.  It is comprehensive but, as in common
+documentations, technical reports and scientific articles, could be
+outdated or be wrong in other ways.  This is not the case for the
+example calculation shown in the green box.  This example is actual
+`Python`_ code that shows how method |lland_model.Calc_NKor_V1| can be
+used and how different input values (for variables |lland_inputs.Nied|
+and |lland_control.KG|) result in different output values (for variable
+|lland_fluxes.NKor|).  Each time a new *HydPy* version is pushed
+into the `GitHub repository`_, automatic test routines on `Travis CI`_ and
+`AppVeyor`_  are trigged.  The new *HydPy* version is rejected, if the
+actual |lland_model.Calc_NKor_V1| method does not result in the exact
+same output values as given in the last line of the example.
+
+Such basic "unit tests" should provide a good basis for discussing the
+proper implementation of certain hydrological processes.  But they
+are no proof a complete model is actually working well.  Therefore
+*HydPy* also offers some "integration test" functionalities.
+
+Each integration test should demonstrate how a certain model could be
+set up meaningfully.  Ideally, the model configuration should be varied
+to show different aspects of its functionality.  See e.g. `example 13`_
+of the documentation on model |dam_v001|, which discusses the implemented
+flood retention routine.  Here, example calculations are performed for a
+period of 20 days, and for each day all input and output values, as well
+as all internal states (e.g. the |dam_states.WaterVolume|), are tabulated.
+Again, `Travis CI`_ checks that all of these values are exactly recalculated
+by each new *HydPy* version.  Additionally, the tabulated values are
+shown in a `Plotly`_ plot, which is also updated for each new *HydPy*
+version automatically.  You can click on the variables and zoom into some
+details you are actually interested in.
+
+If there were some methodical or technical flaws in the retention routine
+of |dam_v001|, you would have good chances to find them when reading the
+documentation critically.  You could tell us about your finding via a
+`GitHub issue`_, allowing us or others to read (and at best solve) the
+problem.  Or you could try to solve it on your own and offer your solution
+as a `Pull Request`_.  You could also add a new test to the documentation
+files to prove that something goes wrong and offer it via a
+`Pull Request`_, which would enable `Travis CI`_ to reject future
+*HydPy* versions that still contain this flaw.
+
+We hope to have made clear that the design of *HydPy* focusses
+on open collaboration in order to improve existing and to develop
+better models.  The :ref:`developer_guide` section offers more information
+on how to actually participate in the further development of *HydPy*.
+Section :ref:`model_families` lists all models implemented so far.
+Sections :ref:`core` covers the basic functionalities of the
+*HydPy* framework.
+
+.. toctree::
+   :hidden:
+
+   installation
+   example_projects
+   quickstart
+   user_guide
+   developer_guide
+   reference_manual
+   Bibliography <zbibliography>
+
+

hydpy/docs/rst/installation.rst

@@ -0,0 +1,155 @@
+
+.. _Python Package Index: https://pypi.org/project/HydPy/
+.. _Python 3.10, 3.11, 3.12, or 3.13: https://www.python.org/downloads/
+.. _numpy: http://www.numpy.org/
+.. _Kalypso: https://kalypso.bjoernsen.de/index.php?id=382&L=1
+.. _Delft-FEWS: https://oss.deltares.nl/web/delft-fews
+.. _releases: https://github.com/hydpy-dev/hydpy/releases
+.. _PyCharm: https://www.jetbrains.com/pycharm/download/#section=windows
+.. _Anaconda: https://www.anaconda.com/what-is-anaconda/
+.. _IDLE: https://docs.python.org/3/library/idle.html
+.. _Spyder: https://www.spyder-ide.org/
+.. _pip: https://pip.pypa.io/en/stable/
+.. _Virtual Environments: https://docs.python.org/3/tutorial/venv.html
+.. _Python Launcher: https://docs.python.org/3/using/windows.html#launcher
+.. _Windows Compilers page: https://wiki.python.org/moin/WindowsCompilers
+.. _GNU Compiler Collection: https://gcc.gnu.org/
+
+
+.. _installation:
+
+Installation
+============
+
+HydPy is available on the `Python Package Index`_.  With `Python 3.10, 3.11, 3.12, or
+3.13`_ on your computer and having access to the internet, you only have to type::
+
+  pip install hydpy
+
+into your command-line tool to install the latest version of HydPy on your computer.
+`pip` then installs necessary site packages like `numpy`_ on the fly.
+
+For 64-bit Windows, the `Python Package Index`_ provides so-called "wheels", which
+include pre-compiled binaries and simplify installing a lot.  On Linux systems, you
+have to install "from source" at the moment, as explained below.
+
+Starting with version 4.0, HydPy also comes as an installer for Windows, including
+Python itself and all required and optional dependencies.  You may find it useful if
+you are new to Python and want to check out HydPy before installing a complete Python
+distribution or if you are afraid to mess up your current Python installation (but then
+you should probably prefer to work in a virtual environment).  Additionally, the
+closedness of the installer might be preferable when coupling HydPy to other software
+systems such as `Kalypso`_ or `Delft-FEWS`_.  See `releases`_ for the latest version of
+the HydPy installer.
+
+
+Selecting a Python distribution
+--------------------------------
+
+Using HydPy requires installing `Python 3.10, 3.11, 3.12, or 3.13`_ first.  You should
+favour the latest Python version unless you plan to use other libraries only available
+for earlier versions.  Alternatively, consider installing a more comprehensive Python
+distribution like `Anaconda`_, already containing many scientific and mathematical
+tools.
+
+Note that these Python distributions do not include the most powerful integrated
+development environments.  For simple tasks, the lightweight IDE `IDLE`_ of the
+original Python distribution might be sufficient.  `Anaconda`_ also comes with
+`Spyder`_, which helps structure medium-sized projects. On the other hand, external
+IDEs like `PyCharm`_ offer significantly more comfort, so the initial installation and
+configuration effort required should quickly pay for itself.
+
+
+Selecting a HydPy distribution
+------------------------------
+
+If you want to contribute to the development of  HydPy or implement new models, please
+see the :ref:`developer_guide` section.  If you want to apply HydPy only, you should
+start with a stable version available under `releases`_.
+
+You are probably interested in using the latest version of HydPy, which has the highest
+version number.  HydPy's version numbers consist of three separate digits.  In
+"X.Y.Z.", "X" is the major number.  There can be substantial differences between HydPy
+versions with different major numbers, possibly resulting in incompatibility issues
+with interfacing systems.  "Y" is the minor revision number, indicating some
+improvements but no potentially problematic changes, e. g. the implementation of
+additional models.  "Z" is the revision number, indicating some necessary corrections
+to the framework or its implemented models.  You should make sure to select the highest
+revision number available, meaning you should prefer using "X.Y.1" over "X.Y.0".
+
+Each release is available in different compressed archives suitable for different
+systems.  Currently, we distribute pre-compiled binaries for 64-bit Windows only (see
+above).  You have to build binaries yourself for all other operating systems and Python
+versions yourself.   Principally, this should be simple, but Windows users might need
+to install the suitable compiler first (see below).  Download and uncompress the
+`source code` archive in an arbitrary folder and open the command line interface within
+the uncompressed `hydpy` folder. Then, write the following commands::
+
+    python prepare_build.py
+    python -m build
+    python -m pip install hydpy --no-index --find-links dist
+
+The first command auto-generates some additional source files.  The second command uses
+the original and the autogenerated sources to build a compressed source distribution
+and a wheel distribution in a folder named "dist".  The wheel distribution contains the
+content of the source distribution plus pre-compiled binaries for your specific system
+and `Python` version.  The third command installs the wheel into the currently active
+site packages folder.  After that, you are ready to go.
+
+
+Creating an Environment
+-----------------------
+
+Refraining from adding site packages like HydPy into the basic Python installation is
+always advisable.  Otherwise, with time, the number of additional packages grows larger
+and larger, and it will not take long until the first incompatibilities emerge.
+
+To avoid such problems, the Python community developed many "environment mechanisms".
+An `environment` is a kind of project- or purpose-specific Python subinstallation that
+is, more or less, independent of other `environments`.
+
+Integrated development environments (IDEs) provide convenient ways to manage multiple
+environments connected to different projects.  But even without a capable IDE, the
+basic steps are straightforward.  For example, each Python installation has tools for
+creating and using `Virtual Environments`_.
+
+With the `Python Launcher`_ installed, the following command creates a virtual
+environment named `venv_hydpy_5` in your current working directory::
+
+    py -m venv venv_hydpy_5
+
+You can activate this virtual environment on Windows by executing the batch file
+`activate.bat`::
+
+    venv_hydpy_5\Scripts\activate
+
+You can now execute the following command to let `pip`_  install the latest release of
+HydPy 5 into the `venv_hydpy_5` environment::
+
+    pip install "hydpy < 6"
+
+After following these steps, you have an outdated HydPy version on your computer.  But
+this does not need to bother you, because you can just as easily install, for example,
+HydPy 6 in a separate environment without the risk of any conflicts::
+
+    deactivate
+    py -m venv venv_hydpy_6
+    venv_hydpy6\Scripts\activate
+    pip install "hydpy < 7"
+
+
+Selecting a C Compiler
+----------------------
+
+You only need to care about selecting a C compiler if no pre-compiled binaries are
+available for your system or if you want to implement new models into the HydPy
+framework.  Also, Linux users should have no trouble, as the `GNU Compiler Collection`_
+is ready for use on standard Linux distributions.  Unfortunately, Windows does not
+include compilers by default.  Search the `Windows Compilers page`_  to learn how to
+select and install the correct compiler.
+
+After installing the required compiler on Windows, you might eventually have to deal
+with the **unable to find vcvarsall.bat** problem.  `vcvarsall` is a batch file Python
+needs to control the installed Visual Studio compiler.  Find this file on your system
+and set a new system variable pointing to its path.  A quick search on the internet
+should provide you with the required information.

hydpy/docs/rst/model_families.rst

@@ -0,0 +1,79 @@
+
+.. _LARSIM: http://www.larsim.info/1/the-model/
+
+.. _model_families:
+
+Model Families
+==============
+
+HydPy divides all models into "families" as :ref:`HydPy-L`.  Each model family consists
+of one base model (e.g. |lland|) and several application models (e.g. |lland_dd|).  The
+base models offer basic features like model parameter classes (e.g.
+|lland_control.KG|), sequence classes (e.g. |lland_fluxes.NKor|) and process equation
+methods (e.g. |lland_model.Calc_NKor_V1|) but cannot perform an actual simulation run.
+This is the task of the application models, which select different parameters,
+sequences, and process equations in a meaningful combination and order.
+
+
+Unless otherwise stated, you can freely combine all models and apply them with
+arbitrary simulation time steps.  It is, for example, possible to simulate "land
+processes" with |hland_96|, "stream processes" with |musk_mct|, and "lake processes"
+with |dam_llake| in either a daily or hourly time step.
+
+Base models often offer different versions of a method to calculate the value of the
+same variable.  For example, base model |evap| has two methods for estimating reference
+evapotranspiration: |evap_model.Calc_ReferenceEvapotranspiration_V1| and
+|evap_model.Calc_ReferenceEvapotranspiration_V2|.  Each application model that wants to
+calculate reference evapotranspiration has to choose. In this case, |evap_ret_fao56|
+selects |evap_model.Calc_ReferenceEvapotranspiration_V1| to follow
+:cite:t:`ref-Allen1998` and  |evap_ret_tw2002| selects
+|evap_model.Calc_ReferenceEvapotranspiration_V2| to follow :cite:t:`ref-DVWK`:
+
+>>> from hydpy.models.evap_ret_tw2002 import *
+>>> parameterstep("1d")
+>>> assert hasattr(model, "calc_referenceevapotranspiration_v2")
+>>> assert not hasattr(model, "calc_referenceevapotranspiration_v1")
+
+For simplicity, the selected method is also accessible without the version suffix (as
+long as the model does not choose multiple versions of the same method, which is a
+HydPy convention only seldom broken by application models):
+
+>>> assert hasattr(model, 'calc_referenceevapotranspiration_v2')
+
+Methods define their parameter and sequence requirements.  Due to choosing
+|evap_model.Calc_ReferenceEvapotranspiration_V2|, application model |evap_ret_tw2002|
+possesses, for example, the flux sequence |evap_fluxes.ReferenceEvapotranspiration|:
+
+>>> assert hasattr(model.sequences.fluxes, 'referenceevapotranspiration')
+
+Due to this selection mechanism, it is relatively easy to compose new models based on
+existing or alternative methods.  However, such compositions are restricted to using
+methods of only one base model or model family.  To overcome this limitation, HydPy
+also implements the so-called "submodel concept", which brings another kind of
+flexibility by coupling main models (of one model family) with submodels (of the same
+or another model family).  This section describes both the main and the submodels.  See
+the :ref:`model_overview` section, which clarifies this distinction more clearly.
+
+
+.. toctree::
+   :hidden:
+
+   HydPy-ARMA
+   HydPy-Conv
+   HydPy-Exch
+   HydPy-Evap
+   HydPy-Dam
+   HydPy-Dummy
+   HydPy-G
+   HydPy-GA
+   HydPy-H
+   HydPy-KinW
+   HydPy-L
+   HydPy-Meteo
+   HydPy-Musk
+   HydPy-Rconc
+   HydPy-SW1D
+   HydPy-Test
+   HydPy-W
+   HydPy-WHMod
+   HydPy-WQ