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

.. _groundwater_parameters:

======================
Groundwater parameters
======================

In Rameau, groundwater reservoirs with an exponential emptying law computes
baseflow |qb| (mm) to the river and eventually drainage |qd| (mm) to the
underlying groundwater reservoir from the infiltration |qs| (mm) coming from the
transfer reservoir 

Groundwater reservoirs can be chained together to form a Nash cascade. In
practice, most configurations use either a single groundwater reservoir or two
groundwater reservoirs, with the second reservoir simulating deeper aquifers
with slower flows. 

The groundwater level |H| (m) is computed from the groundwater reservoir water
level |HG| (mm). In case of several groundwater reservoirs, the one that wille
be used to compute |H| needs to be specified in the parameters.

Two categories subdivide groundwater parameters: groundwater reservoir
parameters related to the physical processes and general parameters related to
groundwater level computation and pumping.

Groundwater general parameters
==============================

Base level
----------

The groundwater base level |HB| (m) is the groundwater level that would be
reached after an infinite time in the absence of any recharge. This parameter
can be estimated either by regression or using a bound-constrained iterative
method. See :ref:`optimization_parameters` for more details.

Should be optimised if parameters estimation rely on observed groundwater
levels. 

.. code-block:: toml

    [watershed.1]
    groundwater.base_level = { value = 0.0, opti = true }


Storage coefficient
-------------------

Storage coefficient of the aquifer |S| (%). Default value is 10%.

.. code-block:: toml

    [watershed.1]
    groundwater.storage.coefficient = { value = 10.0, lower = 0.10000, upper = 90.00000, opti = true, sameas = 0 }

.. note::

    In most cases, |S| is not precisely known, and will have to be calculated by
    the model. It will be interesting to compare his value with the one
    for an unconfined aquifer or an effective porosity value, to see if the order
    of magnitude is roughly the same. However, if the observation point is close
    to a river (or lake), which imposes little variation in level, |S| will be
    considerably higher than the unconfined aquifer's actual storage
    coefficient. Care must also be taken to ensure that |S| is not extremely
    low, to artificially compensate for the fact that the model has evacuated
    most of the flow as surface runoff.

Observed groundwater reservoir
------------------------------

Groundwater reservoir number corresponding to the observed groundwater level
time series. Default value is 1 (first groundwater reservoir corresponding to
an unconfined aquifer).

.. code-block:: toml

    [watershed.1]
    groundwater.observed_reservoir = 1

Direct reservoir pumping
------------------------

If true, groundwater pumping |Qp| provided in the model inputs in |m3/s|
are directly converted in mm and withdrawn from the groundwater
reservoir corresponding to the ``observed_reservoir`` index value. The
conversion from |m3/s| to mm is done using the watershed drainage area as
follows:

.. math::

    q_p = \frac{Q_p10^{-3}\Delta t}{A}

with |A| (km²) the watershed area and |Deltat| (s) the time step duration.

.. code-block:: toml

    [watershed.1]
    groundwater.direct_reservoir_pumping = false


.. _groundwater-reservoirs:

Groundwater reservoir parameters
================================

Baseflow halflife time
----------------------

The baseflow halflife time |tGB| (months) is the time after which, in the
absence of recharge, the flow rate towards the river is halved. A value of
zero means no baseflow will be produced by the reservoir.

Should be optimised. Default value is 2 months.

.. code-block:: toml

    [watershed.1]
    groundwater.1.halflife_baseflow = { value = 2.0, lower = 0.00100, upper = 15.00000, opti = true, sameas = 0 }

.. note::

    Common values depend on the dynamics that the groundwater reservoir is
    supposed to reproduce. For unsaturated water table (i.e. first groundwater
    reservoir) :

    * 2 months for river flow calculations
    * 3 to 8 months for sources or large-scale unsaturated groundwater level evolutions

    If present, for the second groundwater reservoir, common values are:

    * 3.5 mois for river flow calculations
    * 4 à 8 mois for sources or large-scale unsaturated groundwater level evolutions

    The value for this parameter should at least be equal to the value
    for the parameter of the overlying groundwater reservoir.


Drainage halflife time
----------------------

The drainage halflife time |tGD| (months) is the time after which, in the
absence of recharge, the flow rate towards the underlying groundwater
reservoir is halved. A value of zero means no drainage will be produced by the
reservoir. If no underlying reservoir is defined, the flow get out of the system.

Should be optimised only with an underlying groundwater reservoir. Default value
is 1 month.

.. code-block:: toml

    [watershed.1]
    groundwater.1.halflife_drainage = { value = 1.0, lower = 0.001, upper = 15.0, opti = false, sameas = 0 }

External exchanges
------------------

Factor |FG| (%) used to calculate groundwater exchanges through the boundaries
of the hydrographic watershed, i.e. the import or export of groundwater flows.
These exchanges may, for example, be a contribution from a deep aquifer. This
parameter is only used to calculate river flow.

Should be optimised in a second phase. Default value is 0.0.

.. code-block:: toml

    [watershed.1]
    groundwater.1.exchanges = { value = 0.0, lower = -30.0, upper = 30.0, opti = false, sameas = 0 }

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

Overflow threshold |HO| (mm). If :math:`H_g > H_o`, an overflow occurs. If
equal to zero, overflow is deactivated.

Should be optimised. Default value is 0.0.

.. code-block:: toml

    [watershed.1]
    groundwater.1.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.

Should be estimated. Default value is 0.0.

.. code-block:: toml

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

Calculating baseflow and drainage
=================================

|HG| varies according to a linear exponential evolution:

.. math::
    :label: eq:H_g

    \frac{dH_g}{dt} & = -u_b -u_d \\
    u_b & = \frac{H_g}{\tau_b} \\
    u_d & = \frac{H_g}{\tau_d}

with :math:`u_b` (|mm/s|) the instantaneous baseflow flowing towards the river
and :math:`u_d` (|mm/s|) the instantaneous drainage eventually flowing towards
the underlying groundwater reservoir.

:math:`\tau_b` (s) and :math:`\tau_d` (s) are two time constants defining the
exponential decay of the groundwater reservoir water level. They are related to
the half-life time parameters |tGB| (month) and |tGD| (month) through the
relationships:

.. math::

    \tau_b = (30.41 \cdot 86400)\frac{t_{1/2}^b}{\ln(2)} \\
    \tau_d = (30.41 \cdot 86400)\frac{t_{1/2}^d}{\ln(2)}

In |rameau|, a sudden inflow of flow :math:`q_f` (mm) coming in the form of a
Dirac feeds the groundwater reservoir at the beginning of each time step of
duration |Deltat|. This flow is either seepage |qs| from the transfer reservoir
for the uppermost groundwater reservoir, or drainage |qd| from the upper
groundwater reservoir for the subsequent groundwater reservoirs. :math:`H_0` is
the value of |HG| at the beginning of the time step (:math:`t = 0`). Then,

.. math::

    H_0 = H_0 + q_f

Eventually, if ``direct_reservoir_pumping`` is set to true, the pumping
:math:`q_p` is added to :math:`q_f`. If the overflow of the transfer reservoir
is set to fed the groundwater reservoir, |qto| is also added to :math:`q_f`.

If :math:`H_0` is negative due to an excess of pumping, it is set to 0 and 
the unmet groundwater pumping is stored as a component of the groundwater reservoir
budget.

Equation :eq:`eq:H_g` can be rewritten as follows:

.. math::
    :label: eq:H_g2

    \frac{dH_g}{dt} & = -\frac{H_g}{\tau_g} \\
    \tau_g        & = \frac{\tau_b\tau_d}{\tau_d + \tau_d}

The analytical solution of equation :eq:`eq:H_g2` is:

.. math::

    H_g(t) = H_0 \exp \left( -\frac{t}{\tau_g} \right)

:math:`u_b` becomes:

.. math::
    
    u_b = \frac{H_0}{\tau_b} \exp \left( -\frac{t}{\tau_g} \right)

Integrating :math:`u_b` between 0 and |Deltat| gives |qb|:

.. math::

    q_b & = H_0 \frac{\tau_g}{\tau_b} \left [ 1 - \exp \left( -\frac{\Delta t}{\tau_g} \right) \right ] \\
        & = H_0\frac{\tau_b}{T_g}

with:

.. math::

    T_g = \frac{1}{1 - \exp \left ( -\frac{\Delta t}{\tau_g} \right ) }

Similarly:

.. math::

    q_d = H_0\frac{\tau_d}{T_g}

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

.. math::

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

with 

.. math::

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

If :math:`\alpha_b \neq 0.0`, exchanges with the outside |qx| (mm) is either
added or removed from baseflow:

.. math::

    q_x = \max (0.01\alpha_bq_b, -q_b)

Calculating groundwater level
=============================

Groundwater level |H| (m) is computed as follows:

.. math::

    H = \frac{0.1}{S}H_g + C_p^gQ_p^g + H_b

See :ref:`regression_gwlevel` for more details.

Groundwater settings for parameter estimation
=============================================

See :ref:`optimization_parameters` for more details.

.. code-block:: toml

    [watershed.1]
    groundwater.weight = 1.00000
    groundwater.obslim = [ 0.00000, 0.00000 ]
    groundwater.storage.regression = true