{"id":48212827,"url":"https://github.com/mhpi/dhbv2","last_synced_at":"2026-04-04T18:52:32.985Z","repository":{"id":278835048,"uuid":"936916087","full_name":"mhpi/dhbv2","owner":"mhpi","description":"High-resolution, distributed, differentiable HBV with daily-scale output for operations-level integration.","archived":false,"fork":false,"pushed_at":"2026-02-04T19:12:15.000Z","size":11246,"stargazers_count":12,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-02-05T03:50:20.014Z","etag":null,"topics":["hydrology","physics-model","r2o"],"latest_commit_sha":null,"homepage":"https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2024WR038928","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":null,"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":"2025-02-21T23:19:08.000Z","updated_at":"2026-02-04T19:12:18.000Z","dependencies_parsed_at":"2025-12-20T03:01:55.405Z","dependency_job_id":null,"html_url":"https://github.com/mhpi/dhbv2","commit_stats":null,"previous_names":["mhpi/dhbv_2_0"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/mhpi/dhbv2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fdhbv2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fdhbv2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fdhbv2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fdhbv2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhpi","download_url":"https://codeload.github.com/mhpi/dhbv2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhpi%2Fdhbv2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31409470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"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":["hydrology","physics-model","r2o"],"created_at":"2026-04-04T18:52:32.186Z","updated_at":"2026-04-04T18:52:32.969Z","avatar_url":"https://github.com/mhpi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eδHBV2.0: Differentiable Rainfall-Runoff Module\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/dhbv2/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/dhbv2?logo=pypi\u0026logoColor=white\u0026labelColor=333333\" alt=\"PyPI\"\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/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=\"https://github.com/mhpi/dhbv2/actions/workflows/lint.yaml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/mhpi/dhbv2/lint.yaml?branch=master\u0026logo=github\u0026label=lint\u0026labelColor=333333\" alt=\"Build\"\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**δHBV 2.0** is a state-of-the-art, distributed differentiable HBV model leveraging intelligent parameterization, big data, and highly-parallelized GPU compute with PyTorch to deliver CONUS-scale, high-resolution inference of parameters and fluxes.\n\nThis repository serves as an **operations-level module** for NOAA-OWP’s [Next Generation National Water Modeling Framework (NextGen)](https://github.com/NOAA-OWP/ngen). It provides **Basic Model Interface (BMI)** adapters for two modeling modalities:\n\n1. **δHBV 2.0**: Daily timestep simulation.\n2. **δHBV 2.0 MTS**: Hourly timestep simulation using a Multi-TimeScale (MTS) architecture.\n\n\u003c/br\u003e\n\n## Installation\n\n```bash\nuv pip install dhbv2\n```\n\nFor operational deployment and NextGen setup, see [docs](https://github.com/mhpi/dhbv2/tree/master/docs).\n\n\u003c/br\u003e\n\n## Model Descriptions\n\n\u003e Models are built on the generic differentiable modeling framework [δMG](https://github.com/mhpi/generic_deltamodel).\n\n### 1. δHBV 2.0 (Daily)\n\n*First introduced by Song et al. (2024) [[1]](#publications).*\n\nThe daily model uses an LSTM and MLP to learn parameters for the differentiable physical model HBV 2.0. Weather forcings (precipitation, temperature, PET) and static catchment attributes are used as inputs to simulate hydrological states and fluxes:\n\n$$\n    \\begin{align}\n    \\theta_{d, m}^{1:t} \u0026= \\text{LSTM}( x_m^{1:t}, A_m ) \\\\\n    \\theta_{s, m} \u0026= \\text{MLP}( A_m ) \\\\\n    Q_k^{1:t}, S_k^{1:t} \u0026= \\text{HBV}(x_m^{1:t}, \\theta_{d, m}^{1:t}, \\theta_{s, m})\n    \\end{align}\n$$\n\nwhere:\n\n* $\\theta$: Learned dynamic ($d$) and static ($s$) parameters.\n* $x_m, A_m$: Forcings and attributes for unit basin $m$.\n* $Q, S$: Model fluxes (e.g., streamflow) and states (e.g., snowpack).\n\nAs this model is designed to operate at the daily timescale, forcings are aggregated at the end of every day to make a single daily prediction. This prediction is then distributed accross the proceeding 24 hours, at which point a new daily prediction is made.\n\nSince HBV is a recurrent bucket-based model, it must be \"warmed up\" making simulations on a period of data just prior to the target simulation window so that it's states can be allowed to saturate. Incidentally, this process also initializes internal states of the parameterization LSTM.\n\n\u003e Note: To run a simulation in NextGen for a given time period, we require the **prior 365 days** of forcing data be included in the input to satisfy warmup described above.\n\u003e\n\u003e E.g., simulations starting 01/01/2009 00:00 require an input dataset timeseries starting at 01/01/2008 00:00.\n\n### 2. δHBV 2.0 MTS (Hourly)\n\n*Introduced by Yang et al. (2025) [[2]](#publications).*\n\nThe **Multi-TimeScale (MTS)** variant adapts the architecture for hourly simulation. It incorporates a rolling window input caching mechanism to bridge the gap between long-term hydrologic memory and high-frequency forcing:\n\n* **Caching:** Caches ~351 days of aggregated daily inputs and ~7 days of hourly inputs.\n* **Warmup:** Performs warmup steps using the cache to prime low-frequency (daily) and high-frequency (hourly) model states before generating hourly predictions.\n* **Rolling Window**: After 7 days of hourly simulation, the cache window shifts forward 7 days and the warmup is repeated.\n\n\u003e Note: To run a simulation in NextGen for a given time period, the **prior 358 days** of forcing data must be included in the input to satisfy warmup described above.\n\u003e\n\u003e E.g., simulations starting 01/01/2009 00:00 require an input dataset timeseries starting at 01/08/2008 00:00.\n\n\u003c/br\u003e\n\n## NextGen Configuration\n\nTo use these models in NextGen, reference the specific class in your realization configuration.\n\n### Daily Simulation\n\nUse `dhbv2.bmi.DeltaModelBmi`.\n\n```json\n{\n    \"time_step\": 3600,\n    \"tag\": \"ngen_dhbv\",\n    \"formulation\": {\n        \"params\": {\n            \"python_type\": \"dhbv2.bmi.DeltaModelBmi\",\n            \"model_type_name\": \"dhbv2.0\",\n            \"init_config\": \"/path/to/bmi_config.yaml\"\n        }\n    }\n}\n```\n\n### Hourly (MTS) Simulation\n\nUse `dhbv2.mts_bmi.MtsDeltaModelBmi`.\n\n```json\n{\n    \"time_step\": 3600,\n    \"tag\": \"ngen_dhbv_mts\",\n    \"formulation\": {\n        \"params\": {\n            \"python_type\": \"dhbv2.mts_bmi.MtsDeltaModelBmi\",\n            \"model_type_name\": \"dhbv2.0 mts\",\n            \"init_config\": \"/path/to/mts_bmi_config.yaml\"\n        }\n    }\n}\n```\n\n\u003c/br\u003e\n\n## Operational Deployment\n\nSee [docs](https://github.com/mhpi/dhbv2/tree/master/docs) for installation and runtime instructions.\n\n\u003c/br\u003e\n\n## Repository Organization\n\nThis package is designed to be installed as a Python dependency or placed in NextGen's `extern/` directory.\n\n```text\nsrc/dhbv2/\n├── bmi.py          # Daily BMI adapter\n├── mts_bmi.py      # Hourly (MTS) BMI adapter\n├── pet.py          # Utility for PET calculations\n└── utils.py        # Shared utilities\n```\n\n## Citation\n\n1. 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\n2. 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\u003c/br\u003e\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"./docs/images/ciroh.png\" alt=\"CIROH Logo\"\u003e\u003c/td\u003e\n\u003ctd\u003eFunding for this project was provided by the National Oceanic \u0026 Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama (NA22NWS4320003).\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for details.\n\n---\n\n*Please submit an [issue](https://github.com/mhpi/dhbv2/issues) to report any questions, concerns, or bugs.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhpi%2Fdhbv2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhpi%2Fdhbv2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhpi%2Fdhbv2/lists"}