Ravenpy

--------------------

This release is primarily a bugfix to address issues arising from dependencies.

Breaking changes
^^^^^^^^^^^^^^^^
* `raven-hydro` version has been bumped from v0.2.1 to v0.2.3. This version provides better support for builds on Windows and MacOS.
* Due to major breaking changes, `pydantic` has been pinned below v2.0 until changes can be made to adapt to their new API.
* `numpy` has been pinned below v1.25.0 to ensure compatibility with `numba`.

Internal changes
^^^^^^^^^^^^^^^^
* ``test_geoserver::test_select_hybas_ar_domain_point`` is now temporarily skipped when testing on MacOS due to a mysterious domain identification error.

--------------------

This release is largely a bugfix to better stabilize performance and enhance the documentation.

* Avoid repeatedly calling `xr.open_dataset` in `OutputReader`'s `hydrograph` and `storage` properties. This seems to cause kernel failures in Jupyter notebooks.

Internal changes
^^^^^^^^^^^^^^^^
* Hyperlinks to documented functions now points to entries in the `User API` section.
* Docstrings are now more conformant to numpy-docstring conventions and formatting errors raised from badly-formatted pydantic-style docstrings have been addressed.
* In order to prevent timeout and excessive memory usage, Jupyter notebooks have been adjusted to no longer run on ReadTheDocs. All notebooks have been updated to the latest RavenPy and remain tested against RavenPy externally.
* Documentation built on ReadTheDocs is now set to `fail_on_warning`.

--------------------

This release includes major breaking changes. It completely overhauls how models are defined, and how to run
simulations, and any code relying on the previous release will most likely break. Please check the documentation
to see how to use the new improved interface.

Breaking changes
^^^^^^^^^^^^^^^^
* The entire model configuration and simulation interface (see PR 269).
* The Raven model executable is now updated to v3.7.
* Added support for Ensemble Kalman Filter using RavenC.
* Now employing the `spotpy` package for model calibration instead of `ostrich`.
* BasinMaker importer assumes `SubBasin=HRU` in order to work with files downloaded from the BasinMaker web site.
* Ravenpy now employs a new method for installing the Raven model using the `raven-hydro <https://github.com/Ouranosinc/raven-hydro>`_ python package (based on `scikit-build-core`) (see PR #278).
* Replaced `setup.py`, `requirements.txt`, and `Manifest.in` for `PEP 517 <https://peps.python.org/pep-0517>`_ compliance (`pyproject.toml`) using the flit backend (see PR #278).
* Dealt with an import-based error that occurred due to the sequence in which modules are loaded at import (attempting to call ravenpy before it is installed).
* Updated pre-commit hooks to include formatters and checkers for TOML files.
* The build recipes no longer build on each other, so when installing the `dev` or `docs` recipe, you must also install the gis recipe.
* Updated the GeoServer API calls to work with the GeoPandas v0.13.0.

--------------------

* Update RavenC executable to v3.6.
* Update xclim library to v0.40.0.
* Update fiona library to v1.9.
* Address some failures that can be caused when attempting to run CLI commands without the proper GIS dependencies installed.
* Addressed warnings raised in conda-forge compilation due to badly-configured MANIFEST.in.
* Update installation documentation to reflect most recent changes.

--------------------

* Update Raven executable to 3.5. Due to a bug in RavenC, simulations storing reservoir information to netCDF will fail. We expect this to be resolved in the next release. Note that we only test RavenPy with one Raven version. There is no guarantee it will work with other versions.
* Relax geo test to avoid failures occurring due to GDAL 3.6.
* Pin numpy below 1.24 (see https://github.com/numba/numba/issues/8615)

-------------------

Breaking changes
^^^^^^^^^^^^^^^^
* HRUState's signature has changed. Instead of passing variables as keyword arguments (e.g. `soil0=10.`), it now expects a `state` dictionary keyed by variables' Raven name (e.g. `{"SOIL[0]": 10}). This change makes `rvc` files easier to read, and avoids Raven warnings regarding 'initial conditions for state variables not in model'.
* `nc_index` renamed to `meteo_idx` to enable the specification of distinct indices for observed streamflow using `hydro_idx`. `nc_index` remains supported for backward compatibility.
* The distributed python testing library, `pytest-xdist` is now a testing and development requirement.
* `xarray` has been pinned below "2022.11.0" due to incompatibility with `climpred=="2.2.0"`.

New features
^^^^^^^^^^^^
* Add support for hydrometric gauge data distinct from meteorological input data. Configuration parameter `hydro_idx` identifies the gauge station index, while `meteo_idx` (previously `nc_index`) stands for the meteo station index.
* Add support for multiple gauge observations. If a list of `hydro_idx` is provided, it must be accompanied with a list of corresponding subbasin identifiers (`gauged_sb_ids`) of the same length.
* Automatically infer scale and offset `:LinearTransform` parameters from netCDF file metadata, so that input data units are automatically converted to Raven-compliant units whenever possible.
* Add support for the command `:RedirectToFile`. Tested for grid weights only.
* Add support for the command `:WriteForcingFunctions`.
* Add support for the command `:CustomOutput`.
* Multiple other new RavenCommand objects added, but not integrated in the configuration, including `:SoilParameterList`, `:VegetationParameterList` and `:LandUseParameterList`.
* Multichoice options (e.g. calendars) moved from RV classes to `config.options`, but aliases created for backward compatibility.
* Patch directory traversal vulnerability (`CVE-2007-4559 <https://github.com/advisories/GHSA-gw9q-c7gh-j9vm>`_).
* A local copy of the raven-testdata with environment variable (`RAVENPY_TESTDATA_PATH`) set to that location is now no longer needed in order to run the testing suite. Test data is fetched automatically and now stored at `~/.raven_testing_data`.
* RavenPy now leverages `pytest-xdist` to distribute tests among Python workers and significantly speed up the testing suite, depending on number of available CPUs. File access within the testing suite has also been completely rewritten for thread safety.
- On pytest launch with "`--numprocesses` > 0", testing data will be fetched automatically from `Ouranosinc/raven-testdata` by one worker, blocking others until this step is complete. Spawned pytest workers will then copy the testing data to their respective temporary directories before beginning testing.
* To aid with development and debugging purposes, two new environment variables and pytest fixtures are now available:
- In order to skip the data collection step: `export SKIP_TEST_DATA=true`
- In order to target a specific branch of `Ouranosinc/raven-testdata` for data retrieval: `export MAIN_TESTDATA_BRANCH="my_branch"`
- In order to fetch testing data using the user-set raven-testdata branch, pytest fixtures for `get_file` and `get_local_testdata` are now available for convenience