.. include:: notations/notations.rst

===============
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 :ref:`snow-reservoir` inside which snow melting can occur,
* a :ref:`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 :ref:`transfer-reservoir` that produces
  surface runoff and infiltration
* one or several :ref:`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 |m3/s| to simulate
the river flow at the outlet of the simulated watershed. Eventually groundwater
reservoir level in mm is converted in m to simulate a groundwater level.

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 :ref:`tomlfile` or by using the Python API.

Building a model relies on several steps. First, :ref:`input-data` must be
provided. Then, the user defines the cluster of :ref:`watersheds <watersheds>`
simulated by the model. How these watersheds are interconnected between
each other to form the stream network is provided by :ref:`the branch tree <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 :ref:`simulation` mode to run a single simulation,
* the :ref:`Optimization <optimization>` mode to perform a parameter estimation,
* the :ref:`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:

.. code-block:: bash

    rameau-cli 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.

.. code-block:: toml

    [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, :ref:`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 or by using a TOML
file.