Introducing earthkit-hydro: an efficient graph-based library for scalable hydrological modelling and analysis

Although numerical representations of river networks are fundamental to hydrological modelling and analysis, their performant and flexible use remains challenging due to inherent spatial dependencies and graph-based structure. Many existing tools are constrained by limited computational efficiency and a lack of support for diverse river network formats. This makes it difficult to compare and analyse data and model outputs from multiple sources.

To address these limitations, we present earthkit-hydro, the hydrological component of ECMWF’s earthkit software for Earth system science workflows. Earthkit-hydro provides a unified interface for operations on river networks, including accumulations, catchment-level statistics, catchment delineation, distance calculations, and computing topological properties. The library supports a wide range of river network formats, including bifurcating river networks, and integrates with major Python array libraries such as NumPy, Xarray, PyTorch, and JAX. In addition, earthkit-hydro is well suited for machine-learning applications, offering GPU support and differentiable operations.

We also present an application to AIFL, ECMWF’s global machine-learning model for streamflow prediction. In this context, earthkit-hydro provides an efficient way of processing ECMWF’s meteorological forecasts by transforming meteorological variables into the catchment-based metrics required as input by AIFL.