Metadata-Version: 2.4
Name: earthkit-hydro
Version: 1.4.0
Summary: A Python library for common hydrological functions
Author-email: "European Centre for Medium-Range Weather Forecasts (ECMWF)" <software.support@ecmwf.int>
Maintainer-email: "Oisín M. Morrison" <oisin.morrison@ecmwf.int>, Corentin Carton de Wiart <corentin.carton@ecmwf.int>
License-Expression: Apache-2.0
Project-URL: documentation, https://earthkit-hydro.readthedocs.io/
Project-URL: issues, https://github.com/ecmwf/earthkit-hydro/issues
Project-URL: repository, https://github.com/ecmwf/earthkit-hydro
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: joblib
Requires-Dist: xarray
Requires-Dist: earthkit-utils~=1.0
Provides-Extra: all
Requires-Dist: earthkit-data[geotiff]~=1.0; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: pre-commit; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: nbconvert; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: sphinx_design; extra == "docs"
Provides-Extra: grit
Requires-Dist: geopandas; extra == "grit"
Requires-Dist: pandas; extra == "grit"
Provides-Extra: readers
Requires-Dist: earthkit-data[geotiff]~=1.0; extra == "readers"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: torch; extra == "tests"
Requires-Dist: jax; extra == "tests"
Dynamic: license-file

<p align="center">
  <picture>
    <source srcset="https://github.com/ecmwf/logos/raw/refs/heads/main/logos/earthkit/earthkit-hydro-dark.svg" media="(prefers-color-scheme: dark)">
    <img src="https://github.com/ecmwf/logos/raw/refs/heads/main/logos/earthkit/earthkit-hydro-light.svg" height="120">
  </picture>
</p>

<p align="center">
  <a href="https://github.com/ecmwf/codex/raw/refs/heads/main/ESEE">
    <img src="https://github.com/ecmwf/codex/raw/refs/heads/main/ESEE/foundation_badge.svg" alt="ECMWF Software EnginE">
  </a>
  <a href="https://github.com/ecmwf/codex/raw/refs/heads/main/Project Maturity">
    <img src="https://github.com/ecmwf/codex/raw/refs/heads/main/Project Maturity/graduated_badge.svg" alt="Maturity Level">
  </a>
  <!-- <a href="https://codecov.io/gh/ecmwf/earthkit-hydro">
    <img src="https://codecov.io/gh/ecmwf/earthkit-hydro/branch/develop/graph/badge.svg" alt="Code Coverage">
  </a> -->
  <a href="https://opensource.org/licenses/apache-2-0">
    <img src="https://img.shields.io/badge/Licence-Apache 2.0-blue.svg" alt="Licence">
  </a>
  <a href="https://github.com/ecmwf/earthkit-hydro/releases">
    <img src="https://img.shields.io/github/v/release/ecmwf/earthkit-hydro?color=purple&label=Release" alt="Latest Release">
  </a>
</p>

<p align="center">
  <!-- <a href="#quick-start">Quick Start</a>
  • -->
  <a href="#installation">Installation</a>
  •
  <a href="https://earthkit-hydro.readthedocs.io">Documentation</a>
</p>

> \[!IMPORTANT\]
> This software is **Graduated** and subject to ECMWF's guidelines on [Software Maturity](https://github.com/ecmwf/codex/raw/refs/heads/main/Project%20Maturity).

**earthkit-hydro** is a Python library for common hydrological functions. It is the hydrological component of [earthkit](https://github.com/ecmwf/earthkit).

## Main Features

<table>
  <tr>
    <td><img src="https://raw.githubusercontent.com/ecmwf/earthkit-hydro/refs/tags/1.0.0/docs/images/glofas.png" height="300" alt="Adapted from: doc_figure" /></td>
    <td><img src="https://raw.githubusercontent.com/ecmwf/earthkit-hydro/refs/tags/1.0.0/docs/images/array_backends_with_xr.png" height="300" alt="Array backends with xr" /></td>
  </tr>
</table>

- Catchment delineation
- Catchment-based statistics
- Directional flow-based accumulations
- River network distance calculations
- Upstream/downstream field propagation
- Bifurcation handling
- Custom weighting and decay support
- Support for PCRaster, CaMa-Flood, HydroSHEDS, MERIT-Hydro and GRIT river network formats
- Compatible with major array-backends: xarray, numpy, cupy, torch, jax, mlx and tensorflow
- GPU support
- Differentiable operations suitable for machine learning


## Installation
For a default installation, run

```
pip install earthkit-hydro
```

*Developer instructions:*

For a developer setup (includes linting and test libraries), run

```
conda create -n hydro python=3.12
conda activate hydro
conda install -c conda-forge rust
git clone https://github.com/ecmwf/earthkit-hydro.git
cd earthkit-hydro
pip install -e .[dev]
pre-commit install
```
Note: this project is a mixed Rust-Python project with a pure Python fallback. To handle this, the behaviour of the install is based on an environmental variable `USE_RUST`, with the following behaviour
- `Not set or any other value (default behaviour)`:
Attempts to build with Rust and if failure, skips and falls back to pure Python implementation.
- `USE_RUST=0`:
Builds pure Python implementation.
- `USE_RUST=1`:
Builds with Rust and fails if something goes wrong.


## Licence

```
SPDX-FileCopyrightText: 2026- European Centre for Medium-Range Weather Forecasts (ECMWF)
SPDX-License-Identifier: Apache-2.0
```

See [LICENSE](LICENSE) for the full licence text, including ECMWF's intergovernmental notice.

## Citing

If you use `earthkit-hydro` in your work, please consider citing

> Morrison, O. M. and Carton de Wiart, C.: Introducing earthkit-hydro: an efficient graph-based library for scalable hydrological modelling and analysis, EGU General Assembly 2026, Vienna, Austria, 3–8 May 2026, EGU26-11233, https://doi.org/10.5194/egusphere-egu26-11233, 2026.

```
@inproceedings{Morrison2026,
  author    = {Morrison, Ois{\'\i}n M. and Carton de Wiart, Corentin},
  title     = {Introducing earthkit-hydro: an efficient graph-based library for scalable hydrological modelling and analysis},
  booktitle = {EGU General Assembly 2026},
  year      = {2026},
  series    = {EGU General Assembly Conference Abstracts},
  volume    = {EGU26-11233},
  address   = {Vienna, Austria},
  month     = may,
  doi       = {10.5194/egusphere-egu26-11233},
  url       = {https://doi.org/10.5194/egusphere-egu26-11233}
}
```
