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

=====
River
=====

.. _river_parameters:

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

Elementary drainage area
------------------------

Each sub-watershed is characterized by an elementary drainage area |A| (km²)
that should be measured or imposed. Nevertheless, this parameter can be
estimated by :ref:`regression <optimization_parameters>` in some cases for which
it is unknown or poorly known:

* Sub-watershed feeding a source
* Loss in the sub-watershed (karstic sub-watershed)
* Outlet of the sub-watershed controlling only a part of the total river flow
* (multiple outlets)

Default value to 1.0.

.. code-block:: toml

    [watershed.1]
    river.area = { value = 150., opti = false }

.. note:: 

    |A| can also been modified through the use of the correction factor |FA| (-).
    In this case, |A| will not be optimised.

Minimum river flow
------------------

The minimum river flow |Qm| (|m3/s|) is the minimum value of the total flow
calculated at the sub-watershed outlet. |Qm| may correspond to an in-stream flow
introduced into the watercourse by dam releases, or guaranteed by a reduction in
river pumping. Can be optimised through :ref:`regression
<optimization_parameters>`.

Default value is 0.0.

.. code-block:: toml

    [watershed.1]
    river.minimum_riverflow = { value = 0.0, opti = false }

Concentration time
------------------

The concentration time |tc| (|timestep|) is the time required for an effective rain
pulse to propagate to the sub-watershed outlet. Should be optimised only if observed
river flows are available.

Default value is 0.0.

.. code-block:: toml

    [watershed.1]
    river.concentration_time = { value = 0.0, lower = 0.0, upper = 10.0, opti = true, sameas = 0 }

Propagation time
----------------

The propagation time |tp| (|timestep|) is the time required for the upstream
river flows to reach the outlet of the current watershed. Should be optimised
only if observed river flows are available.

Default value is 0.0.

.. code-block:: toml

    [watershed.1]
    river.propagation_time = { value = 0.0, lower = 0.0, upper = 10.0, opti = true, sameas = 0 }

Calculation of the total river flow
===================================

The total river flow |Q| at time :math:`t` at the outlet of the watershed is

.. math::

    Q(t) = \max \left (F_{A}A\frac{q_l(t - t_c)}{86.4} + \sum_{j=1}^{n}Q_j(t-t_p) + Q_p, Q_m \right )

with |ql| (mm) the local simulated river flow related to the rainfall
reaching the elementary drainage area of the watershed and |Qp|
(|m3/s|) the withdrawals/injections applied to the outlet of the watershed.
:math:`\sum_{j=1}^{n}Q_j` is the sum of the upstream river flows of the
upstream watersheds, with :math:`n` the total number of upstream watersheds.

River parameter estimation settings
===================================

See :ref:`optimization parameters <optimization_parameters>` for more
information.

.. code-block:: toml

    [watershed.1]
    river.weight = 1.00000
    river.obslim = [ 0.00000, 0.00000 ]