From a TELEMAC 2D model

The objective of this tutorial is to model the habitat of the adult barbel from several TELEMAC 2D hydraulic simulations. The results will be visualised in interactive figures, in GIS output and in 3D. The main steps are as follows:

1. TELEMAC data will be read by the software to create a hydraulic .hyd file.
2. The substrate data will be read by the software to create a .sub substrate file.
3. The .hyd and .sub files will be merged into a .hab file from which HABBY can perform habitat calculations.
4. The biological model of the adult barbel will be selected.
5. The habitat calculation will be performed.
6. The results will then be visualised and exported.

• Install HABBY.
• Download and extract the hydraulic and substrate example files:
  • tuto_telemac_example_data.zip
• GIS software, such as QGIS or ArcGIS (for viewing map exports).
• The open-source software Paraview (to visualise the 3-dimensional exports) https://www.paraview.org/.
• A spreadsheet program, such as LibreOffice Calc or Excel (for viewing TXT exports).

These files are EDF data and can only be used for HABBY tutorials.

Here are the contents of the indexHYDRAU.txt file:

EPSG=unknown
filename Q[m3/s]
d1.slf 9.2
d2.slf 21.2
d3.slf 35
d4.slf 48.4
d5.slf 74.7
d6.slf 110
d7.slf 150
d8.slf 175
d9.slf 259

*User guide: Creating a .hyd file.

These files are fictitious data and are used only for the tutorial.

Here are the contents of the file 'sub_PolygonSandreCoarser-dom.txt':

substrate_classification_code=Sandre
substrate_classification_method=coarser-dominant
default_values=12, 12

*User guide: Detailed description of substrate files

• Start the software.
• Go to menu Project - New.

This opens the HABBY - New Project window.

• If necessary, change the Projects folder:, by clicking on .
• Enter in Project name:: 'Tuto_TELEMAC'.
• Choose in Project type:: 'physique'.
• Click on [Create Project].

The project is then created and gives you access to new tabs.

*User guide : Project creation

• Open the tab Hydraulic.
• For Select a model choose 'TELEMAC 2D'.

This opens the input file manager for TELEMAC.

• In Result file (.res, .., click on to then select all TELEMAC files ('d1.slf, …, d9.slf') or only the 'indexHYDRAU.txt' file.

• If the pre-reading went well, the software should display the following information:
  • Reach name:: 'Tronçon D'.
  • Unit name:: selection of '9.2' to '259'
  • Type: 'discharge [m³/s]'
  • Number: '9/9'
  • Mesh data: ''
  • Node data: 'elevation, water depth, water velocity'
  • EPSG code: '2154'
  • .hyd filename : 'd1_to_d9.hyd'

• If this information is valid, you can start the calculation by pressing the [Create 1 file .hyd] button.

Once the process is complete, a file 'd1_to_d9.hyd' is created.

*User guide: Creating a .hyd file

• Open the Substrate tab.
• For Substrate mapping method from check that 'polygons (.shp, .gpkg)' is selected.
• In File (.shp, .gpkg), click on and select the file 'sub_PolygonSandreCoarser-dom.shp'.

• If the pre-reading went well, the software should display the following information:
  • File (.shp, .gpkg): 'sub_PolygonSandreCoarser-dom.shp'
  • Classification code:: 'Sandre'
  • Classification method: : 'coarser-dominant'
  • Default values : '12, 12'
  • EPSG code: '2154'
  • .sub file name : 'sub_PolygonSandreCoarser-dom.sub'

• If the information displayed in this tab is valid, you can start the calculation by pressing the [Create .sub file] button.

Once the process is finished, a file 'sub_PolygonSandreCoarser-dom.sub' is created.

*User guide: Creating a .sub file

• Stay in the Substrate tab.
• In the Merging of hydraulics and substrate data group, check that the file names are selected for:
  • .hyd filename: 'd1_to_d9.hyd'.
  • .sub filename: 'sub_PolygonSandreCoarser-dom.sub'.

• Then launch the merge with the [Create .hab file] button.

Once the process is finished, a 'd1_to_d9_sub_PolygonSandreCoarser-dom.hab' file is created.

*User guide: Merging Hydraulics and Substrate

• Open the tab Calc. Habitat tab.
• Check for Habitat File(s) that the 'd1_to_d9_sub_PolygonSandreCoarser-dom.hab' file is selected.
• To add biological models to be calculated, click on the [Add Models] button.

This opens the biological model explorer.

• In the first tab Model filter, refine your search by the following criteria:
  • Country: 'France'.
  • Aquatic animal type: 'fish'.
  • Stage and size: 'adult'.
  • Code alternative filter : 'BAF'.

• In the second tab Model selection:
  • Click on the model 'Barbus barbus - adult - BAF01' in the left-hand list Available models.
  • (Optional) You can click on [Show habitat suitability indices] to display the biological model in an interactive figure
  • Drag and drop from left to right the 'Barbus barbus - adult - BAF01' model into the right-hand list Selected models.

• Validate with the [Validate selected models] button.

The model 'Barbus barbus - adult - BAF01' has been added to the list of models to be calculated.

• The hydraulics and substrate options for the biological model 'Barbus barbus - adult - BAF01' are left as default:
  • Hydraulic option: 'HV' (Height and Velocity).
  • Substrate option: 'Dominant' (Dominant substrate).

• You can now start the habitat calculation for the adult barbel with the [Compute habitat] button.

Once the process is finished, the result of the model 'BAF01_adult_HV_Dominant' has been added to the file 'd1_to_d9_sub_PolygonSandreCoarser-dom.hab'. By default, at each calculation, the text habitat calculation result file is created: 'd1_to_d9_sub_PolygonSandreCoarser-dom_spu.txt' describing the habitat values and the weighted usable area of adult barbel for each simulated discharge.

You can view the results in detail, either via the figures or via exports from the explorateur de données.

The *User guide: Calculating habitat from a .hab file explains in more detail the possibilities offered by HABBY.

In this tutorial, for the adult barbel, we will :

1. Create figures to visualise:
   1. an interactive habitat map for a discharge of 74.7 m³/s.
   2. an interactive habitat record for all discharges.
2. Create GIS, 3D and TXT file exports.
3. View the exported files:
   1. GIS representing the mesh for all discharges (.gpkg).
   2. 3D representing the topography of the river bottom (.stl).
   3. 3D representing the water level for all discharges (.pvd representing several .vtu).
   4. TXT describing the state of the mesh for all discharges.

To view the data in detail as a figure and as a file export:

• Open the Data Explorer tab.

*User guide: Data Explorer

• In the Data Explorer tab, for file types, select 'habitat'.
• In the list of File name, select the file 'd1_to_d9_sub_PolygonSandreCoarser-dom.hab'.
• Open the group Figure viewer/exporter by clicking on its name.

Interactive map

• In this group Figure viewer/explorer, choose:
  • reach(s): 'Tronçon D'.
  • discharge [m³/s]: '74.7'.
  • mesh variables: 'BAF01_adult_HV_Dominant'.
  • Figure options:
    • map: enabled.
    • global habitat value: disabled.
    • mode: 'interactive'.

• Start the figure creation process with the [run] button.

An interactive habitat map is then displayed.

NB: To close all interactive figure windows, use the button in the main window's quick menu.

Interactive Chronicle

• In this group Figure viewer/exporter, choose:
  • tronçon(s): 'Tronçon D'.
  • discharge [m³/s]</hi>: all discharges (from '9.2' to '259').
  • mesh variables: 'BAF01_adult_HV_Dominant'.
  • Figure options:
    • map: disabled.
    • global habitat value: enabled.
    • mode: 'interactive'.

• Start the figure creation process with the [run] button.

An interactive habitat chronicle is then displayed.

NB: To close all interactive figure windows, use the button in the main window's quick menu.

In the Data Explorer tab, for file types, check that 'habitat' is selected.

• In the list of File name, check that the file 'd1_to_d9_sub_PolygonSandreCoarser-dom.hab' is selected.
• Preferably, close the Figure viewer/exporter group.
• Open the group Data exporter by clicking on its name.
• Check the following items:
  • Geopackage (.gpkg) Mesh units
  • 3D (.slt) Mesh whole profile (DEM)
  • 3D (.pvd, .vtu) Mesh units
  • TXT (.txt) Mesh detailled

• Start the export process with the [run] button.

At the end of the process, all the requested files have been exported.

NB: All exported files are located in the project's output directory. To access them, use the button in the main window's quick menu.

SIG

First, we will look at the exports Geopackage (.gpkg) Mesh units, which is the file 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_mesh.gpkg'.

• Open this file 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_mesh.gpkg' in the project directory ('…\Tuto_TELEMAC\output\GIS') in your GIS software.

This Geopackage file contains several layers (each equivalent to a Shapefile) of triangular polygons (mesh data) for each discharge.

The attribute tables of these layers contain all the mesh data including the habitat data of the adult barbel.

3D

In a second step, we will look at the exports 3D (.stl) Mesh whole profile, i.e. the file 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_unit_all_wholeprofile_mesh.stl'. This 3D .stl (stereolithography) file represents the digital terrain model of the watercourse in 3 dimensions.

• Open this file in the project directory ('…\Tuto_TELEMAC\output3D') in the Paraview software, using drag and drop.

• Display the layer by clicking on the icon to the left of the file name.

In a third step, we will look at the exports 3D (.pvd, .vtu) Mesh units, namely:

• the file 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_water level.pvd'.
• the 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_XXXX_water level.vtu' files.

Together, these 3D .pvd and .vtu files represent the water level in 3 dimensions for each unit.

• Add the file 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_water level.pvd' to the Paraview software, using drag and drop.
• Display it with .
• In the 'Properties' tab and then the 'Display' sub-tab of the .pvd file layer, choose for 'Coloring': 'BAF01_adult_HV_Dominant' to display the coloration of the Barbel habitat.

• You can change the angle of view using the mouse or mouse + CTRL
• You can also scroll through the units using the buttons.

TXT

Finally, we will look at the TXT exports in the '…\Tuto_TELEMAC\outputtext' project directory, i.e. :

• 'd1_to_d9_sub_PolygonSandreCoarser-dom_spu.txt': habitat chronicle exported at each calculation.
• 'd1_to_d9_sub_PolygonSandreCoarser-dom_Troncon D_XXXX_detailled_mesh.txt': mesh data per unit, exported manually.

These can be directly used in a spreadsheet by drag and drop.

The objective of this last part of the tutorial is to find out the habitat values for a discharge time series using the Interpolation tool.

• Open the Tools tab.
• Open the Interpolation sub-tab.

*User guide: Interpolation

• If necessary, click on the Available data group to open it.
• Select the habitat file 'd1_to_d9_sub_PolygonSandreCoarser-dom.hab'.
• Check that the 'Tronçon D' is selected.
• Check that the 'BAF01_adult_HV_Dominant' is selected.

The Desired data group is then ready to choose the data to be interpolated.

• If necessary, close the Data available group.
• If necessary, click on the Desired data group to open it.
• Select the discharge chronicle file 'discharge_chronicle.txt' with the [load and run] button of the group from .txt file.

The interpolated results are then displayed in the Interpolated results group.

• If necessary, close the Desired data group.
• If necessary, click on the Interpolated results group to open it.

• Click the [run] button of View interpolated chronicle: to display the interpolated chronicle.