# google-research/flood-forecasting architecture

> Architecture diagram of the GitHub repository google-research/flood-forecasting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-research/flood-forecasting
- Repository: https://github.com/google-research/flood-forecasting

## Overview

OpenHydroNet supports the workflow from preparing catchment and meteorological inputs, through training a configured sequence-forecast model, to evaluation or inference; evaluation can optionally assimilate recent observations. Its main runtime is the googlehydrology package, with separate catchment delineation and MultiMet static-feature extraction tools. The graph combines README-described capabilities with relationships visible in sampled source references; unsampled modules are represented by their exact tree paths, and uncertain links are omitted.

Main entry points: [`googlehydrology/training/basetrainer.py`](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/basetrainer.py) (Trainer), [`googlehydrology/evaluation/tester.py`](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/tester.py) (Tester and inference), [`googlehydrology/datasetzoo/multimet.py`](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datasetzoo/multimet.py) (MultiMet dataset), [`googlehydrology/modelzoo/basemodel.py`](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/basemodel.py) (Model base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_delineate["Catchment delineation<br/>[delineator.py]"]
  node_tile_access["Flow tiles and GCS<br/>[tiles.py]"]
  node_caravan_convert["Caravan conversion<br/>[convert.py]"]
  node_caravan_data["Caravan dataset<br/>[caravan.py]"]
  node_multimet_data["MultiMet dataset<br/>[multimet.py]"]
  node_sample_validation["Sample validation"]
  node_scaling["Feature scaling<br/>[scaler.py]"]
end

subgraph group_runtime["Forecast runtime"]
  node_run_cli["Run commands<br/>[run.py]"]
  node_configuration["Run configuration<br/>[config.py]"]
  node_model_base["Model base<br/>[basemodel.py]"]
  node_mean_lstm["Mean-embedding LSTM"]
  node_handoff_lstm["Handoff LSTM"]
end

subgraph group_learn["Training"]
  node_trainer["Trainer<br/>[basetrainer.py]"]
  node_loss["Training losses<br/>[loss.py]"]
  node_logger["Experiment logger<br/>[logger.py]"]
end

subgraph group_assess["Evaluation and inference"]
  node_tester["Tester and inference<br/>[tester.py]"]
  node_assimilation["Data assimilation<br/>[assimilation.py]"]
  node_metrics["Forecast metrics<br/>[metrics.py]"]
end

subgraph group_extract["Static extraction"]
  node_climate["Climate features<br/>[climate.py]"]
  node_static_extractor["Static extraction<br/>[extractor.py]"]
  node_gcs_utils["GCS utilities<br/>[gcs.py]"]
end

node_user(("User"))
node_zarr[("Zarr data stores")]
node_gcs[("Google Cloud Storage")]

node_user -->|"delineates basins"| node_delineate
node_delineate -->|"reads flow tiles"| node_tile_access
node_user -->|"converts legacy data"| node_caravan_convert
node_caravan_convert -->|"writes Zarr"| node_zarr
node_user -->|"configures forcings"| node_multimet_data
node_multimet_data -->|"reads cloud data"| node_gcs
node_user -->|"starts run"| node_run_cli
node_run_cli -.->|"loads settings"| node_configuration
node_trainer -->|"loads training data"| node_multimet_data
node_trainer -.->|"trains model"| node_model_base
node_trainer -->|"computes loss"| node_loss
node_trainer -->|"logs training"| node_logger
node_mean_lstm -->|"extends base"| node_model_base
node_handoff_lstm -->|"extends base"| node_model_base
node_user -->|"trains model"| node_trainer
node_user -->|"evaluates or infers"| node_tester
node_tester -->|"loads evaluation data"| node_multimet_data
node_tester -->|"optionally assimilates"| node_assimilation
node_assimilation -->|"optimizes embeddings"| node_model_base
node_tester -->|"computes metrics"| node_metrics
node_user -.->|"extracts static features"| node_static_extractor
node_static_extractor -.->|"uses climate indices"| node_climate
node_climate -->|"downloads climate data"| node_gcs_utils
node_gcs_utils -.->|"transfers files"| node_gcs

click node_delineate "https://github.com/google-research/flood-forecasting/blob/main/catchment_delineation/delineator.py"
click node_tile_access "https://github.com/google-research/flood-forecasting/blob/main/catchment_delineation/tiles.py"
click node_caravan_convert "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datautils/convert.py"
click node_caravan_data "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datasetzoo/caravan.py"
click node_multimet_data "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datasetzoo/multimet.py"
click node_sample_validation "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datautils/validate_samples.py"
click node_scaling "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datautils/scaler.py"
click node_run_cli "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/run.py"
click node_configuration "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/utils/config.py"
click node_model_base "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/basemodel.py"
click node_mean_lstm "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/mean_embedding_forecast_lstm.py"
click node_handoff_lstm "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/handoff_forecast_lstm.py"
click node_trainer "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/basetrainer.py"
click node_loss "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/loss.py"
click node_logger "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/logger.py"
click node_tester "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/tester.py"
click node_assimilation "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/assimilation.py"
click node_metrics "https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/metrics.py"
click node_climate "https://github.com/google-research/flood-forecasting/blob/main/multimet/static_extractor/climate.py"
click node_static_extractor "https://github.com/google-research/flood-forecasting/blob/main/multimet/static_extractor/extractor.py"
click node_gcs_utils "https://github.com/google-research/flood-forecasting/blob/main/multimet/utils/gcs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_delineate,node_tile_access,node_caravan_convert,node_caravan_data,node_multimet_data,node_sample_validation,node_scaling,node_user toneBlue
class node_run_cli,node_configuration,node_model_base,node_mean_lstm,node_handoff_lstm,node_zarr,node_gcs toneAmber
class node_trainer,node_loss,node_logger toneMint
class node_tester,node_assimilation,node_metrics toneRose
class node_climate,node_static_extractor,node_gcs_utils toneIndigo
```

## Components

### Data preparation

- [Catchment delineation](https://github.com/google-research/flood-forecasting/blob/main/catchment_delineation/delineator.py): `catchment_delineation/delineator.py`
- [Flow tiles and GCS](https://github.com/google-research/flood-forecasting/blob/main/catchment_delineation/tiles.py): `catchment_delineation/tiles.py`
- [Caravan conversion](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datautils/convert.py): `googlehydrology/datautils/convert.py`
- [Caravan dataset](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datasetzoo/caravan.py): `googlehydrology/datasetzoo/caravan.py`
- [MultiMet dataset](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datasetzoo/multimet.py): `googlehydrology/datasetzoo/multimet.py`
- [Sample validation](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datautils/validate_samples.py): `googlehydrology/datautils/validate_samples.py`
- [Feature scaling](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/datautils/scaler.py): `googlehydrology/datautils/scaler.py`

### Forecast runtime

- [Run commands](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/run.py): `googlehydrology/run.py`
- [Run configuration](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/utils/config.py): `googlehydrology/utils/config.py`
- [Model base](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/basemodel.py): `googlehydrology/modelzoo/basemodel.py`
- [Mean-embedding LSTM](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/mean_embedding_forecast_lstm.py): `googlehydrology/modelzoo/mean_embedding_forecast_lstm.py`
- [Handoff LSTM](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/modelzoo/handoff_forecast_lstm.py): `googlehydrology/modelzoo/handoff_forecast_lstm.py`

### Training

- [Trainer](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/basetrainer.py): `googlehydrology/training/basetrainer.py`
- [Training losses](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/loss.py): `googlehydrology/training/loss.py`
- [Experiment logger](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/training/logger.py): `googlehydrology/training/logger.py`

### Evaluation and inference

- [Tester and inference](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/tester.py): `googlehydrology/evaluation/tester.py`
- [Data assimilation](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/assimilation.py): `googlehydrology/evaluation/assimilation.py`
- [Forecast metrics](https://github.com/google-research/flood-forecasting/blob/main/googlehydrology/evaluation/metrics.py): `googlehydrology/evaluation/metrics.py`

### Static extraction

- [Climate features](https://github.com/google-research/flood-forecasting/blob/main/multimet/static_extractor/climate.py): `multimet/static_extractor/climate.py`
- [Static extraction](https://github.com/google-research/flood-forecasting/blob/main/multimet/static_extractor/extractor.py): `multimet/static_extractor/extractor.py`
- [GCS utilities](https://github.com/google-research/flood-forecasting/blob/main/multimet/utils/gcs.py): `multimet/utils/gcs.py`

### Other components

- **User**
- **Zarr data stores**
- **Google Cloud Storage**

## Connections

- User → Catchment delineation: delineates basins
- Catchment delineation → Flow tiles and GCS: reads flow tiles (evidence: `catchment_delineation/delineator.py`)
- User → Caravan conversion: converts legacy data
- Caravan conversion → Zarr data stores: writes Zarr
- User → MultiMet dataset: configures forcings
- MultiMet dataset → Google Cloud Storage: reads cloud data
- User → Run commands: starts run
- Run commands → Run configuration: loads settings
- Trainer → MultiMet dataset: loads training data (evidence: `googlehydrology/training/basetrainer.py`)
- Trainer → Model base: trains model
- Trainer → Training losses: computes loss (evidence: `googlehydrology/training/basetrainer.py`)
- Trainer → Experiment logger: logs training (evidence: `googlehydrology/training/basetrainer.py`)
- Mean-embedding LSTM → Model base: extends base (evidence: `googlehydrology/modelzoo/mean_embedding_forecast_lstm.py`)
- Handoff LSTM → Model base: extends base (evidence: `googlehydrology/modelzoo/handoff_forecast_lstm.py`)
- User → Trainer: trains model
- User → Tester and inference: evaluates or infers
- Tester and inference → MultiMet dataset: loads evaluation data (evidence: `googlehydrology/evaluation/tester.py`)
- Tester and inference → Data assimilation: optionally assimilates (evidence: `googlehydrology/evaluation/tester.py`)
- Data assimilation → Model base: optimizes embeddings (evidence: `googlehydrology/evaluation/assimilation.py`)
- Tester and inference → Forecast metrics: computes metrics (evidence: `googlehydrology/evaluation/tester.py`)
- User → Static extraction: extracts static features
- Static extraction → Climate features: uses climate indices
- Climate features → GCS utilities: downloads climate data (evidence: `multimet/static_extractor/climate.py`)
- GCS utilities → Google Cloud Storage: transfers files