dhbv2 0.5.2

NextGen-compatible δHBV2.0 rainfall-runoff module.

δHBV2.0: Differentiable Rainfall-Runoff Module

---

δ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.

This repository serves as an operations-level module for NOAA-OWP’s Next Generation National Water Modeling Framework (NextGen). It provides Basic Model Interface (BMI) adapters for two modeling modalities:

1. δHBV 2.0: Daily timestep simulation.
2. δHBV 2.0 MTS: Hourly timestep simulation using a Multi-TimeScale (MTS) architecture.

Installation

uv pip install dhbv2

For operational deployment and NextGen setup, see docs.

Model Descriptions

Models are built on the generic differentiable modeling framework δMG.

1. δHBV 2.0 (Daily)

First introduced by Song et al. (2024) [1].

The 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:

$$ \begin{align} \theta_{d, m}^{1:t} &= \text{LSTM}( x_m^{1:t}, A_m ) \ \theta_{s, m} &= \text{MLP}( A_m ) \ Q_k^{1:t}, S_k^{1:t} &= \text{HBV}(x_m^{1:t}, \theta_{d, m}^{1:t}, \theta_{s, m}) \end{align} $$

where:

• $\theta$: Learned dynamic ($d$) and static ($s$) parameters.
• $x_m, A_m$: Forcings and attributes for unit basin $m$.
• $Q, S$: Model fluxes (e.g., streamflow) and states (e.g., snowpack).

As 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.

Since 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.

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.

E.g., simulations starting 01/01/2009 00:00 require an input dataset timeseries starting at 01/01/2008 00:00.

2. δHBV 2.0 MTS (Hourly)

Introduced by Yang et al. (2025) [2].

The 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:

• Caching: Caches ~351 days of aggregated daily inputs and ~7 days of hourly inputs.
• Warmup: Performs warmup steps using the cache to prime low-frequency (daily) and high-frequency (hourly) model states before generating hourly predictions.
• Rolling Window: After 7 days of hourly simulation, the cache window shifts forward 7 days and the warmup is repeated.

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.

E.g., simulations starting 01/01/2009 00:00 require an input dataset timeseries starting at 01/08/2008 00:00.

NextGen Configuration

To use these models in NextGen, reference the specific class in your realization configuration.

Daily Simulation

Use dhbv2.bmi.DeltaModelBmi.

{
    "time_step": 3600,
    "tag": "ngen_dhbv",
    "formulation": {
        "params": {
            "python_type": "dhbv2.bmi.DeltaModelBmi",
            "model_type_name": "dhbv2.0",
            "init_config": "/path/to/bmi_config.yaml"
        }
    }
}

Hourly (MTS) Simulation

Use dhbv2.mts_bmi.MtsDeltaModelBmi.

{
    "time_step": 3600,
    "tag": "ngen_dhbv_mts",
    "formulation": {
        "params": {
            "python_type": "dhbv2.mts_bmi.MtsDeltaModelBmi",
            "model_type_name": "dhbv2.0 mts",
            "init_config": "/path/to/mts_bmi_config.yaml"
        }
    }
}

Operational Deployment

See docs for installation and runtime instructions.

Repository Organization

This package is designed to be installed as a Python dependency or placed in NextGen's extern/ directory.

src/dhbv2/
├── bmi.py          # Daily BMI adapter
├── mts_bmi.py      # Hourly (MTS) BMI adapter
├── pet.py          # Utility for PET calculations
└── utils.py        # Shared utilities

Citation

1. 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},
   }
   

2. 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},
   }
   

Funding for this project was provided by the National Oceanic & 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).

Contributing

We welcome contributions! See CONTRIBUTING.md for details.

---

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