.. _tree:

==============
Stream network
==============

Stream network uses the concept of Strahler stream order
:cite:p:`1957:strahler_quantitative`. The stream order is a positive whole
number used in geomorphology and hydrology to indicate the level
of branching in a river system.

|rameau| needs information about the branching system between watersheds to
build the stream network. The user can provide this information by creating a
simple text file with two columns. This text file is called the branch tree file.

Branch tree file
================

The branch tree file starts with a free header that is skipped during a
simulation run. In the first column, the user assigns a whole positive number
to each watershed which will be used as an identifier. These identifiers need
not be ordered, but must be unique.

In the second column, the user fills in the identifier corresponding to the
downstream watershed of the associated identifier in the first column on the
same line. A value of zero in the second column means the outlet of the
watershed.

A simple example is shown below:

.. admonition:: Example of the branch tree file.

    ::

        Id Downstream
        1 0
        3 1
        2 1

This stream network consists in three watersheds. The watersheds 2 and 3 are
connected to the watershed 1. River flow from watershed 1 provides the outlet
river flow of the stream network.

The branch tree file is identified in the ``[files]`` table in the TOML file:

.. code-block:: toml

    [files]
    tree = "tree.csv"

Each identifier assigned in the branch tree file is used in the TOML
configuration file to describe the physical parameters of each basin:
        
.. code-block:: toml

    [watershed.1] # Id of the watershed is 1
    name = "My Watershed 1!"
    [watershed.2] # Id of the watershed is 2
    name = "My Watershed 2!"
    [watershed.3] # Id of the watershed is 3
    name = "My Watershed 3!"