HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/auxs/quadtools.py

@@ -0,0 +1,61 @@
+"""This module specialises class |Submodel| for quadrature problems.
+
+Module |quadtools| provides Python interfaces only.  See the Cython extension module
+`quadutils` for the actual implementations of the mathematical algorithms.
+"""
+
+# import...
+
+# ...from HydPy
+from hydpy.core import modeltools
+from hydpy.core.typingtools import *
+
+if TYPE_CHECKING:
+    from hydpy.cythons import quadutils
+else:
+    from hydpy.cythons.autogen import quadutils
+
+
+class Quad(modeltools.Submodel):
+    """Numerical solver for quadrature problems based on the Gauss-Lobatto
+    quadrature."""
+
+    CYTHONBASECLASS = quadutils.QuadBase
+    PYTHONCLASS = quadutils.QuadPython
+    _cysubmodel: quadutils.QuadBase
+
+    # positional arguments required for consistency with the cythonized extension class:
+    def integrate(  # pylint: disable=too-many-positional-arguments
+        self, x0: float, x1: float, nmin: int, nmax: int, tol: float, /
+    ) -> float:
+        """Repeatedly integrate the target function within the interval
+        :math:`x0 \\leq x \\leq x1` until the estimated accuracy is smaller than
+        `tol` using at least `xmin` and at most `xmax` number of nodes.
+
+        The algorithm underlying |Quad| works acceptable, but should be improvable
+        both regarding accuracy and efficiency.  We postpone this and provide
+        example calculations afterwards.  Please see the documentation on method
+        |wland_model.Calc_DVEq_V1| to see |Quad| in action until then.
+        """
+        return self._cysubmodel.integrate(x0, x1, nmin, nmax, tol)
+
+    def apply_method0(self, value: float, /) -> float:
+        """Apply the model method to be integrated.
+
+        For example, submodel |wland_model.QuadDVEq_V1| integrates method
+        |wland_model.Return_DVH_V1|:
+
+        >>> from hydpy.models.wland import *
+        >>> parameterstep()
+        >>> thetas(0.4)
+        >>> psiae(300.0)
+        >>> b(5.0)
+        >>> sh(0.0)
+        >>> derived.rh1.update()
+        >>> from hydpy import round_
+        >>> round_(model.return_dvh_v1(600.0))
+        0.05178
+        >>> round_(model.quaddveq_v1.apply_method0(600.0))
+        0.05178
+        """
+        return self._cysubmodel.apply_method0(value)

hydpy/auxs/roottools.py

@@ -0,0 +1,228 @@
+"""This module specialises class |Submodel| for root-finding problems.
+
+Module |roottools| provides Python interfaces only.  See the
+Cython extension module `rootutils` for the actual implementations
+of the mathematical algorithms.
+"""
+
+# import...
+
+# ...from HydPy
+from hydpy.core import modeltools
+from hydpy.core.typingtools import *
+
+if TYPE_CHECKING:
+    from hydpy.cythons import rootutils
+else:
+    from hydpy.cythons.autogen import rootutils
+
+
+class Pegasus(modeltools.Submodel):
+    """Root-finder based on the `Pegasus method`_.
+
+    .. _`Pegasus method`: https://link.springer.com/article/10.1007/BF01932959
+
+    The Pegasus method is a root-finding algorithm which sequentially
+    decreases its search radius (like the simple bisection algorithm)
+    and shows superlinear convergence properties (like the Newton-Raphson
+    algorithm).  Our implementation adds a simple "interval widening"
+    strategy that comes into play when the given initial interval does not
+    contain the root.  This widening should be left for emergencies as
+    it might be not always efficient.  So please try to provide to
+    initial interval estimates that rather overestimate than underestimate
+    the interval width.  Additionally, make sure you apply |Pegasus| on
+    monotone functions only.
+    """
+
+    CYTHONBASECLASS = rootutils.PegasusBase
+    PYTHONCLASS = rootutils.PegasusPython
+    _cysubmodel: rootutils.PegasusBase
+
+    # positional arguments required for consistency with the cythonized extension class:
+    def find_x(  # pylint: disable=too-many-positional-arguments
+        self,
+        x0: float,
+        x1: float,
+        xmin: float,
+        xmax: float,
+        xtol: float,
+        ytol: float,
+        itermax: int,
+        /,
+    ) -> float:
+        """Find the relevant root within the interval
+        :math:`x0 \\leq x \\leq x1` with an accuracy meeting at least
+        one of the absolute tolerance values `xtol` and `ytol` (or the
+        accuracy achieved by performing the maximum number of iteration
+        steps, defined by argument `itermax`).
+
+        The arguments `xmin` and `xmax` define the smallest and largest
+        allowed `x` value, respectively.  Method |Pegasus.find_x| never
+        evaluates the underlying function for any `x` value outside these
+        bounds, even if its "interval widening" strategy suggests so.
+        Instead, it returns the relevant `xmin` or `xmax` value.
+
+        In the following, we explain the details of our Pegasus implementation
+        by using method |lland_model.Return_TempSSurface_V1|.
+
+        Method |lland_model.Return_TempSSurface_V1| (used by application model
+        |lland_knauf|) implements the Pegasus iteration to determine the surface
+        temperature of the snow layer with the help of the Pegasus subclass
+        |lland_model.PegasusTempSSurface|.  For the correct surface
+        temperature, the net energy gain of the surface (defined by method
+        |lland_model.Return_EnergyGainSnowSurface_V1|) must be zero.
+        Iteration is necessary, as some terms of the net energy gain (for
+        example, the emitted longwave radiation) depend on the surface
+        temperature in a non-linear manner.
+
+        As a starting point, we use the setting provided by the documentation
+        on method |lland_model.Return_TempSSurface_V1| but work in pure Python
+        mode for flexibility (more specifically, to have direct access to
+        method `find_x`) and focus on a single hydrological response unit
+        for simplicity:
+
+        >>> from hydpy import pub
+        >>> with pub.options.usecython(False):
+        ...     from hydpy.models.lland import *
+        ...     simulationstep("1d")
+        ...     parameterstep("1d")
+        >>> nhru(1)
+        >>> lnk(ACKER)
+        >>> turb0(2.0)
+        >>> turb1(2.0)
+        >>> ktschnee(5.0)
+        >>> inputs.relativehumidity = 60.0
+        >>> states.waes.values = 1.0
+        >>> fluxes.tkor = -3.0
+        >>> fluxes.reducedwindspeed2m = 3.0
+        >>> fluxes.actualvapourpressure = 2.9
+        >>> fluxes.netshortwaveradiationsnow = 10.0
+        >>> aides.temps = -2.0
+        >>> aides.rlatm = 200.0
+
+        Method |lland_model.Return_TempSSurface_V1| finds the following
+        surface temperature value:
+
+        >>> model.idx_hru = 0
+        >>> from hydpy import round_
+        >>> round_(model.return_tempssurface_v1(0))
+        -8.307868
+
+        We confirm that the net energy gain corresponding to this surface
+        temperature is approximately zero to validate this result:
+
+        >>> round_(model.return_energygainsnowsurface_v1(-8.3078682))
+        0.0
+
+        Method `apply_method0` always calls the appropriate target
+        method, which is, for |lland_model.PegasusTempSSurface|,
+        method |lland_model.Return_EnergyGainSnowSurface_V1|:
+
+        >>> round_(model.pegasustempssurface.apply_method0(-8.3078682))
+        0.0
+
+        To check for some exceptional cases, we call the `find_x` method of
+        class |lland_model.PegasusTempSSurface| directly.  First, we pass
+        the same arguments as in method |lland_model.Return_TempSSurface_V1|
+        and thus get the same result:
+
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, 5.0, -100.0, 100.0, 0.0, 1e-8, 10))
+        -8.307868
+
+        Through decreasing the maximum number of iterations, the result
+        becomes less accurate:
+
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, 5.0, -100.0, 100.0, 0.0, 1e-8, 3))
+        -8.312628
+        >>> round_(model.return_energygainsnowsurface_v1(-8.312628))
+        0.09905
+
+        Use the `ytol` argument to control the achieved accuracy more
+        explicitly:
+
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, 5.0, -100.0, 100.0, 0.0, 0.1, 10))
+        -8.312628
+        >>> round_(model.return_energygainsnowsurface_v1(-8.312628))
+        0.09905
+
+        Pass an `xtol` value larger than zero to stop iteration as soon as
+        the search interval is small enough:
+
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, 5.0, -100.0, 100.0, 0.1, 1e-8, 10))
+        -8.30786
+        >>> round_(model.return_energygainsnowsurface_v1(-8.30786))
+        -0.000171
+
+        `x0` does not need to be smaller than `x1`, and `xmin` does not need to be
+        smaller than `xmax` by necessity (the algorithm swaps values when necessary):
+
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     50.0, -50.0, 100.0, -100.0, 0.0, 1e-8, 10))
+        -8.307868
+
+        An ill-defined initial interval might decrease efficiency but
+        should usually not affect the result:
+
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     0.0, 5.0, -100.0, 100.0, 0.0, 1e-8, 10))
+        -8.307868
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, -20.0, -100.0, 100.0, 0.0, 1e-8, 10))
+        -8.307868
+
+        Defining proper values for arguments `xmin` and `xmax` provides a way to
+        prevent possible program crashes.  As an example, we do not care about
+        physics and set the snow layer's temperature to -300 °C.  Theoretically,
+        the surface temperature must also be (unrealistically) low to prevent a
+        considerable energy gain of the surface due to an extreme temperature
+        gradient within the snow layer. However, -100 °C is the lowest value allowed,
+        so method |lland_model.PegasusTempSSurface| returns this boundary-value.
+        It is up to the model developer to handle such misleading responses
+        (if possible):
+
+        >>> aides.temps = -400
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, 5.0, -100.0, 100.0, 0.0, 1e-8, 10))
+        -100.0
+        >>> round_(model.return_energygainsnowsurface_v1(-100.0))
+        -524.133374
+
+        To demonstrate the upper boundary's functionality, we set the snow layer
+        temperature to 4'000 °C (also not the most plausible value, of course):
+
+        >>> aides.temps = 4000.0
+        >>> round_(model.pegasustempssurface.find_x(
+        ...     -50.0, 5.0, -100.0, 100.0, 0.0, 1e-8, 10))
+        100.0
+        >>> round_(model.return_energygainsnowsurface_v1(100.0))
+        3561.059134
+
+        Finally, we evaluate some additional snow layer temperatures
+        to show that everything works consistently:
+
+        >>> from hydpy import print_vector
+        >>> for temps in [-500, -400, -300, -4, -2, 2, 2000, 3000, 4000]:
+        ...    aides.temps = temps
+        ...    tempssurface = model.pegasustempssurface.find_x(
+        ...        -50.0, 5.0, -100.0, 100.0, 0.0, 1e-8, 10)
+        ...    energygain = model.return_energygainsnowsurface_v1(tempssurface)
+        ...    print_vector([temps, tempssurface, energygain])
+        -500, -100.0, -1024.133374
+        -400, -100.0, -524.133374
+        -300, -100.0, -24.133374
+        -4, -8.790047, 0.0
+        -2, -8.307868, 0.0
+        2, -7.353441, 0.0
+        2000, 85.175508, 0.0
+        3000, 97.204856, 0.0
+        4000, 100.0, 3561.059134
+        """
+        return self._cysubmodel.find_x(x0, x1, xmin, xmax, xtol, ytol, itermax)
+
+    def apply_method0(self, value: float) -> float:
+        """Apply the model method relevant for root-finding."""
+        return self._cysubmodel.apply_method0(value)

hydpy/auxs/smoothtools.py

@@ -0,0 +1,273 @@
+"""This module implements features which help to regularize discontinuous
+process equations.
+
+.. _Tyralla (2016): http://www.hydrology.ruhr-uni-bochum.de/hydrolgy/mam/\
+download/schriftenreihe_29.pdf
+
+Many hydrological models rely heavily on discontinuous equations describing
+hydrological processes.  The related "if-else" blocks are often not
+theoretically motivated.  Instead, they are thought to ease implementing
+ad hoc solutions of different (parts of) process equations without taking
+care of the entire set of process equations.
+
+There are some reasons to ground new model concepts on mainly continuous
+process descriptions. See e. g. `Tyralla (2016)`_ for more a more exhaustive
+discussion of this topic.  Nevertheless, one might often want -- at least as
+a starting point -- to pick single discontinuous but well-established
+equations of old model concepts for a new model concept.  The tools
+provided by this module can be used to regularize the discontinuities of
+such equations.  More concrete, the tools are thought for replacing
+discontinuous process equations by continuous approximations.
+
+Some of the implemented features are to be applied during model simulations
+or are in some other way performance-critical, which is why we implement
+them computationally efficient by using Cython (see the extension module
+|smoothutils|.
+"""
+
+# import...
+# ...from standard-library
+import os
+
+# ...from site-packages
+# from scipy but not optional due to using interp1d during module initialisation:
+from scipy import interpolate
+import numpy
+
+# ...from HydPy
+from hydpy import conf
+from hydpy.core import exceptiontools
+from hydpy.core.typingtools import *
+
+if TYPE_CHECKING:
+    from scipy import optimize
+    from hydpy.cythons import smoothutils
+else:
+    optimize = exceptiontools.OptionalImport("optimize", ["scipy.optimize"], locals())
+    from hydpy.cythons.autogen import smoothutils
+
+
+def calc_smoothpar_logistic1(metapar):
+    """Return the smoothing parameter corresponding to the given meta
+    parameter when using |smooth_logistic1|.
+
+    Calculate the smoothing parameter value corresponding the meta parameter
+    value 2.5:
+
+    >>> from hydpy.auxs.smoothtools import calc_smoothpar_logistic1
+    >>> smoothpar = calc_smoothpar_logistic1(2.5)
+
+    When using this smoothing parameter value, the output of function
+    |smooth_logistic1| differs by 1 % from the related "true" discontinuous
+    step function for the input values -2.5 and 2.5 (located at a distance
+    of 2.5 from the position of the discontinuity):
+
+    >>> from hydpy.cythons import smoothutils
+    >>> from hydpy import round_
+    >>> round_(smoothutils.smooth_logistic1(-2.5, smoothpar))
+    0.01
+    >>> round_(smoothutils.smooth_logistic1(2.5, smoothpar))
+    0.99
+
+    For zero or negative meta parameter values, function
+    |calc_smoothpar_logistic1| zero:
+
+    >>> round_(calc_smoothpar_logistic1(0.0))
+    0.0
+    >>> round_(calc_smoothpar_logistic1(-1.0))
+    0.0
+    """
+    return numpy.clip(metapar / numpy.log(99.0), 0.0, numpy.inf)
+
+
+def _error_smoothpar_logistic2(par, metapar):
+    return smoothutils.smooth_logistic2(-metapar, par) - 0.01
+
+
+def _smooth_logistic2_derivative1(par, metapar):
+    return smoothutils.smooth_logistic2_derivative1(metapar, par)
+
+
+def calc_smoothpar_logistic2(metapar, iterate: bool = False):
+    """Return the smoothing parameter corresponding to the given meta
+    parameter when using |smooth_logistic2|.
+
+    Calculate the smoothing parameter value corresponding the meta parameter
+    value 2.5:
+
+    >>> from hydpy.auxs.smoothtools import calc_smoothpar_logistic2
+    >>> smoothpar = calc_smoothpar_logistic2(2.5)
+
+    When using this smoothing parameter value, the output of function
+    |smooth_logistic2| differs by 1% from the related "true" discontinuous
+    step function for the input values -2.5 and 2.5 (located at a distance
+    of 2.5 from the position of the discontinuity):
+
+    >>> from hydpy.cythons import smoothutils
+    >>> from hydpy import round_
+    >>> round_(smoothutils.smooth_logistic2(-2.5, smoothpar))
+    0.01
+    >>> round_(smoothutils.smooth_logistic2(2.5, smoothpar))
+    2.51
+
+    For zero or negative meta parameter values, function
+    |calc_smoothpar_logistic2| returns zero:
+
+    >>> round_(calc_smoothpar_logistic2(-1.0))
+    0.0
+    >>> round_(calc_smoothpar_logistic2(-1.0, iterate=True))
+    0.0
+
+    Note that function |calc_smoothpar_logistic2| returns approximations
+    only.  By standard, it relies on linear interpolation between 10,000
+    unevenly spaced supporting points in the interval [0.0, 1,000].  The
+    achieved interpolation accuracy should suffice for the anticipated
+    applications, but be aware of low accuracies in the extrapolation range:
+
+    >>> metapars = 1000.0, 2000.0, 3000.0
+    >>> smoothpars = calc_smoothpar_logistic2(metapars)
+    >>> for metapar, smoothpar in zip(metapars, smoothpars):
+    ...     round_(smoothutils.smooth_logistic2(-metapar, smoothpar))
+    0.01
+    0.010137
+    0.011697
+
+    Alternatively, you can gain higher accuracies through the iterative
+    refinement of the results based on the Newton method:
+
+    >>> for metapar, smoothpar in zip(metapars, smoothpars):
+    ...     smoothpar = calc_smoothpar_logistic2(metapar, iterate=True)
+    ...     round_(smoothutils.smooth_logistic2(-metapar, smoothpar))
+    0.01
+    0.01
+    0.01
+
+    However, this is possible for scalar values only and very time-consuming.
+    Furthermore, there is no guarantee for success (in the extrapolation range):
+
+    >>> calc_smoothpar_logistic2(1000000.0, iterate=True)   # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    RuntimeError: Failed to converge ...
+
+    Hence, our advice to model developers is to restrict the allowed
+    span of all smoothing parameters relying on function
+    |calc_smoothpar_logistic2| to the mentioned interval and not to use
+    the iterative refinement strategy.  Consider the refinement only in
+    cases that require extremely high accuracies or where one needs to
+    extrapolate a little (of course, the range of the supporting points,
+    provided by file `support_points_for_smoothpar_logistic2.npy`, could
+    also be extended).
+    """
+    if iterate:
+        if metapar <= 0.0:
+            return 0.0
+        return optimize.newton(
+            _error_smoothpar_logistic2,
+            0.3 * metapar**0.84,
+            _smooth_logistic2_derivative1,
+            args=(metapar,),
+        )
+    return numpy.clip(
+        _cubic_interpolator_for_smoothpar_logistic2(metapar), 0.0, numpy.inf
+    )
+
+
+def calc_smoothpar_logistic3(metapar):
+    """Return the smoothing parameter corresponding to the given meta
+    parameter when using |smooth_logistic3|.
+
+    |smooth_logistic3| is only an alias for |smooth_logistic2|.
+
+    Calculate the smoothing parameter value corresponding the meta parameter
+    value 2.5:
+
+    >>> from hydpy.auxs.smoothtools import calc_smoothpar_logistic3
+    >>> smoothpar = calc_smoothpar_logistic3(2.5)
+
+    When using this smoothing parameter value, the output of function
+    |smooth_logistic3| would ideally differ by 1% from the related "true"
+    discontinuous step function for the input values -2.5 and 3.5 (located
+    at a distance of 2.5 from the position of the nearest discontinuity):
+
+    >>> from hydpy.cythons import smoothutils
+    >>> from hydpy import round_
+    >>> round_(smoothutils.smooth_logistic3(-2.5, smoothpar))
+    0.009876
+    >>> round_(smoothutils.smooth_logistic3(3.5, smoothpar))
+    0.990124
+
+    In contrast to the examples shown for functions |smooth_logistic1| and
+    |smooth_logistic2|, the smoothing parameter determined for function
+    |smooth_logistic3| is not in perfect agreement with the given meta
+    parameter.  For most purposes, the resulting error is negligible.
+    If you strive for very high accuracy, ask us to implement some iterative
+    refinement strategy or try it on your own.
+    """
+    return calc_smoothpar_logistic2(metapar)
+
+
+def calc_smoothpar_max1(metapar):
+    """Return the smoothing parameter corresponding to the given meta
+    parameter when using |smooth_max1|.
+
+    |smooth_max1| is only an alias for |smooth_logistic2|.
+
+    Calculate the smoothing parameter value corresponding the meta parameter
+    value 2.5:
+
+    >>> from hydpy.auxs.smoothtools import calc_smoothpar_max1
+    >>> smoothpar = calc_smoothpar_max1(2.5)
+
+    When using this smoothing parameter value, the output of function
+    |smooth_max1| is 0.01 above the discontinuous maximum function result, if
+    the absolute value of the difference between the x and the y value is 2.5:
+
+    >>> from hydpy.cythons import smoothutils
+    >>> from hydpy import round_
+    >>> round_(smoothutils.smooth_max1(4.0, 1.5, smoothpar))
+    4.01
+    """
+    return calc_smoothpar_logistic2(metapar)
+
+
+def calc_smoothpar_min1(metapar):
+    """Return the smoothing parameter corresponding to the given meta
+    parameter when using |smooth_min1|.
+
+    |smooth_min1| is only an alias for |smooth_logistic2|.
+
+    Calculate the smoothing parameter value corresponding the meta parameter
+    value 2.5:
+
+    >>> from hydpy.auxs.smoothtools import calc_smoothpar_min1
+    >>> smoothpar = calc_smoothpar_min1(2.5)
+
+    When using this smoothing parameter value, the output of function
+    |smooth_min1| is 0.01 below the discontinuous minimum function result, if
+    the absolute value of the difference between the x and the y value is 2.5:
+
+    >>> from hydpy.cythons import smoothutils
+    >>> from hydpy import round_
+    >>> round_(smoothutils.smooth_min1(-4.0, -1.5, smoothpar))
+    -4.01
+    """
+    return calc_smoothpar_logistic2(metapar)
+
+
+# Calculate and save the supporting points required for method
+# `calc_smoothpar_logistic2`:
+# xys = numpy.zeros((2, 10000), dtype=config.NP_FLOAT)
+# xys[0, :] = numpy.linspace(0., 1000.**(1./3.), 10000)**3.
+# xys[1, :] = [calc_smoothpar_logistic2(x, iterate=True) for x in xys[0]]
+# numpy.save(os.path.join(
+#     conf.__path__[0], "support_points_for_smoothpar_logistic2.npy"), xys)
+
+
+# Load the supporting points required for method `calc_smoothpar_logistic2`:
+confpath = conf.__path__[0]
+xys = numpy.load(os.path.join(confpath, "support_points_for_smoothpar_logistic2.npy"))
+_cubic_interpolator_for_smoothpar_logistic2 = interpolate.interp1d(
+    xys[0], xys[1], kind="cubic", fill_value="extrapolate"
+)
+del xys