HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/docs/enable_autodoc.py

@@ -0,0 +1,7 @@
+"""Better remove the "USEAUTODOC" option soon..."""
+
+with open("hydpy/config.py", encoding="utf-8") as configfile:
+    text = configfile.read()
+text = text.replace("USEAUTODOC = False", "USEAUTODOC = True")
+with open("hydpy/config.py", "w", encoding="utf-8") as configfile:
+    configfile.write(text)

hydpy/docs/polish_html.py

@@ -0,0 +1,57 @@
+"""Improve the headers and the in-text tables of content for all base and application
+models."""
+
+import importlib
+import os
+
+import click
+
+from hydpy.core import modeltools
+from hydpy.exe import xmltools
+
+
+def _replace_toc(dirpath: str, name: str, docname: modeltools.DocName) -> None:
+    html = os.path.join(dirpath, f"{docname.family}.html")
+    with open(html, encoding="utf-8") as file_:
+        text = file_.read()
+    template = '"toctree-l1"><a class="reference internal" href="%s.html">%s</a><'
+    old = template % (name, name)
+    new = template % (name, f"{name} &raquo; {docname.complete}")
+    text = text.replace(old, new)
+    with open(html, "w", encoding="utf-8") as file_:
+        file_.write(text)
+
+
+def _replace_header(dirpath: str, name: str, docname: modeltools.DocName) -> None:
+    html = os.path.join(dirpath, f"{name}.html")
+    with open(html, encoding="utf-8") as file_:
+        text = file_.read()
+    template = '<h1>%s<a class="headerlink"'
+    text = text.replace(template % name, template % docname.complete)
+    with open(html, "w", encoding="utf-8") as file_:
+        file_.write(text)
+
+
+@click.command()
+@click.option(
+    "-d",
+    "--dirpath",
+    type=str,
+    required=False,
+    default="auto/build",
+    help="Path of the directory containing the HTML files.",
+)
+def _polish_html(dirpath: str) -> None:
+    for name in xmltools.XSDWriter.get_basemodelnames():
+        module = importlib.import_module(f"hydpy.models.{name}.{name}_model")
+        _replace_header(dirpath=dirpath, name=name, docname=module.Model.DOCNAME)
+        _replace_toc(dirpath=dirpath, name=name, docname=module.Model.DOCNAME)
+
+    for name in xmltools.XSDWriter.get_applicationmodelnames():
+        module = importlib.import_module(f"hydpy.models.{name}")
+        _replace_header(dirpath=dirpath, name=name, docname=module.Model.DOCNAME)
+        _replace_toc(dirpath=dirpath, name=name, docname=module.Model.DOCNAME)
+
+
+if __name__ == "__main__":
+    _polish_html()  # pylint: disable=no-value-for-parameter

hydpy/docs/prepare.py

@@ -0,0 +1,224 @@
+"""Move, create and modify documentation files before applying `Sphinx`.
+
+Sphinx is to be executed in a freshly created folder named `auto`.  If this folder
+exists already, `prepare` removes it first and builds it from scratch afterwards, in
+order to assure that no old documentation files find their way into the html
+documentation.
+"""
+
+# import...
+# ...from standard library
+import datetime
+import importlib
+import inspect
+import os
+import shutil
+import sys
+import textwrap
+import zipfile
+
+os.chdir(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
+# pylint: disable=wrong-import-position
+# (changing the path is necessary when calling `prepare.py` from the command line)
+# ...from HydPy
+import hydpy
+from hydpy import auxs
+from hydpy import core
+from hydpy import cythons
+from hydpy import data
+from hydpy import docs
+from hydpy import exe
+from hydpy import interfaces
+from hydpy import models
+from hydpy.core import autodoctools
+from hydpy.core import masktools
+from hydpy.core import modeltools
+from hydpy.core import parametertools
+from hydpy.core import sequencetools
+from hydpy.core import variabletools
+from hydpy.docs import autofigs
+from hydpy.docs import bib
+from hydpy.docs import figs
+from hydpy.docs import sphinx
+from hydpy.docs import rst
+from hydpy.core.typingtools import *
+
+# Prepare folder `auto`.
+docspath: str = docs.__path__[0]
+AUTOPATH = os.path.join(docspath, "auto")
+if os.path.exists(AUTOPATH):
+    shutil.rmtree(AUTOPATH)
+os.makedirs(AUTOPATH)
+shutil.copytree(os.path.join(docspath, "html_"), os.path.join(AUTOPATH, "html_"))
+
+# Import all base and application models, to make sure all substituters are up-to-date.
+# (I am not sure if this is really necessary but it does not hurt.)
+modelspath: str = models.__path__[0]
+for filename in sorted(os.listdir(modelspath)):
+    if not filename.startswith("_"):
+        filename = filename.split(".")[0]
+        importlib.import_module(f"{models.__name__}.{filename}")
+hydpy.substituter.update_slaves()
+
+# Write one rst file for each module (including the ones defining application models)
+# and each base model defining a base model.  Each rst file should contain commands to
+# trigger the autodoc mechanism of Sphinx as well as the substitution replacement
+# commands relevant for the respective module or package.
+path2source = {}
+for subpackage in (auxs, core, cythons, exe, interfaces, models):
+    subpackagepath: str = subpackage.__path__[0]
+    filenames = sorted(os.listdir(subpackagepath))
+    substituter = hydpy.substituter
+    for filename in filenames:
+        is_module = (filename.endswith("py") or filename.endswith("pyx")) and (
+            filename != "__init__.py"
+        )
+        is_package = (
+            (subpackage is models)
+            and ("." not in filename)
+            and (filename not in ("build", "__pycache__"))
+        )
+        assert not (is_module and is_package)
+        source: str | None = None
+        if is_module:
+            path = os.path.join(subpackagepath, filename)
+            with open(path, encoding="utf-8") as file_:
+                sources = [file_.read()]
+            module = importlib.import_module(
+                f'{subpackage.__name__}.{filename.partition(".")[0]}'
+            )
+            for member in getattr(module, "__dict__", {}).values():
+                if inspect.isclass(member) and issubclass(
+                    member,
+                    (
+                        modeltools.Model,
+                        modeltools.Method,
+                        parametertools.SubParameters,
+                        sequencetools.SubSequences,
+                        masktools.Masks,
+                    ),
+                ):
+                    sources.append(member.__doc__ if member.__doc__ else "")
+            source = "\n".join(sources)
+        elif is_package:
+            sources = []
+            path = os.path.join(subpackagepath, filename)
+            for subfilename in sorted(os.listdir(path)):
+                if subfilename.endswith(".py"):
+                    subpath = os.path.join(path, subfilename)
+                    with open(subpath, encoding="utf-8") as file_:
+                        sources.append(file_.read())
+            source = "\n".join(sources)
+            modulename = f'{subpackage.__name__}.{filename.partition(".")[0]}'
+            module = importlib.import_module(modulename)
+        filename = filename.partition(".")[0]
+        if (is_module and (subpackage is models)) or is_package:
+            module = importlib.import_module(f"{models.__name__}.{filename}")
+            substituter = module.substituter
+        if is_module or is_package:
+            _exc_mem = autodoctools.excluded_members.copy()
+            if subpackage is models:
+                for member in vars(module).values():
+                    if (
+                        inspect.isclass(member)
+                        and issubclass(member, variabletools.SubVariables)
+                        and not member.CLASSES
+                    ):
+                        _exc_mem.add(member.__name__)
+            excludemembers = ", ".join(_exc_mem)
+            lines = [
+                "",
+                f".. _{filename}:",
+                "",
+                filename,
+                "=" * len(filename),
+                "",
+                f'.. automodule:: {".".join((subpackage.__name__, filename))}',
+                "    :members:",
+                "    :show-inheritance:",
+                f"    :exclude-members: {excludemembers}",
+                "",
+            ]
+            path = os.path.join(AUTOPATH, filename + ".rst")
+            with open(path, "w", encoding="utf-8") as file_:
+                assert source is not None
+                path2source[path] = source
+                file_.write(substituter.get_commands(source))
+                file_.write("\n")
+                file_.write("\n".join(lines))
+
+# Copy additional files into folder `auto` and, for the rst files, add the
+# required substitution replacement commands.
+for subpackage in (autofigs, bib, figs, sphinx, rst):
+    subpackagepath = subpackage.__path__[0]
+    for filename in sorted(os.listdir(subpackagepath)):
+        path_in = os.path.join(subpackagepath, filename)
+        path_out = os.path.join(AUTOPATH, filename)
+        if os.path.isfile(path_in) and (filename != "__init__.py"):
+            if subpackage is rst:
+                with open(path_in, encoding="utf-8") as file_:
+                    orig = file_.read()
+                with open(path_out, "w", encoding="utf-8") as file_:
+                    source = path2source.get(path_out, "")
+                    source = "\n".join([source, orig])
+                    file_.write(hydpy.substituter.get_commands(source))
+                    file_.write("\n")
+                    file_.write(orig)
+            elif filename != "build":
+                shutil.copy(path_in, path_out)
+
+# copy _themes path from sphinx subpackage into folder `auto`
+# _themes folder contains the modified sphinx html themes
+themespath = os.path.join(sphinx.__path__[0], "_themes")
+themespathdest = os.path.join(AUTOPATH, "_themes")
+if not os.path.isdir(themespath):
+    raise RuntimeError("Cannot find path `_themes` in sphinx subpackage")
+shutil.copytree(themespath, themespathdest)
+
+# Collect all example projects in individual zip archives
+
+header = (
+    f"This README describes a Hydpy {hydpy.__version__} example project.\n"
+    f"© 2013-{datetime.datetime.now().year} HydPy Developers\n"
+    f"https://github.com/hydpy-dev/hydpy/\n"
+)
+
+filepath = os.path.join(rst.__path__[0], "example_projects.rst")
+with open(filepath, encoding="utf-8") as rstfile:
+    descriptions = rstfile.read()
+
+for line in descriptions.splitlines():
+    if line.startswith(".. _example_projects:"):
+        break
+    if line.startswith(".. _`"):
+        assert line.count("`: ") == 1
+        link, url = line[5:].split("`: ")
+        descriptions = descriptions.replace(f"`{link}`_", f"{link} [{url}]")
+
+mark2 = "Click :download:"
+datadirpath = data.__path__[0]
+for projectname in os.listdir(datadirpath):
+    projectpath = os.path.join(datadirpath, projectname)
+    if os.path.isdir(projectpath) and not projectname.startswith("_"):
+        zipfilename = os.path.join(AUTOPATH, f"{projectname}.zip")
+        with zipfile.ZipFile(zipfilename, "w") as zipfile_:
+            for subdirpath, _, filenames in os.walk(projectpath):
+                zipdirpath = os.path.relpath(subdirpath, datadirpath)
+                for filename in filenames:
+                    zipfile_.write(
+                        filename=os.path.join(subdirpath, filename),
+                        arcname=os.path.join(zipdirpath, filename),
+                    )
+            mark1 = f".. _{projectname}:\n"
+            assert mark1 in descriptions, f"{mark1} not in project description"
+            description = descriptions.split(mark1)[1]
+            assert mark2 in descriptions, f"{mark2} not in project description"
+            description = description.split(mark2)[0]
+            paragraphs = (
+                "\n".join(textwrap.wrap(text=p, width=90, break_long_words=False))
+                for p in description.split("\n\n")[1:]
+            )
+            description = "\n\n".join(paragraphs)
+            description = "\n".join([header, description])
+            zipfile_.writestr(zinfo_or_arcname="README.txt", data=description)

hydpy/docs/publish_docs.py

@@ -0,0 +1,53 @@
+"""Push the `result` folder prepared by the `combine_docversions.py` script to
+Github-Pages.
+
+Only pushes when the current branch is among the relevant branches listed in
+`relevant_branches.txt`.
+"""
+
+import os
+import sys
+
+import ghp_import
+
+
+def print_(*message: str) -> None:
+    """Print immediately."""
+    print(*message)
+    sys.stdout.flush()
+
+
+def main() -> None:
+    """Push when appropriate."""
+
+    if (token := os.environ.get("GH_TOKEN")) is not None:
+        repo = os.environ["TRAVIS_REPO_SLUG"]
+        remote = f"https://{token}@github.com/{repo}.git"
+        actual_branch = os.environ["TRAVIS_BRANCH"]
+
+        with open("relevant_branches.txt", encoding="utf-8") as file_:
+            lines = file_.readlines()[1:]
+
+        for line in lines:
+            try:
+                branch = line.split()[0]
+            except IndexError:
+                continue
+            if branch == actual_branch:
+                print_("Push to GitHub-Pages:")
+                ghp_import.ghp_import(
+                    srcdir="result",
+                    remote=remote,
+                    branch="gh-pages",
+                    mesg="update documentation",
+                    push=True,
+                    prefix=None,
+                    force=True,
+                    nojekyll=True,
+                )
+                break
+
+    print_("No push to GitHub-Pages.")
+
+
+main()

hydpy/docs/rst/HydPy-ARMA.rst

@@ -0,0 +1,27 @@
+
+.. _HydPy-ARMA:
+
+HydPy-ARMA
+==========
+
+Many hydrologists use linear system approaches to solve flood routing problems
+approximately.  Famous examples are the Unit Hydrograph approach and the Muskingum
+flood routing method.  One can understand the Unit Hydrograph approach as a moving
+average process (MA), and the Muskingum method as a mixed autoregressive and moving
+average process (ARMA).  Unit Hydrographs consist of an arbitrary number of MA
+coefficients.  The Muskingum method defines three parameters, exactly two MA
+coefficients associated with the "new" and the "old" flow into the channel, and one AR
+coefficient associated with the "old" flow out of the channel.
+
+The HydPy-ARMA base model supports implementing such methods in a generalised manner.
+Consider using one of its application models when you require a robust, computationally
+efficient, easily calibratable approach.  However, taking nonlinear rating curves or
+backwater effects into account can be cumbersome or even impossible.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   arma
+   arma_rimorido

hydpy/docs/rst/HydPy-Conv.rst

@@ -0,0 +1,22 @@
+.. _HydPy-Conv:
+
+HydPy-Conv
+==========
+
+HydPy-Conv models are no real hydrological models.  Instead, they serve as converters
+that allow connecting different kinds of models providing output and requiring input
+that does not fit immediately.  The most typical use case is interpolating data, which
+is implemented by the application model |conv_nn| using the nearest-neighbour, by
+application model |conv_idw| using the inverse distance weighted approach, and by
+application model |conv_idw_ed| combining inverse distance weighting with linear
+regression.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   conv
+   conv_nn
+   conv_idw
+   conv_idw_ed

hydpy/docs/rst/HydPy-Dam.rst

@@ -0,0 +1,79 @@
+
+.. _Landeshochwasserzentrum (LHWZ): https://www.umwelt.sachsen.de/umwelt/wasser/72.htm
+.. _LARSIM: http://www.larsim.de/das-modell/
+.. _`German Federal Institute of Hydrology (BfG)`: https://www.bafg.de/EN
+
+.. _HydPy-Dam:
+
+HydPy-Dam
+=========
+
+The HydPy-Dam 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 in 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 of the first five application models might be helpful:
+
+================================================================= ==== ==== ==== ==== ====
+Does the dam model…                                               v001 v002 v003 v004 v005
+================================================================= ==== ==== ==== ==== ====
+…calculate the demand at a remote location itself?                yes  no   no   no   yes
+
+…lie in a river upstream of the remote location?                  yes  yes  no   no   yes
+
+…tell another model if it cannot supply the remote demand?        no   no   no   no   yes
+
+…discharge to another remote location for flood protection?       no   no   no   yes  no
+
+…ask for additional water supply from a remote location?          no   no   no   no   yes
+
+…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)`_.  Later, we added the application models |dam_llake|,
+|dam_lretention|, and |dam_lreservoir| 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).  Most
+recently, we developed |dam_pump|, |dam_sluice|, and |dam_pump_sluice| for improving
+simulations in low-land areas, where the draining of land areas via pumps and sluices
+often plays a more relevant role than gravity-driven runoff.
+
+|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 for becomimg acquainted with any of the application models prepared so
+far.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   dam
+   dam_v001
+   dam_v002
+   dam_v003
+   dam_v004
+   dam_v005
+   dam_llake
+   dam_lretention
+   dam_lreservoir
+   dam_pump
+   dam_sluice
+   dam_pump_sluice

hydpy/docs/rst/HydPy-Dummy.rst

@@ -0,0 +1,21 @@
+
+.. _HydPy-Dummy:
+
+HydPy-Dummy
+===========
+
+HydPy-Dummy models do not apply any process equations.  Instead, they serve as simple
+placeholders which forward their input without modifications.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   dummy
+   dummy_node2node
+   dummy_interceptedwater
+   dummy_soilwater
+   dummy_snowcover
+   dummy_snowycanopy
+   dummy_snowalbedo

hydpy/docs/rst/HydPy-Evap.rst

@@ -0,0 +1,26 @@
+.. _HydPy-Evap:
+
+HydPy-Evap
+==========
+
+The HydPy-Evap model family aims to calculate different kinds of reference, potential,
+or actual evapo(transpi)ration.  The implemented application models work as stand-alone
+models but are primarily thought to be used as submodels by main models like
+|lland_dd|.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   evap
+   evap_ret_io
+   evap_ret_fao56
+   evap_ret_tw2002
+   evap_pet_m
+   evap_pet_mlc
+   evap_pet_ambav1
+   evap_pet_hbv96
+   evap_aet_hbv96
+   evap_aet_minhas
+   evap_aet_morsim

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 data
+more flexibly.
+
+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.  One purpose of HydPy-Exch
+is to facilitate similar exchanges between different model instances more modularly.
+Application model |exch_weir_hbv96|, 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_weir_hbv96| 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).
+
+Besides such explanation requiring models, HydPy-Exch also provides straightforward
+models like |exch_branch_hbv96|, which distributes its inflow to multiple locations.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   exch
+   exch_branch_hbv96
+   exch_weir_hbv96
+   exch_waterlevel

hydpy/docs/rst/HydPy-G.rst

@@ -0,0 +1,40 @@
+.. _HydPy-G:
+
+HydPy-G (GR)
+============
+
+The HydPy-G model family (modèle due Génie Rural) comprises daily lumped hydrological
+models that differ in their amount of parameters, in their calculation of groundwater
+exchange, and partly in their calculation of runoff concentration.  Compared to the
+other main models provided by HydPy, they are limited to the bare essentials.  For
+example, you can apply them only "lumped", meaning there is no way to distinguish
+between different types of land covers within one subcatchment.
+
+Generally, all models follow the implementations of the R package airGR
+:cite:p:`ref-airGR2017`.  However, while airGR provides models for specific simulation
+time steps (e.g. GR4J for daily and GR4H for hourly steps), all members of HydPy-G are
+(in principle) applicable to arbitrary simulation time steps.  Additionally, in air GR,
+only some, but in HydPy-G, all models allow for configuring the interception capacity.
+
+None of the available application models contains a snow module.  Still, you can use
+the models of the members of the HydPy-Snow model family to modify precipitation
+accordingly before giving it to a HydPy-G model.  (Admittedly, this is a little
+cumbersome.  For more comfort, we will turn all snow models into "real" submodels in a
+later HydPy version.)
+
+
+Base model:
+
+.. toctree::
+   :maxdepth: 1
+
+   gland
+
+Application models:
+
+.. toctree::
+   :maxdepth: 1
+
+   gland_gr4
+   gland_gr5
+   gland_gr6