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

.. _snow-reservoir:

==============
Snow reservoir
==============

In |rameau|, the snow reservoir produces snow melting |qm| (mm) and snow runoff
|qn| (mm) according to the values of rainfall |R| (mm), |PET| |EP| (mm),
temperature |T| (°C) and, if available, snow |RS| (mm). |qm| and |qn| are then
added to the effective rainfall produced by the soil reservoir.

The |SWE| |HN| (mm) determines how much water the snowpack in the
reservoir contains. The liquid water retention |r| (%) corresponds
to the fraction of |HN| bounded by capillarity to the snowpack.

During a time step, snow melting occurs according to a succession of
physical processes:

#. Snow melting by soil calories :math:`M_s` (mm),
#. Snow melting using a degree day model :math:`M_d` (mm),
#. If :math:`R > E_P`, snow melting by rainfall calories :math:`M_r` (mm).

If :math:`R < E_P`, |PET| may not be fully satisfied by rainfall and
the rest may be taken from the snow by sublimation,
leading to the calculation of an |AET| from the snow :math:`E_S`
(mm) and an |UPET| :math:`E_U`.

:math:`M_s` participates in feeding the soil reservoir while 
:math:`M_d + M_r` are partitioned between storage in the snow pack,
|qm| and |qn|.

Activate snow
=============

To activate snow in the model, the user needs to provide at least a
temperature input data file.

.. code-block:: toml

    [files]
    temperature = "temperature.csv"

In this case, snow is produced if :math:`T < 0`. Alternatively, a snow input
data file can directly been provided in addition to the temperature data file.

.. code-block:: toml

    [files]
    temperature = "temperature.csv"
    snow = "snow.csv"

.. _snow_parameters:

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

Temperature correction
----------------------

Additive temperature correction |TC| (°C). Before proceeding with snow melting
processes, |T| is potentially corrected by |TC| in order to correct the possible
discrepancies affecting the model input temperature:

.. math::

    T = T + T_c.

Should be optimised. Default value is 0 °C.

.. code-block:: toml

    [watershed.1]
    snow.correction.temperature = { value = 0.0, lower = -3.0, upper = 3.0, opti = false, sameas = 0 }

Snow melting by soil calories
-----------------------------

Amount of |SWE| likely to melt under the action of the calories released by the
soil |MS| (|0.1mm/day|).

Should be optimised. Default value is 5 |0.1mm/day|.

.. code-block:: toml

    [watershed.1]
    snow.melting = { value = 5.0, lower = 0.001, upper = 20.0, opti = false, sameas = 0 }

Degree day model coefficient
----------------------------

Degree day coefficient of the degree day model |CD| (|mm/°C/day|).

Should be optimised. Default value is 4 |mm/°C/day|.

.. code-block:: toml

    [watershed.1]
    snow.degree_day.coefficient = { value = 4.0, lower = 0.001, upper = 7.0, opti = false, sameas = 0 }

Degree day model temperature threshold
--------------------------------------

Temperature threshold of the degree day model |TD| (°C).

Should be optimised. Default value is 0 °C.

.. code-block:: toml

    [watershed.1]
    snow.degree_day.temperature = { value = 0.0, lower = -2.0, upper = 2.0, opti = false, sameas = 0 }

Correction factor of snow melting by rain
-----------------------------------------

Correction factor |FM| (%) applied to the amount of snow that will melt
under the action of rainfall.

Should not be optimised in most cases. Default value is 0%.

.. code-block:: toml

    [watershed.1]
    snow.correction.rainfall = { value = 0.0, lower = -20, upper = 20.0, opti = false, sameas = 0 }

Correction factor of |PET|
--------------------------

Correction factor |FS| (%) applied to |EP| for calculating the amount of |SWE|
that will evaporate by sublimation. |FS| corrects :math:`E_p` since the
evaporation rate is not necessarily the same between the soil reservoir and the
snowpack.

Should not be estimated in most cases. Default value is 0%.

.. code-block:: toml

    [watershed.1]
    snow.correction.pet = { value = 0.0, lower = -20.0, upper = 20.0, opti = false, sameas = 0 }

Maximum snow retention
----------------------

The maximum snow retention of the snow pack |rm| (%).

Could be optimised. Default value is 5%.

.. code-block:: toml

    [watershed.1]
    snow.maximum_retention = { value = 5.0, lower = 0.001, upper = 30.0, opti = false, sameas = 0 }

Calculating snow melting
========================

In the following section, :math:`H_0` and :math:`r_0` designate the initial
|SWE| and retention values, respectively, at the beginning of the time step of
duration |Deltat| (s).

Snow melting by soil calories
-----------------------------

If :math:`H_n > 0`, snow can melt daily under the action of the calories
released by the soil. The |SWE| likely to melt in this way is noted as
|MS| (|0.1mm/day|):

.. math::

    H_n & = \max \left (H_0 - \frac{\Delta t}{86400}C_s, 0 \right ) \\
    M_s & = H_0 - H_n.

Degree day model
----------------

A degree day model assumes that, for each 1°C over 0°C, a certain depth of snow
will be melted. The degree day parameters are the degree day factor |CD|
(|mm/°C/day|) and the temperature threshold |TD| (°C) above which melting
occurs. If :math:`T > 0`:

.. math::

    H_n' & = \max \left (H_n - \frac{\Delta t}{86400}C_d(T - T_d), 0 \right ) \\
    M_d  & = H_n' - H_n \\
    H_n  & = H_n'.

Snow melting by rainfall calories
---------------------------------

If :math:`R > E_p` and :math:`T > 0`, snow can melt under the action of
the rainfall calories:

.. math::

    H_n' & = \max \left (H_n - (1 + 0.01F_r)\frac{(R - E_p)T}{79.7}, 0 \right ) \\
    M_r  & = H_n'- H_n \\
    H_n & = H_n'.

The latent heat of fusion of water is 79.7 calories per gram.

Sublimation of snow
-------------------

If :math:`R < E_p`, :math:`E_a` and :math:`E_u` (mm) are
calculated as follows:

.. math::

    H_n' & = \max (H_n - ((1 +0.01F_s)E_p - R), 0) \\
    E_S  & = H_n - H_n' \\
    E_U  & = \max(E_P - E_S, 0) \\
    H_n    & = H_n'.

Snow melting and runoff calculation
-----------------------------------

Assuming that :math:`M_s` feeds directly the soil reservoir, the
free liquid water in the snowpack :math:`W_r` (mm) is:

.. math::

    W_f = M_d + M_r + \max (R - E_p, 0)

The total available liquid water in the snowpack is equal to the
addition of the bounded water :math:`r_0H_0` and the free water
:math:`W_f`. If :math:`r_0 < r_m`, a part of this total available
liquid water, denoted :math:`W_d`, will replenish the snowpack in order
for |r| to reach the maximum snow retention |rm| (%):

.. math::

    r   & = \min \left (\frac{r_0H_0 + W_f}{H_n}, 0.01r_m \right ) \\
    W_d & = \min((0.01r_m - r)H_n, W_f) \\
    H_n & = H_n + W_d.

:math:`1 - \frac{W_d}{W_f}` is the fraction of the total liquid
water available that contribute either to |qm| or to |qn|:

.. math::

    q_{sm} & = M_s  \left (1 - \frac{W_d}{W_f} \right ) \\
    q_{sr} & = \max \left ( \left ( R - E_p \right) \left( 1 - \frac{W_d}{W_f} \right), 0 \right)