HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/models/evap_ret_io.py

@@ -0,0 +1,74 @@
+# pylint: disable=line-too-long, unused-wildcard-import
+"""
+Use |evap_ret_io| as a submodel for handing externally available time series of
+reference evapotranspiration to main models like |lland_dd|.
+
+Integration test
+================
+
+.. how_to_understand_integration_tests::
+
+The only functionality of |evap_ret_io| besides reading input time series is to adjust
+the given values to multiple hydrological response units.  Hence, configuring and
+testing it does not require additional explanations:
+
+>>> from hydpy.models.evap_ret_io import *
+>>> parameterstep()
+>>> from hydpy import Element
+>>> element = Element("element")
+>>> element.model = model
+
+>>> from hydpy import IntegrationTest, pub
+>>> pub.timegrids = "2000-01-01", "2000-01-03", "1d"
+>>> nmbhru(2)
+>>> hruarea(0.2, 0.8)
+>>> evapotranspirationfactor(0.8, 1.2)
+
+>>> test = IntegrationTest(element)
+>>> test.dateformat = "%Y-%d-%m"
+
+>>> inputs.referenceevapotranspiration.series = 1.0, 2.0
+
+.. integration-test::
+
+    >>> test()
+    |       date | referenceevapotranspiration |      referenceevapotranspiration | meanreferenceevapotranspiration |
+    -----------------------------------------------------------------------------------------------------------------
+    | 2000-01-01 |                         1.0 | 0.8                          1.2 |                            1.12 |
+    | 2000-02-01 |                         2.0 | 1.6                          2.4 |                            2.24 |
+"""
+# import...
+# ...from HydPy
+from hydpy.core import modeltools
+from hydpy.exe.modelimports import *
+from hydpy.interfaces import petinterfaces
+from hydpy.models.evap import evap_model
+
+
+class Model(evap_model.Sub_ETModel, petinterfaces.PETModel_V1):
+    """|evap_ret_io.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(short="Evap-RET-IO", description="external data")
+    __HYDPY_ROOTMODEL__ = False
+
+    INLET_METHODS = ()
+    RECEIVER_METHODS = ()
+    RUN_METHODS = (
+        evap_model.Calc_ReferenceEvapotranspiration_V3,
+        evap_model.Adjust_ReferenceEvapotranspiration_V1,
+        evap_model.Calc_MeanReferenceEvapotranspiration_V1,
+    )
+    INTERFACE_METHODS = (
+        evap_model.Determine_PotentialEvapotranspiration_V1,
+        evap_model.Get_PotentialEvapotranspiration_V1,
+        evap_model.Get_MeanPotentialEvapotranspiration_V1,
+    )
+    ADD_METHODS = ()
+    OUTLET_METHODS = ()
+    SENDER_METHODS = ()
+    SUBMODELINTERFACES = ()
+    SUBMODELS = ()
+
+
+tester = Tester()
+cythonizer = Cythonizer()

hydpy/models/evap_ret_tw2002.py

@@ -0,0 +1,165 @@
+# pylint: disable=line-too-long, unused-wildcard-import
+"""The primary purpose of |evap_ret_tw2002| is to serve as a submodel that provides
+estimates of potential grass reference evapotranspiration following :cite:t:`ref-DVWK`,
+as demonstrated for |lland_dd|.  However, you can also use it as a stand-alone model,
+as it does not require interaction with a main model.  The following examples make use
+of this stand-alone functionality.
+
+|evap_ret_tw2002| requires two submodels.  One must follow the |RadiationModel_V1| or
+the |RadiationModel_V2| interface and provide global radiation data; the other must
+follow the |TempModel_V1| or the |TempModel_V2| interface and provide temperature data.
+
+Integration tests
+=================
+
+.. how_to_understand_integration_tests::
+
+Application model |evap_ret_tw2002| requires no input from an external model and does
+not supply any data to an outlet sequence.  Hence, assigning a model instance to a
+blank |Element| instance is sufficient:
+
+>>> from hydpy import Element
+>>> from hydpy.models.evap_ret_tw2002 import *
+>>> parameterstep()
+>>> element = Element("element")
+>>> element.model = model
+
+The implemented Turc-Wendling should be applied to daily data:
+
+>>> from hydpy import IntegrationTest, pub
+>>> pub.timegrids = "2000-07-06", "2000-07-07", "1d"
+
+We set the parameter and input values in agreement with the
+:ref:`evap_ret_fao56_hourly_simulation` example of |evap_ret_fao56|, which allows for
+comparison with the results of the FAO reference evapotranspiration model applied to
+data of station Uccle (Brussels, Belgium), as reported in example 18 of
+:cite:t:`ref-Allen1998`:
+
+>>> nmbhru(1)
+>>> hruarea(1.0)
+>>> evapotranspirationfactor(1.0)
+>>> hrualtitude(100.0)
+
+|evap_ret_fao56| has no counterpart for the |CoastFactor| parameter.  We set its value from
+our gut feeling to 0.9, as Brussels is not directly adjacent to the coastline (0.6) but
+also not that far away from it (1.0):
+
+>>> coastfactor(0.9)
+
+A |meteo_glob_io| and a |meteo_temp_io| submodel provide the required global radiation
+and temperature data:
+
+>>> with model.add_radiationmodel_v2("meteo_glob_io"):
+...     pass
+>>> with model.add_tempmodel_v2("meteo_temp_io"):
+...     temperatureaddend(1.0)
+
+Now, we can initialise an |IntegrationTest| object and set the required meteorological
+input:
+
+>>> test = IntegrationTest(element)
+>>> test.dateformat = "%Y-%d-%m"
+>>> model.tempmodel.sequences.inputs.temperature.series = 15.9
+>>> model.radiationmodel.sequences.inputs.globalradiation.series = 255.367464
+
+For the example at hand, there is an excellent agreement with the result calculated by
+|evap_ret_fao56| and given by :cite:t:`ref-Allen1998`, which is 3.75 mm/d:
+
+.. integration-test::
+
+    >>> test()
+    |       date | airtemperature | globalradiation | referenceevapotranspiration | meanreferenceevapotranspiration |
+    -----------------------------------------------------------------------------------------------------------------
+    | 2000-06-07 |           16.9 |      255.367464 |                    3.787245 |                        3.787245 |
+
+Instead of IO submodels, one could use the main model of |evap_ret_tw2002| for
+providing the temperature data or a "real" submodel that calculates the global
+radiation data.  The first option is not feasible here due to not using
+|evap_ret_tw2002| as a submodel but as a stand-alone model.  But we can demonstrate the
+latter option by using, for example, |meteo_glob_fao56|, which we also configure in
+agreement with the :ref:`evap_ret_fao56_hourly_simulation` example.  Hence,
+|meteo_glob_fao56| reproduces the global radiation above so that |evap_ret_tw2002|
+calculates the same potential evapotranspiration value:
+
+>>> with model.add_radiationmodel_v1("meteo_glob_fao56"):
+...     latitude(50.8)
+...     angstromconstant(0.25)
+...     angstromfactor(0.5)
+
+>>> test = IntegrationTest(element)
+>>> test.dateformat = "%Y-%d-%m"
+>>> model.tempmodel.sequences.inputs.temperature.series = 15.9
+>>> model.radiationmodel.sequences.inputs.sunshineduration.series = 9.25
+
+.. integration-test::
+
+    >>> test()
+    |       date | airtemperature | globalradiation | referenceevapotranspiration | meanreferenceevapotranspiration |
+    -----------------------------------------------------------------------------------------------------------------
+    | 2000-06-07 |           16.9 |      255.367464 |                    3.787245 |                        3.787245 |
+
+"""
+# import...
+# ...from HydPy
+from hydpy.core import modeltools
+from hydpy.exe.modelimports import *
+from hydpy.interfaces import petinterfaces
+from hydpy.interfaces import radiationinterfaces
+from hydpy.interfaces import tempinterfaces
+from hydpy.models.evap import evap_model
+
+
+class Model(
+    evap_model.Main_TempModel_V1,
+    evap_model.Main_TempModel_V2A,
+    evap_model.Main_RadiationModel_V1,
+    evap_model.Main_RadiationModel_V2,
+    evap_model.Sub_ETModel,
+    petinterfaces.PETModel_V1,
+):
+    """|evap_ret_tw2002.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="Evap-RET-TW2002",
+        description="Turc-Wendling reference evapotranspiration, 2002",
+    )
+    __HYDPY_ROOTMODEL__ = False
+
+    INLET_METHODS = ()
+    RECEIVER_METHODS = ()
+    RUN_METHODS = (
+        evap_model.Process_RadiationModel_V1,
+        evap_model.Calc_GlobalRadiation_V1,
+        evap_model.Calc_AirTemperature_V1,
+        evap_model.Calc_ReferenceEvapotranspiration_V2,
+        evap_model.Adjust_ReferenceEvapotranspiration_V1,
+        evap_model.Calc_MeanReferenceEvapotranspiration_V1,
+    )
+    INTERFACE_METHODS = (
+        evap_model.Determine_PotentialEvapotranspiration_V1,
+        evap_model.Get_PotentialEvapotranspiration_V1,
+        evap_model.Get_MeanPotentialEvapotranspiration_V1,
+    )
+    ADD_METHODS = (
+        evap_model.Calc_AirTemperature_TempModel_V1,
+        evap_model.Calc_AirTemperature_TempModel_V2,
+    )
+    OUTLET_METHODS = ()
+    SENDER_METHODS = ()
+    SUBMODELINTERFACES = (
+        tempinterfaces.TempModel_V1,
+        tempinterfaces.TempModel_V2,
+        radiationinterfaces.RadiationModel_V1,
+    )
+    SUBMODELS = ()
+
+    tempmodel = modeltools.SubmodelProperty(
+        tempinterfaces.TempModel_V1, tempinterfaces.TempModel_V2
+    )
+    radiationmodel = modeltools.SubmodelProperty(
+        radiationinterfaces.RadiationModel_V1, radiationinterfaces.RadiationModel_V2
+    )
+
+
+tester = Tester()
+cythonizer = Cythonizer()

hydpy/models/exch/__init__.py

@@ -0,0 +1,14 @@
+"""
+The |exch.DOCNAME.complete| 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()

hydpy/models/exch/exch_control.py

@@ -0,0 +1,262 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from site-packages
+import numpy
+
+# ...from HydPy
+import hydpy
+from hydpy.core import devicetools
+from hydpy.core import exceptiontools
+from hydpy.core import objecttools
+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
+
+
+class Delta(parametertools.MonthParameter):
+    """Monthly varying difference for increasing or decreasing the input [e.g. m³/s]."""
+
+    TYPE, TIME, SPAN = float, None, (None, None)
+    INIT = 0.0
+
+
+class Minimum(parametertools.Parameter):
+    """The allowed minimum value of the adjusted input [e.g. m³/s]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, float, None, (None, None)
+    INIT = 0.0
+
+
+class XPoints(parametertools.Parameter):
+    """Supporting points for the independent input variable [e.g. m³/s].
+
+    There must be at least two supporting points, and they must be strictly monotonous.
+    If not, |XPoints| raises the following errors:
+
+    >>> from hydpy.models.exch_branch_hbv96 import *
+    >>> parameterstep()
+    >>> xpoints(1.0, 2.0)
+    >>> xpoints
+    xpoints(1.0, 2.0)
+
+    >>> xpoints(1.0)
+    Traceback (most recent call last):
+    ...
+    ValueError: Branching via linear interpolation requires at least two supporting \
+points, but parameter `xpoints` of element `?` received 1 value(s).
+
+    >>> xpoints(1.0, 2.0, 2.0, 3.0)
+    Traceback (most recent call last):
+    ...
+    ValueError: The values of parameter `xpoints` of element `?` must be arranged \
+strictly monotonously, which is not the case for the given values `1.0, 2.0, 2.0, and \
+3.0`.
+    """
+
+    NDIM, TYPE, TIME, SPAN = 1, float, None, (None, None)
+
+    def __call__(self, *args, **kwargs) -> None:
+        self._set_shape(len(args))
+        if (shape := self._get_shape()[0]) < 2:
+            raise ValueError(
+                f"Branching via linear interpolation requires at least two supporting "
+                f"points, but parameter {objecttools.elementphrase(self)} received "
+                f"{shape} value(s)."
+            )
+        super().__call__(*args, **kwargs)
+        if min(numpy.diff(self._get_value())) <= 0.0:
+            raise ValueError(
+                f"The values of parameter {objecttools.elementphrase(self)} must be "
+                f"arranged strictly monotonously, which is not the case for the given "
+                f"values `{objecttools.enumeration(self._get_value())}`."
+            )
+
+
+class YPoints(parametertools.Parameter):
+    """Supporting points for the dependent output variables [e.g. m³/s].
+
+    Preparing parameter |YPoints| requires consistency with parameter |XPoints| and the
+    currently available |Node| objects.
+
+    .. testsetup::
+
+        >>> from hydpy import reverse_model_wildcard_import
+        >>> reverse_model_wildcard_import()
+
+    >>> from hydpy.models.exch_branch_hbv96 import *
+    >>> parameterstep("1d")
+    >>> ypoints
+    ypoints(?)
+
+    You need to prepare parameter |XPoints| first:
+
+    >>> ypoints(1.0, 2.0)
+    Traceback (most recent call last):
+    ...
+    RuntimeError: The shape of parameter `ypoints` of element `?` depends on the \
+shape of parameter `xpoints`, which is not defined so far.
+
+    >>> xpoints(1.0, 2.0, 3.0)
+
+    Supply the names of the output |Node| objects as keyword arguments:
+
+    >>> ypoints(1.0, 2.0)
+    Traceback (most recent call last):
+    ...
+    ValueError: For parameter `ypoints` of element `?`, no branches are defined.  Do \
+this via keyword arguments, as explained in the documentation.
+
+    The number of x and y supporting points must be identical for all branches.:
+
+    >>> ypoints(branch1=[1.0, 2.0],
+    ...         branch2=[2.0, 4.0])
+    Traceback (most recent call last):
+    ...
+    ValueError: Each branch requires the same number of supporting points as given \
+for parameter `xpoints`, which is 3, but for branch `branch1` of parameter `ypoints` \
+of element `?`, 2 values are provided.
+
+    >>> xpoints(1.0, 2.0)
+
+    When working on an actual project (indicated by a predefined project name), each
+    branch name must correspond to a |Node| name:
+
+    >>> from hydpy import pub, Nodes
+    >>> pub.projectname = "test"
+    >>> nodes = Nodes("branch1")
+    >>> ypoints(branch1=[1.0, 2.0],
+    ...         branch2=[2.0, 4.0])
+    Traceback (most recent call last):
+    ...
+    RuntimeError: Parameter `ypoints` of element `?` is supposed to branch to node \
+`branch2`, but such a node is not available.
+
+    We use the following general exception message for some unexpected errors:
+
+    >>> nodes = Nodes("branch1", "branch2")
+    >>> ypoints(branch1=[1.0, 2.0],
+    ...         branch2="xy")
+    Traceback (most recent call last):
+    ...
+    ValueError: While trying to set the values for branch `branch2` of parameter \
+`ypoints` of element `?`, the following error occurred: could not convert string to \
+float: 'xy'
+
+    Changing the number of branches during runtime might result in erroneous
+    connections to the |Node| objects:
+
+    >>> ypoints(branch1=[1.0, 2.0],
+    ...         branch2=[2.0, 4.0])
+    >>> ypoints
+    ypoints(branch1=[1.0, 2.0],
+            branch2=[2.0, 4.0])
+    >>> ypoints(branch1=[1.0, 2.0])
+    Traceback (most recent call last):
+    ...
+    RuntimeError: The number of branches of the exch model should not be changed \
+during run time.  If you really need to do this, first initialise a new "branched" \
+sequence and connect it to the respective outlet nodes properly.
+    """
+
+    NDIM, TYPE, TIME, SPAN = 2, float, None, (None, None)
+
+    def __call__(self, *args, **kwargs) -> None:
+        try:
+            shape = (len(kwargs), self.subpars.xpoints.shape[0])
+        except exceptiontools.AttributeNotReady:
+            raise RuntimeError(
+                f"The shape of parameter {objecttools.elementphrase(self)} depends on "
+                f"the shape of parameter `xpoints`, which is not defined so far."
+            ) from None
+        if shape[0] == 0:
+            raise ValueError(
+                f"For parameter {objecttools.elementphrase(self)}, no branches are "
+                f"defined.  Do this via keyword arguments, as explained in the "
+                f"documentation."
+            )
+        branched = self.subpars.pars.model.sequences.outlets.branched
+        if (branched.shape[0] != 0) and (branched.shape[0] != shape[0]):
+            raise RuntimeError(
+                "The number of branches of the exch model should not be changed "
+                "during run time.  If you really need to do this, first initialise a "
+                'new "branched" sequence and connect it to the respective outlet '
+                "nodes properly."
+            )
+        self.shape = shape
+        self.values = numpy.nan
+        for idx, (key, value) in enumerate(sorted(kwargs.items())):
+            if key not in devicetools.Node.query_all():
+                if exceptiontools.attrready(hydpy.pub, "projectname"):
+                    raise RuntimeError(
+                        f"Parameter {objecttools.elementphrase(self)} is supposed to "
+                        f"branch to node `{key}`, but such a node is not available."
+                    )
+            try:
+                self.values[idx] = value  # type: ignore[index]
+            except BaseException:
+                if shape[1] != len(value):
+                    raise ValueError(
+                        f"Each branch requires the same number of supporting points "
+                        f"as given for parameter `xpoints`, which is {shape[1]}, but "
+                        f"for branch `{key}` of parameter "
+                        f"{objecttools.elementphrase(self)}, {len(value)} values are "
+                        f"provided."
+                    ) from None
+                objecttools.augment_excmessage(
+                    f"While trying to set the values for branch `{key}` of parameter "
+                    f"{objecttools.elementphrase(self)}"
+                )
+        if branched.shape == (0,):
+            branched.shape = shape[0]
+        self.subpars.pars.model.sequences.fluxes.outputs.shape = shape[0]
+        self.subpars.pars.model.nodenames.clear()
+        for idx, key in enumerate(sorted(kwargs.keys())):
+            setattr(self, key, self.values[idx])  # type: ignore[index]
+            self.subpars.pars.model.nodenames.append(key)
+
+    def __repr__(self) -> str:
+        try:
+            names = self.subpars.pars.model.nodenames
+            lines = []
+            for idx, (name, values) in enumerate(zip(names, self._get_value())):
+                line = f"{name}={objecttools.repr_list(values)},"
+                if not idx:
+                    lines.append(f"ypoints({line}")
+                else:
+                    lines.append(f"        {line}")
+            lines[-1] = f"{lines[-1][:-1]})"
+            return "\n".join(lines)
+        except BaseException:
+            return "ypoints(?)"

hydpy/models/exch/exch_derived.py

@@ -0,0 +1,36 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import parametertools
+from hydpy.models.exch import exch_control
+
+
+class MOY(parametertools.MOYParameter):
+    """References the "global" month of the year index array [-]."""
+
+
+class NmbBranches(parametertools.Parameter):
+    """The number of branches [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, int, None, (1, None)
+
+    CONTROLPARAMETERS = (exch_control.YPoints,)
+
+    def update(self):
+        """Determine the number of branches."""
+        con = self.subpars.pars.control
+        self(con.ypoints.shape[0])
+
+
+class NmbPoints(parametertools.Parameter):
+    """The number of supporting points for linear interpolation [-]."""
+
+    NDIM, TYPE, TIME, SPAN = 0, int, None, (2, None)
+
+    CONTROLPARAMETERS = (exch_control.YPoints,)
+
+    def update(self):
+        """Determine the number of points."""
+        con = self.subpars.pars.control
+        self(con.ypoints.shape[1])

hydpy/models/exch/exch_factors.py

@@ -0,0 +1,26 @@
+# pylint: disable=missing-module-docstring
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+from hydpy.core import variabletools
+
+
+class WaterLevels(variabletools.MixinFixedShape, sequencetools.FactorSequence):
+    """The water level at two locations [m].
+
+    After each simulation step, the value of |exch_factors.WaterLevels| corresponds to
+    the value of the |LoggedWaterLevels| 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 |LoggedWaterLevels| of the previous simulation step.
+    """
+
+    NDIM = 0

hydpy/models/exch/exch_fluxes.py

@@ -0,0 +1,48 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import objecttools
+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
+
+
+class OriginalInput(sequencetools.FluxSequence):
+    """Unadjusted total input [e.g. m³/s]."""
+
+    NDIM, NUMERIC = 0, False
+
+
+class AdjustedInput(sequencetools.FluxSequence):
+    """Adjusted total input [e.g. m³/s]."""
+
+    NDIM, NUMERIC = 0, False
+
+
+class Outputs(sequencetools.FluxSequence):
+    """Branched outputs [e.g. m³/s]."""
+
+    NDIM, NUMERIC = 1, False
+
+    def __repr__(self) -> str:
+        names = self.subseqs.seqs.model.nodenames
+        lines = []
+        for idx, (name, values) in enumerate(zip(names, self.values)):
+            line = f"{name}={objecttools.repr_(values)},"
+            if not idx:
+                lines.append(f"outputs({line}")
+            else:
+                lines.append(f"        {line}")
+        lines[-1] = f"{lines[-1][:-1]})"
+        return "\n".join(lines)

hydpy/models/exch/exch_inlets.py

@@ -0,0 +1,11 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+
+
+class Total(sequencetools.InletSequence):
+    """Total input [e.g. m³/s]."""
+
+    NDIM, NUMERIC = 1, False

hydpy/models/exch/exch_logs.py

@@ -0,0 +1,12 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+
+
+class LoggedWaterLevels(sequencetools.LogSequenceFixed):
+    """Logged water levels [m]."""
+
+    NUMERIC = False
+    SHAPE = 2