hydrodl2 1.3.0

Differentiable Hydrologic Model Library

HydroDL2: Differentiable Hydrologic Models

---

A library of hydrological models developed on PyTorch and designed alongside 𝛿MG for the creation of end-to-end differentiable models, enabling parameter learning, bias correction, missing process representation, and more.

See 𝛿MG/examples using HydroDL2-based HBV models for published differentiable parameter learning (dPL) applications.

Installation

uv pip install hydrodl2

For development installs, see setup.

Quick Start

import hydrodl2

# List all available models
hydrodl2.available_models()
# {'hbv': ['hbv', 'hbv_1_1p', 'hbv_2', 'hbv_2_hourly', 'hbv_2_mts', 'hbv_adj']}

# Load a model class
Hbv = hydrodl2.load_model('hbv')

# Instantiate and use in a differentiable pipeline
model = Hbv()

Models are standard torch.nn.Module subclasses and can be composed with neural networks via δMG for end-to-end differentiable training.

Available Models

Model	Name	Description
HBV 1.0	hbv	Base differentiable HBV model
HBV 1.1p	hbv_1_1p	HBV with capillary rise modification
HBV 2.0	hbv_2	Multi-scale HBV with elevation-dependent parameters
HBV 2.0 Hourly	hbv_2_hourly	Sub-daily variant of HBV 2.0
HBV 2.0 MTS	hbv_2_mts	Multi-timescale variant of HBV 2.0
HBV Adjoint	hbv_adj	Implicit scheme with adjoint-based gradients

Repository Structure

.
├── src/
│   └── hydrodl2/
│       ├── api/                   # Main API
│       │   ├── __init__.py
│       │   └── methods.py         # Methods exposed to end-users
│       ├── core/                  # Methods used internally
│       ├── models/                # Shared models directory
│       │   └── hbv/               # HBV model variants
│       └── modules/               # Augmentations for δMG models
├── docs/
├── tests/
└── pyproject.toml

Citation

This work is maintained by MHPI and advised by Dr. Chaopeng Shen. If you find it useful, please cite:

Shen, C., et al. (2023). Differentiable modelling to unify machine learning and physical models for geosciences. Nature Reviews Earth & Environment, 4(8), 552--567. https://doi.org/10.1038/s43017-023-00450-9

BibTeX

@article{shen2023differentiable,
  title={Differentiable modelling to unify machine learning and physical models for geosciences},
  author={Shen, Chaopeng and others},
  journal={Nature Reviews Earth \& Environment},
  volume={4},
  number={8},
  pages={552--567},
  year={2023},
  publisher={Nature Publishing Group},
  doi={10.1038/s43017-023-00450-9}
}

Contributing

We welcome contributions! See CONTRIBUTING.md for details.

---

Please submit an issue to report any questions, concerns, or bugs.