Tutorial

In this tutorial we will give a short overview on how the model can be configured for practical use. On the one hand, we will explain how the configuration file (.ini-file) should be made, and on the other hand, how the prefered model options are enabled or disabled.

0. Getting started

First of all, an installation of a simple text editor like notepad++ is needed in order to edit the configuration file (.ini-file). A GIS program is needed as well to create the necessary input rasters and to view the output rasters. We recommend QGIS or Saga GIS. In this tutorial we will not explain how to use GIS, nor how to make the input rasters, these are basic GIS-tasks and these are explained in several tutorials online. We encourage readers to start the tutorial by using the tutorial_1.ini file, and adapt this file according to the exercise. This file can be found on the github page of CN-WS, under the folder: docs/tutorials. The other tutorial ini-files in the tutorials folder can be used to check your adaptations.

Then, you need to download the latest release of the model. Pre-build binaries exist for windows and linux. It is also possible to build the model from source. See the installation page for more information.

All example model runs described below make use of the test dataset which is available in the repository under testfiles/molenbeek/modelinput.

1. A basic model run with WaTEM/SEDEM

As a first exercise in the tutorial we will make a basic model run with WaTEM/SEDEM. The basic model run includes only mandatory input files. This run does not use advanced model extensions. All keywords used in an ini-file are explained in the reference.

[Working directories]
input directory = ../testfiles/molenbeek/modelinput/
output directory = ../testfiles/molenbeek/modeloutput_tutorial_1/

[Files]
dtm filename = dtm.rst
p factor map filename = P_molenbeek.rst
parcel filename = perceelskaart_2018_molenbeek_s1.rst
c factor map filename = C_spring_2018_molenbeek_s1.rst
k factor filename = K3_CNWS_molenbeek.rst
ktc map filename = ktcmap_2018_molenbeek_s1.rst 

[Parameters]
parcel connectivity cropland = 90
parcel connectivity forest = 30
parcel trapping efficiency cropland = 0
parcel trapping efficiency forest = 75
parcel trapping efficiency pasture = 75
bulk density = 1350
r factor = 1250

After navigating to the folder where you have build the model, or installed the binary, you can use your terminal to run the model, as follows:

$ watem_sedem "<path to watem-sedem repository>/watem_sedem/docs/tutorials/tutorial_1.ini"

When the model run starts you will see:

WATEM/SEDEM model version: 5.0.0

Inifile : <path to watem-sedem repository>/watem_sedem/docs/tutorials/tutorial_1.ini

After the completion of the calculations, the model reports the execution time:

Calculations completed. Program Execution Time: 3.4 sec

Now, you can have a look in the model output folder defined in the ini-file. A txt-file with a summary of the results is written: Total sediment.txt.

Total erosion: -26917936.54 (kg)
Total deposition: 22765482.64 (kg)
Sediment leaving the catchment, via the river: 3694854.5 (kg)
Sediment leaving the catchment, not via the river: 445206.09 (kg)
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

Total sediment passing at each outlet [kg]
Outlet ID	Sediment
1	48886.38281

This table contains the sum of all pixels with a negative mass balance (Total erosion) and a positive mass balance (total deposition). A negative mass balance means that the available sediment (RUSLE + SediIn) in a pixel is smaller than the transport capacity, and thus leads to a net erosion in this pixel. A positive mass balance means that the available sediment in the pixel is larger than the transport capacity, and thus leads to a net sedimentation in this pixel. We refer to the WaTEM/SEDEM section where these concepts are explained more in depth.

The total sediment table also reports how much sediment enters the river pixels (Sediment leaving the catchment, via the river). The sediment leaving the catchment, not via the river is (mostly) a small fraction of the sediment that leaves the catchment via the borders (to nodata pixels).

It is important to note that the model made a catchment outlet itself: the model looked for the lowest (river) pixel treated in the routing algorithm and assigned this pixel as the model domain outlet. All the sediment is routed through the landscape to this pixel If you have a look in the model input folder, you will see that Outlet.rst appeared. All pixels in this raster have value ‘0’ except one pixel with value 1. This pixel is the outlet of the model.

Congratulations! You just finished your first model calculation with WaTEM/SEDEM!

2. Get more model output!

The first tutorial described a very basic model run: only a txt file with a summary of the results is written as output. If we want spatial information about where erosion and sedimentation occurs, we can enable various output options. Therefore, we need to add a section in the ini-file with the desired output: write sediment export and write water erosion.

write water erosion = 1

To do so, you can make a copy of the tutorial_1.ini-file in a directory of your choice, adapt the ini-file with the lines stated above, and rename the file to ‘tutorial_2.ini’. Then the adapted model can be ran using

watem_sedem $your_favorite_folder/tutorial_2.ini

If this is not working as it should, please check if the reference ‘your_favorite_folder’ is the folder where you saved the tutorial_2.ini- file. If unsure, you can always check and run the reference tutorial_2 .ini-file present in the repository with:

watem_sedem <path to watem-sedem repository>/watem-sedem/docs/tutorials/tutorial_2.ini

The following output rasters will emerge in the output folder:

• SediExport_kg.rst,

• SediOut_kg.rst,

• SediIn_kg.rst,

• WATEREROS (kg per gridcel).rst,

• WATEREROS (mm per gridcel).rst

These rasters can help us to identify the spatial patterns of the soil erosion and sediment deposition in the model area. The SediExport_kg.rst is a very useful raster when examining the river locations with large sediment inputs. This raster shows how much sediment enters every river pixel. Remember, the total amount of sediment entering the rivers can be found in Total sediment.txt (Sediment leaving the catchment, via the river). This amount is in fact the sum of all river pixels in SediExport_kg.rst.

If you want to see the paths of the sediment transport through the landscape, you can look at SediOut_kg.rst or SediIn_kg.rst. These rasters display how much sediment (in kg) is transported into and out of a cell.

The WATEREROS rasters can help with making a spatial analysis of areas where a lot of erosion occurs, or where a lot of deposition is possible. These rasters represent the result of the comparison between the total available sediment and the trasport capacity of a pixel (for more information about this concept, see here). Positive values in these rasters indicate deposition, negative values indicate erosion. The Total sediment file, discussed in the tutorial ‘1. A basic model run with WaTEM/SEDEM’, contained the values ‘total erosion’ and ‘total deposition’. These values are calculated as the sum of all pixels in the WATEREROS raster where the pixel value is larger (deposition) or smaller (erosion) than zero.

If you want more spatial output, have a look in the reference about all the possibilities!

3. Adding buffer basins

In the previous tutorials we learned how to run WaTEM-SEDEM and how to enable or disable model output. In this tutorial we will explain how to enable one of the advanced features of the model, the so-called model extensions. The example will make use of the Include Buffers extension, but the same principles can be used for all other extensions!

Buffer basins are infrastructural features that trap sediment. As described in the reference. Two extra parameters are needed in the ini-file if we want to enable this feature: the buffer map filename and the number of buffers.

In this example we will add 31 buffers to the modelled catchment. After adding the buffer map filename and the number of buffers the ini-file looks like this:

[Working directories]
input directory = ../testfiles/molenbeek/modelinput/
output directory = ../testfiles/molenbeek/modeloutput_tutorial_3/

[Files]
dtm filename = dtm.rst
p factor map filename = P_molenbeek.rst
parcel filename = perceelskaart_2018_molenbeek_s1.rst
c factor map filename = C_spring_2018_molenbeek_s1.rst
k factor filename = K3_CNWS_molenbeek.rst
ktc map filename = ktcmap_2018_molenbeek_s1.rst 
buffer map filename = buffers_molenbeek_s1.rst

[Parameters]
parcel connectivity cropland = 90
parcel connectivity forest = 30
parcel trapping efficiency cropland = 0
parcel trapping efficiency forest = 75
parcel trapping efficiency pasture = 75
bulk density = 1350
r factor = 1250

[Output]
write sediment export = 1
write water erosion = 1

[Extensions]
include buffers = 1

[Parameters extensions]
number of buffers = 31

If we run the model with this configuration (tutorial_3a.ini) we get:

WaTEM/SEDEM model version: 5.0.0

Inifile : <path to inifile>\docs\tutorials\tutorial_3a.ini

Error in data input: Buffer 1 trapping efficiency value missing or wrong
data format

Oh no, an error has occured. What does this mean? This error indicates that the input data in the configuration file is not correct. We read that the trapping efficiency value of Buffer 1 is missing or is given in a wrong data format. On the Model choices page, more information can be found. There, you find that we need to define the trapping efficiency, the extension id and buffer id for every buffer in the configuration file (see here). This has not yet been done here. So, we need to add 31 sections, one for every buffer, with these data (see also tutorials/tutorial_3b.ini):

[Working directories]
input directory = ../testfiles/molenbeek/modelinput/
output directory = ../testfiles/molenbeek/modeloutput_tutorial_3/

[Files]
dtm filename = dtm.rst
p factor map filename = P_molenbeek.rst
parcel filename = perceelskaart_2018_molenbeek_s1.rst
c factor map filename = C_spring_2018_molenbeek_s1.rst
k factor filename = K3_CNWS_molenbeek.rst
ktc map filename = ktcmap_2018_molenbeek_s1.rst 
buffer map filename = buffers_molenbeek_s1.rst

[Parameters]
parcel connectivity cropland = 90
parcel connectivity forest = 30
parcel trapping efficiency cropland = 0
parcel trapping efficiency forest = 75
parcel trapping efficiency pasture = 75
bulk density = 1350
r factor = 1250

[Output]
write sediment export = 1
write water erosion = 1

[Extensions]
include buffers = 1

[Parameters extensions]
number of buffers = 31

[Buffer 1]
trapping efficiency = 75
extension id = 16385

[Buffer 2]
trapping efficiency = 75
extension id = 16386

[Buffer 3]
trapping efficiency = 75
extension id = 16387

[Buffer 4]
trapping efficiency = 75
extension id = 16388

[Buffer 5]
trapping efficiency = 75
extension id = 16389

[Buffer 6]
trapping efficiency = 75
extension id = 16390

[Buffer 7]
trapping efficiency = 75
extension id = 16391

[Buffer 8]
trapping efficiency = 75
extension id = 16392

[Buffer 9]
trapping efficiency = 75
extension id = 16393

[Buffer 10]
trapping efficiency = 75
extension id = 16394

[Buffer 11]
trapping efficiency = 75
extension id = 16395

[Buffer 12]
trapping efficiency = 75
extension id = 16396

[Buffer 13]
trapping efficiency = 75
extension id = 16397

[Buffer 14]
trapping efficiency = 75
extension id = 16398

[Buffer 15]
trapping efficiency = 75
extension id = 16399

[Buffer 16]
trapping efficiency = 75
extension id = 16400

[Buffer 17]
trapping efficiency = 75
extension id = 16401

[Buffer 18]
trapping efficiency = 75
extension id = 16402

[Buffer 19]
trapping efficiency = 75
extension id = 16403

[Buffer 20]
trapping efficiency = 75
extension id = 16404

[Buffer 21]
trapping efficiency = 75
extension id = 16405

[Buffer 22]
trapping efficiency = 75
extension id = 16406

[Buffer 23]
trapping efficiency = 75
extension id = 16407

[Buffer 24]
trapping efficiency = 75
extension id = 16408

[Buffer 25]
trapping efficiency = 75
extension id = 16409

[Buffer 26]
trapping efficiency = 75
extension id = 16410

[Buffer 27]
trapping efficiency = 75
extension id = 16411

[Buffer 28]
trapping efficiency = 75
extension id = 16412

[Buffer 29]
trapping efficiency = 75
extension id = 16413

[Buffer 30]
trapping efficiency = 75
extension id = 16414

[Buffer 31]
trapping efficiency = 75
extension id = 16415

A buffer should trap sediment. So, after a successful model run with the above given ini-file, we can look at the Total sediment file in the output folder, to see that the ‘sediment trapped in buffers’ line is added.

Total erosion: -26815659.39 (kg)
Total deposition: 21944564.64 (kg)
Sediment leaving the catchment, via the river: 3641522.62 (kg)
Sediment leaving the catchment, not via the river: 445206.09 (kg)
Sediment trapped in buffers: 771972.72 (kg)
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

Total sediment passing at each outlet [kg]
Outlet ID	Sediment
1	45451.28516

This line gives us the total amount of sediment trapped in the 31 buffer basins added to the model. We also see that the amount of sediment that reached the river (Sediment leaving the catchment, via the river) is less in this model run than in the previous model run (see section 1). We can conclude that the addition of buffers in this model run is a good measure to reduce the sediment input in the rivers.

4. Use the CN extension

To use the CN-extension of WaTEM-SEDEM, we need to enable it with the curve number option.

[Extensions]
Curve number = 1

Using the CN-extension implies we need to define additional input in the ini-file. At the bottom of the curve number-section, the mandatory input is for running the WaTEM-SEDEM with the CN model extension is described. We extend the ini-file with this input:

[Files]
...
cn map filename = CNmap.rst
rainfall filename = LS09_15B_N_event_1_dummy.txt
...
[Parameters extensions]
...
alpha = 0.4
beta = 0.05
stream velocity = 0.3
5-day antecedent rainfall = 0
desired timestep for model = 60
endtime model = 2940
...

The CN module will create some additional output. Most output is automatically generated by enabling the CN module, however, it is posible to write an extra output raster, namely, the ‘rainfall excess’ raster (Remap.rst). This can be done by adding following line to the ini-file:

[Output]
...
write rainfall excess = 1
...

We refer to the documentation about CN for the interpretation of the output.

5. More examples?

Do you want to experiment even more with the options of WaTEM-SEDEM? The test files in the repository contain an example project where following options are used:

• river routing

• include ditches

• include sewers

• create ktc map

• …

Have a look at them, and using the principles explained above you should be able to get these working!