{"id":44162730,"url":"https://github.com/mhpi/hydrodl2","last_synced_at":"2026-05-16T01:05:23.854Z","repository":{"id":271605517,"uuid":"880562931","full_name":"mhpi/hydrodl2","owner":"mhpi","description":"Repository for MHPI differentiable hydrological models.","archived":false,"fork":false,"pushed_at":"2026-04-13T16:26:35.000Z","size":4206,"stargazers_count":14,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-04-13T17:40:48.636Z","etag":null,"topics":["deep-learning","differentiable-physics","hydrology"],"latest_commit_sha":null,"homepage":"https://mhpi.github.io/benchmarks/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mhpi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-30T00:16:41.000Z","updated_at":"2026-04-13T16:25:00.000Z","dependencies_parsed_at":"2025-02-16T20:22:50.400Z","dependency_job_id":null,"html_url":"https://github.com/mhpi/hydrodl2","commit_stats":null,"previous_names":["mhpi/hydrodl2"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mhpi/hydrodl2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fhydrodl2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fhydrodl2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fhydrodl2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fhydrodl2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhpi","download_url":"https://codeload.github.com/mhpi/hydrodl2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fhydrodl2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31863499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","differentiable-physics","hydrology"],"created_at":"2026-02-09T08:07:28.508Z","updated_at":"2026-04-15T23:00:58.827Z","avatar_url":"https://github.com/mhpi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/mhpi/hydrodl2/blob/master/docs/images/hydrodl2.drawio.svg?raw=true\" alt=\"HydroDL2\" width=\"300\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eDifferentiable Hydrologic Models\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.9--3.13-blue?labelColor=333333\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/hydrodl2/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/hydrodl2?cacheSeconds=300\u0026logo=pypi\u0026logoColor=white\u0026labelColor=333333\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/torch/\"\u003e\u003cimg src=\"https://img.shields.io/badge/dynamic/json?label=PyTorch\u0026query=info.version\u0026url=https%3A%2F%2Fpypi.org%2Fpypi%2Ftorch%2Fjson\u0026logo=pytorch\u0026color=EE4C2C\u0026logoColor=F900FF\u0026labelColor=333333\" alt=\"PyTorch\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/mhpi/hydrodl2/actions/workflows/pytest.yaml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/mhpi/hydrodl2/pytest.yaml?branch=master\u0026logo=github\u0026label=tests\u0026labelColor=333333\" alt=\"Build\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\u0026labelColor=333333\" alt=\"Ruff\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Non--Commercial_(PSU)-yellow?labelColor=333333\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003c/br\u003e\n\nA library of hydrological models developed on PyTorch and designed alongside [𝛿MG](https://github.com/mhpi/generic_deltamodel) for the creation of end-to-end [differentiable models](https://www.nature.com/articles/s43017-023-00450-9), enabling parameter learning, bias correction, missing process representation, and more.\n\nSee [`𝛿MG/examples`](https://github.com/mhpi/generic_deltamodel/tree/master/example/hydrology) using HydroDL2-based HBV models for published differentiable parameter learning (dPL) applications, and see [citation](#citation) for details on individual model architectures.\n\n\u003c/br\u003e\n\n## Installation\n\n```bash\nuv pip install hydrodl2\n```\n\nFor development installs, see [setup](https://github.com/mhpi/hydrodl2/blob/master/docs/setup.md).\n\n## Quick Start\n\n```python\nimport hydrodl2\n\n# List all available models\nhydrodl2.available_models()\n# {'hbv': ['hbv', 'hbv_1_1p', 'hbv_2', 'hbv_2_hourly', 'hbv_2_mts', 'hbv_adj']}\n\n# Load a model class\nHbv = hydrodl2.load_model('hbv')\n\n# Instantiate and use in a differentiable pipeline\nmodel = Hbv()\n```\n\nModels are standard `torch.nn.Module` subclasses and can be composed with neural networks via [\u0026delta;MG](https://github.com/mhpi/generic_deltamodel) for end-to-end differentiable training.\n\n\u003c/br\u003e\n\n## Available Models\n\n| Model | Name | Description |\n|-------|------|-------------|\n| HBV 1.0 | `hbv` | Base lumped differentiable HBV model |\n| HBV Adjoint | `hbv_adj` | Implicit scheme with adjoint-based gradients |\n| HBV 1.1p | `hbv_1_1p` | HBV with capillary rise modification |\n| HBV 2.0 | `hbv_2` | Multi-scale, distributed HBV with elevation-dependent parameters |\n| HBV 2.0 Hourly | `hbv_2_hourly` | Sub-daily variant of HBV 2.0 |\n| HBV 2.0 MTS | `hbv_2_mts` | Multi-timescale variant of HBV 2.0 |\n\n\u003c/br\u003e\n\n## Repository Structure\n\n```text\n.\n├── src/\n│   └── hydrodl2/\n│       ├── api/                   # Main API\n│       │   ├── __init__.py\n│       │   └── methods.py         # Methods exposed to end-users\n│       ├── core/                  # Methods used internally\n│       ├── models/                # Shared models directory\n│       │   └── hbv/               # HBV model variants\n│       └── modules/               # Augmentations for δMG models\n├── docs/\n├── tests/\n└── pyproject.toml\n```\n\n## Citation\n\nThis work is maintained by [MHPI](http://water.engr.psu.edu/shen/) and advised by [Dr. Chaopeng Shen](https://water.engr.psu.edu/shen/). If you find it useful, please cite:\n\n\u003e 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). \u003chttps://doi.org/10.1038/s43017-023-00450-9\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBibTeX\u003c/summary\u003e\n\n```bibtex\n@article{shen_differentiable_2023,\n    title = {Differentiable modelling to unify machine learning and physical models for geosciences},\n    volume = {4},\n    issn = {2662-138X},\n    url = {https://doi.org/10.1038/s43017-023-00450-9},\n    doi = {10.1038/s43017-023-00450-9},\n    pages = {552--567},\n    number = {8},\n    journaltitle = {Nature Reviews Earth \\\u0026 Environment},\n    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},\n    date = {2023-08-01},\n}\n```\n\n\u003c/details\u003e\n\n\u003c/br\u003e\n\nModels:\n\n1. **(HBV)**  Feng, D., Liu, J., Lawson, K., \u0026 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. \u003chttps://doi.org/10.1029/2022WR032404\u003e\n\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @article{https://doi.org/10.1029/2022WR032404,\n        author = {Feng, Dapeng and Liu, Jiangtao and Lawson, Kathryn and Shen, Chaopeng},\n        title = {Differentiable, Learnable, Regionalized Process-Based Models With Multiphysical Outputs can Approach State-Of-The-Art Hydrologic Prediction Accuracy},\n        journal = {Water Resources Research},\n        volume = {58},\n        number = {10},\n        pages = {e2022WR032404},\n        keywords = {rainfall runoff, differentiable programming, machine learning, physical model, differentiable hydrology, LSTM},\n        doi = {https://doi.org/10.1029/2022WR032404},\n        year = {2022},\n    }\n    ```\n\n    \u003c/details\u003e\n\n    \u003c/br\u003e\n\n2. **(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, \u003chttps://doi.org/10.5194/hess-28-3051-2024\u003e, 2024.\n\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @Article{hess-28-3051-2024,\n        AUTHOR = {Song, Y. and Knoben, W. J. M. and Clark, M. P. and Feng, D. and Lawson, K. and Sawadekar, K. and Shen, C.},\n        TITLE = {When ancient numerical demons meet physics-informed machine learning:\n        adjoint-based gradients for implicit differentiable modeling},\n        JOURNAL = {Hydrology and Earth System Sciences},\n        VOLUME = {28},\n        YEAR = {2024},\n        NUMBER = {13},\n        PAGES = {3051--3077},\n        URL = {https://hess.copernicus.org/articles/28/3051/2024/},\n        DOI = {10.5194/hess-28-3051-2024}\n    }\n    ```\n\n    \u003c/details\u003e\n\n    \u003c/br\u003e\n\n3. **(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. \u003chttps://doi.org/10.1029/2025WR040414\u003e\n\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @article{https://doi.org/10.1029/2025WR040414,\n      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},\n      title = {Physics-Informed, Differentiable Hydrologic Models for Capturing Unseen Extreme Events},\n      journal = {Water Resources Research},\n      volume = {62},\n      number = {2},\n      pages = {e2025WR040414},\n      keywords = {differentiable models, LSTM, physics-informed machine learning, HBV, extreme event},\n      doi = {https://doi.org/10.1029/2025WR040414},\n      url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2025WR040414},\n      eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2025WR040414},\n      note = {e2025WR040414 2025WR040414},\n      year = {2026}\n    }\n    ```\n\n    \u003c/details\u003e\n\n    \u003c/br\u003e\n\n4. **(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. \u003chttps://doi.org/10.1029/2024WR038928\u003e\n\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @article{https://doi.org/10.1029/2024WR038928,\n        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},\n        title = {High-Resolution National-Scale Water Modeling Is Enhanced by Multiscale Differentiable Physics-Informed Machine Learning},\n        journal = {Water Resources Research},\n        volume = {61},\n        number = {4},\n        pages = {e2024WR038928},\n        keywords = {differentiable modeling, physics-informed machine learning, National Water Model, routing, Muskingum Cunge, multiscale training},\n        doi = {https://doi.org/10.1029/2024WR038928},\n        year = {2025},\n    }\n    ```\n\n    \u003c/details\u003e\n\n    \u003c/br\u003e\n\n5. **(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. \u003chttps://arxiv.org/abs/2510.08488\u003e **[Under Review]**\n\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @misc{yang2025diffusionbasedprobabilisticmodelinghourly,\n          title={Diffusion-Based Probabilistic Modeling for Hourly Streamflow Prediction and Assimilation},\n          author={Wencong Yang and Haoyu Ji and Leo Lonzarich and Yalan Song and Chaopeng Shen},\n          year={2025},\n          eprint={2510.08488},\n          archivePrefix={arXiv},\n          primaryClass={physics.geo-ph},\n          url={https://arxiv.org/abs/2510.08488},\n    }\n    ```\n\n    \u003c/details\u003e\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](https://github.com/mhpi/hydrodl2/blob/master/docs/CONTRIBUTING.md) for details.\n\n---\n\n*Please submit an [issue](https://github.com/mhpi/hydrodl2/issues) to report any questions, concerns, or bugs.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhpi%2Fhydrodl2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhpi%2Fhydrodl2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhpi%2Fhydrodl2/lists"}