bakaano-hydro 1.2.1

Distributed hydrology-guided neural network for streamflow prediction

Bakaano-Hydro

Description

Bakaano-Hydro is a distributed hydrology-guided neural network model for streamflow prediction. It uniquely integrates physically based hydrological principles with the generalization capacity of machine learning in a spatially explicit and physically meaningful way. This makes it particularly valuable in data-scarce regions, where traditional hydrological models often struggle due to sparse observations and calibration limitations, and where current state-of-the-art data-driven models are constrained by lumped modeling approaches that overlook spatial heterogeneity and the inability to capture hydrological connectivity.

By learning spatially distributed, physically meaningful runoff and routing dynamics, Bakaano-Hydro is able to generalize across diverse catchments and hydro-climatic regimes. This hybrid design enables the model to simulate streamflow more accurately and reliably—even in ungauged or poorly monitored basins—while retaining interpretability grounded in hydrological processes.

Key Features

• Distributed architecture: Captures spatial heterogeneity of hydrological processes using gridded runoff and flow routing.
• Hybrid modeling: Combines physically based hydrology with deep learning for enhanced accuracy and realism.
• Scalable and generalizable: Trains a single model across basins, regions, or continents—no need for basin-specific calibration.
• Reliable in data-scarce regions: Designed to perform well even with sparse observational data.
• High-performance ready: Compatible with GPU acceleration for fast training and inference on large-scale datasets.
• Seamless integration: Modular components allow for easy adaptation with other runoff models, routing schemes, or neural network architectures.
• Automated end-to-end pipeline: From climate data ingestion and preprocessing to runoff simulation, routing, and streamflow prediction—Bakaano-Hydro automates the entire workflow with minimal user intervention.
• Easy deployment: Installable via pip and designed with reproducibility in mind.
• Versatile applications: Suitable for streamflow forecasting, climate adaptation planning, flood risk assessment, and more.

Installation

Bakaano-Hydro is built on TensorFlow and is designed to leverage GPU acceleration for training. This requires a system with an NVIDIA GPU installed or bundled CUDA and cuDNN runtime libraries. GPU acceleration is strongly recommended for training deep learning components and running large-scale simulations, as it significantly improves speed and scalability.

If you have a compatible NVIDIA GPU and drivers installed, install with:

pip install bakaano-hydro[gpu]

This will automatically install the correct version of TensorFlow along with CUDA and cuDNN runtime libraries

If you do not have access to a GPU, you can still install and use Bakaano-Hydro in CPU mode (e.g., for inference, testing or small-scale evaluation):

pip install bakaano-hydro

Note: Training on CPU is supported but will be significantly slower, especially on large datasets or deep learning tasks.

Getting started / Example notebooks

Bakaano-Hydro requires three primary data or inputs

1. Shapefile of study area or river basin
2. Observed streamflow data in NetCDF format from Global Runoff Data Center (https://portal.grdc.bafg.de/applications/public.html?publicuser=PublicUser#dataDownload/Home). Because Bakaano-Hydro aims to use only open-source data, it currently accepts observed streamflow data only from GRDC.
3. Registration at Google Earth Engine (https://code.earthengine.google.com/register). Bakaano-Hydro retrieves, NDVI, tree cover and meteorological variables from ERA5-land or CHIRPS from Google Earth Engine Data Catalog. This platform requires prior registration for subsequent authentication during execution of the model

Model execution then involves only a few guided steps. See the quick start notebook https://github.com/confidence-duku/bakaano-hydro/blob/main/quick_start.ipynb for guidance.

Code architecture

Support

For assistance, please contact Confidence Duku ([e-mail])

Contributing

No contributions are currently accepted.

Authors and acknowledgment

See CITATION.cff file.

Bakaano-Hydro was developed as part of Wageningen University & Research Investment theme 'Data-driven discoveries in a changing climate' and also as part of the KB program 'Climate resilient land use'.

License

Apache License