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 snowmelt calculations

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

• Flexible ET modeling – read from data or use the Thornthwaite–Chang equation

• Mass-conserving – strict water balance closure each water year

• Model evaluation – built-in Nash–Sutcliffe Efficiency (NSE) computation

• 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

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
  • Complete Example
  • Illustrative Starting Points
• Model Description
  • Theory & Mathematical Formulation
  • Daily Water Balance
  • Snowpack Module (Optional)
  • Linear Reservoir Cascade
  • Evapotranspiration
  • Model Skill Evaluation
  • Model Assumptions & Limitations

Reference

• API Reference
  • Buckets
  • Reservoir
  • Snowpack
• References
  • Key Publications
  • Related Work
  • Software
  • External Resources

Quick Example

Python API:

import hydroravens

model = hydroravens.Buckets()
model.initialize('config.yml')
model.run()
nse = model.computeNSE(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.