Hydpy

With HydPy 6.1, we switch to a tighter release cycle. Compared to HydPy 6.0, there are a few breaking changes, but those require, at most, little client code adjustments (ask you type checker) and do not change any functionality. Hence, the transition from 6.0 to 6.1 should be smooth.

Here is the list of the most notable new features, documentation improvements, and fixes.

New features:

- The different file managers (for example, the [ConditionManager](https://hydpy-dev.github.io/hydpy/6/filetools.html#hydpy.core.filetools.ConditionManager)) now print a note when they create or remove a directory. This feature can be turned off by setting [printprogress](https://hydpy-dev.github.io/hydpy/6/optiontools.html#hydpy.core.optiontools.Options.printprogress) to `False`.
- The new "script function" [xml_validate](https://hydpy-dev.github.io/hydpy/6/xmltools.html#hydpy.exe.xmltools.xml_validate) allows to check if an XML workflow file fits to XSD schema definition file of the relevant HydPy version from the command line.
- Reading time series from or writing time series to NetCDF files via the related methods of the classes [HydPy](https://hydpy-dev.github.io/hydpy/6/hydpytools.html#hydpy.core.hydpytools.HydPy), [Elements](https://hydpy-dev.github.io/hydpy/6/devicetools.html#hydpy.core.devicetools.Elements), and [Nodes](https://hydpy-dev.github.io/hydpy/6/devicetools.html#hydpy.core.devicetools.Nodes) now works "automatically", meaning one has not to bother with manually opening and closing NetCDF reader and writer objects anymore.
- The option [reprdigits](https://hydpy-dev.github.io/hydpy/6/optiontools.html#hydpy.core.optiontools.Options.reprdigits) now controls the number format for writing ASCII time series files. By default, all numbers are written in scientific notation (consistent with HydPy 6.0). If you set [reprdigits](https://hydpy-dev.github.io/hydpy/6/optiontools.html#hydpy.core.optiontools.Options.reprdigits) to two, for example, all numbers are written in the decimal form with at most two decimal places
- Class [ConditionManager](https://hydpy-dev.github.io/hydpy/6/filetools.html#hydpy.core.filetools.ConditionManager) now has the option [prefix](https://hydpy-dev.github.io/hydpy/6/filetools.html#hydpy.core.filetools.ConditionManager.prefix) for changing the prefix of the automatically determined, time-dependent condition directory names. This feature eases, for example, to read the initial conditions of different ensemble members from separate directories
- All subelements of `<conditions_io>` in XML workflow files are now optional. Making the XML elements `<inputpath>` and `<outputpath>` optional was necessary because otherwise, the new element `<prefix>` would be generally impactless. Making the XML element `<zip>` optional was primarily for consistency but also for convenience, as its default value `false` should apply to most use cases.
- When using HydPy from the command line, you can now select two alternative error styles (`single_line` and `splittable`) to squeeze printed error messages in single lines, which is more easily processable for tools like [Delft-FEWS](https://oss.deltares.nl/web/delft-fews). The old behaviour is now named `multiline` and the default of the new `errorstyle` option. For more information, please look at the documentation for the central [hyd.py](https://hydpy-dev.github.io/hydpy/6/hyd.html) script.
- Function [summarise_ncfile](https://hydpy-dev.github.io/hydpy/6/netcdftools.html#hydpy.core.netcdftools.summarise_ncfile) now automatically determines and prints the time grid of the analysed NetCDF file if it has the `time reference` attribute defined.
- The new functions [create_projectstructure](https://hydpy-dev.github.io/hydpy/6/filetools.html#hydpy.core.filetools.create_projectstructure) and [check_projectstructure](https://hydpy-dev.github.io/hydpy/6/filetools.html#hydpy.core.filetools.check_projectstructure) create and check the basic directory structure of a HydPy project. By default, checking also happens automatically when initialising class [HydPy](https://hydpy-dev.github.io/hydpy/6/hydpytools.html#hydpy.core.hydpytools.HydPy). This feature can be turned off by setting [checkprojectstructure](https://hydpy-dev.github.io/hydpy/6/optiontools.html#hydpy.core.optiontools.Options.checkprojectstructure) to `False`.

Documentation improvements:

- We added the [Simulation](https://hydpy-dev.github.io/hydpy/6/simulation.html#simulation) section to the [User Guide](https://hydpy-dev.github.io/hydpy/6/user_guide.html). It explains semi-comprehensively performing a simulation run via Python scripts or XML workflow files. It should build a bridge between the [Quick Start's](https://hydpy-dev.github.io/hydpy/6/quickstart.html) introductory remarks and the [Reference Manual's](https://hydpy-dev.github.io/hydpy/6/reference_manual.html) extremely detailed explanations.
- The new [Creating an Environment](https://hydpy-dev.github.io/hydpy/6/installation.html#creating-an-environment) section of the [Installation Instructions](https://hydpy-dev.github.io/hydpy/6/installation.html) introduces to using virtual environments for the robust installation of, for example, different HydPy versions on the same computer.

Fixes:

- Reading initial conditions files with initial condition data already in RAM (for example, resulting from a previous simulation run) could result in unnecessary trimmings of the read values. The user was warned but had to solve the problem himself (for example, by deleting the data first and rereading the files afterwards). We fixed this issue by applying the "postponed trimming" strategy already implemented for resetting data via dictionaries.

In HydPy 6.0.0, when iterating through the individual [Timegrid](https://hydpy-dev.github.io/hydpy/6/timetools.html#hydpy.core.timetools.Timegrid) instances handled by an instance of class [Timegrids](https://hydpy-dev.github.io/hydpy/6/timetools.html#hydpy.core.timetools.Timegrids), [eval_](https://hydpy-dev.github.io/hydpy/6/timetools.html#hydpy.core.timetools.Timegrids.eval_) was skipped. We fixed this in commit a32142d4ff4e52af823963f3151155bbeec355ea.

We are happy to announce the release of HydPy 6.0, which comes with many documentation improvements, lots of new models, and, most importantly, a boost in flexibility in combining different model components.


Documentation improvements
----------------------------------

We gave the documentation a new structure. Beginners will find it convenient that it now differentiates between a [User Guide](https://hydpy-dev.github.io/hydpy/6/user_guide.html), which offers a basic introduction to HydPy, and a [Reference Manual](https://hydpy-dev.github.io/hydpy/6/reference_manual.html), which explains everything in depth. We included introductory tutorials (and plan to add tutorials that cover more complex use cases soon) based on the reworked [HydPy-H-Lahn example project](https://hydpy-dev.github.io/hydpy/6/example_projects.html).


Submodel concept
---------------------

Previously, one could easily combine models of different "families" in one project (for example, of [HydPy-H(BV)](https://hydpy-dev.github.io/hydpy/6/HydPy-H.html) and [HydPy-L(ARSIM)](https://hydpy-dev.github.io/hydpy/6/HydPy-L.html). However, no out-of-the-box mechanism existed for creating new combinations of different model components. Therefore, HydPy 6.0 introduces the *Submodel concept*. It allows, for example, to set up an HBV-like model that calculates evaporation similar to LARSIM.

So far, the new *Submodel concept* has been widely rolled out for meteorological factors like global radiation and evapotranspiration, and it at least partly covers topics like runoff concentration and flow formulas. We will modularise more model components in future HydPy versions. See the *Submodel Graph* in the new [Model overview](https://hydpy-dev.github.io/hydpy/6/model_overview.html) section for a complete list of the currently possible (and advisable) model compositions.


New models
--------------

At first sight, HydPy 6.0 comes with a multitude of new models. However, many are just new *submodels* that we extracted from already existing *main models* (the new [Definitions](https://hydpy-dev.github.io/hydpy/6/definitions.html) section explains these terms in detail). For example, [HydPy-Evap-PET-HBV96](https://hydpy-dev.github.io/hydpy/6/evap_pet_hbv96.html) stems from [HydPy-H-HBV96](https://hydpy-dev.github.io/hydpy/6/hland_96.html).

Nevertheless, there are still some truly new models worth mentioning:

- [HydPy-Evap-PET-AMBAV-1.0](https://hydpy-dev.github.io/hydpy/6/evap_pet_ambav1.html) calculates potential evapotranspiration in agreement with the AMBAV 1.0 model of the Deutscher Wetterdienst.
- [HydPy-Dam](https://hydpy-dev.github.io/hydpy/6/HydPy-Dam.html) contains three new models for modelling pumps and sluices.
- The new model family [HydPy-GA](https://hydpy-dev.github.io/hydpy/6/HydPy-GA.html) is supposed to provide Green-Ampt infiltration models. The first available models implement the [GARTO](https://hydpy-dev.github.io/hydpy/6/ga_garto.html) method, which can be used both as a *main model* to simulate infiltration excess overland flow for complex rainfall events independently and as a *submodel* to refine the volume-based runoff generation approach of [HydPy-L(ARSIM)](https://hydpy-dev.github.io/hydpy/6/HydPy-L.html).
- The new model family [HydPy-SW1D](https://hydpy-dev.github.io/hydpy/6/HydPy-SW1D.html) introduces "hydrodynamic flood routing" to HydPy. It aims to robustly solve the 1-dimensional shallow water equations in river and channel networks. So, HydPy can now deal much better with catchments in lowland regions where hydraulic structures like weirs and sluices or tidal effects play a major role.


Model name changes
------------------------

HydPy's model names were too cryptic, so we switched to more descriptive ones. For example, [hland_v1 or HydPy-H-Land Version 1](https://hydpy-dev.github.io/hydpy/5.0/hland_v1.html) is from now on [hland_96 or HydPy-H-HBV96 (adoption of SMHI-IHMS-HBV96)](https://hydpy-dev.github.io/hydpy/6/hland_96.html). You can find a complete list of all renamings [here](https://github.com/hydpy-dev/hydpy/issues/99).

This is the first pre-release of HydPy 6.0. Almost all of its new features have been implemented. Please look at issue 122 for the things still to come, which are mainly documentation-related.

We now support NumPy 1 and 2 (see issue 147). We included both in our test suites, but the now consistent usage of 64-bit integers (and floats) on all systems and all NumPy versions might cause unexpected inconveniences. Please open an issue if you encounter any problems.

This release includes minor adjustments to make HydPy 5.0 compatible with older versions of NumPy (tested against NumPy 1.22).

This release contains minor technical improvements compared to 5.0.1 and, more importantly, some adjustments to recent site-package changes (e.g. of [NumPy](https://numpy.org/)). Its wheels are also available for Python 3.11, the latest Python version.