dhbv2 0.5.0

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

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 01:00 require an input dataset timeseries starting at 01/08/2008 01: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": 86400,
    "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

Publications

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

   BibTeX

   @article{shen2023differentiable,
   title = {High-Resolution National-Scale Water Modeling Is Enhanced by Multiscale Differentiable Physics-Informed Machine Learning},
   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},
   journal = {Water Resources Research},
   volume = {61},
   number = {4},
   pages = {e2024WR038928},
   year={2025},
   doi = {https://doi.org/10.1029/2024WR038928},
   url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2024WR038928}
   }
   

   
   

2. Yang, W., Ji, H., Lonzarich, L., Song, Y., Lawson, K., Shen, C. (2025). [In Review]

Contributing

We welcome contributions! See CONTRIBUTING.md for details.

---

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