HydroRaVENS Documentation

A simple, flexible reservoir-based hydrological model for water balance simulation and streamflow prediction.

HydroRaVENS (Rain and Variable Evapotranspiration, Nieve, and Streamflow) is a conceptual daily-timestep model that routes precipitation through an optional snowpack and a cascade of linear reservoirs. Ideal for ungauged basins, climate impact studies, and educational applications.

Key Features

• Optional snowpack module – positive-degree-day melt with rain-on-snow sensible heat

• Optional frozen ground module – Molnau & Bissell FGI blocks deep infiltration

• Cascading linear reservoirs – stack multiple reservoirs from soil to groundwater

• Flexible ET – read from data or compute with the Thornthwaite–Chang equation

• Exact annual water balance – ET scaled so P - Q - ET = 0 over each water year

• Calibration module – KGE, NSE, and log-KGE scoring; AIC; baseflow index; flow duration curve; Nash-cascade channel routing; decadal chaining

• Python API and command-line interface

• Lightweight – minimal dependencies (NumPy, Pandas, Matplotlib, PyYAML)

Getting Started

• Installation
  • Requirements
  • From PyPI
  • From Source (Development)
  • Installing Documentation Dependencies
  • Verification
  • Troubleshooting
  • Next Steps
• Quick Start
  • Prepare Your Data
  • Create a Configuration File
  • Run the Model
  • Adjust Parameters
  • Next Steps
• Tutorial: From Data to Calibrated Model
  • Overview
  • Input Data Format
  • Stage 1 — Estimate Priors
  • Stage 2 — Write a Configuration File
  • Stage 3 — Quick Check Before Calibrating
  • Stage 4 — Calibrate
  • Stage 5 — Evaluate
  • See Also

User Guide

• Configuration Reference
  • Configuration File Structure
  • The timeseries section
  • The initial_conditions section
  • The catchment section
  • The general section
  • The reservoirs section
  • The snowmelt section
  • The modules section
  • ET Module Parameters
  • Complete Example
  • Illustrative Starting Points
• Model Description
  • Theory & Mathematical Formulation
  • Daily Water Balance
  • Optional Process Modules
  • Snowpack Module (Optional)
  • Frozen Ground Module (Optional)
  • Regional Groundwater Import (Optional)
  • Direct Runoff Bypass (Optional)
  • Linear Reservoir Cascade
  • Nonlinear (Power-Law) Recession (Optional)
  • Saturation-Excess Runoff (PDM, Optional)
  • Suggested Model Structures
  • Evapotranspiration
  • Model Skill Evaluation
  • Model Assumptions & Limitations

Reference

• API Reference
  • Buckets
  • Reservoir
  • Snowpack
  • run_and_score
  • CalibResult
  • HydrographSeparation
• Calibration
  • run_and_score()
  • CalibResult
  • Goodness-of-Fit Metrics
  • Practical Calibration Workflow
  • Suggested Parameter Sets
• Recession Analysis
  • Theory
  • Brutsaert–Nieber Analysis
  • Using Results in HydroRaVENS
  • Workflow
  • Goodness of fit and the power-law assumption
  • Interpretation guide
  • References
• Data-Driven Priors
  • suggest_priors()
  • Priors
• References
  • Model Development
  • Snowpack and Rain-on-Snow
  • Frozen Ground
  • Evapotranspiration
  • Reservoir Cascade Structure
  • Channel Routing
  • Model Calibration and Evaluation
  • Software
  • External Resources

Integration

• CSDMS Basic Model Interface
  • Overview
  • Installation
  • Usage
  • Exposed Variables
  • Grid and Time
  • Caveats
  • API Reference

Quick Example

Python API:

import hydroravens

model = hydroravens.Buckets()
model.initialize('config.yml')
model.run()
nse = model.compute_NSE(verbose=True)
model.plot()

Command-line:

hydroravens -y config.yml

Getting Help

• Report bugs: GitHub Issues

• Discuss: GitHub Discussions

• Learn more: CSDMS Model Page

About

HydroRaVENS is developed and maintained by the MNiMORPH group. It is published under the GNU General Public License v3.0.

Citation:

If you use HydroRaVENS in your research, please cite it using the information in CITATION.cff at the repository root, or via the Zenodo DOI badge above.