HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/models/wq_trapeze.py

@@ -0,0 +1,168 @@
+# pylint: disable=unused-wildcard-import
+"""
+|wq_trapeze| is a stateless "two-way" submodel.  It supports calculating properties
+like the wetted area for a given water depth and properties like the water depth for a
+given wetted area.  See the documentation on the application model |sw1d_channel|,
+which shows the usage of "both ways" in practice.  Here, we only aim to visualise how
+|wq_trapeze| combines multiple symmetric trapezes to a single cross-section profile via
+method |TrapezeModel.plot|.
+
+The following test function helps us to use method |TrapezeModel.plot| repeatedly and
+insert the generated figures into the online documentation:
+
+>>> from matplotlib import pyplot
+>>> from hydpy.core.testtools import save_autofig
+>>> def plot(example=None, save=True, add_x_y=None, **kwargs):
+...     derived.trapezeheights.update()
+...     derived.slopewidths.update()
+...     figure = model.plot(**kwargs)
+...     if add_x_y is not None:
+...         x, y = add_x_y
+...         pyplot.plot([x, x], [y, 5.0], color=kwargs.get("color"), linestyle=":")
+...         pyplot.plot([-x, -x], [y, 5.0], color=kwargs.get("color"), linestyle=":")
+...     if example is not None:
+...         save_autofig(f"wq_trapeze_{example}.png", figure=figure)
+
+We start with a single trapeze:
+
+>>> from hydpy.models.wq_trapeze import *
+>>> parameterstep()
+>>> nmbtrapezes(1)
+
+Parameter |BottomLevels| does not affect the profile's shape for a single trapeze.  We
+set its value to one meter arbitrarily:
+
+>>> bottomlevels(1.0)
+
+With parameter |BottomWidths| larger than zero and parameter |SideSlopes| being zero,
+the single trapeze becomes a simple, infinitely high rectangle:
+
+>>> bottomwidths(2.0)
+>>> sideslopes(0.0)
+>>> plot("rectangle")
+
+.. image:: wq_trapeze_rectangle.png
+   :width: 400
+
+Conversely, the single trapeze becomes a simple, infinitely high triangle:
+
+>>> bottomwidths(0.0)
+>>> sideslopes(2.0)
+>>> plot("triangle")
+
+.. image:: wq_trapeze_triangle.png
+   :width: 400
+
+Set both values larger than zero to gain a "complete" trapeze:
+
+>>> bottomwidths(2.0)
+>>> sideslopes(2.0)
+>>> plot("one_trapeze")
+
+.. image:: wq_trapeze_one_trapeze.png
+   :width: 400
+
+Next, we want to construct a more complex profile consisting of three trapezes:
+
+>>> nmbtrapezes(3)
+
+We must assign them increasing bottom levels (the bottom level of an upper trapeze
+defines the height of its lower neighbour):
+
+>>> bottomlevels(1.0, 3.0, 4.0)
+
+The following profile combines the three previously defined geometries:
+
+>>> bottomwidths(2.0, 0.0, 2.0)
+>>> sideslopes(0.0, 2.0, 2.0)
+>>> plot("three_trapezes")
+
+.. image:: wq_trapeze_three_trapezes.png
+   :width: 400
+
+Note that each upper trapeze is stretched according to the width of its lower
+neighbour.  The following example illustrates this more clearly by plotting each
+trapeze in a different colour:
+
+>>> nmbtrapezes(1)
+>>> bottomlevels(1.0)
+>>> bottomwidths(2.0)
+>>> sideslopes(0.0)
+>>> plot(add_x_y=(1.0, 3.0), ymax=3.0, color="green", label="trapeze 1")
+>>> bottomlevels(3.0)
+>>> bottomwidths(2.0)
+>>> sideslopes(2.0)
+>>> plot(add_x_y=(3.0, 4.0), ymax=4.0, color="yellow", label="trapeze 2")
+>>> bottomlevels(4.0)
+>>> bottomwidths(8.0)
+>>> sideslopes(2.0)
+>>> plot("config_1", ymax=5.0, color="red", label="trapeze 3")
+
+.. image:: wq_trapeze_config_1.png
+   :width: 400
+
+In addition to the configuration options shown in the last example, one can pass |True|
+to the keyword argument `label`. Then, |TrapezeModel.plot| tries to include the
+responsible element's name into the legend, which is impossible in this example, so
+that "?" serves as a spare:
+
+>>> plot("config_2", ymax=3.0, label=True)
+
+.. image:: wq_trapeze_config_2.png
+   :width: 400
+
+(Upon closer inspection, the last example also shows that |TrapezeModel.plot| ignores
+too low `ymax`  values silently.)
+"""
+# import...
+
+# ...from HydPy
+from hydpy.core import modeltools
+from hydpy.interfaces import routinginterfaces
+from hydpy.exe.modelimports import *
+
+# ...from wq
+from hydpy.models.wq import wq_model
+
+
+class Model(wq_model.TrapezeModel, routinginterfaces.CrossSectionModel_V2):
+    """|wq_trapeze.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="WQ-Trapeze", description="multi-trapeze river profile submodel"
+    )
+    __HYDPY_ROOTMODEL__ = False
+
+    INLET_METHODS = ()
+    RECEIVER_METHODS = ()
+    RUN_METHODS = ()
+    INTERFACE_METHODS = (
+        wq_model.Use_WaterDepth_V2,
+        wq_model.Use_WaterLevel_V2,
+        wq_model.Use_WettedArea_V1,
+        wq_model.Get_WaterDepth_V1,
+        wq_model.Get_WaterLevel_V1,
+        wq_model.Get_WettedArea_V1,
+        wq_model.Get_WettedPerimeter_V1,
+    )
+    ADD_METHODS = (
+        wq_model.Set_WaterDepth_V1,
+        wq_model.Set_WaterLevel_V1,
+        wq_model.Set_WettedArea_V1,
+        wq_model.Calc_WaterDepth_V1,
+        wq_model.Calc_WaterDepth_V2,
+        wq_model.Calc_WaterLevel_V1,
+        wq_model.Calc_WettedAreas_V1,
+        wq_model.Calc_WettedArea_V1,
+        wq_model.Calc_WettedPerimeters_V1,
+        wq_model.Calc_WettedPerimeter_V1,
+        wq_model.Calc_WettedPerimeterDerivatives_V1,
+    )
+    OUTLET_METHODS = ()
+    SENDER_METHODS = ()
+    SUBMODELINTERFACES = ()
+    SUBMODELS = ()
+
+
+tester = Tester()
+cythonizer = Cythonizer()

hydpy/models/wq_trapeze_strickler.py

@@ -0,0 +1,101 @@
+# pylint: disable=unused-wildcard-import
+"""
+|wq_trapeze_strickler| is a stateless submodel that requires information on the current
+water level or depth from its main model (usually a routing model).  It returns the
+corresponding discharge and related properties, such as the kinematic wave celerity.
+See the documentation on the application model |musk_mct|, which shows how to use
+|wq_trapeze_strickler| in practice.  Also, please see the documentation on the related
+application model |wq_trapeze|, which also relies on stacket and symmetric trapezes but
+does not include discharge calculations.
+
+|wq_trapeze| and |wq_trapeze_strickler| offer the same plotting functionalities.  To
+avoid redundancies, we give a single example for |wq_trapeze_strickler| and refer you
+to the documentation on |wq_trapeze| for further details:
+
+>>> from hydpy.core.testtools import save_autofig
+>>> from hydpy.models.wq_trapeze_strickler import *
+>>> parameterstep()
+>>> nmbtrapezes(3)
+>>> bottomlevels(1.0, 3.0, 4.0)
+>>> bottomwidths(2.0, 0.0, 2.0)
+>>> sideslopes(0.0, 2.0, 2.0)
+>>> derived.trapezeheights.update()
+>>> derived.slopewidths.update()
+>>> figure = model.plot()
+>>> save_autofig(f"wq_trapeze_strickler_three_trapezes.png", figure=figure)
+
+.. image:: wq_trapeze_strickler_three_trapezes.png
+   :width: 400
+"""
+# import...
+# ...from HydPy
+from hydpy.core import importtools
+from hydpy.core import modeltools
+from hydpy.interfaces import routinginterfaces
+from hydpy.exe.modelimports import *
+
+# ...from wq
+from hydpy.models.wq import wq_control
+from hydpy.models.wq import wq_model
+
+
+class Model(wq_model.TrapezeModel, routinginterfaces.CrossSectionModel_V1):
+    """|wq_trapeze_strickler.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="WQ-Trapeze-Strickler",
+        description=(
+            "multi-trapeze river profile submodel including Strickler-based "
+            "calculations"
+        ),
+    )
+    __HYDPY_ROOTMODEL__ = False
+
+    INLET_METHODS = ()
+    RECEIVER_METHODS = ()
+    RUN_METHODS = ()
+    INTERFACE_METHODS = (
+        wq_model.Use_WaterDepth_V1,
+        wq_model.Use_WaterLevel_V1,
+        wq_model.Get_WettedArea_V1,
+        wq_model.Get_SurfaceWidth_V1,
+        wq_model.Get_Discharge_V1,
+        wq_model.Get_Celerity_V1,
+    )
+    ADD_METHODS = (
+        wq_model.Set_WaterDepth_V1,
+        wq_model.Set_WaterLevel_V1,
+        wq_model.Calc_WaterDepth_V1,
+        wq_model.Calc_WaterLevel_V1,
+        wq_model.Calc_WettedAreas_V1,
+        wq_model.Calc_WettedArea_V1,
+        wq_model.Calc_WettedPerimeters_V1,
+        wq_model.Calc_WettedPerimeterDerivatives_V1,
+        wq_model.Calc_SurfaceWidths_V1,
+        wq_model.Calc_SurfaceWidth_V1,
+        wq_model.Calc_Discharges_V1,
+        wq_model.Calc_Discharge_V2,
+        wq_model.Calc_DischargeDerivatives_V1,
+        wq_model.Calc_DischargeDerivative_V1,
+        wq_model.Calc_Celerity_V1,
+    )
+    OUTLET_METHODS = ()
+    SENDER_METHODS = ()
+    SUBMODELINTERFACES = ()
+    SUBMODELS = ()
+
+    @importtools.define_targetparameter(wq_control.BottomSlope)
+    def prepare_bottomslope(self, bottomslope: float) -> None:
+        """Set the bottom's slope (in the longitudinal direction) [-].
+
+        >>> from hydpy.models.wq_trapeze_strickler import *
+        >>> parameterstep()
+        >>> model.prepare_bottomslope(0.01)
+        >>> bottomslope
+        bottomslope(0.01)
+        """
+        self.parameters.control.bottomslope(bottomslope)
+
+
+tester = Tester()
+cythonizer = Cythonizer()

hydpy/models/wq_walrus.py

@@ -0,0 +1,57 @@
+# pylint: disable=unused-wildcard-import
+"""
+.. _`issue 120`: https://github.com/hydpy-dev/hydpy/issues/120
+
+|wq_walrus| is a submodel that supplies its main model with discharge estimates.  It
+implements the equation suggested by :cite:t:`ref-Brauer2014` for calculating the
+outflow of a subcatchment through a ditch or channel, which assumes a rectangular
+channel geometry and, optionally, the existence of a weir at the channel outlet.  See
+`issue 120`_ for more additional information.
+
+As |wq_walrus| only applies the single method |Calculate_Discharge_V1|, we keep the
+tests short and take a single example from its documentation:
+
+>>> from hydpy.models.wq_walrus import *
+>>> simulationstep("12h")
+>>> parameterstep("1d")
+>>> channeldepth(5.0)
+>>> crestheight(2.0)
+>>> bankfulldischarge(2.0)
+>>> dischargeexponent(2.0)
+>>> crestheighttolerance(0.1)
+>>> derived.crestheightregularisation.update()
+>>> from hydpy import round_
+>>> round_(model.calculate_discharge(3.0))
+0.111111
+"""
+# import...
+# ...from HydPy
+from hydpy.core import modeltools
+from hydpy.exe.modelimports import *
+
+# ...from ga
+from hydpy.models.wq import wq_model
+
+
+class Model(modeltools.AdHocModel, wq_model.Base_DischargeModel_V2):
+    """|wq_walrus.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="WQ-WALRUS",
+        description="WALRUS default function for calculating catchment outflow",
+    )
+    __HYDPY_ROOTMODEL__ = False
+
+    INLET_METHODS = ()
+    RECEIVER_METHODS = ()
+    RUN_METHODS = ()
+    INTERFACE_METHODS = (wq_model.Calculate_Discharge_V1,)
+    ADD_METHODS = ()
+    OUTLET_METHODS = ()
+    SENDER_METHODS = ()
+    SUBMODELINTERFACES = ()
+    SUBMODELS = ()
+
+
+tester = Tester()
+cythonizer = Cythonizer()

hydpy/tests/.coveragerc

@@ -0,0 +1,22 @@
+
+[run]
+source =
+    hydpy
+omit =
+    */hydpy/tests/*
+    */hydpy/docs/*
+    */hydpy/cythons/modelutils.py
+parallel=True
+
+[report]
+show_missing = True
+exclude_lines =
+    pragma: no cover
+    if TYPE_CHECKING
+    if typing.TYPE_CHECKING
+    ^    +\.\.\.
+    ^    +pass$
+    ^    +pass .*
+    assert .*
+    ^    +assert_never\(.*\)
+    ^    +from .* import .*

hydpy/tests/check_consistency.py

@@ -0,0 +1,32 @@
+"""Perform all available consistency checks."""
+
+# import...
+# ...from standard library
+import os
+import sys
+
+# ...from HydPy
+from hydpy import models
+from hydpy.core.testtools import perform_consistencychecks
+
+print("Perform all available consistency checks:\n")
+dirpath: str = models.__path__[0]
+applicationmodels = sorted(
+    fn.split(".")[0]
+    for fn in os.listdir(dirpath)
+    if (fn != "__init__.py") and os.path.isfile(os.path.join(dirpath, fn))
+)
+results: list[str] = []
+for applicationmodel in applicationmodels:
+    subresult = perform_consistencychecks(applicationmodel=applicationmodel, indent=4)
+    if subresult:
+        results.append(
+            f"Potential consistency problems for "
+            f"application model {applicationmodel}"
+        )
+        results.append(f"{subresult}\n")
+if results:
+    print("\n".join(results))
+    sys.exit(1)
+print("   nothing to report\n")
+sys.exit(0)

hydpy/tests/hydpydoctestcustomize.pth

@@ -0,0 +1 @@
+import hydpydoctestcustomize

hydpy/tests/hydpydoctestcustomize.py

@@ -0,0 +1,15 @@
+"""Copy `hydpydoctestcustomize.pth` and `hydpydoctestcustomize.py` into the
+site-packages folder to ensure the coverage measurement is complete when executing
+tests in sub-processes."""
+
+import os
+
+import coverage
+
+basepath = os.path.abspath(os.path.split(coverage.__path__[0])[0])
+path_rcfile = os.path.join(basepath, "hydpy", "tests", ".coveragerc")
+os.environ["COVERAGE_PROCESS_START"] = path_rcfile
+os.environ["COVERAGE_RCFILE"] = path_rcfile
+basepath_datafile = os.path.join(basepath, ".coverage")
+os.environ["COVERAGE_FILE"] = basepath_datafile
+coverage.process_startup()

hydpy/tests/run_doctests.py

@@ -0,0 +1,233 @@
+# pylint: disable=import-outside-toplevel
+# due to importing hydpy after eventually changing its source path
+"""Evaluate all doctests defined in the different modules and documentation files."""
+
+from __future__ import annotations
+from collections.abc import Iterable, Sequence
+import os
+import sys
+import importlib
+import time
+from typing import NamedTuple, NoReturn
+import unittest
+import doctest
+import warnings
+
+import click
+
+
+def print_(*args: str) -> None:
+    """Print immediately."""
+    print(*args)
+    sys.stdout.flush()
+
+
+class _FilterFilenames:
+    file_doctests: set[str]
+
+    def __init__(self, file_doctests: Iterable[str]) -> None:
+        self.file_doctests = set(file_doctests)
+
+    def __call__(self, filenames: Sequence[str]) -> tuple[str, ...]:
+        if self.file_doctests:
+            return tuple(fn for fn in filenames if fn in self.file_doctests)
+        return tuple(filenames)
+
+
+DocTest = dict[str, tuple[unittest.TestResult, int]]
+
+
+class DocTests(NamedTuple):
+    """Stores the results of the successfull and failing test runs seperately."""
+
+    successfull: DocTest
+    failing: DocTest
+
+
+@click.command()
+@click.option(
+    "-h",
+    "--hydpy-path",
+    type=str,
+    required=False,
+    default=None,
+    help="Path of the HydPy package to be tested.",
+)
+@click.option(
+    "-f",
+    "--file-doctests",
+    type=str,
+    required=False,
+    multiple=True,
+    default=[],
+    help="Name of the files that define the relevant doctests.",
+)
+@click.option(
+    "-p",
+    "--python-mode",
+    type=bool,
+    default=True,
+    help="Execute all tests in Python-mode.",
+)
+@click.option(
+    "-c",
+    "--cython-mode",
+    type=bool,
+    default=True,
+    help="Execute all tests in Cython-mode.",
+)
+def main(  # pylint: disable=too-many-branches
+    hydpy_path: str | None,
+    file_doctests: list[str],
+    python_mode: bool,
+    cython_mode: bool,
+) -> NoReturn:
+    """Perform all tests (first in Python mode, then in Cython mode)."""
+
+    alldoctests: dict[str, DocTests] = {}
+    if python_mode:
+        alldoctests["Python"] = DocTests(successfull={}, failing={})
+    if cython_mode:
+        alldoctests["Cython"] = DocTests(successfull={}, failing={})
+    if not alldoctests:
+        raise RuntimeError("Neither `Python` nor `Cython` mode selected for testing.")
+
+    if hydpy_path is not None:
+        sys.path.insert(0, hydpy_path)
+
+    import hydpy
+    from hydpy import config
+    from hydpy import pub
+    from hydpy.core import devicetools
+    from hydpy.core import testtools
+
+    filter_filenames = _FilterFilenames(file_doctests)
+    pingtime: float = time.perf_counter()
+
+    for mode, doctests in alldoctests.items():
+        path_ = hydpy.__path__[0]
+        filenames_: Sequence[str]
+        for dirpath, _, filenames_ in os.walk(path_):
+            if (  # pylint: disable=too-many-boolean-expressions
+                ("__init__.py" not in filenames_)
+                or dirpath.endswith("tests")
+                or dirpath.endswith("docs")
+                or dirpath.endswith("sphinx")
+                or dirpath.endswith("autogen")
+                or dirpath.endswith("build")
+                or dirpath.endswith("__pycache__")
+            ):
+                continue
+            filenames_ = filter_filenames(filenames_)
+            packagename = dirpath.replace(os.sep, ".") + "."
+            packagename = packagename[packagename.rfind("hydpy.") :]
+            modulenames = [
+                f"{packagename}{fn.split('.')[0]}"
+                for fn in filenames_
+                if fn.endswith(".py")
+            ]
+            docfilenames = [
+                os.path.join(dirpath, fn)
+                for fn in filenames_
+                if fn[-4:] in (".rst", ".pyx")
+            ]
+            for name in modulenames + docfilenames:
+                if time.perf_counter() > pingtime + 5 * 60:
+                    print_("`run_doctests` still running...")
+                    pingtime = time.perf_counter()
+                suite = unittest.TestSuite()
+                try:
+                    if name[-4:] in (".rst", ".pyx"):
+                        test = doctest.DocFileSuite(name, module_relative=False)
+                    else:
+                        test = doctest.DocTestSuite(importlib.import_module(name))
+                    suite.addTest(test)
+                except ValueError as exc:
+                    if exc.args[-1] != "has no docstrings":
+                        raise exc
+                else:
+                    del pub.projectname
+                    del pub.timegrids
+                    options = pub.options
+                    options.checkprojectstructure = False
+                    del options.checkseries
+                    options.ellipsis = 0
+                    del pub.options.parameterstep
+                    options.printprogress = False
+                    options.reprdigits = 6
+                    del pub.options.simulationstep
+                    del options.timestampleft
+                    del options.trimvariables
+                    options.usecython = mode == "Cython"
+                    del options.usedefaultvalues
+                    del options.utclongitude
+                    del options.utcoffset
+                    del options.warnmissingcontrolfile
+                    del options.warnmissingobsfile
+                    del options.warnmissingsimfile
+                    options.warnsimulationstep = False
+                    options.warntrim = False
+                    testtools.IntegrationTest.plotting_options = (
+                        testtools.PlottingOptions()
+                    )
+                    if name[-4:] in (".rst", ".pyx"):
+                        name = name[name.find("hydpy" + os.sep) :]
+                    with warnings.catch_warnings(), open(
+                        os.devnull, "w", encoding=config.ENCODING
+                    ) as file_, devicetools.clear_registries_temporarily():
+                        warnings.filterwarnings(action="error", module="hydpy")
+                        warnings.filterwarnings(
+                            action="ignore",
+                            category=DeprecationWarning,
+                            message="`np.bool`",
+                        )
+                        warnings.filterwarnings(
+                            action="ignore",
+                            category=DeprecationWarning,
+                            message="datetime.datetime.utcfromtimestamp",
+                        )
+                        runner = unittest.TextTestRunner(stream=file_)
+                        result = runner.run(suite)
+                        nmbproblems = len(result.errors) + len(result.failures)
+                        if nmbproblems:
+                            doctests.failing[name] = (result, nmbproblems)
+                        else:
+                            doctests.successfull[name] = (result, nmbproblems)
+                    problems = result.errors + result.failures
+                    if problems:
+                        pingtime = time.perf_counter()
+                        print_(f"\nDetailed error information on module {name}:")
+                        for idx, problem in enumerate(problems):
+                            print_(f"    Error no. {idx+1}:")
+                            print_(f"        {problem[0]}")
+                            for line in problem[1].split("\n"):
+                                print_(f"        {line}")
+
+        if doctests.successfull:
+            print_(f"\nIn the following modules, no doc test failed in {mode} mode:")
+            for name, (testresult, _) in sorted(doctests.successfull.items()):
+                if name[-4:] in (".rst", ".pyx"):
+                    print_(f"    {name}")
+                else:
+                    print_(f"    {name} ({testresult.testsRun} successes)")
+        if doctests.failing:
+            print_(
+                f"\nAt least one doc test failed in each of the following modules in "
+                f"{mode} mode:"
+            )
+            for name, (_, nmbproblems) in sorted(doctests.failing.items()):
+                print_(f"    {name} ({nmbproblems} failures/errors)")
+
+    # Return the exit code.
+    code = 0
+    for mode, doctests in alldoctests.items():
+        code = min(code + len(doctests.failing), 1)
+        print_(
+            f"\nrun_doctests.py found {len(doctests.failing)} failing doctest "
+            f"suites in {mode} mode."
+        )
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter