Add the first version of application model hland_v3, combining conc…

…epts from HB96 and PREVAH (closes #67). (work in progress)

We still need to:
 * write the documentation of the application model
 * add a figure

This commit also tidies up the general documentation on `hland`, trying to keep everything consistent.

hydpy/core/testtools.py

@@ -140,6 +140,7 @@ def filenames(self) -> List[str]:
          'hland_constants.py',
          'hland_control.py',
          'hland_derived.py',
+         'hland_fixed.py',
          'hland_fluxes.py',
          'hland_inputs.py',
          'hland_logs.py',
@@ -170,6 +171,7 @@ def modulenames(self) -> List[str]:
         ['hland_constants',
          'hland_control',
          'hland_derived',
+         'hland_fixed',
          'hland_fluxes',
          'hland_inputs',
          'hland_logs',
@@ -197,7 +199,7 @@ def perform_tests(self) -> None:
         However, you are free to call it any time when in doubt of the functionality
         of a particular base or application model.  Doing so might change some of the
         states of your current configuration, but only temporarily (besides
-        "projectname" we pick the |Timegrids| object of module |pub| as an example,
+        "projectname") we pick the |Timegrids| object of module |pub| as an example,
         which is changed multiple times during testing but finally reset to the
         original value):
 
@@ -214,6 +216,8 @@ def perform_tests(self) -> None:
                 no failures occurred
             * hland_derived:
                 no failures occurred
+            * hland_fixed:
+                no failures occurred
             * hland_fluxes:
                 no failures occurred
             * hland_inputs:
@@ -245,10 +249,9 @@ def perform_tests(self) -> None:
                   "2001-01-01 00:00:00",
                   "1d")
 
-        To show the reporting of possible errors, we change the
-        string representation of parameter |hland_control.ZoneType|
-        temporarily.  Again, the |Timegrids| object is reset to its
-        initial state after testing:
+        To show the reporting of possible errors, we change the string representation
+        of parameter |hland_control.ZoneType| temporarily.  Again, the |Timegrids|
+        object is reset to its initial state after testing:
 
         >>> from unittest import mock
         >>> with mock.patch(

hydpy/docs/bibliography/refs.bib

@@ -131,7 +131,7 @@ @Book{DVWK1996
   author    = {{GFA} {Gesellschaft} zur {Förderung} der {Abwassertechnik} {e.V}.},
 }
 
-@Article{LINDSTROM1997272,
+@Article{Lindstrom1997HBV96,
   author   = {Göran Lindström and Barbro Johansson and Magnus Persson and Marie Gardelin and Sten Bergström},
   title    = {Development and test of the distributed HBV-96 hydrological model},
   journal  = {Journal of Hydrology},
@@ -221,4 +221,15 @@ @article{Brauer2014
   doi={10.5194/hess-18-4007-2014}
 }
 
+@article{Viviroli2009PREVAH,
+  title={An introduction to the hydrological modelling system PREVAH and its pre-and post-processing-tools},
+  author={Viviroli, Daniel and Zappa, Massimiliano and Gurtz, Joachim and Weingartner, Rolf},
+  journal={Environmental Modelling \& Software},
+  volume={24},
+  number={10},
+  pages={1209--1222},
+  year={2009},
+  publisher={Elsevier}
+}
+
 @Comment{jabref-meta: databaseType:bibtex;}

hydpy/docs/rst/HydPy-H.rst

@@ -4,18 +4,16 @@
 HydPy-H (HBV)
 =============
 
-HydPy implements a very close emulation of the central routines of
-the famous HBV96 model, introduced by Lindstroem et al
-:cite:`ref-LINDSTROM1997272`.
-As discussed in :cite:`ref-Tyralla2013`, the results of
-version 1 application models of HydPy-H and the IHMS-HBV96
-implementation of the Swedish Meteorological and Hydrological Institute
-agree very well for the majority of the tested river basins [#f1]_.
-This documentation focusses on technical aspects of HydPy-H and tries
-to be as precise as possible regarding the implementation of the
-process equations.  The background of the scientifical development of
-the HBV96 model is more thoroughly covered in Lindstroem et al
-:cite:`ref-LINDSTROM1997272`.
+*HydPy* implements a very close emulation of the central routines of the famous
+HBV96 model, introduced by Lindstroem et al :cite:`ref-Lindstrom1997HBV96`.
+As discussed in :cite:`ref-Tyralla2013`, the results of version 1 application
+models of HydPy-H and the IHMS-HBV96 implementation of the Swedish
+Meteorological and Hydrological Institute agree very well for the majority of
+the tested river basins [#f1]_. This documentation focusses on technical
+aspects of HydPy-H and tries to be as precise as possible regarding the
+implementation of the process equations.  The background of the scientifical
+development of the HBV96 model is more thoroughly covered in Lindstroem et al.
+:cite:`ref-Lindstrom1997HBV96`.
 
 HydPy-H is divided into three base models, which can be used to compile
 different application models:
@@ -31,13 +29,14 @@ So far the following application models are compiled:
 
 .. toctree::
 
-   hland_v1 (HBV96 version of HydPy-H-Land) <hland_v1>
+   hland_v1 (HBV96) <hland_v1>
    hland_v2 (under development) <hland_v2>
-   hstream_v1 (HBV96 version of HydPy-H-Stream) <hstream_v1>
-   hbranch_v1 (HBV96 version of HydPy-H-Branch) <hbranch_v1>
+   hland_v3 (HBV96/PREVAH) <hland_v3>
+   hstream_v1 (HBV96) <hstream_v1>
+   hbranch_v1 (HBV96) <hbranch_v1>
 
 All these application models are stand-alone models, which can be
-combined freely with all other models implemented in HydPy.
+combined freely with all other models implemented in *HydPy*.
 
 .. rubric:: Footnotes
 

hydpy/models/hland/hland_constants.py

@@ -1,29 +1,19 @@
 # -*- coding: utf-8 -*-
-"""The HydPy-H-Land model (|hland|) allows for the subdivision of subbasins
-into zones (hydrological response units).  Some processes, e.g. interception,
-are calculated separately for each zone.  This is why some parameters (e.g.
-the interception capacity |IcMax|) and some sequences (e.g. the actual
-interception storage |Ic|) are 1-dimensional.  Each entry represents the
-value of a different zone.
-
-In contrasts to the original HBV96 model, the HydPy-H-Land model allows for
-arbitrary definitions of zones.  Nevertheless, the original distinction
-in accordance with four different zone types is still supported.  The
-parameter |ZoneType| defines e.g. which entry of |IcMax| is related to
-which zone type via integer values.  Note that for zones of type |FIELD|
-and |FOREST| the same equations are applied. (Usually, larger |IcMax|
-values and smaller |CFMax| are assigned to |FOREST| zones due to their
-higher leaf area index and the associated decrease in solar radiation.)
-On the contrary, zones of type |GLACIER| and |ILAKE| are partly connected
-to different process equations.
-
-For comprehensibility, this module introduces the relevant integer constants.
-Through performing a wildcard import
+"""Base model |hland| allows dividing subbasins into zones (hydrological response
+units).  It applies the equations related to some processes (for example, interception)
+separately for each zone.  Consequently, parameters as the interception capacity
+|IcMax| and sequences as the actual interception storage |Ic| are 1-dimensional.
+Each entry represents the value of a different zone.
+
+In contrast to the original HBV96 model, |hland| allows defining individual parameter
+values for each zone, which provides flexibility but might also be a little overwhelming
+in many use-cases.  Hence, we also support the original HBV96-distinction into the zone
+types "field", "forest", "glacier", and "ilake" (internal lake).  Parameter "ZoneType"
+specifies the type of each response unit via one of the integer constants |FIELD|,
+|FOREST|, |GLACIER|, and |ILAKE|. Through performing a wildcard import, these constants
+become available in your local namespace:
 
 >>> from hydpy.models.hland import *
-
-these are available in your local namespace:
-
 >>> FIELD, FOREST, GLACIER, ILAKE
 (1, 2, 3, 4)
 """