earthkit-hydro 1.3.0

A Python library for common hydrological functions

Installation • Documentation

[!IMPORTANT] This software is Graduated and subject to ECMWF's guidelines on Software Maturity.

earthkit-hydro is a Python library for common hydrological functions. It is the hydrological component of earthkit.

Main Features

• 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

Copyright 2024, European Centre for Medium Range Weather Forecasts.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

In applying this licence, ECMWF does not waive the privileges and immunities
granted to it by virtue of its status as an intergovernmental organisation
nor does it submit to any jurisdiction.

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}
}