Add dHBV2.0 MTS (hourly) #385
Description
1. Contributor Information
- Name: Leo Lonzarich
- Email: lgl5139@psu.edu
- Institution/Organization: The Pennsylvania State University
- GitHub Username: leoglonz
- Model Name: dhbv2_mts
- Model Version: v0.4.0
- Date Submitted: 23 Jan 2026
2. Model Overview
Basic Information
- Model Description: (Provide a brief description of what the model does)
dHBV2.0 MTS is a multi-timescale, distributed differentiable HBV model for rainfall-runoff simulation. This is the hourly-resolution successor to the daily model, dHBV2.0, which was integrated earlier.
Note, models live in the same NextGen module, dhbv2.
-
Model Type: (Check all that apply)
- Hydrologic Process Model
- Routing Model
- Forcing Engine
- Calibration Tool
- Post-processing Tool
- Other: _______________
-
Programming Language(s):
- C/C++
- Fortran
- Python
- Other: _______________
-
Primary Use Case:
dhbv2_mts is intended to provide runoff predictions at hourly resolution on the CONUS hydrofabric. While it is capable of river routing, we defer to T-Route here.
3. Technical Requirements
BMI Compliance
-
BMI Implementation: Does your model implement the Basic Model Interface (BMI)?
- Yes - Full BMI implementation
- Partial - Specify which functions: _______________
- No - Plan to implement: _______________
-
BMI Language Binding:
- C
- C++
- Fortran
- Python
- Other: _______________
Dependencies
-
Required Libraries: (List all required libraries and their versions)
-
uv
-
gcc
-
gcc-c++
-
System Dependencies: (List any system-level requirements)
- Python 3.9 or later
-
Python Packages: (If applicable, list required Python packages)
- bmipy
- dmg @master
- hydrodl2 @master
- h5netcdf
- numpy~=1.0
- pandas
- pre-commit
- torch
- tqdm
- uv
- xarray
Build System
-
Build System Used:
- CMake
- Make
- Autotools
- Python setuptools
- Other: _______________
-
Build Instructions Provided:
- Yes - Link: https://github.com/mhpi/dhbv2/blob/master/docs/1-module_setup.md
- Need assistance
-
Compilation Flags/Options: (List any special compilation requirements)
None
4. Code Repository
Source Code
-
Repository URL:
-
Repository Access:
- Public
- Private (requires access request)
-
License:
- Open Source License (Specify): _______________
- Proprietary (explain restrictions): No commercial use without permission.
-
Branch/Tag for Integration:
master
Documentation
-
Documentation Available:
- README with basic usage
- Installation guide
- [] API/BMI documentation
- Configuration file documentation
- Example/tutorial
- Scientific documentation/paper
-
Documentation Links:
- README
- Installation guide
- Configuration file documentation
- Example/tutorial
- Scientific documentation/paper
-
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
-
Yang, W., Ji, H., Lonzarich, L., Song, Y., Lawson, K., Shen, C. (2025). [In Review]
-
5. Configuration & Data Requirements
Input Requirements
-
Input File Formats: (List all required input formats)
- NetCDF (.nc)
- CSV (.csv)
-
Required Input Variables: (List all required input variables with units)
- Precipitation (mm/hr)
- Temperature(K)
- PET(mm/hr) -- will be removed in favor of internal BMI calculation soon.
-
Sample Input Data Provided:
- Yes - Link: https://github.com/mhpi/dhbv2/tree/master/ngen_resources/data/
- No - Can provide upon request
Output Specifications
-
Output File Formats:
- NetCDF (.nc)
- CSV (.csv)
- Numpy (.npy)
-
Output Variables: (List all output variables with units)
Runoff (m3/s)
-
Output Frequency:
- Sub-hourly (specify): _______________
- Hourly
- Daily
- Other: _______________
Configuration Files
-
Configuration File Format:
- JSON
- YAML
- INI
- Custom text format
- Other: _______________
-
Sample Configuration Provided:
- Yes - Link: _______________
- No - Can provide
-
Configuration Parameters Documented:
- Yes
- Partial
- No
6. Testing & Validation
Testing Status
-
Unit Tests Available:
- Yes - Coverage: _____%
- No - Plan to add
-
Integration Tests Available:
- Yes
- No
-
Test Data Included:
- Yes - Link: https://github.com/mhpi/dhbv2/blob/master/tests/dhbv2_mts_cat-2453_runoff_benchmark.npy
- No - Can provide
Validation
-
Model Validation Performed:
- Yes - Published results available
- Yes - Internal validation only
- In progress
- Not yet validated
-
Validation Domain/Region:
Tested on CAMELS catchments from 2008-01-09 to 2010-12-31.
-
Performance Metrics: (If available)
-
NSE 0.71
-
More coming
7. Container Compatibility
Docker Requirements
-
Base Image Preference:
- Rocky Linux 9.1 (NGIAB default)
- Ubuntu
- Alpine
- Other: _______________
-
Special Container Requirements:
- Dockerfile will require AWS download to acquire dhbv2_mts model weights, normalization statistics, and configuration file.
- High CPU availability (dhbv2_mts CPU runtime is comparable to GPU parallelized runtimes for systems with >200 CPUs available).
HPC/Singularity Considerations
-
HPC Compatibility Required:
- Yes
- No
- Not sure
-
MPI Support:
- Required
- Optional
- Not needed
-
Parallel Execution Support:
- Shared memory (OpenMP)
- Distributed memory (MPI)
- GPU/CUDA
- Serial only
8. Integration Planning
Timeline
-
Target Integration Date:
- January 2026
-
Development Status:
- Production-ready
- Beta/testing
- Early development
- Proof of concept
Support & Maintenance
-
Maintenance Commitment:
- Will maintain long-term
- Limited support available
- Community maintenance
- Unsure
-
Point of Contact for Technical Questions:
- Name: Leo Lonzarich
- Email: lgl5139@psu.edu
- Preferred contact method: Email or CIROH slack
-
Expected Response Time for Issues:
- Within 24 hours
- Within 1 week
- Best effort
- Other: _______________
Collaboration
-
Open to Collaboration:
- Yes - Open to contributions
- Yes - With approval
- Prefer to maintain independently
-
CIROH/NGIAB Team Support Needed:
- BMI implementation assistance
- Containerization help
- CI/CD pipeline setup
- Documentation improvement
- Testing framework
- Other: _______________
9. Specific NGIAB Integration
Hydrofabric Compatibility
-
Works with NOAA Hydrofabric:
- Yes - Tested
- Should work (not tested)
- Requires modifications
- Not applicable
-
Spatial Resolution:
- Catchment-level
- Grid-based (specify resolution): _______________
- Point-based
- Other: _______________
-
Required Input Variables: (List all required input variables with units)
- Catchment area (km2)
- basin length (km)
- basin area (km2)
(All other parameters are uniquely derived)
- aridity
- NDVI
- FW
- meanslope
- SoilGrids1km_sand
- SoilGrids1km_clay
- SoilGrids1km_silt
- glaciers
- HWSD_clay
- HWSD_gravel
- HWSD_sand
- HWSD_silt
- meanelevation
- permafrost
- permeability,
- snow_fraction,
- T_clay,
- T_gravel,
- T_sand,
- T_silt,
- Porosity,
- catchsize,
- lengthkm,
NextGen Framework Integration
-
Integration Level:
- Core modeling component (replaces/supplements existing formulation)
- Pre-processing tool
- Post-processing tool
- Visualization component
- Evaluation tool
- Other: _______________
-
Compatibility with Existing Components:
- CFE
- NOAH-OWP-Modular
- TOPMODEL
- t-route
- Other formulations: _______________
Data Integration
-
Data Sources Supported:
- NOAA forcing data
- USGS observations
- Custom forcing files
- Other: _______________
-
Compatible with NGIAB Data Preprocess Module:
- Yes - Tested
- Should be compatible
- Requires adaptation
- Not applicable
10. Additional Information
Publications
-
Related Publications: (List papers, reports, or documentation)
-
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
-
Yang, W., Ji, H., Lonzarich, L., Song, Y., Lawson, K., Shen, C. (2025). [In Review]
-
CIROH Project(s)
- CIROH A22-0307-S003: PI: Chaopeng Shen. NOAA NA22NWS4320003: Improving the integration of ML with physically-based hydrologic and routing modeling via large-scale parameter and structure learning schemes
Known Limitations
-
Known Issues/Limitations:
[Describe any known limitations or constraints]
Use Cases
-
Example Use Cases:
- Modeling runoff on catchment scale, which can then be routed through river network by T-Route.
Model runtime cost (e.g., time/memory/cpu cost to forward for X catchments and T timesteps)
N/A -- need to assess
Additional Notes
[Any additional information that would be helpful for integration]
11. Checklist Summary
Pre-submission Requirements (Must Complete)
- Model source code is accessible
- Basic documentation is available
- Dependencies are clearly listed
- Sample configuration file provided
- Build instructions included
- License is specified
- Point of contact identified
Recommended (Strongly Encouraged)
- BMI implementation completed or in progress
- Test data available
- Model has been validated in at least one domain
- Compatible with NGIAB standard formats
- Documentation includes usage examples
Optional (Nice to Have)
- Unit tests included
- Published validation results
- HPC/parallel execution support
- Integration with existing NGIAB tools demonstrated
12. Submission
I confirm that:
- All required information above has been provided
- The model code is ready for review
- I am authorized to submit this model for integration
- I agree to provide reasonable support during integration
Metadata
Metadata
Type
Projects
Status