.. include:: ../notations/notations.rst

.. _transfer-reservoir:

==================
Transfer reservoir
==================

The transfer reservoir computes surface runoff |qr| (mm) and seepage |qs| (mm)
from the effective rainfall |RE| (mm). |HT| (mm) is the transfer reservoir water
level.

.. _transfer_reservoir_parameters:

Physical parameters
===================

Runoff/seepage ratio height
---------------------------

The runoff/seepage ratio height |HR| (mm) is the water level for which surface
runoff and infiltration are equal. For example, if |HT| is equal to :math:`n`
times |HR|, surface runoff is equal to :math:`n` times infiltration.

Should be optimised. Default value is 70 mm.

.. code-block:: toml

    [watershed.1]
    transfer.runsee = { value = 70.0, lower = 0.1, upper = 5000., opti = true, sameas = 0 }

Transfer halflife time
----------------------

Transfer reservoir halflife time |tT| (months). This parameter characterizes the
response time between an effective rainfall and an increase in the river flow
slow component. Common values are:

* 0.5 months for rapid river flows
* 1 to 5 months for sources or deep groundwater level evolutions.

Should be optimised. Default value is 1 month.

.. code-block:: toml

    [watershed.1]
    transfer.halflife = { value = 0.5, lower = 0.01, upper = 10.0, opti = true, sameas = 0 }

Overflow fate
-------------

Fate of overflow. 

    =================  =========================================
    loss               description
    =================  =========================================
    ``'no'``           Overflow is directly added to the river
                       flow.
    ``'loss'``         Overflow leaves the system.

    ``'groundwater'``  Overflow is added to the baseflow
                       component of the river flow.
    =================  =========================================

Default value is "no".

.. code-block:: toml

    [watershed.1]
    transfer.overflow.loss = "no" 

Overflow threshold
------------------

Overflow threshold |HO| (mm). If |HT| > |HO| threshold, an overflow occurs. If
equal to zero, overflow is deactivated. 

Default value is 0.

.. code-block:: toml

    [watershed.1]
    transfer.overflow.threshold = { value = 0.0, lower = 0.0, upper = 10.0, opti = false, sameas = 0 }

Overflow halflife time
----------------------

Overflow half-life time |tTO| (|timestep|). It controls the response time of the
reservoir level decrease due to overflow. A value of zero means instantaneous
overflow.

Default value is 0.

.. code-block:: toml

    [watershed.1]
    transfer.overflow.halflife = { value = 0.0, lower = 0.001, upper = 10.0, opti = false, sameas = 0 }

Calculation of surface runoff and seepage
=========================================

Instantaneous runoff :math:`u_r` (|mm/s|) and seepage
:math:`u_s` (|mm/s|) take place simultaneously according to
two types of reservoir draining:

.. math::

    u_r &= \frac{H_t^2}{\tau H_r} \\
    u_s &= \frac{H_t}{\tau}

:math:`\tau` (s) is a time constant defining the exponential decay of |HT|.
:math:`\tau` is related to |tT| through the relationship:

.. math::

    \tau = (30.41 \cdot 86400)\frac{t_{1/2}^t}{\ln(2)}.

|HT| decreases over a time step according to the following equation:

.. math::
    :label: eq:H

    \frac{dH_t}{dt} = -u_r -u_s

In |rameau|, the transfer reservoir is fed at the beginning of each
time step of duration |Deltat| by a sudden inflow of effective
rainfall |RE| coming from the soil reservoir in the form of a
Dirac. :math:`H_0` is the value of |HT| at the beginning of the time step
(:math:`t = 0`). Then,

.. math::

    H_0 = H_0 + R_E

Overflow |qto| (mm) may occur if |HO| > 0. In this case, if :math:`H_0 > H_o`,
overflow occurs according to a linear exponential draining of half-life time
|tTO| (|timestep|) and :math:`H_0` is updated consequently:

.. math::

    q_o & = \frac{H_0 - H_o}{T_o} \\
    H_0 & = \max \left ( H_0 - q_o, 0. \right )

with 

.. math::

    T_o = \frac{1}{1 - \exp \left(-\frac{\ln2}{t_{1/2}^o} \right)}.

The analytical solution of the equation :eq:`eq:H` is:

.. math::

    H_t(t) & = \frac{CH_r\exp \left (\frac{-t}{\tau} \right )}{1 - C\exp \left (\frac{-t}{\tau} \right )} \\
         C & = \frac{1}{1 + \frac{H_r}{H_0}}.

Integrating :math:`u_s` between :math:`t` and :math:`t + \Delta t` gives the 
seepage flowing during the time step |qs| (mm):

.. math::

    q_s & = H_r\ln \left ( \frac{1 - C \exp \left (-\frac{\Delta t}{\tau} \right )}{1 - C} \right ) \\
        & = H_r\ln \left ( 1 + \frac{H_0}{H_r} \left (1 - \exp \left(-\frac{\Delta t}{\tau} \right ) \right ) \right ) \\
        & = H_r\ln \left ( 1 + \frac{H_0}{T_hH_r} \right )

with:

.. math::

    T_h = \frac{1}{1 - \exp \left(-\frac{\Delta t}{\tau} \right)}.

Finally, mass conservation gives:

.. math::

    q_r = (H_0 - H_t(\Delta t)) - q_s