You are looking at an old revision of the page Running-StreamFlow. This revision was created by Aurelien Gallice.

Table of Content

This page explains how to run a StreamFlow simulation


StreamFlow is an extension to the spatially-distributed snow model Alpine3D which allows the user to perform hydrological simulations. Both tools run independently, but Alpine3D needs to be configured in such a way that it outputs a set of files which are expected by StreamFlow as input data (see below). In case you do not know how to run an Alpine3D simulation, please have a look at the Alpine3D documentation.

Once the Alpine3D simulation is run, you can either copy the output data to a new folder or directly perform the StreamFlow simulation in the same folder as Alpine3D (StreamFlow was designed so that no conflict occurs). Similarly to the other tools of the Alpine3D suite, the behavior of StreamFlow is controlled by a configuration file. You can actually use the same one as for Alpine3D, simply adding the keys which are required by StreamFlow (see below).

Additionally to the output data generated by Alpine3D, StreamFlow requires specific files in order to run properly. The latter include the grid delineating the subwatersheds as well as two data files specifying the location and structure of the stream network. All these files can be generated by TauDEM, a tool that was designed to extract various hydrological variables from digital elevation models (see below).

Before being actually run, StreamFlow may need to be calibrated in case it is applied over a new catchment. As for any other hydrological model, this step may be quite computationally intensive since at least a thousand runs are typically required to obtain good parameter estimates. A few guidelines helping you efficiently calibrating the model can be found below.

Once calibrated, the model can eventually be run. The configuration file allows you to control many aspects of the simulation, such as the algorithm which is used to advect water along the stream network, whether stream temperature should be computed or not, or even the rate at which data should be written in the output files.

In summary, the usual procedure for running a StreamFlow simulation is the following:

  1. Configure and run Alpine3D so that it produces the data required by StreamFlow
  2. Create the simulation folder for the StreamFlow simulation, or simply re-use the Alpine3D one
  3. Create the configuration file for the StreamFlow simulation, or simply modify the Alpine3D one by adding the missing keys
  4. Use TauDEM to generate the additional files required by StreamFlow, and copy these files in the simulation folder of StreamFlow
  5. Calibrate StreamFlow
  6. Run the StreamFlow simulation by calling the executable on the command line with the proper options

Each one of these six steps is detailed in a dedicated section below.

Configuration of Alpine3D

Minimum requirements

At the very minimum, StreamFlow requires from Alpine3D the amount of water infiltrating into each subwatershed at every time step. Two possibilities are available for this:

  • In case you already have the grid delineating the subwatersheds (see section about TauDEM below), you can configure Alpine3D so that it computes the total amount of water infiltrating into each subwatershed at each time step. The infiltration values will then be written out in SMET files, one for each subwatershed. To this end, you need to copy the grid in folder input\surface-grids of the Alpine3D simulation directory. Please make sure that this grid is in a format that is readable by Alpine3D (TauDEM generates a TIFF grid which needs to be converted; the list of Alpine3D compatible formats can be found in the MeteoIO documentation). You then need to add the following keys in section [INPUT] of the Alpine3D configuration file, with [format] to be replaced with the grid format (e.g. ARC), [folder] with the (absolute or relative) path to the folder in which the grid is located (e.g. ./input/surface-grids), and [file_name] with the grid name (without the path):

        GRID2D              = [format]
        GRID2DPATH          = [folder]
        CATCHMENT           = [file_name]

    Additionally, the following line has to be added in section [OUTPUT] of the Alpine3D configuration file, where [folder] stands for the (absolute or relative) path to the folder in which the SMET files containing the subwatershed infiltration rates will be generated by Alpine3D:

        CATCHMENTS_PATH = [folder]

  • If you do not have the grids delineating the subwatersheds yet, you need to configure Alpine3D so that it outputs the grids containing the water exfiltration rate at the bottom of each soil column at each time step. The sum of these exfiltration rates over each subwatershed will then be performed in StreamFlow itself. The writing of the exfiltration grids is triggered by adding the following keys in section [OUTPUT] of the Alpine3D configuration file, with [format] and [folder] to be replaced with the format and the (relative or absolute) path to the folder in which the grids should be written, respectively:

        RUNOFF_GRID2D      = [format]
        RUNOFF_GRID2DPATH  = [folder]

    It is recommended that you use the binary NETCDF format for the grids, since it is associated with reduced reading and writing overheads (see section about the NETCDF plugin in the MeteoIO documentation).

Additional requirements

The above configuration of Alpine3D is sufficient in case you intend to compute only discharge and water depth in the stream network. The computation of stream temperature requires additional output from Alpine3D:

  1. Depending on the configuration of StreamFlow, the computation of the temperature of water exfiltrating out of the subwatersheds into the stream network may require soil or air temperature averaged over each subwatershed. It should be mentioned that the value of soil temperature which is expected by StreamFlow corresponds to the average temperature between the soil surface and a given depth (see below). Two cases might occur:
    • In case you have the grid delineating the subwatersheds, you can simply add the following lines in section [INPUT] of the Alpine3D configuration file (on top of the four lines mentioned in the first bullet point of the above section):

              SOIL_TEMPERATURE_DEPTH  = [depth]

      [depth] should be replaced with the depth (in meters) down to which soil temperature should be averaged. The first line tells Alpine3D to add the average air and soil temperature to the SMET files which are created for each subwatershed and contain the water infiltration values.
    • If you have not generated the grid delineating the subwatersheds yet, you should simply follow the steps indicated in point 2 below. In this case, StreamFlow will itself average soil and air temperature over each subwatershed, based on the corresponding grids generated by Alpine3D.
  2. On top of soil and air temperature values averaged over the subwatersheds, StreamFlow requires the values of air temperature, wind velocity, relative humidity, incoming short and long wave radiations, as well as soil temperature over each stream cell in order to compute stream temperature.
    • The easiest way consists in configuring Alpine3D so that it outputs soil temperature grids at regular time intervals. These grids will be used to compute the diffusive thermal exchange between the water and the stream bed. Depending on the configuration of StreamFlow, they may also be used to compute the temperature of water exfiltrating out of the hillslopes into the stream (see documentation of StreamFlow). The meteorological data will be re-interpolated from the stations' measurements over the stream cells

Simulation folder

Although not strictly required, it is recommended that you create a new folder for each StreamFlow simulation with the same structure as recommended for Alpine3D. Alternatively, you can simply use the same folder as the one in which the Alpine3D simulation was run.

Configuration file

Generation of the stream network with TauDEM


Calling the executable