Skip to main content

HydroDL2

Differentiable Hydrologic Models

Python PyPI version PyTorch

Build Ruff License



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, and see citation for details on individual model architectures.


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 lumped differentiable HBV model
HBV Adjoint hbv_adj Implicit scheme with adjoint-based gradients
HBV 1.1p hbv_1_1p HBV with capillary rise modification
HBV 2.0 hbv_2 Multi-scale, distributed 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

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., Appling, A.P., Gentine, P. et al. Differentiable modelling to unify machine learning and physical models for geosciences. Nat Rev Earth Environ 4, 552–567 (2023). https://doi.org/10.1038/s43017-023-00450-9

BibTeX
@article{shen_differentiable_2023,
    title = {Differentiable modelling to unify machine learning and physical models for geosciences},
    volume = {4},
    issn = {2662-138X},
    url = {https://doi.org/10.1038/s43017-023-00450-9},
    doi = {10.1038/s43017-023-00450-9},
    pages = {552--567},
    number = {8},
    journaltitle = {Nature Reviews Earth \& Environment},
    author = {Shen, Chaopeng and Appling, Alison P. and Gentine, Pierre and Bandai, Toshiyuki and Gupta, Hoshin and Tartakovsky, Alexandre and Baity-Jesi, Marco and Fenicia, Fabrizio and Kifer, Daniel and Li, Li and Liu, Xiaofeng and Ren, Wei and Zheng, Yi and Harman, Ciaran J. and Clark, Martyn and Farthing, Matthew and Feng, Dapeng and Kumar, Praveen and Aboelyazeed, Doaa and Rahmani, Farshid and Song, Yalan and Beck, Hylke E. and Bindas, Tadd and Dwivedi, Dipankar and Fang, Kuai and Höge, Marvin and Rackauckas, Chris and Mohanty, Binayak and Roy, Tirthankar and Xu, Chonggang and Lawson, Kathryn},
    date = {2023-08-01},
}

Models:

  1. (HBV) Feng, D., Liu, J., Lawson, K., & Shen, C. (2022). Differentiable, learnable, regionalized process-based models with multiphysical outputs can approach state-of-the-art hydrologic prediction accuracy. Water Resources Research, 58, e2022WR032404. https://doi.org/10.1029/2022WR032404

    BibTeX
    @article{https://doi.org/10.1029/2022WR032404,
        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},
    }
    

  2. (HBV Adj.) Song, Y., Knoben, W. J. M., Clark, M. P., Feng, D., Lawson, K., Sawadekar, K., and Shen, C.: When ancient numerical demons meet physics-informed machine learning: adjoint-based gradients for implicit differentiable modeling, Hydrol. Earth Syst. Sci., 28, 3051–3077, https://doi.org/10.5194/hess-28-3051-2024, 2024.

    BibTeX
    @Article{hess-28-3051-2024,
        AUTHOR = {Song, Y. and Knoben, W. J. M. and Clark, M. P. and Feng, D. and Lawson, K. and Sawadekar, K. and Shen, C.},
        TITLE = {When ancient numerical demons meet physics-informed machine learning:
        adjoint-based gradients for implicit differentiable modeling},
        JOURNAL = {Hydrology and Earth System Sciences},
        VOLUME = {28},
        YEAR = {2024},
        NUMBER = {13},
        PAGES = {3051--3077},
        URL = {https://hess.copernicus.org/articles/28/3051/2024/},
        DOI = {10.5194/hess-28-3051-2024}
    }
    

  3. (HBV 1.1p) Song, Y., Sawadekar, K., Frame, J. M., Pan, M., Clark, M. P., Knoben, W. J. M., et al. (2026). Physics-informed, Differentiable hydrologic models for capturing unseen extreme events. Water Resources Research, 62, e2025WR040414. https://doi.org/10.1029/2025WR040414

    BibTeX
    @article{https://doi.org/10.1029/2025WR040414,
      author = {Song, Yalan and Sawadekar, Kamlesh and Frame, Jonathan M. and Pan, Ming and Clark, Martyn P. and Knoben, Wouter J. M. and Wood, Andrew W. and Lawson, Kathryn E. and Patel, Trupesh and Shen, Chaopeng},
      title = {Physics-Informed, Differentiable Hydrologic Models for Capturing Unseen Extreme Events},
      journal = {Water Resources Research},
      volume = {62},
      number = {2},
      pages = {e2025WR040414},
      keywords = {differentiable models, LSTM, physics-informed machine learning, HBV, extreme event},
      doi = {https://doi.org/10.1029/2025WR040414},
      url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2025WR040414},
      eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2025WR040414},
      note = {e2025WR040414 2025WR040414},
      year = {2026}
    }
    

  4. (HBV 2.0) Song, Y., Bindas, T., Shen, C., Ji, H., Knoben, W. J. M., Lonzarich, L., et al. (2025). High-resolution national-scale water modeling is enhanced by multiscale differentiable physics-informed machine learning. Water Resources Research, 61, e2024WR038928. https://doi.org/10.1029/2024WR038928

    BibTeX
    @article{https://doi.org/10.1029/2024WR038928,
        author = {Song, Yalan and Bindas, Tadd and Shen, Chaopeng and Ji, Haoyu and Knoben, Wouter J. M. and Lonzarich, Leo and Clark, Martyn P. and Liu, Jiangtao and van Werkhoven, Katie and Lamont, Sam and Denno, Matthew and Pan, Ming and Yang, Yuan and Rapp, Jeremy and Kumar, Mukesh and Rahmani, Farshid and Thébault, Cyril and Adkins, Richard and Halgren, James and Patel, Trupesh and Patel, Arpita and Sawadekar, Kamlesh Arun and Lawson, Kathryn},
        title = {High-Resolution National-Scale Water Modeling Is Enhanced by Multiscale Differentiable Physics-Informed Machine Learning},
        journal = {Water Resources Research},
        volume = {61},
        number = {4},
        pages = {e2024WR038928},
        keywords = {differentiable modeling, physics-informed machine learning, National Water Model, routing, Muskingum Cunge, multiscale training},
        doi = {https://doi.org/10.1029/2024WR038928},
        year = {2025},
    }
    

  5. (HBV 2.0 MTS) Yang, W., Ji, H., Lonzarich, L., Song, Y., Shen, C. (2025). Diffusion-Based Probabilistic Modeling for Hourly Streamflow Prediction and Assimilation. arXiv. https://arxiv.org/abs/2510.08488 [Under Review]

    BibTeX
    @misc{yang2025diffusionbasedprobabilisticmodelinghourly,
          title={Diffusion-Based Probabilistic Modeling for Hourly Streamflow Prediction and Assimilation},
          author={Wencong Yang and Haoyu Ji and Leo Lonzarich and Yalan Song and Chaopeng Shen},
          year={2025},
          eprint={2510.08488},
          archivePrefix={arXiv},
          primaryClass={physics.geo-ph},
          url={https://arxiv.org/abs/2510.08488},
    }
    

Contributing

We welcome contributions! See CONTRIBUTING.md for details.


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

Metadata

Release files for hydrodl2 1.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hydrodl2 1.4.1
File Size Uploaded Provenance Actions
hydrodl2-1.4.1.tar.gz 2.5 MB With provenance Details for hydrodl2-1.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hydrodl2 1.4.1
File Interpreter ABI Platform Actions
hydrodl2-1.4.1-py3-none-any.whl Python 3 none any Details for hydrodl2-1.4.1-py3-none-any.whl

Total release size: 2.6 MB

Release files / hydrodl2-1.4.1.tar.gz

Download URL hydrodl2-1.4.1.tar.gz
Size 2.5 MB
Tags Source
SHA-256 checksum
How to use checksums
aec6c95798650c2f8ae91b0b27a1c2812379d68f280df5886a106499ca09bdc4
BLAKE2b-256 checksum
How to use checksums
2faa5a491630d3b9001ea93835e0be4179fb58430835b62eb538ef53dd7a0730
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / hydrodl2-1.4.1-py3-none-any.whl

Download URL hydrodl2-1.4.1-py3-none-any.whl
Size 67.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
13675cfa291c4969ecedc7fb465c82eb2d9fc92946df0b77ef72163be4f6032a
BLAKE2b-256 checksum
How to use checksums
4a2059628da1a72cd356afc2e3db7cbd5da4c3db250084fa2e19a8d0d918fb5e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for hydrodl2 1.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hydrodl2-1.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page