Main principles

How the model works

Rameau is a semi-distributed hydrological model that describes hydrological systems as a cluster of watersheds connected to each other from upstream to downstream. A lumped model simulates the water cycle in each watershed using at most four reservoirs flowing into each other. Each reservoir corresponds to a component of the hydrological system:

  • a Snow reservoir inside which snow melting can occur,

  • a Soil reservoir that represents the first few centimeters of soil in which evapotranspiration occurs (zone of influence of vegetation roots),

  • an intermediate zone in the form of a Transfer reservoir that produces surface runoff and infiltration

  • one or several Groundwater reservoirs connected to each other to form a Nash cascade for simulating multilayer aquifer systems, which in turn produces baseflow towards the river.

Lumped models take as inputs meteorological data (rainfall, PET, snowfall, temperature) as water levels in mm. The model performs a water balance in mm between the inputs and the outputs (flows or AET) at each computational time step. Reservoir output flows are converted in \(\mathrm{m^3.s^{-1}}\) to simulate the river flow at the outlet of the simulated watershed.

The calculation involves two functions traditionally known as the production function and the transfer function.

The production function identifies which water quantity will be evaporated or infiltrated in the soil layers for getting out later at the outlet of the watershed. The production function occurs in the soil reservoir.

The transfer function identity when the water that was not evaporated will reach the outlet of the watershed or will reach the aquifer. The transfer function occurs in the transfer and groundwater reservoir(s).

How to build a model

Model can be built either through a TOML configuration file or by using the API.

Building a model relies on several steps. First, Input data must be provided. Then, the user defines the cluster of watersheds simulated by the model. How these watersheds are interconnected between each other to form the stream network is provided by the branch tree. The branch tree is optional only when a single watershed is simulated.

Before using the model, several settings related to the operating mode of Rameau need to be defined. There are three operating modes when using Rameau:

  • the Simulation mode to run a single simulation,

  • the Optimization mode to perform a parameter estimation,

  • the Forecast mode to issue an ensemble forecast.

How to use the model

You can use Rameau either through the command line interface (CLI) or through the Python API. The command line interface is a convenient way to run simulations without writing code. The Python API is more flexible and allows you to build more complex models and use the Python ecosystem.

Using Rameau through the CLI

To use Rameau through the CLI, you need to pass the TOML configuration file to the as an argument to run the model:

./rameau my_model.toml

For performing a single simulation, optimisation and forecast mode needs to be deactivated by setting the maxit key to zero and the forecast key to false, respectively.

[optimization]
maxit = 0
[forecast]
forecast = false

For performing a parameter estimation, turn the maxit key to a positive integer. For performing a forecast, turn the forecast key to true. Both optimisation and forecast mode are compatible: a parameter estimation will be performed before the forecast.

Once the model run is done, Outputs are generated in a specific folder depending on the simulation name. Outputs depend on the operating mode.

Using Rameau through the Python API

A Model can be created through the Python API from scratch of by using a TOML file.