OneScience-Group/Global-Flood-LSTM

Global-Flood-LSTM

Model Introduction

Global-Flood-LSTM is a probabilistic streamflow model for ungauged watersheds worldwide. It combines historical weather, forecast forcing, and basin attributes to predict seven-day flow distributions and extreme-flood reliability.

Paper: Global prediction of extreme floods in ungauged watersheds
https://doi.org/10.1038/s41586-024-07145-1

Model Description

The model was proposed by researchers from Google Research, ECMWF, the Helmholtz Centre for Environmental Research, and RAND Corporation. It was trained with streamflow observations from 5,680 GRDC gauges and inputs from HRES, ERA5-Land, CPC, IMERG, and HydroATLAS. By combining historical and forecast forcings through an encoder-decoder LSTM with probabilistic outputs, it supports seven-day streamflow and extreme-flood forecasting in ungauged basins.

Use Cases

Use Case	Description
Ungauged-basin forecasting	Apply a shared model to basins excluded from training.
Extreme-flood warning	Evaluate precision, recall, and F1.
Probabilistic streamflow	Produce lead-dependent conditional distributions.
Hydrological benchmarking	Compute RMSE and KGE.
ModelScope/OneCode execution	Validate structured data, training, inference, probabilistic precipitation metrics, and visualization in ModelScope or OneCode.
Multi-GPU training	Start multi-process training through torchrun.

Usage Instructions

Download

hf download OneScience-Group/Global-Flood-LSTM --local-dir ./Global-Flood-LSTM
cd Global-Flood-LSTM

Environment Dependencies

Hardware Requirements

• A GPU or DCU is recommended.
• A CPU can run the default small-sample connectivity configuration.
• DCU users should install DTK 25.04.2 or a compatible OneScience-recommended version first.

DCU Environment

# Activate DTK and Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai

GPU Environment

# Activate Conda first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai

Synthetic Data

The paper combines a 365-day meteorological history, seven-day forecast forcing, HydroATLAS attributes, and GRDC daily streamflow over 5,680 basins. Synthetic data preserve the 365-day history, 14 dynamic source channels, seven-day output, and probability-distribution protocol while reducing basin count, hidden width, and training iterations; the static feature count is explicitly an engineering ledger because the paper does not enumerate it. Results verify the workflow only and do not represent paper performance.

python scripts/fake_data.py

Training

Single-process training:

python scripts/train.py

Distributed training:

torchrun --nproc_per_node=2 --nnodes=1 --master_addr="localhost" --master_port=29500 scripts/train.py

The default synthetic run optimizes the asymmetric Laplace negative log-likelihood, and both single-process and two-process DDP training have been verified. Training produces one recoverable checkpoint and records the training loss. Training results are saved to:

result/checkpoints/global_flood_lstm.pt
result/training/metrics.json

Weights

The paper describes a research implementation in NeuralHydrology, but this reproduction does not provide a weight link because a separately licensed original checkpoint was not confirmed.

Inference

python scripts/inference.py

Inference restores one checkpoint and generates three model-member forecasts over seven days for 12 synthetic basins. The output has passed shape and finite-value checks. Inference results are saved to:

result/output/predictions.npz

Evaluation

python scripts/result.py

Evaluation reports RMSE, precision, recall, F1, and KGE and creates lead-time error and event-skill curves. All metrics are finite; synthetic data use a percentile proxy rather than the paper's Bulletin 17B return-period thresholds. Evaluation results are saved to:

result/evaluation/metrics.json
result/evaluation/comparison.png

Official OneScience Information

Platform	OneScience	OneSkills
Gitee	https://gitee.com/onescience-ai/onescience	https://gitee.com/onescience-ai/oneskills
GitHub	https://github.com/onescience-ai/OneScience	https://github.com/onescience-ai/oneskills

Citation and License

This repository is an independent engineering reproduction of the public Global-Flood-LSTM specifications, with code licensed under the Apache License 2.0.

The original paper is licensed under CC BY 4.0; the paper and GRDC, HRES, ERA5-Land, CPC, IMERG, and HydroATLAS data remain subject to their respective licenses and terms.