Add precipitation and evaporation to the water balance of all dam a…

…pplication models.

This commit addresses issues #51 and #69.

This commit also fixes many typos in the related modules. Module `dam_model` still needs proofreading.

hydpy/core/sequencetools.py

@@ -1197,9 +1197,11 @@ def numericsequences(self) -> Iterator["FluxSequence"]:
         >>> from hydpy import prepare_model
         >>> model = prepare_model("dam_v001")
         >>> len(model.sequences.fluxes)
-        11
+        13
         >>> for seq in model.sequences.fluxes.numericsequences:
         ...     print(seq)
+        adjustedprecipitation(nan)
+        actualevaporation(nan)
         inflow(nan)
         actualrelease(nan)
         flooddischarge(nan)

hydpy/docs/rst/HydPy-D.rst

@@ -8,29 +8,27 @@
 HydPy-D (DAM)
 =============
 
-The HydPy-D model family implements dams and similar natural and
-anthropogenic flow barriers.
-
-At the current state of development, all its application models rely
-on an adaptive explicit Runge-Kutta method. This integration method
-allows for performing simulations with adjustable numerical precision.
-However, it works best for continuous differential equations. Hence,
-most process equations of base model |dam| are either continuous by nature
-or are "regularisable", meaning one can smooth their discontinuities by
-a degree one considers useful.
-
-Each application model provides a different combination of control
-capabilities.. Many take "remote locations" into account, for example,
-to release additional water to the downstream river channel to increase
-water stages at remote gauges.
-
-All application models are tested and ready for use.  However, please note
-that some improvements in style and structure (e.g. changes in some
-variable names) might be necessary for the future. At the moment, it is a
-little hard to pick the correct application model.  We will have to find
-a way to prevent selecting the right model becoming too hard when the
-set of application models grows.  For the moment, the following overview
-over the first five application models might be helpful:
+The HydPy-D model family implements dams and similar natural and anthropogenic
+flow barriers.
+
+At the current state of development, all its application models rely on an
+adaptive explicit Runge-Kutta method. This integration method allows for
+performing simulations with adjustable numerical precision. However, it works
+best for continuous differential equations. Hence, most process equations of
+base model |dam| are either continuous by nature or "regularisable", meaning
+one can smooth their discontinuities by a degree one considers useful.
+
+Each application model provides a different combination of control capabilities.
+Many take "remote locations" into account, for example, to release additional
+water to the downstream river channel to increase water stages at remote gauges.
+
+All application models are tested and ready for use.  However, please note that
+some improvements in style and structure (e.g. changes in some variable names)
+might be necessary for the future. At the moment, it is a little hard to pick
+the correct application model.  We will have to find a way to prevent selecting
+a suitable model from becoming too hard when the collection of application
+models grows.  For the moment, the following overview over the first five
+application models might be helpful:
 
 ================================================================= ==== ==== ==== ==== ====
 Does the dam model…                                               v001 v002 v003 v004 v005
@@ -48,18 +46,18 @@ Does the dam model…                                               v001 v002 v0
 …allow for discharge from a remote location for flood protection? no   no   no   no   yes
 ================================================================= ==== ==== ==== ==== ====
 
-These five application models are independent implementations, developed
-for the forecasting system of the German federal state of Saxony and run
-by the `Landeshochwasserzentrum (LHWZ)`_.  More recently, we added the
-application models |dam_v006|, |dam_v007|, and |dam_v008| on behalf of
-the `German Federal Institute of Hydrology (BfG)`_.  Conceptionally, these
-*HydPy* models correspond the `LARSIM`_ models "SEEG" (controlled lake),
-"RUEC" (retention basin) and "TALS" (reservoir).
-
-|dam_v001| has been the starting point for the development of the
-other application models. Hence its documentation is very comprehensive,
-and it seems to be a good starting point to become acquainted with any
-of the application models prepared so far.
+These five application models are independent implementations, developed for
+the forecasting system of the German federal state of Saxony and run by the
+`Landeshochwasserzentrum (LHWZ)`_.  More recently, we added the application
+models |dam_v006|, |dam_v007|, and |dam_v008| on behalf of the `German Federal
+Institute of Hydrology (BfG)`_.  Conceptionally, these *HydPy* models
+correspond to the `LARSIM`_ models "SEEG" (controlled lake), "RUEC" (retention
+basin) and "TALS" (reservoir).
+
+|dam_v001| has been the starting point for the development of the other
+application models. Hence its documentation is very comprehensive, and it seems
+to be a good starting point to become acquainted with any of the application
+models prepared so far.
 
 Base model:
 

hydpy/models/dam/dam_aides.py

@@ -14,13 +14,12 @@ class WaterLevel(sequencetools.AideSequence):
 
 
 class SurfaceArea(sequencetools.AideSequence):
-    """Surface area [million m²]."""
+    """Surface area [km²]."""
 
     NDIM, NUMERIC, SPAN = 0, True, (None, None)
 
 
 class AllowedDischarge(sequencetools.AideSequence):
-    """Discharge threshold that should not be overcut by the actual discharge
-    [m³/s]."""
+    """Discharge threshold not to be overcut by the actual discharge [m³/s]."""
 
     NDIM, NUMERIC, SPAN = 0, True, (None, None)

hydpy/models/dam/dam_control.py

@@ -8,6 +8,12 @@
 from hydpy.auxs import anntools
 
 
+class SurfaceArea(parametertools.Parameter):
+    """Average size of the water surface [km²]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+
+
 class CatchmentArea(parametertools.Parameter):
     """Size of the catchment draining into the dam [km²]."""
 
@@ -28,6 +34,7 @@ class NmbLogEntries(parametertools.Parameter):
     ...     print(seq)
     loggedtotalremotedischarge(nan, nan, nan)
     loggedoutflow(nan, nan, nan)
+    loggedadjustedevaporation(nan)
     loggedrequiredremoterelease(nan)
     loggedallowedremoterelieve(nan)
     """
@@ -43,9 +50,27 @@ def __call__(self, *args, **kwargs):
                 pass
 
 
+class CorrectionPrecipitation(parametertools.Parameter):
+    """Precipitation correction factor [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+
+
+class CorrectionEvaporation(parametertools.Parameter):
+    """Evaporation correction factor [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
+
+
+class WeightEvaporation(parametertools.Parameter):
+    """Time weighting factor for evaporation [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, True, (0.0, 1.0)
+
+
 class RemoteDischargeMinimum(parametertools.SeasonalParameter):
-    """Discharge threshold of a cross section far downstream that
-    should not be undercut by the actual discharge [m³/s]."""
+    """Discharge threshold of a cross-section far downstream not to be undercut by the
+    actual discharge [m³/s]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (0.0, None)
 
@@ -55,29 +80,29 @@ def __call__(self, *args, **kwargs):
 
 
 class RemoteDischargeSafety(parametertools.SeasonalParameter):
-    """Safety factor to reduce the risk to release not enough water [m³/s]."""
+    """Safety factor for reducing the risk to release not enough water [m³/s]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (0.0, None)
 
 
-class WaterLevel2PossibleRemoteRelieve(anntools.ANN):
-    """Artificial neural network describing the relationship between
-    water level and the highest possible water release used to relieve
-    the dam during high flow conditions [-]."""
+class WaterLevel2PossibleRemoteRelief(anntools.ANN):
+    """Artificial neural network describing the relationship between water level and
+    the highest possible water release used to relieve the dam during high flow
+    conditions [-]."""
 
     XLABEL = "water level [m]"
     YLABEL = "possible remote relieve [m³/s]"
 
 
-class RemoteRelieveTolerance(parametertools.Parameter):
-    """A tolerance value for the "possible remote relieve" [m³/s]."""
+class RemoteReliefTolerance(parametertools.Parameter):
+    """A tolerance value for |PossibleRemoteRelief| [m³/s]."""
 
     NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
 
 
 class NearDischargeMinimumThreshold(parametertools.SeasonalParameter):
-    """Discharge threshold of a cross section in the near of the dam that
-    not be undercut by the actual discharge [m³/s]."""
+    """Discharge threshold of a cross-section near the dam not to be undercut by the
+    actual discharge [m³/s]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (0.0, None)
 
@@ -104,44 +129,58 @@ class WaterVolumeMinimumThreshold(parametertools.SeasonalParameter):
 class WaterLevelMinimumThreshold(parametertools.Parameter):
     """The minimum operating water level of the dam [m]."""
 
-    NDIM, TYPE, TIME, SPAN = 0, float, None, (0, None)
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (None, None)
 
 
 class WaterLevelMinimumTolerance(parametertools.Parameter):
-    """A tolarance value for the minimum operating water level [m]."""
+    """A tolerance value for the minimum operating water level [m]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0, None)
+
+
+class ThresholdEvaporation(parametertools.Parameter):
+    """The water level at which actual evaporation is 50 % of potential evaporation
+    [m]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (0, None)
+
+
+class ToleranceEvaporation(parametertools.Parameter):
+    """A tolerance value defining the steepness of the transition of actual evaporation
+    between zero and potential evaporation [m]."""
 
     NDIM, TYPE, TIME, SPAN = 0, float, None, (0, None)
 
 
 class WaterLevelMinimumRemoteThreshold(parametertools.Parameter):
-    """The minimum operating water level of the dam regarding remote
-    water supply [m]."""
+    """The minimum operating water level of the dam regarding remote water supply
+    [m]."""
 
     NDIM, TYPE, TIME, SPAN = 0, float, None, (0, None)
 
 
 class WaterLevelMinimumRemoteTolerance(parametertools.Parameter):
-    """A tolarance value for the minimum operating water level regarding
-    remote water supply [m]."""
+    """A tolerance value for the minimum operating water level regarding remote water
+    supply [m]."""
 
     NDIM, TYPE, TIME, SPAN = 0, float, None, (0, None)
 
 
-class HighestRemoteRelieve(parametertools.SeasonalParameter):
-    """The highest possible relieve discharge from another location [m³/s]."""
+class HighestRemoteRelief(parametertools.SeasonalParameter):
+    """The highest possible relief discharge from another location [m³/s]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (None, None)
 
 
-class WaterLevelRelieveThreshold(parametertools.SeasonalParameter):
-    """The threshold water level of the dam regarding the allowed
-    relieve discharge from another location [m]."""
+class WaterLevelReliefThreshold(parametertools.SeasonalParameter):
+    """The threshold water level of the dam regarding the allowed relief discharge from
+    another location [m]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (None, None)
 
 
-class WaterLevelRelieveTolerance(parametertools.SeasonalParameter):
-    """A tolerance value for parameter |WaterLevelRelieveThreshold| [m]."""
+class WaterLevelReliefTolerance(parametertools.SeasonalParameter):
+    """A tolerance value for parameter |WaterLevelReliefThreshold| [m]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (None, None)
 
@@ -153,8 +192,8 @@ class HighestRemoteSupply(parametertools.SeasonalParameter):
 
 
 class WaterLevelSupplyThreshold(parametertools.SeasonalParameter):
-    """The threshold water level of the dam regarding the requried
-    supply discharge from another location [m]."""
+    """The threshold water level of the dam regarding the required supply discharge
+    from another location [m]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (None, None)
 
@@ -178,16 +217,16 @@ class HighestRemoteTolerance(parametertools.Parameter):
 
 
 class WaterVolume2WaterLevel(anntools.ANN):
-    """Artificial neural network describing the relationship between
-    water level and water volume [-]."""
+    """Artificial neural network describing the relationship between water level and
+    water volume [-]."""
 
     XLABEL = "water volume [million m³]"
     YLABEL = "water level [m]"
 
 
 class WaterLevel2FloodDischarge(anntools.SeasonalANN):
-    """Artificial neural network describing the relationship between
-    flood discharge and water volume [-]."""
+    """Artificial neural network describing the relationship between flood discharge
+    and water volume [-]."""
 
     XLABEL = "water level [m]"
     YLABEL = "flood discharge [m³/s]"
@@ -200,8 +239,7 @@ class AllowedWaterLevelDrop(parametertools.Parameter):
 
 
 class AllowedDischargeTolerance(parametertools.Parameter):
-    """Smoothing parameter eventually associated with |AllowedWaterLevelDrop|
-    [m³/s]."""
+    """Smoothing parameter eventually associated with |AllowedWaterLevelDrop| [m³/s]."""
 
     NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)
 
@@ -213,8 +251,8 @@ class AllowedRelease(parametertools.SeasonalParameter):
 
 
 class TargetVolume(parametertools.SeasonalParameter):
-    """The desired volume of water to be stored within the dam at specific
-    times of the year [Mio. m³]."""
+    """The desired volume of water required within the dam at specific times of the
+    year [Mio. m³]."""
 
     NDIM, TYPE, TIME, SPAN = 1, float, None, (0.0, None)
 
@@ -227,8 +265,7 @@ class TargetRangeAbsolute(parametertools.Parameter):
 
 
 class TargetRangeRelative(parametertools.Parameter):
-    """The relative interpolation range related to parameter |TargetVolume|
-    [-]."""
+    """The relative interpolation range related to parameter |TargetVolume| [-]."""
 
     NDIM, TYPE, TIME, SPAN = 0, float, None, (0.0, None)