Home About Downloads Utilities RavenR Forum the Team


The Raven Hydrological Framework supports a wide variety of modelling options, and sits atop a robust and extendible software architecture. It is being used by a number of organizations within Canada for reservoir management and flood forecasting.

Flexible Discretization
Raven supports a generic discretization approach whereby the land surface is subdivided into subbasins, which are collections of hydrological response units (relatively homogeneous land parcels with a unique hydrologic signature). Water is distributed vertically within HRUs and redistributed laterally via routing. The geometry of the land parcels may conform to a fixed grid (as done with many fully distributed models or land surface schemes), using a subcatchment-discretized approach, or treated using a single lumped watershed.

Flexible Process Representation
Models built with Raven can be assembled using a wide variety of hydrological process descriptions, ranging from simple empirical models to complex physically-based schemes. Algorithms used to describe fluxes of water and energy in the system can vary spatially and temporally, and are rigorously connected with an intelligent global solver which appropriately handles constraints and thresholds. Raven has over 80 hydrological process algorithms and over 40 forcing function generators with which to assemble models.

Raven provides a number of features which make model assembly, manipulation, and application easy for practical application. It can handle man-made inflows and outflows to the stream network, simulate time-dependent reservoir operation rules, handle time-dependent land use changes. Hydrologic process application may be conditional upon land cover, enabling a single model to handle mountains, foothills, and valleys with three separate (and appropriate) model configurations. Input time series coverage and temporal resolution is independent of the model time period, so the same model can be run for a different duration at a different timestep with a different start date only by editing three lines of a single input file. Most modeled parameters and states may be overridden by user-specified time series, which is useful in calibration and data integration.

Custom Output and Diagnostics
Raven provides complete control over generated output, allowing for easily generated reports on the statistics and distributions of modeled state variables such as soil moisture or snow depth or system fluxes such as evapotranspiration or groundwater recharge. Raven can also generate more than a dozen model quality diagnostics when provided with observed hydrographs, reservoir stages, or any other time series corresponding to a modeled state variable.

Emulation Capabilities
Raven is uniquely capable of emulating other hydrological modelling codes by building the model structure piecemeal. Level 1 (near-exact) emulation has been implemented for the hydrological simulators HBV-EC (Environment Canada's version of the HBV code), GR4J, and the UBC Watershed Model developed by Dr. Michael Quick of the University of British Columbia. Level 2 (conceptual) emulation is available for various algorithms comparable to those used within Brook90, SWAT, VIC, PRMS, and/or described within various hydrological texts, such as Dingman's 2002 'Physical Hydrology'. A complete description of available algorithms is included in the manual.

Raven is fast. Really fast. Optimized for both speed and flexibility, Raven is perfect for optimization, parameter estimation, and ensemble forecasting where thousands of model evaluation runs can be run in minutes. It is also platform-independent, compiling on Windows, Linux, and Mac.

Parameter Manipulation
Raven has a library of pedotransfer functions and empirical relationships that allow the user to autogenerate parameters from simple soil and land use specifications. All parameters are assigned to soil, land use, vegetation, and terrain classes (rather than to specific land parcels), encouraging parameter parsimony and portability of calibrated parameter sets.

Open Source
Available code where you can see what its doing (presuming, of course, you understand c++). Under the Artistic License 2.0, Raven source code is freely available, well-documented, and you can modify it in-house to meet your specific project needs.

Model Coverage
Raven Model Coverage Area

Papers/Theses using Raven

To cite Raven, please use:

Craig, J.R., G. Brown, R. Chlumsky, W. Jenkinson, G. Jost, K. Lee, J. Mai, M. Serrer, M. Shafii, N. Sgro, A. Snowdon, and B.A. Tolson, Flexible watershed simulation with the Raven hydrological modelling framework, Environmental Modelling and Software, 129, 104728, doi:10.1016/j.envsoft.2020.104728, July 2020 (paper)

To cite Raven technical details for technical reports, the current version of the User and Developer's manual:

Craig, J.R., and the Raven Development Team, Raven user's and developer's manual (Version 3.0.x), URL: http://raven.uwaterloo.ca/ (Accessed xxx, 2021).

Raven-related papers/theses:

Brown, G., and J.R. Craig, Multi-gauge calibration of a hydrological model of the Liard river basin, Canadian Water Resources Journal, 2020 (paper)

Brown, G., Application of a Hydrological Model for Predicting River Ice Breakup", MASc thesis, University of Waterloo, 2019

Chernos, M., R. MacDonald, J.R. Craig, Efficient semi-distributed hydrological modelling workflow for simulating streamflow and characterizing hydrologic processes, Confluence: Journal of Watershed Science and Management, , 1(3), 2017 (paper)

Chernos, M., R. MacDonald, M.W. Nemeth, and J.R. Craig, Current and future projections of glacier contributions to streamflow in the Upper Athabasca River basin, Canadian Water Resources Journal, 2020 (paper)

Chlumsky, R., "Rigorous validation of hydrologic models in support of decision-making", MASc thesis, University of Waterloo, 2017

Chlumsky, R., J. Mai, J.R. Craig, and B.A. Tolson, Simultaneous calibration of hydrologic model structure and parameters using a blended model, Water Resources Research, 57, e2020WR029229, doi:10.1029/2020WR029229, 2021 (paper)

Jansen, K., A. J. Teuling, J.R. Craig, M. Dal Molin, W. Knoben, J. Paarajka, M. Vis, L.A. Melsen, Mimicry of a conceptual hydrological model (HBV): What’s in a name? Water Resources Research, e2020WR029143, doi:10.1029/2020WR029143, 2021 (paper)

Leach, J.A., J.M. Buttle, K.L. Webster, P.W., Hazlett, and D.S. Jeffries, Travel times for snowmelt-dominated headwater catchments: Influences of wetlands and forest harvesting, and linkages to stream water quality Hydrological Processes 34, p2154-2175, 2020, doi:10.1002/hyp.13746 (paper)

Lee, K., Assessing the utility of hydrologic model diagnostics for decision support", MASc thesis, University of Waterloo, 2018

Mai, J. , B. A. Tolson, H. Shen, É. Gaborit, V. Fortin, N. Gasset, H. Awoye, T. A. Stadnyk, L. M. Fry, E. A. Bradley, F. Seglenieks, A. G. Temgoua, D. G. Princz, S. Gharari, A. Haghnegahdar, M. E. Elshamy, S. Razavi, M. Gauch, J. Lin, X. Ni, Y. Yuan, M. McLeod, N. Basu, R. Kumar, O. Rakovec, L. Samaniego, S. Attinger, N. K. Shrestha, P. Daggupati, T. Roy, S. Wi, T. Hunter, J. R. Craig, and A. Pietroniro The Great Lakes runoff intercomparison project phase 3: Lake Erie (GRIP-E), Journal of Hydrologic Engineering, 26(9), 2021 (paper)

Mai, J., J.R. Craig, and B.A. Tolson, Simultaneously determining global sensitivities of model parameters and model structure, Hydrology and Earth System Science, 24, p5835-5858, 2020 (paper)

Sgro, N., "Formal hypothesis testing for prospective hydrological model improvements", MASc thesis, University of Waterloo, 2016

Shafii, M. J.R. Craig, M.L. Macrae, M. C. English, S. Schiff, P. van Cappellen, and N. Basu, A diagnostic approach to constraining flow partitioning in hydrologic models using a multi-objective optimization framework, Water Resources Research, 53, doi:10.1002/2016WR019736, 2017 (paper)

Snowdon, A., "Improved numerical methods for distributed hydrological models", MASc thesis, University of Waterloo, 2010

Snowdon, A., "Upscaling of coupled models with topography-driven surface-water/groundwater interactions", PhD thesis, University of Waterloo, 2016

Spieler, D., B.A. Tolson, J. Mai, J.R. Craig, and N. Schuetze, Automatic model structure identification for conceptual hydrologic models, Water Resources Research, 2020 (paper)

Weier, J., Niederschlag-Abfluss-Modellierung unter Hinzunahme eines Permafrostmoduls am Beispiel der Selenga (Precipitation runoff modeling with the addition of a permafrost module using the example of Selenga), MSc Thesis, Universität Heidelberg, 2019

Yao H, Field T, McConnell C, Beaton A, James AL. Comparison of five snow water equivalent estimation methods across categories. Hydrological Processes. 2018;32:1894–1908. https://doi.org/10.1002/hyp.13129

Raven Applications/Presentations

Raven development has been supported by the following organizations:

Alberta Environment and Parks Alberta WaterSmart ArcticNet BC Hydro City of Calgary Canarie Environment Canada FloodNet Geoscience BC Mac Hydro Northwest Hydraulic Consultants National Research Council Canada National Resources Canada Okanagan Basin Water Board New Brunswick Department of Environment and Local Government Northwest Territories ENR NSERC Ontario Power Generation Ouranos Petroleum Technology Alliance Canada TransAlta Water Security Agency
En français