.. currentmodule:: rameau.core

.. _watersheds:

===================
Building watersheds
===================

In |rameau|, a watershed is defined by a set of settings and physical parameters
that need to be specified. All settings and physical parameters are optional.
If they are not provided, default values are applied.

All watersheds are identified by an identifier in the form of an integer. In the
TOML configuration file, the identifier appears in the table describing the
watershed. For example, parameter keys for the watershed with identifier 1
will be filled in the table ``[watershed.1]``. The identifier is the number
assigned to the watershed in the branch tree file (see :ref:`tree`).

A special watershed identifier is ``all``. It describes physical parameters for
all watersheds at once. Parameters are described by keys in the watershed table.
The keys are the same for all watersheds. If the same parameter appears both in
the overall table and in the watershed-specific table, the watershed-specific
value is the one considered.

.. admonition:: Example

    .. code-block:: toml

        [watershed.all]
        river.concentration_time = { value = 1.0 }
        # Concentration time is set to 1.0 for all watersheds.
        [watershed.2]
        river.concentration_time = { value = 0.5 }
        # Concentration time is set to 0.5 for watershed 2.
        # It overrides the 1.0 value.
    
Physical parameter
==================

Physical parameters are provided as tables with the following keys:

* ``value``: parameter float value.
* ``lower``: lower bound float value for the parameter estimation algorithm.
* ``upper``: upper bound float value for the parameter estimation algorithm.
* ``opti``: boolean set to true for optimizing this parameter.
* ``sameas``: watershed identifier to which this parameter is linked. 

.. code-block:: toml

    [watershed.1]
    river.concentration_time = { value = 0.5, lower = 0.1, upper = 5.0, opti = false, sameas = 0}
    
Linked parameters
=================

If the key ``sameas`` is equal to another watershed identifier, this parameter
value will not be estimated but will be set equal to the parameter value of the
other watershed identifier. A value of zero means that this parameter will be
estimated only if ``opti`` is true. Default value is 0.

.. admonition:: Example

    .. code-block:: toml

        [watershed.1]
        river.concentration_time = { opti = false, sameas = 2 }
        # Parameter value is linked to watershed 2.
        [watershed.2]
        river.concentration_time = { opti = false, sameas = 3 }
        # Parameter value is linked to watershed 3.
        [watershed.3]
        river.concentration_time = { opti = true, sameas = 0 }
        # Parameter value is estimated.

Watershed settings
==================

Name
----

The name of a watershed is defined by the ``name`` key. Outputs use this name
to identify the watershed in their headers (see :ref:`outputs`).
Default value is ``Watershed #``, with ``#`` the identifier of the watershed.

.. code-block:: toml

    [watershed.1]
    name = "My watershed" # Default value would be "Watershed 1"

Is_confluence
-------------

``is_confluence`` is a boolean key specifying whether the watershed is a
confluence. A confluence is only a junction point in the stream network
where no computation occurs.

.. code-block:: toml

    [watershed.1]
    is_confluence = false # Default to false

Unit_time_step
--------------

``unit_time_step`` is a boolean key specifying whether all halflife time
parameter values are specified in time step unit or in month unit. If false,
halflife time values are specified in month unit. To see a direct application
of this parameter, see :ref:`_patate_reunion`.

Default value is false.

.. code-block:: toml

    [watershed.1]
    unit_time_step = false # Default to false

Watershed parameters
====================

Watershed parameters are divided into several categories:

* :ref:`meteo_parameters` 
* :ref:`forecast_parameters`
* :ref:`correction_parameters`
* :ref:`River parameters <river_parameters>`
* :ref:`Soil reservoir parameters <soil_reservoir_parameters>`
* :ref:`Transfer reservoir parameters <transfer_reservoir_parameters>`
* :ref:`Groundwater reservoir parameters <groundwater_parameters>`
* :ref:`Snow reservoir parameters <snow_parameters>`
* :ref:`Pumping reservoir parameters <pumping_parameters>`

.. toctree::
    :maxdepth: 2
    :hidden:
 
    tree
    correction
    river
    soil_reservoir
    transfer_reservoir
    groundwater
    snow_reservoir
    pumping