Tutorial

This tutorial shows how to run a basic Itzï simulation using freely available dataset.

It assumes that GRASS 7 and Itzï are properly installed on your machine and that you possess a basic knowledge of GRASS.

Get ready

Here we will use the GRASS North Carolina dataset. Please download the GRASS 7 version and extract it in your grassdata directory.

Then start GRASS in the PERMANENT mapset.

Adjust the region

Fit the lidar elevation raster map and set a resolution of 5m:

$ g.region -p raster=elev_lid792_1m@PERMANENT res=5 save=lidar_5m

Resample the DEM

Please note that this step is not strictly necessary. The Itzï simulation will be carried out in any case on the defined computational region extent and resolution. However the bilinear interpolation smooth the surface, which prevent high slope values that could occur if using the GRASS default nearest-neighbour sampling.

$ r.resamp.interp input=elev_lid792_1m@PERMANENT output=elev_lid792_5m

Create a raster mask

Generate a drainage direction map and then create a watershed raster using the outlet point coordinates:

$ r.watershed elevation=elev_lid792_5m drainage=elev_lid792_5m_drainage
$ r.water.outlet input=elev_lid792_5m_drainage output=watershed coordinates=638888,220011

Create a raster mask to prevent calculation outside of the watershed:

$ r.mask rast=watershed

Create boundary condition maps

Create a vector map with the watershed outlet point:

$ echo '638888|220011' > watershed_out.txt
$ v.in.ascii input=watershed_out.txt output=watershed_out

Using this vector map, create two raster maps for the boundary conditions. The first with a value corresponding to the type of condition, here 4 corresponds to a fixed water depth inside the domain. The second being the value of the depth wanted, here 0.

$ v.to.rast input=watershed_out type=point output=bctype use=val value=4
$ v.to.rast input=watershed_out type=point output=bcvalue use=val value=0

Create rainfall and friction maps

Create maps of uniform rainfall and friction coefficient:

$ r.mapcalc exp='rain=100'
$ r.mapcalc exp='n=0.05'

Run the simulation

Create a new parameter file and fill it with the created map. It should look like the following:

[time]
duration = 02:00:00
record_step = 00:05:00

[input]
dem = elev_lid792_5m@PERMANENT
friction = n@PERMANENT
rain = rain@PERMANENT
bctype = bctype@PERMANENT
bcval = bcvalue@PERMANENT

[output]
prefix = nc_itzi_tutorial
values = h, wse, v, vdir, boundaries

[statistics]
stats_file = nc_itzi_tutorial.csv

Run the simulation:

$ itzi run <parameter_file_name>

At the end of the simulation, Itzï should have generated five Space-Time Raster Dataset (STRDS) in the form:

<prefix>_<variable>

The maps contained in those STDRS are following this naming convention:

<prefix>_<variable>_<order_number>

Here is the example of the map nc_itzi_tutorial_h_0020:

NC depth

All the results can be processed using the GRASS tools for raster maps and / or space-time dataset. For instance, it is easy to generate an animation of the results using g.gui.animation.