HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/docs/rst/HydPy-GA.rst

@@ -0,0 +1,34 @@
+.. _HydPy-GA:
+
+HydPy-GA (Green-Ampt)
+=====================
+
+The members of HydPy-GA calculate surface water infiltration into soils based on the
+simplifying Green-Ampt assumption of "piston-like" wetting fronts.  Opposed to purely
+volume-based approaches, they consider the influence of rainfall intensity on
+infiltration and, thus, the potential generation of surface runoff.  Hence, one might
+prefer them when dealing with short but intensive (often convective) rainfall events.
+However, Green-Ampt methods are also usually more demanding regarding computational
+effort and the required geodata and are more sensitive to data uncertainties.  Compared
+with numerical approximations of the Richards equation, they are less flexible (e.g.
+because of neglecting soil heterogeneities) but more stable and efficient (as they rely
+on relatively simple ordinary instead of highly-stiff partial differential equations).
+
+So far, |ga_garto| is the only HydPy-GA member usable as a stand-alone model.  It
+implements GARTO, a "Green-Ampt infiltration with Redistribution" model that
+"incorporates features from the Talbot-Ogden infiltration and redistribution method"
+:cite:p:`ref-Lai2015`.  It should outperform simpler Green-Ampt approaches when
+simulating complex rainfall events that include significant low-intensity subperiods.
+
+Hydrologically, |ga_garto_submodel1| works like |ga_garto|, Technically, it is a
+submodel that can hook into larger main models like |lland_dd| to include (additional)
+surface runoff due to infiltration excess into simulations.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   ga
+   ga_garto
+   ga_garto_submodel1

hydpy/docs/rst/HydPy-H.rst

@@ -0,0 +1,24 @@
+
+.. _HydPy-H:
+
+HydPy-H (HBV)
+=============
+
+*HydPy* implements a very close emulation of the central routines of the famous HBV96
+model, introduced by :cite:t:`ref-Lindstrom1997HBV96`.  As discussed by
+:cite:t:`ref-Tyralla2013`, the results of |hland_96| and the IHMS-HBV96 implementation
+of the Swedish Meteorological and Hydrological Institute agree very well for the tested
+river basins.  This documentation focusses on technical aspects of HydPy-H and tries to
+be as precise as possible regarding the implementation of the process equations.  The
+background of the scientifical development of the HBV96 model is more thoroughly
+covered in :cite:t:`ref-Lindstrom1997HBV96`.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   hland
+   hland_96
+   hland_96p
+   hland_96c

hydpy/docs/rst/HydPy-KinW.rst

@@ -0,0 +1,32 @@
+
+.. _`LARSIM`: http://www.larsim.de/en/the-model/
+
+.. _HydPy-KinW:
+
+HydPy-KinW
+==========
+
+The HydPy-KinW model family provides storage-based routing methods that rely on the
+simplifying kinematic wave assumption.  Currently, all its members follow routing
+methods applied by the `LARSIM`_ model.
+
+For reasons of consistency with the original LARSIM implementation, the names of all
+parameter and sequence classes are German terms and abbreviations.  Additionally, the
+documentation on each parameter or sequence contains an English translation.
+
+.. warning::
+
+   We might change the implemented application models soon.  Backward-incompatible
+   changes might include switching to English variable names, improving numerical
+   performance, or supporting more channel profile geometries.  It is also possbile we
+   drop HydPy-KinW entirely if, for example, alternative routing methods like
+   |musk_mct| prove superior in every respect.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   kinw
+   kinw_williams
+   kinw_williams_ext

hydpy/docs/rst/HydPy-L.rst

@@ -0,0 +1,42 @@
+
+.. _`LARSIM`: http://www.larsim.de/en/the-model/
+.. _`German Federal Institute of Hydrology (BfG)`: https://www.bafg.de/EN
+.. _Bremicker: http://www.larsim.info/fileadmin/files/Dokumentation/FSH-Bd11-Bremicker.pdf
+.. _LARSIM-Entwicklergemeinschaft: http://www.larsim.info/fileadmin/files/Dokumentation/LARSIM-Dokumentation.pdf
+.. _LARSIM Online-Hilfe: http://www.larsim.info/larsim-hilfe/
+.. _KLIWAS: http://www.kliwas.de/KLIWAS/DE/Service/Downloads/Publikationen/abschlussbericht.pdf;jsessionid=C89ED85DF782A3D5FE117808A6129002.live21303?__blob=publicationFile
+
+.. _HydPy-L:
+
+HydPy-L (LARSIM)
+================
+
+*HydPy* implements a close but not exact emulation of the central routines of the
+`LARSIM`_ model, applied by many forecasting centres in Germany and some neighbouring
+countries.  The version 1 application model of *HydPy-L* agrees very well with a LARSIM
+configuration called LARSIM-ME ("ME" stands for Middle Europe), used by the `German
+Federal Institute of Hydrology (BfG)`_ for calculating hydroclimatic scenarios for
+large river basins (see e. g. the `KLIWAS`_ project).
+
+*HydPy-L* is partly based on the original publication on LARSIM (`BREMICKER`_), the
+summary of the theory and the range of applications of LARSIM, which is continuously
+updated by the LARSIM development community (`LARSIM-Entwicklergemeinschaft`_), the
+LARSIM online documentation (`LARSIM Online-Hilfe`_), and some helpful hints of the
+colleagues of the LUBW (Landesanstalt für Umwelt, Messungen und Naturschutz
+Baden-Württemberg) and the HYDRON GmbH.  Some other parts of *HydPy-L* have been
+programmed more independently and were incorporated into the original LARSIM
+implementation later.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   lland
+   lland_dd
+   lland_knauf
+   lland_knauf_ic
+
+For reasons of consistency with the original LARSIM implementation, the names of all
+parameter and sequence classes are German terms and abbreviations.  Additionally, the
+documentation on each parameter or sequence contains an English translation.

hydpy/docs/rst/HydPy-Meteo.rst

@@ -0,0 +1,28 @@
+.. _HydPy-Meteo:
+
+HydPy-Meteo
+===========
+
+The `HydPy-Meteo` model family provides models that calculate meteorological factors.
+One example is |meteo_glob_fao56|, which calculates global and clear sky solar
+radiation.  Application models of other model families, for example, |evap_ret_fao56|,
+require such factors as input.  Users can either prepare the complete time series of
+these factors during preprocessing and let |evap_ret_fao56| read them from files before
+or during a simulation or couple |meteo_glob_fao56| and |evap_ret_fao56| to calculate
+global and clear sky radiation "on the fly".
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   meteo
+   meteo_glob_io
+   meteo_clear_glob_io
+   meteo_psun_sun_glob_io
+   meteo_temp_io
+   meteo_precip_io
+   meteo_glob_fao56
+   meteo_glob_morsim
+   meteo_sun_fao56
+   meteo_sun_morsim

hydpy/docs/rst/HydPy-Musk.rst

@@ -0,0 +1,21 @@
+
+.. _HydPy-Musk:
+
+HydPy-Musk (Muskingum)
+======================
+
+The HydPy-Musk model family provides models that solve the routing problem like the
+classic Muskingum method or its derivatives.  One can understand all application models
+as non-adaptive finite-difference approximations of (extremely) simplified versions of
+the Saint-Vernant equations.  Hence, they are more limited than hydrodynamical
+approaches but are simpler to handle and much more efficient regarding computation
+times.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   musk
+   musk_classic
+   musk_mct

hydpy/docs/rst/HydPy-Rconc.rst

@@ -0,0 +1,17 @@
+
+.. _HydPy-Rconc:
+
+HydPy-Rconc
+===========
+
+All HydPy-Rconc models are submodels that calculate runoff concentration by either the
+convolution of a unit hydrograph or the linear storage cascade approach (Nash-Cascade).
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   rconc
+   rconc_uh
+   rconc_nash

hydpy/docs/rst/HydPy-SW1D.rst

@@ -0,0 +1,49 @@
+
+.. _HydPy-SW1d:
+
+HydPy-SW1D (Shallow Water 1D)
+=============================
+
+All models of the HydPy-SW1D model family serve to solve the 1-dimensional shallow
+water equations.  Opposed to models like |musk_mct|, they do so in a more
+`hydrodynamical` manner, which extends their scope to situations where traditional
+`hydrological` flood routing approaches fail.  Most importantly, they can account for
+backwater effects.  However, this additional functionality comes at the cost of
+increased complexity, as less stable numerical schemes are used, and the different
+parts of a channel network must be coupled more tightly.  The application model
+|sw1d_channel| documentation discusses the first and the application model
+|sw1d_network| documentation discusses the second topic.
+
+The available application models are responsible for different tasks. sw1d_channel is a
+"normal" main model that is associated with |Element| object as usual.  The
+particularity is that one usually does not apply |sw1d_channel| to perform simulations.
+Behind the scenes, *HydPy* couples all |sw1d_channel| models (or, more precisely, the
+involved submodels) belonging to the same |Element.collective| and delegates the actual
+simulation work to an automatically generated |sw1d_network| instance.
+
+By themself, |sw1d_channel| and |sw1d_network| provide little "hydrodynamical"
+functionality.  Instead, they rely on submodels compatible with a finite volume
+staggered grid discretisation.  First, they need submodels following the
+|StorageModel_V1| interface (as |sw1d_storage|) for keeping track of the amount of
+water stored in a channel segment.  Second, they need submodels for providing the
+inflow into the upper segments (like |sw1d_q_in|, which follows the |RoutingModel_V1|
+interface), for calculating the flow between channel segments (like |sw1d_lias|, which
+follows the |RoutingModel_V2| interface), and for removing water from the lower
+segments (like |sw1d_weir_out|, which follows the |RoutingModel_V3| interface).
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   sw1d
+   sw1d_channel
+   sw1d_network
+   sw1d_storage
+   sw1d_q_in
+   sw1d_lias
+   sw1d_lias_sluice
+   sw1d_pump
+   sw1d_q_out
+   sw1d_weir_out
+   sw1d_gate_out

hydpy/docs/rst/HydPy-Test.rst

@@ -0,0 +1,19 @@
+
+.. _HydPy-Test:
+
+HydPy-Test
+==========
+
+The HydPy-Test base model is thought for providing simple test models to test and
+explain the functionality of some framework features.   So far, three applications
+models for testing numerical integration algorithms are available.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   test
+   test_stiff0d
+   test_stiff1d
+   test_discontinous

hydpy/docs/rst/HydPy-W.rst

@@ -0,0 +1,20 @@
+
+.. _`WALRUS`: https://www.wur.nl/en/Research-Results/Chair-groups/Environmental-Sciences/Hydrology-and-Quantitative-Water-Management-Group/Research/WALRUS-1.htm
+
+.. _HydPy-W:
+
+HydPy-W (WALRUS)
+================
+
+The HydPy-W model family is based on the `WALRUS`_ model, specifically designed to
+simulate surface water fluxes in lowland catchments influenced by near-surface
+groundwater :cite:`ref-Brauer2014`.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   wland
+   wland_wag
+   wland_gd

hydpy/docs/rst/HydPy-WHMod.rst

@@ -0,0 +1,19 @@
+
+.. _HydPy-WHMod:
+
+HydPy-WHMod
+===========
+
+The HydPy-WHMod model family provides hydrological models for analysing and predicting
+various aspects of the water balance at specific sites and larger areas.  It focusss on
+SVAT-like descriptions of vertical processes.  The basic model concept was initially
+developed by :cite:t:`ref-Probst2002`.
+
+Base model:
+
+.. toctree::
+   :maxdepth: 1
+
+   whmod
+   whmod_rural
+   whmod_urban

hydpy/docs/rst/HydPy-WQ.rst

@@ -0,0 +1,20 @@
+
+.. _HydPy-WQ:
+
+HydPy-WQ
+========
+
+All HydPy-WQ models are "function-like" submodels that calculate discharge based on
+information like the current water level, as needed, for example,  for flood routing.
+We intend to increase the number of available submodels and possible main models
+step-wise to give users more freedom in choosing the preferred approach.
+
+Available models:
+
+.. toctree::
+   :maxdepth: 1
+
+   wq
+   wq_trapeze
+   wq_trapeze_strickler
+   wq_walrus

hydpy/docs/rst/additional_repositories.rst

@@ -0,0 +1,40 @@
+
+.. _HydPy project page: https://github.com/hydpy-dev
+.. _hydpy repository: https://github.com/hydpy-dev/hydpy
+.. _Delft-FEWS-demos repository: https://github.com/hydpy-dev/Delft-FEWS-demos
+.. _Delft-FEWS: https://oss.deltares.nl/web/delft-fews
+.. _OpenDA repository: https://github.com/hydpy-dev/OpenDA
+.. _OpenDA: http://openda.org/
+.. _Dud: https://github.com/hydpy-dev/OpenDA/blob/master/demos/openda_projects/DUD/README.rst
+.. _Travis CI: https://travis-ci.com/
+.. _AppVeyor: https://www.appveyor.com/
+
+.. _additional_repositories:
+
+Additional repositories
+_______________________
+
+The `HydPy project page`_ does not only contain the `hydpy repository`_
+itself, but also repositories for *HydPy* extensions.  At the time of
+writing, there is the `Delft-FEWS-demos repository`_, providing
+configuration files for using *HydPy* within `Delft-FEWS`_, and the
+`OpenDA repository`_, providing a based wrapper wrapper for optimising
+*HydPy* simulations with `OpenDA`_.  Additional repositories should be
+created for all new *HydPy* functionalities not integrating naturally
+into its source files.  The `OpenDA`_ wrapper, for example, must respect
+both the logic of `OpenDA`_ and *HydPy*.  Programming such a wrapper
+within the main `hydpy repository`_ would impair the consistency and
+thus the maintainability of *HydPy*.
+
+We cannot give clear recommendations on the design of additional
+repositories, due to their potentially very diverse nature (for example,
+the `Delft-FEWS-demos repository`_ is primarily XML based, and the
+`OpenDA repository`_ is primarily Java based).  At least, try to
+compile online documentation pages comparable to the ones of *HydPy*.
+For example, we added linked *README* files to the subfolders of the
+`OpenDA repository`_, which seems to be an acceptable lightweight alternative.
+When following the *rst* file format instead of the commonly used *md*
+file format, one can even include doctests into such *README* files,
+as we did for explaining the `Dud`_ algorithm.  Ideally, one would also
+test the code and build the sources on `Travis CI`_ or `AppVeyor`_, but t
+here might be software or license restrictions preventing this.

hydpy/docs/rst/auxiliaries.rst

@@ -0,0 +1,31 @@
+
+.. _auxiliaries:
+
+Auxiliary Tools
+===============
+
+The `auxs` subpackage provides features that are not essential for the functionality of
+HydPy in general, but possibly help when implementing new models or writing workflow
+scripts.
+
+The available `auxs` modules cover diverse topics, ranging from hydrological approaches
+like calculating Unit Hydrograph ordinates (|iuhtools|) to pure mathematical issues
+like numerical integration (|quadtools|). A short look into each module's general
+description should help determine its purpose.
+
+
+.. toctree::
+   :hidden:
+
+   anntools
+   armatools
+   calibtools
+   interptools
+   iuhtools
+   networktools
+   ppolytools
+   quadtools
+   roottools
+   smoothtools
+   statstools
+   validtools

hydpy/docs/rst/continuous_integration.rst

@@ -0,0 +1,75 @@
+.. _GitHub: https://github.com
+.. _Travis CI: https://travis-ci.com/
+.. _AppVeyor: https://www.appveyor.com/
+.. _hydpy repository: https://github.com/hydpy-dev/hydpy
+.. _Travis log-page: https://travis-ci.com/hydpy-dev/hydpy
+.. _AppVeyor log-page: https://ci.appveyor.com/project/tyralla/hydpy/history
+.. _travis.yml: https://github.com/hydpy-dev/hydpy/blob/master/.travis.yml
+.. _setup.py: https://github.com/hydpy-dev/hydpy/blob/master/setup.py
+.. _GitHub pages: https://pages.github.com/
+.. _appveyor.yml: https://github.com/hydpy-dev/hydpy/blob/master/appveyor.yml
+.. _Python Package Index: https://pypi.org/project/HydPy/
+
+.. _continuous_integration:
+
+Continuous Integration
+______________________
+
+To contribute to the code base of *HydPy*, you need a copy of its sources
+(a separate fork, see section :ref:`version_control`).  The existence
+of multiple copies of the same code bears the danger of integration problems
+due to incompatible changes.  An obvious problem is when two developers
+introduce different changes to the same code lines. However, even untuned
+changes in separate code sections can break functionalities.  As a means to
+reduce such risks, different working copies should be synchronised
+"continuously".  Taking the code changes of colleagues into account as often
+as possible decreases the likelihood of simultaneous changes to the same code
+sections and keeps the complexity of possible conflicts to a minimum.
+
+The online development of *HydPy* relies, besides `GitHub`_, on `Travis CI`_
+and `AppVeyor`_.  Both are a hosted, distributed continuous integration
+services.  They are configured to check and eventually release new *HydPy*
+versions in different ways.  Each time someone suggests changes to the
+`hydpy repository`_, either via a direct commit or a pull request (see
+section :ref:`version_control`), `GitHub`_ sends a message to the servers of
+`Travis CI`_ and `AppVeyor`_.  They then download the new source code,
+examine it, and log their results to the `Travis log-page`_ and the
+`AppVeyor log-page`_, respectively.
+
+`travis.yml`_ defines the following `Travis CI`_ workflow:
+
+  * Download and install all *HydPy* dependencies on the Debian based
+    Linux operating system Ubuntu separately for each currently
+    supported CPython version.
+  * Call `setup.py`_ to copy *HydPy* to the site-packages folder and
+    build some additional files (e.g. Dynamic Link Library files).
+    For reasons of measuring code coverage, `setup.py`_ also triggers
+    all "conventional" unit tests and doctests.
+  * Prepare a test coverage report (see section :ref:`tests_and_documentation`).
+  * Generate the online documentation (for the latest stable Python version).
+  * Publish the online documentation on `GitHub pages`_ in case the
+    build process succeeded, all tests passed, and no formatting errors
+    or wrong links corrupted the documentation. Additionally, the evaluated
+    branch must be the master branch.
+
+The workflow defined by `appveyour.yml` is as follows:
+
+  * As on `Travis CI`_, download and install all *HydPy* dependencies for
+    each supported CPython version, but on Windows Server instead of Linux.
+  * As on `Travis CI`_, call `setup.py`_ to install *HydPy*, but do not
+    measure code coverage.
+  * Create binary distributions for the respective Python versions based
+    on the extension files generated in the last step.
+  * Remove the already installed files, reinstall *HydPy* based on the
+    new binary distributions, and apply all tests.
+  * Make all artefacts available (currently, besides the binary distributions,
+    the automatically generated XML schema files).
+  * Upload the binary distributions to the `Python Package Index`_  for
+    tagged commits in case all tests passed.
+
+Together, both continuous integration services capture a wide range
+of possible problems, not only addressing the implemented hydrological
+models, but also the release and documentation cycles.  If applied
+regularly, chances are good to trace unexpected errors to specific code
+changes.  Additionally, `Travis CI`_ and `AppVeyor`_ help you to decide
+if contributions by colleagues are mature enough to be merged in your code.

hydpy/docs/rst/core.rst

@@ -0,0 +1,75 @@
+
+.. _core:
+
+Core Tools
+==========
+
+The `core` subpackage of HydPy essentially defines how models can and should be
+programmed, documented and applied.  As can be seen in the sidebar, the list of modules
+contained in the core subpackage is quite extensive.  The following paragraphs explain
+which central aspects of using HydPy are related to which module.
+
+Module |hydpytools| provides the |HydPy| class.  This class aims to help users
+accomplish complex things via a simple interface.  Very often, you will only need to
+initialise an |HydPy| object and call its methods to, for example, load all input data,
+perform a simulation run, and store the relevant results.  So, getting an overview of
+the methods of class |HydPy| is generally a good idea.
+
+Module |filetools| defines the standard directory structure of HydPy projects and its
+possible modifications.  Also, it is responsible for many aspects of loading data from
+files and storing data in files.  It is supplemented by module |netcdftools| for
+reading data from and storing data to NetCDF files.
+
+HydPy represents the network of a river basin via connected objects of the classes
+|Node| and |Element|, defined in module |devicetools|.  It is often helpful to create
+subsets of networks named "selections", for which module |selectiontools| provides some
+convenient features.  (In this context, reading the documentation on module
+|networktools| might also be interesting, as this module implements strategies to
+derive networks for large basins.)
+
+The modules |modeltools|, |parametertools|, and |sequencetools| form the basis for
+programming models.  While |modeltools| focuses on the more general aspects,
+|parametertools|, and |sequencetools| cover the more specific topics of implementing
+model parameters and sequences.
+
+
+Module |timetools| provides multiple classes that wrap the "date and time"
+functionalities of the Python standard library to simplify and standardise the related
+operations (which are prone to hard-to-detect errors) in workflow scripts.
+
+If you are thinking about contributing to HydPy's source code, you should also read the
+documentation of some other modules.  Then, essential are |autodoctools| (deals with
+automatised generation of this online documentation), |testtools| (provides features
+for automatised testing via doctests), |objecttools| (contains different kinds of
+features to simplify and standardise writing HydPy code), and |typingtools| (makes
+general and HydPy-specific type hint features available).
+
+.. toctree::
+   :hidden:
+
+   aliastools
+   autodoctools
+   auxfiletools
+   devicetools
+   exceptiontools
+   filetools
+   hydpytools
+   importtools
+   indextools
+   itemtools
+   masktools
+   modeltools
+   netcdftools
+   objecttools
+   optiontools
+   parametertools
+   printtools
+   propertytools
+   pubtools
+   selectiontools
+   sequencetools
+   seriestools
+   testtools
+   timetools
+   typingtools
+   variabletools

hydpy/docs/rst/cythons.rst

@@ -0,0 +1,47 @@
+
+.. _cythons:
+
+Cython Tools
+============
+
+The modules of the `cythons` subpackage should only be of interest to framework
+developers (and eventually some model developers).
+
+The most crucial module (and so far the only one which is a Python module) is
+|modelutils|, which implements the routines to translate Python code into Cython code,
+to translate Cython code into C code, to compile C code, and to embed the compilation
+into a "Python dll" (a "pyd" file on Windows and a "so" file on Linux systems).
+
+The other modules are Cython extension modules.  Often, they are named similar to the
+Python modules of other packages (for example, |anntools| and :ref:`annutils`).  The
+respective Cython extension module then implements the performance-critical part of the
+required functionality.
+
+The required dll files are shipped with the available HydPy wheels or automatically
+generated when building HydPy locally.  You can find them in the `cythons` subpackage
+`autogen`.  The same holds for the dll files of the "cythonized"  hydrological models.
+
+If you want to change a model in Python (for example, for testing) and also want to
+update its cythonized counterpart, use the responsible |Cythonizer| instance, which is
+a member of the subpackage (in case of a base model) or module (in case of an
+application model).
+
+Note that it is more effort to maintain Cython code than to maintain Python code.  So
+please refrain from writing Cython code when the expected computational time gain is
+small or when Python offers other strategies to decrease computation times.
+
+
+.. toctree::
+   :hidden:
+
+   annutils
+   configutils
+   interfaceutils
+   interputils
+   modelutils
+   pointerutils
+   ppolyutils
+   quadutils
+   rootutils
+   sequenceutils
+   smoothutils