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

Exchange river flow
-------------------

The exchange river flow |Qe| (|m3/s|) is a constant value that is always added
to the simulated river flow. |Qe| should be equal to 0.0 except in some
particular cases: watershed leak, constant water export or import from a
channel, withdrawal.

Can be optimised through :ref:`regression <optimization_parameters>`.

Default value is 0.0.

.. code-block:: toml

    [watershed.1]
    river.exchange_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) = F_{A}A\frac{q_l(t - t_c)}{86.4} + \sum_{j=1}^{n}Q_j(t-t_p) + Q_p + Q_e

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 ]