HydroDL

https://mhpi.github.io
Admin
HydroDL is a deep learning library designed to model hydrologic systems using data-driven neural...
Tokens:5,676
Snippets:71
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install 𝛿MG via UV

Source: https://mhpi.github.io/dmg/detail

Clone the repository and install the package in developer mode using Astral UV.

```bash
git clone git@github.com:mhpi/generic_deltamodel.git
uv pip install -e ./generic_deltamodel
```

--------------------------------

### Install hydroDL via PyPI

Source: https://mhpi.github.io/Installation

Installs the stable version of the hydroDL package using pip.

```bash
pip install hydroDL
```

--------------------------------

### HydroDL Model Training and Testing Workflow

Source: https://mhpi.github.io/Quick_start

Demonstrates the standard pipeline for initializing a model, training it with specific data, and performing validation.

```python
# imports
from hydroDL.model.crit import RmseLoss
from hydroDL.model.rnn import CudnnLstmModel as LSTM
from hydroDL.model.train import trainModel
from hydroDL.model.test import testModel

# load your training and testing data 
# x: forcing data (pixels, time, features)
# c: attribute data (pixels, features)
# y: observed values (pixels, time, 1)
x_train, c_train, y_train, x_val, c_val, y_val = load_data(...)

# define your model and loss function
model = LSTM(nx=num_variables, ny=1)
loss_fn = RmseLoss()

# train your model
model = trainModel(model,
    x_train,
    y_train,
    c_train,
    loss_fn,
)

# validate your model
pred = testModel(model,
             x_val,
             c_val,
)
```

--------------------------------

### Create and activate a Conda environment

Source: https://mhpi.github.io/Installation

Sets up a dedicated Python 3.10 environment for hydroDL.

```bash
conda create -n mhpihydrodl python=3.10
conda activate mhpihydrodl
```

--------------------------------

### Run Differentiable Parameter Learning

Source: https://mhpi.github.io/dmg/detail

Initialize a DplModel by composing a physical HBV model with a neural network for parameter learning.

```python
from hydroDL2.models.hbv.hbv import HBV

from dMG.core.data.loaders import HydroLoader
from dMG.core.utils import load_nn_model, print_config, set_randomseed
from dMG.models.delta_models import DplModel
from example import load_config, take_data_sample

CONFIG_PATH = '../example/conf/config_dhbv_1_0.yaml'


# Model configuration
config = load_config(CONFIG_PATH)

# Initialize physical model and NN.
phy_model = HBV(config['delta_model']['phy_model'])
nn = load_nn_model(phy_model, config['delta_model'])

# Create differentiable model dHBV: a torch.nn.Module that describes how 
# the NN is linked to the physical model HBV.
dpl_model = DplModel(phy_model=phy_model, nn_model=nn)

# Load dataset of NN and HBV inputs.
dataset = HydroLoader(config).dataset
dataset_sample = take_data_sample(config, dataset, days=730, basins=100)

output = dpl_model(dataset_sample)
```

--------------------------------

### Repository Directory Structure

Source: https://mhpi.github.io/dmg/detail

Visual representation of the project file hierarchy, including source code, configuration, and documentation directories.

```text
.
├── src/dMG/
│   ├── __main__.py                 # Runs 𝛿MG; models, experiments
│   ├── core/                       
│   │   ├── calc/                   # Calculation utilities
│   │   ├── data/                   # Data loaders and samplers
│   │   ├── post/                   # Post-processing utilities; plotting
│   │   └── utils/                  # Helper functions
│   ├── models/                     
│   │   ├── criterion               # Loss functions  
│   │   ├── delta_models            # Differentiable model modalities
│   │   ├── multimodels             # Multimodeling processors
│   │   ├── neural_networks/        # Neural network architectures
│   │   ├── phy_models/             # Physical Models
│   │   └── model_handler.py        # High-level model manager
│   └── trainers/                   # Model training routines
├── conf/
│   ├── hydra/                      # Hydra settings
│   ├── observations/               # Observation configuration files
│   ├── config.py                   # Configuration validator
│   └── default.yaml                # Default master configuration file
├── docs/                           
├── envs/                           # Python ENV configurations
└── example/                        # Tutorials
```

--------------------------------

### Clone hydroDL from GitHub

Source: https://mhpi.github.io/Installation

Downloads the latest development version of the hydroDL package from the official repository.

```bash
git clone https://github.com/mhpi/hydroDL.git
```

--------------------------------

### DplModel Internal Forward Pass

Source: https://mhpi.github.io/dmg/detail

Demonstrates the internal composition of the neural network and physical model within the DplModel forward pass.

```python
# NN forward
parameters = self.nn_model(dataset_sample['xc_nn_norm'])        

# Physics model forward
predictions = self.phy_model(
    dataset_sample,
    parameters,
)
```

--------------------------------

### Bibtex Citation for Liu et al. 2022

Source: https://mhpi.github.io/codes/liu_2022

Use this BibTeX entry to cite the multiscale deep learning model research paper.

```bibtex
@article{liu2022multiscale,
  title={A multiscale deep learning model for soil moisture integrating satellite and in situ data},
  author={Liu, Jiangtao and Rahmani, Farshid and Lawson, Kathryn and Shen, Chaopeng},
  journal={Geophysical Research Letters},
  volume={49},
  number={7},
  pages={e2021GL096847},
  year={2022},
  publisher={Wiley Online Library}
}
```

--------------------------------

### Bibtex Citation for LSTM SWE Study

Source: https://mhpi.github.io/codes/Song_SWE_2023

Use this BibTeX entry to cite the research paper detailing the LSTM-based data integration methodology.

```bibtex
@article{song2024lstm,
  title={LSTM-based data integration to improve snow water equivalent prediction and diagnose error sources},
  author={Song, Yalan and Tsai, Wen-Ping and Gluck, Jonah and Rhoades, Alan and Zarzycki, Colin and McCrary, Rachel and Lawson, Kathryn and Shen, Chaopeng},
  journal={Journal of Hydrometeorology},
  volume={25},
  number={1},
  pages={223--237},
  year={2024},
  publisher={American Meteorological Society}
}
```

--------------------------------

### Bibtex Citation for δHBV1.1p

Source: https://mhpi.github.io/codes/song_2026

Use this Bibtex entry to cite the research paper associated with the differentiable hydrologic model.

```bibtex
@article{song2026physics,
  title={Physics-informed, Differentiable hydrologic models for capturing unseen extreme events},
  author={Song, Yalan and Sawadekar, Kamlesh and Frame, Jonathan M and Pan, Ming and Clark, Martyn P and Knoben, Wouter JM and Wood, Andrew W and Lawson, Kathryn E and Patel, Trupesh and Shen, Chaopeng},
  journal={Water Resources Research},
  volume={62},
  number={2},
  pages={e2025WR040414},
  year={2026},
  publisher={Wiley Online Library}
}
```

--------------------------------

### Bibtex Citation for Rahmani et al. 2023

Source: https://mhpi.github.io/codes/Rahmani_et_al_2023

Use this BibTeX entry to cite the research paper in academic publications.

```bibtex
@article{Rahmani2021lstm,
  title={Identifying Structural Priors in a Hybrid Differentiable Model for Stream Water Temperature Modeling},
  author={Rahmani, Farshid and Appling, Alison and Feng, Dapeng and Lawson, Kathryn and Shen, Chaopeng},
  journal={Water Resources Research},
  year={2023},
  publisher={AGU}
}
```

--------------------------------

### BibTeX Citations for HBV-hydroDL Research

Source: https://mhpi.github.io/codes/feng_2023

Use these BibTeX entries to cite the research papers associated with the differentiable hydrologic models.

```bibtex
@article{feng2022WRR,
author = {Feng, Dapeng and Liu, Jiangtao and Lawson, Kathryn and Shen, Chaopeng},
title = {Differentiable, Learnable, Regionalized Process-Based Models With Multiphysical Outputs can Approach State-Of-The-Art Hydrologic Prediction Accuracy},
journal = {Water Resources Research},
volume = {58},
number = {10},
pages = {e2022WR032404},
keywords = {rainfall runoff, differentiable programming, machine learning, physical model, differentiable hydrology, LSTM},
doi = {https://doi.org/10.1029/2022WR032404},
year = {2022}
}
@Article{feng2023HESS,
AUTHOR = {Feng, D. and Beck, H. and Lawson, K. and Shen, C.},
TITLE = {The suitability of differentiable, physics-informed machine learning
hydrologic models for ungauged regions and climate change impact assessment},
JOURNAL = {Hydrology and Earth System Sciences},
VOLUME = {27},
YEAR = {2023},
NUMBER = {12},
PAGES = {2357--2373},
URL = {https://hess.copernicus.org/articles/27/2357/2023/},
DOI = {10.5194/hess-27-2357-2023}
}
@article{feng2023GMDD,
  title={Deep Dive into Global Hydrologic Simulations: Harnessing the Power of Deep Learning and Physics-informed Differentiable Models ($\delta$HBV-globe1. 0-hydroDL)},
  author={Feng, Dapeng and Beck, Hylke and de Bruijn, Jens and Sahu, Reetik Kumar and Satoh, Yusuke and Wada, Yoshihide and Liu, Jiangtao and Pan, Ming and Lawson, Kathryn and Shen, Chaopeng},
  journal={Geoscientific Model Development Discussions},
  volume={2023},
  pages={1--23},
  year={2023},
  publisher={G{\"o}ttingen, Germany}
}
```
Tokens:
Raw