Raven hydrologic model: Framework for flexibility

Download buttonContact

james craigJames Craig, Department of Civil and Environmental Engineering, Canada Research Chair in Hydrologic Modelling and Analysis


Computational hydrological models have become increasingly complex and wide-ranging. The sophisticated physics of mixed-saturation soil water flow, evapotranspiration, snow melt, overland flow, and heat transfer at multiple interacting time and spatial scales often limit their direct incorporation into existing hydrological models. A variety of ways exist to represent any given physical process. The choices for any pathway are typically made by the model developer, and influence the capability of the model to adequately simulate the hydrological processes in a given watershed.

To date, no single model allows for the vast array of discrete model choices to be individually or collectively assessed, especially not while supporting other features often deemed essential in operational hydrologic modelling. One solution is to use a flexible hydrologic modelling framework that can support and test a wide variety of modelling approaches while avoiding the pitfalls of excessive abstraction. Raven is a such a framework.

In this article, we outline the general structure of Raven and its implementation, discuss its development and application, and report on a number of unique model features.


Raven is a unique modelling framework that is compatible with a wide range of hydrological process representations, model structures, discretization approaches, parameterizations, and numerical algorithms that can be found in individual hydrological models. The fundamental spatial discretization approach used in Raven is consistent with most semi-distributed surface water models (Figure 1). In Raven, a watershed-scale model is composed of a number of subbasins through which water is routed. Each subbasin contains a stream/river channel discretized into reaches, and is subdivided into contiguous or non-contiguous hydrological response units (HRUs). Raven simulates the hydrologic system by solving for a coupled system of ordinary and partial differential equations within each HRU. While some hydrologic processes can be simply treated as the movement of water mass or energy from one storage compartment to another, many processes are too coupled to be represented in such a simple fashion. Raven supports over 100 hydrologic process algorithms and has been uniquely designed to support conditional application of these processes.

 The various discretization schemes that can be simulated using Raven (a) semi-distributed by basin (b) semi-distributed by grid (c) triangulated irregular network (d) lumped.

Figure 1: The various discretization schemes that can be simulated using Raven: (a) semi-distributed by basin, (b) semi-distributed by grid, (c) triangulated irregular network and (d) lumped.

The data needs to parameterize models often increases dramatically as they move from lumped to distributed approaches. In Raven, this issue is alleviated by assuming that each HRU belongs to a unique set of non-overlapping classifications, including vegetation, land use, terrain and soil classes. The benefit of this approach is that parameters need only be specified on a class-by-class basis rather than an HRU-by-HRU basis, simplifying the mechanics of calibration, data storage, and improving the transferability of parameters to ungauged basins.

Climatic data required by Raven includes, at a minimum, time series of total precipitation and minimum, maximum or average daily temperature. From these, Raven includes a suite of algorithms for determining related forcings, such as potential evapotranspiration, potential melt, short and long-wave radiation and snow-rain partitioning.

Raven’s hydrological simulations are characterized by two independent levels of temporal discretization as the global solution algorithm is decoupled from the individual process algorithms. At the top level, a user-specified global time step is used, while individual process algorithms can use smaller independent time steps to meet stability constraints or to react to specific occurrences, for example storm events. This flexibility minimizes the need to address complicated temporal discretization when building simpler process models, while still accommodating complex processes, which require fine temporal discretization. To facilitate flexibility in choice of routing algorithms, Raven was generalized to accommodate the quickflow/baseflow output from HRUs and to consistently represent the state variables of volumetric flow along the basin reach.

Lastly, Raven is the only known flexible hydrologic modelling framework that supports contaminant transport processes. The advective transport model is incorporated such that the water balance simulation is wholly independent of the transport simulation. This implies that when new hydrological process algorithms are added, they automatically support advective transport.


The Raven hydrologic modelling framework has been formalized to accommodate a wide range of model structures, process representations, spatial discretization approaches, interpolation methods, and numerical algorithms. While Raven possesses similar traits to existing modelling frameworks, the Raven framework is distinct in a number of notable ways, it:

  • Includes a generic in-catchment and in-channel advective transport routine which is independent of the hydrological model configuration;
  • Has been designed for operational application as well as research deployment, and therefore directly supports the simulation of lakes, wetlands, reservoirs, irrigation demand, injection and extraction from reservoirs and streams, and integration with existing forecasting systems;
  • Supports a range of stream network routing algorithms;
  • Is the only framework which is sufficiently abstracted to mix-and-match any subset of process algorithms and forcing representations;
  • Enables the testing of a wide range of forcing function estimators and process algorithms and therefore supports the assessment of the interplay between forcing estimation and model structure;
  • Allows for the simultaneous comparison and evaluation of routing, forcings, parameter uncertainty, and structural uncertainty, while providing sufficient computational abstraction to evolve as new capabilities are added.

Current research with Raven is aimed at using its flexibility to test methods for improving model structure, assessing and comparing between model choices, and examining the impact of various forms of model uncertainty. The model is also being extended to further support contaminant transport simulation. It is presently used by a number of flood and reservoir inflow forecasting agencies, including BC Hydro, TransAlta, the Government of the Northwest Territories, the Water Security Agency of Saskatchewan, BC River Forecasting Agency and New Brunswick Power. Raven is a fully object-oriented code written in C++, it is open source, and available at http://raven.uwaterloo.ca.

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

For more information about WaterResearch, contact Allie Dusome.