Add application model exch_v001 (closes #69).

hydpy/docs/rst/HydPy-Exch.rst

@@ -0,0 +1,36 @@
+.. _HydPy-Exch:
+
+HydPy-Exch
+==========
+
+The `HydPy-Exch` model family enables instances of other model types to exchange
+information.   Usually, model instances eventually receive inflow and pass
+outflow to other models without knowing anything about them.  One exception is
+the highly specialised application model |dam_v004|, which calculates its
+discharge to a |dam_v005| instance based on some knowledge of the other model's
+internal state.  The purpose of `HydPy-Exch` is to facilitate similar exchanges
+between different model instances more modularly. Application model |exch_v001|,
+for example, simulates a weir.  Conceptionally, it enables a bidirectional water
+exchange between two lakes, where the flow direction depends on the difference
+of the lakes' water levels.  Technically, we can combine |exch_v001| with all
+model types calculating (something like) water level information and accepting
+an additional inlet that can supply positive and negative values.  Due to this
+flexible approach, we do not need to implement the weir formula to different
+|dam| models.  On the downside, this looser coupling often comes with some
+limitations.  One example is numerical accuracy, which might be suboptimal due
+to solving the interconnected differential equations of different model
+instances sequentially (we might improve this later).
+
+Base model:
+
+.. toctree::
+   :maxdepth: 1
+
+   exch
+
+Application model:
+
+.. toctree::
+   :maxdepth: 1
+
+   exch_v001 (weir) <exch_v001>

hydpy/docs/rst/modelcollection.rst

@@ -79,6 +79,7 @@ and will have to be discussed later.
    HydPy-A
    HydPy-C
    HydPy-E
+   HydPy-Exch
    HydPy-D
    HydPy-Dummy
    HydPy-H

hydpy/models/exch/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=wildcard-import
+"""
+The `HydPy-Exch` base model provides features to implement helper models that enable
+other models to exchange data more freely.
+"""
+# import...
+# ...from HydPy
+from hydpy.exe.modelimports import *
+
+# ...from exch
+from hydpy.models.exch.exch_model import Model
+
+tester = Tester()
+cythonizer = Cythonizer()
+cythonizer.finalise()

hydpy/models/exch/exch_control.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=missing-docstring
+# pylint: enable=missing-docstring
+
+# import...
+
+# ...from HydPy
+from hydpy.core import parametertools
+
+
+class CrestHeight(parametertools.Parameter):
+    """Crest height [m]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+
+
+class CrestWidth(parametertools.Parameter):
+    """Crest width [m]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+
+
+class FlowCoefficient(parametertools.Parameter):
+    """Flow coefficient [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+    INIT = 0.62
+
+
+class FlowExponent(parametertools.Parameter):
+    """Flow exponent [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+    INIT = 1.5
+
+
+class AllowedExchange(parametertools.Parameter):
+    """The highest water exchange allowed [m³/s]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+    INIT = 1.5

hydpy/models/exch/exch_factors.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=missing-docstring
+# pylint: enable=missing-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+
+
+class WaterLevel(sequencetools.MixinFixedShape, sequencetools.FactorSequence):
+    """Water level [m].
+
+    After each simulation step, the value of |WaterLevel| corresponds to the value
+    of the |LoggedWaterLevel| of the previous simulation step.
+    """
+
+    NDIM = 1
+    SHAPE = (2,)
+
+
+class DeltaWaterLevel(sequencetools.FactorSequence):
+    """Effective difference of the two water levels [m].
+
+    After each simulation step, the value of |DeltaWaterLevel| corresponds to the value
+    of the |LoggedWaterLevel| of the previous simulation step.
+    """
+
+    NDIM = 0

hydpy/models/exch/exch_fluxes.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=missing-docstring
+# pylint: enable=missing-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+
+
+class PotentialExchange(sequencetools.FluxSequence):
+    """The potential bidirectional water exchange [m³/s]."""
+
+    NDIM, NUMERIC = 0, False
+
+
+class ActualExchange(sequencetools.FluxSequence):
+    """The actual bidirectional water exchange [m³/s]."""
+
+    NDIM, NUMERIC = 0, False

hydpy/models/exch/exch_logs.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=missing-docstring
+# pylint: enable=missing-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+
+
+class LoggedWaterLevel(sequencetools.LogSequenceFixed):
+    """Logged water level [m]."""
+
+    NUMERIC = False
+    SHAPE = 2