the Raven Hydrological Framework

About

Overview

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.

Practicality

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 twenty 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), HBV-Light, GR4J, HMETS, MOHYSE, SAC-SMA, HYMOD, and the UBC Watershed Model. 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'.

Speed

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

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.7), URL: http://raven.uwaterloo.ca/ (Accessed xxx, 2023).

Raven-related papers/theses:

Arsenault, R., D. Huard, J. Martel, M. Troin, J. Mai, F. Brissette, C. Jauvin, L. Vu, J.R Craig, T. Logan, T.J. Smith, B.A. Tolson, M. Han, S. Langlois, The PAVICS-Hydro platform: a virtual laboratory for hydroclimatic modelling and forecasting over North America, Environmental Modelling and Software, 168, 105808, 2023 (paper)

Brown, G., and J.R. Craig, Structural calibration of a semi-distirbuted 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)

Chlumsky, R., J.R. Craig, S. Lin, S. Grass, L. Scantlebury, G. Brown, and R. Arabzadeh, RavenR: an open source R package to support flexible hydrologic modelling, Geoscientific Model Development, doi:10.5194/gmd-2021-336, 2022 (paper)

Goodbrand, A., Anderson, A., Devito, K. and Silins, U., Untangling harvest-streamflow responses in foothills conifer forests: nexus of teleconnections, summer-dominated precipitation, and storage. Hydrological Processes. e14479, doi:10.1002/hyp.14479, 2022 (paper)

Han, M., J. Mai, B.A. Tolson, J.R. Craig, É. Gaborit, H. Liu, and K. Lee, Subwatershed-based lake and river routing products for hydrologic and land surface models applied over Canada, Canadian Water Resources Journal, doi:10.1080/07011784.2020.1772116, 2020 (paper)

King, L.M. and Micovic, Z. Application of the British Columbia MetPortal for estimation of probable maximum precipitation and probable maximum flood for a coastal watershed. Water 2022, 14, 785. https://doi.org/10.3390/w14050785 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., H. Shen, B.A. Tolson, É. Gaborit, R. Arsenault, J.R. Craig, V. Fortin, L.M. Fry, M. Gauch, D. Klotz, F. Kratzert, N. O’Brien, D.G. Princz, S. Rasiya Koya, T. Roy, F. Seglenieks, N.K. Shrestha, A. G. T. Temgoua, V. Vionnet, and J.W. Waddell, The Great Lakes Runoff Intercomparison Project Phase 4: The Great Lakes (GRIP-GL), Hydrology and Earth System Sci, (in press), 2022 (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)

Mai, J., J.R. Craig, B.A. Tolson, and R. Arsenault, The sensitivity of simulated streamflow to individual hydrologic processes across North America, Nature Communications 13(1), 455, 2022 (paper)(interactive website)

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)

Singh, H., and M. R. Najafi. Evaluation of gridded climate datasets over Canada using univariate and bivariate approaches: Implications for hydrological modelling.. Journal of Hydrology 584 (2020): 124673.(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)

Taheri, M., M. Ranjram, and J.R. Craig, An upscaled model of fill-and-spill hydrological response, Water Resources Research, 59, e2022WR033494. doi:/10.1029/2022WR033494, 2023 (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

Zhou, L., P. Liu, X. Zhang, L. Cheng, Q. Xia, K. Xie, W. Liu, J. Xia, Improving structure identifiability of hydrological processes by temporal sensitivity with a flexible modeling framework, Journal of Hydrology, Volume 616, 2023, https://doi.org/10.1016/j.jhydrol.2022.128843