# mhpi/hydrodl architecture

> Architecture diagram of the GitHub repository mhpi/hydrodl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mhpi/hydrodl
- Repository: https://github.com/mhpi/hydrodl

## Overview

hydroDL is a hydrologic deep-learning toolkit for tasks such as streamflow forecasting and soil-moisture estimation. The main workflow is to load forcing, attribute, and observation data; prepare and normalize it; configure a model and loss; train; then validate or test predictions and analyze results. The repository also includes multiscale and uncertainty-oriented model/loss capabilities, CAMELS and CSV data access, and plotting/statistics utilities. Edges reflect the README and source-index references; several model and data modules were not sampled, so their internal connections are omitted.

Main entry points: [`hydroDL/data/dbCsv.py`](https://github.com/mhpi/hydrodl/blob/release/hydroDL/data/dbCsv.py) (CSV data access), [`hydroDL/master/master.py`](https://github.com/mhpi/hydrodl/blob/release/hydroDL/master/master.py) (Experiment orchestration), [`hydroDL/data/camels.py`](https://github.com/mhpi/hydrodl/blob/release/hydroDL/data/camels.py) (CAMELS access), [`hydroDL/model/train.py`](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data access"]
  node_camels["CAMELS access<br/>[camels.py]"]
  node_csv["CSV data access<br/>[dbCsv.py]"]
  node_dataset["Data abstractions<br/>[dataset.py]"]
  node_normalization["Normalization<br/>[norm.py]"]
end

subgraph group_model["Modeling"]
  node_recurrent["Recurrent models"]
  node_cnn["CNN models<br/>[LstmCnn1d.py]"]
  node_losses["Loss functions<br/>[crit.py]"]
  node_dropout["Dropout layers<br/>[dropout.py]"]
end

subgraph group_workflow["Experiment workflow"]
  node_master["Experiment orchestration<br/>[master.py]"]
  node_training["Model training<br/>[train.py]"]
  node_inference["Validation and testing<br/>[master.py]"]
  node_multiscale["Multiscale training<br/>[train_multi.py]"]
end

subgraph group_analysis["Results and utilities"]
  node_plotting["Scientific plotting<br/>[plot.py]"]
  node_statistics["Prediction statistics<br/>[stat.py]"]
  node_time["Time utilities<br/>[time.py]"]
end

node_user(("Hydrology researcher"))
node_predictions["Hydrologic predictions"]

node_user -->|"configures experiment"| node_master
node_user -->|"selects data"| node_camels
node_user -.->|"selects data"| node_csv
node_camels -->|"uses abstractions"| node_dataset
node_csv -->|"uses abstractions"| node_dataset
node_camels -->|"uses date ranges"| node_time
node_csv -->|"uses date ranges"| node_time
node_csv -->|"normalizes data"| node_normalization
node_master -->|"invokes training"| node_training
node_master -->|"invokes testing"| node_inference
node_master -->|"configures model"| node_recurrent
node_training -->|"uses loss"| node_losses
node_training -->|"uses CNN modules"| node_cnn
node_cnn -->|"uses dropout"| node_dropout
node_recurrent -->|"uses dropout"| node_dropout
node_inference -->|"produces predictions"| node_predictions
node_user -->|"runs multiscale workflow"| node_multiscale
node_user -.->|"explores results"| node_plotting
node_user -.->|"evaluates results"| node_statistics
node_multiscale -->|"uses evaluation"| node_statistics

click node_camels "https://github.com/mhpi/hydrodl/blob/release/hydroDL/data/camels.py"
click node_csv "https://github.com/mhpi/hydrodl/blob/release/hydroDL/data/dbCsv.py"
click node_dataset "https://github.com/mhpi/hydrodl/blob/release/hydroDL/dataset.py"
click node_normalization "https://github.com/mhpi/hydrodl/blob/release/hydroDL/utils/norm.py"
click node_master "https://github.com/mhpi/hydrodl/blob/release/hydroDL/master/master.py"
click node_training "https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/train.py"
click node_inference "https://github.com/mhpi/hydrodl/blob/release/hydroDL/master/master.py"
click node_recurrent "https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/rnn/CudnnLstmModel_R2P.py"
click node_cnn "https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/cnn/LstmCnn1d.py"
click node_losses "https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/crit.py"
click node_dropout "https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/dropout.py"
click node_multiscale "https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/train_multi.py"
click node_plotting "https://github.com/mhpi/hydrodl/blob/release/hydroDL/post/plot.py"
click node_statistics "https://github.com/mhpi/hydrodl/blob/release/hydroDL/post/stat.py"
click node_time "https://github.com/mhpi/hydrodl/blob/release/hydroDL/utils/time.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_camels,node_csv,node_dataset,node_normalization toneBlue
class node_recurrent,node_cnn,node_losses,node_dropout toneAmber
class node_master,node_training,node_inference,node_multiscale toneMint
class node_plotting,node_statistics,node_time toneRose
class node_user,node_predictions toneIndigo
```

## Components

### Data access

- [CAMELS access](https://github.com/mhpi/hydrodl/blob/release/hydroDL/data/camels.py): `hydroDL/data/camels.py`
- [CSV data access](https://github.com/mhpi/hydrodl/blob/release/hydroDL/data/dbCsv.py): `hydroDL/data/dbCsv.py`
- [Data abstractions](https://github.com/mhpi/hydrodl/blob/release/hydroDL/dataset.py): `hydroDL/dataset.py`
- [Normalization](https://github.com/mhpi/hydrodl/blob/release/hydroDL/utils/norm.py): `hydroDL/utils/norm.py`

### Modeling

- [Recurrent models](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/rnn/CudnnLstmModel_R2P.py): `hydroDL/model/rnn/CudnnLstmModel_R2P.py`
- [CNN models](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/cnn/LstmCnn1d.py): `hydroDL/model/cnn/LstmCnn1d.py`
- [Loss functions](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/crit.py): `hydroDL/model/crit.py`
- [Dropout layers](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/dropout.py): `hydroDL/model/dropout.py`

### Experiment workflow

- [Experiment orchestration](https://github.com/mhpi/hydrodl/blob/release/hydroDL/master/master.py): `hydroDL/master/master.py`
- [Model training](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/train.py): `hydroDL/model/train.py`
- [Validation and testing](https://github.com/mhpi/hydrodl/blob/release/hydroDL/master/master.py): `hydroDL/master/master.py`
- [Multiscale training](https://github.com/mhpi/hydrodl/blob/release/hydroDL/model/train_multi.py): `hydroDL/model/train_multi.py`

### Results and utilities

- [Scientific plotting](https://github.com/mhpi/hydrodl/blob/release/hydroDL/post/plot.py): `hydroDL/post/plot.py`
- [Prediction statistics](https://github.com/mhpi/hydrodl/blob/release/hydroDL/post/stat.py): `hydroDL/post/stat.py`
- [Time utilities](https://github.com/mhpi/hydrodl/blob/release/hydroDL/utils/time.py): `hydroDL/utils/time.py`

### Other components

- **Hydrology researcher**
- **Hydrologic predictions**

## Connections

- Hydrology researcher → Experiment orchestration: configures experiment (evidence: `README.md`)
- Hydrology researcher → CAMELS access: selects data (evidence: `README.md`)
- Hydrology researcher → CSV data access: selects data
- CAMELS access → Data abstractions: uses abstractions (evidence: `hydroDL/data/camels.py`)
- CSV data access → Data abstractions: uses abstractions (evidence: `hydroDL/data/dbCsv.py`)
- CAMELS access → Time utilities: uses date ranges (evidence: `hydroDL/data/camels.py`)
- CSV data access → Time utilities: uses date ranges (evidence: `hydroDL/data/dbCsv.py`)
- CSV data access → Normalization: normalizes data
- Experiment orchestration → Model training: invokes training (evidence: `hydroDL/master/master.py`)
- Experiment orchestration → Validation and testing: invokes testing (evidence: `hydroDL/master/master.py`)
- Experiment orchestration → Recurrent models: configures model (evidence: `hydroDL/master/master.py`)
- Model training → Loss functions: uses loss (evidence: `hydroDL/model/train.py`)
- Model training → CNN models: uses CNN modules (evidence: `hydroDL/model/train.py`)
- CNN models → Dropout layers: uses dropout (evidence: `hydroDL/model/cnn/LstmCnn1d.py`)
- Recurrent models → Dropout layers: uses dropout (evidence: `hydroDL/model/rnn/CudnnLstmModel_R2P.py`)
- Validation and testing → Hydrologic predictions: produces predictions (evidence: `hydroDL/master/master.py`)
- Hydrology researcher → Multiscale training: runs multiscale workflow (evidence: `README.md`)
- Hydrology researcher → Scientific plotting: explores results
- Hydrology researcher → Prediction statistics: evaluates results
- Multiscale training → Prediction statistics: uses evaluation (evidence: `hydroDL/model/train_multi.py`)
