Run and Analyze

Run Gaia

Make sure that the simulation folder (e.g., /gaia2d-tutorial/) contains at least the following files (or similar, depending on the simulation case):

With these files available, open Terminal, go to the TELEMAC configuration folder (e.g., ~/telemac/v8p2/configs/), and load the environment (e.g., - use the same as for compiling TELEMAC).

cd ~/telemac/v8p2/configs

With the TELEMAC environment loaded, change to the directory where the TELEMAC Gaia simulation lives (e.g., /home/telemac/v8p2/mysimulations/gaia2d-tutorial/) and run the *.cas file by calling it with the script (it will automatically know that it needs to use Gaia when it reads the line COUPLING WITH : 'GAIA').

cd ~/telemac/v8p2/mysimulations/gaia2d-tutorial/ steady2d-gaia.cas

Speed up

With parallelism enabled (e.g., in the Mint Hyfo Virtual Machine), speed up the calculation by using multiple cores through the --ncsize=N flag. For instance, the following line runs the unsteady simulation on N=4 cores: steady2d-gaia.cas --ncsize=4

A successful computation should end with the following lines (or similar) in Terminal:

                    *    END OF MEMORY ORGANIZATION:    *


                             1  HOURS
                             4  MINUTES
                            34  SECONDS
... merging separated result files

... handling result files
       moving: r2dsteady-gaia.slf
       moving: rGaia-steady2d.slf
       moving: r-control-sections.txt
... deleting working dir

My work is done

TELEMAC will write the files r2dsteady-gaia.slf, rGaia-steady2d.slf, and r-control-sections.txt in the simulation folder. These result files are also available in this eBook’s modeling repository for accomplishing the post-processing tutorial:


Control Section Fluxes

The control sections enable insights into the correct adaptation of the flow at the upstream and downstream boundaries (prescribed Q only). Figure 155 shows the modeled flow rates where the Inflow_boundary and Outflow_boundary curves converge after approximately 10000 timesteps. Note that the graph shows absolute numbers while the original output in r-control-sections.txt is negative because of the order of node definitions in control-sections.txt. The hotstart initialization makes that the fluxes fluctuate around the prescribed inflow of 35 m\(^{3}\)/s from the beginning. The Outflow_boundary flowrate increase toward the end of the simulation can be attributed to sediment erosion and the free flux downstream boundary type (544-4).

result flow discharge telemac2d morphodynamic gaia inflow outflow control sections

Fig. 155 The simulated flows over the upstream Inflow_boundary and the downstream Outflow_boundary control sections.

How to distinguish water fluxes at inflow and outflow control sections from sediment transport rates?

With the two boundary files for Telemac2d and Gaia, it is possible to use different boundary types in the hydrodynamic (steady2d-gaia.cas) and morphodynamic (gaia-morphodynamics.cas) steering files. Thus, water volume fluxes can be prescribed at the inflow and the outflow sections through 455-type boundaries (prescribed Q only) in the hydrodynamic steering and/or boundaries files. For instance, with 455-type upstream and downstream hydrodynamic boundaries, adapt the PRESCRIBED FLOWRATES keyword to 35.;35 in the hydrodynamics steering file (steady2d-gaia.cas) without changing the morphodynamics (Gaia) boundary and steering files.

Visualization with QGIS

The results of the Gaia simulation can be visualized and time snapshots exported to raster (e.g., GeoTIFF) or shapefile formats by using the PostTelemac plugin in QGIS the same way as explained in the steady2d tutorial. The latest QGIS releases additionally enable loading of a Selafin (results) mesh file (here: r2dsteady-gaia.slf) as QGIS mesh layer, which can then be visualized in the viewport and exported to a video with the Crayfish plugin. To this end, launch QGIS, set the project CRS to EPSG:25833 (ETRS89 / UTM zone 33N), and save the new project in the gaia2d-tutorial/ folder (or where ever the Gaia simulation files live). In QGIS’ Browser panel, find the Project Home folder, expand it, and drag-and-drop the two simulation results meshes (r2dsteady-gaia.slf and rGaia-steady2d.slf) to the Layers panel.

Double-click on r2dsteady-gaia.slf or rGaia-steady2d.slf to open their Mesh Layer Properties, then go to the Source tab to toggle hydrodynamic (e.g., water depth or scalar flowrate m2s) or morphodynamic Gaia (e.g., qs bedload kg(ms)) simulation parameters, respectively, at different timesteps. Figure 156 shows the QGIS mesh Layer Properties window of the rGaia-steady2d.slf simulation results geometry where red boxes highlight steps for toggling output variables and visualization timesteps. In addition, the Symbology tab provides options for value color scales or vector representations (e.g., for velocity vectors in r2dsteady-gaia.slf).

qgis telemac2d gaia morphodynamics solid discharge bedload results slf

Fig. 156 The mesh Layer Properties window with the Source tab for selecting Gaia output variables. The screenshot indicates steps for visualization of qs bedload at the simulation end time (red boxes). In addition, plot color ranges can be adapted in the Symbology tab (dashed red box).

Note that only parameters defined with the VARIABLES FOR GRAPHIC PRINTOUTS keywords in the hydrodynamic (steady2d-gaia.cas) and morphodynamic (gaia-morphodynamics.cas) steering files can be plotted in QGIS.

To export a video of the simulation results, use the Crayfish plugin:

  • In QGIS, make sure the Crayfish plugin is installed (recall the QGIS instructions).

  • In the Layer panel, select rGaia-steady2d (or r2dsteady-gaia).

  • With rGaia-steady2d (or r2dsteady-gaia) selected, go to Mesh (top dropdown menu) > Crayfish > Export Animation … (if the layer is not highlighted, an error message pops up: Please select a Mesh Layer for export).

  • In the Export Animation window, go to the General tab and define an output file name by clicking on the button (e.g., velocity-video.avi).

  • Optionally adapt the Layout and Video settings.

  • Click OK to start the video export.

The first time that a video is exported, Crayfish will require the definition of an FFmpeg video encoder and guide through the installation (if required). Follow the instructions and re-start exporting the video. The following video was exported with Crayfish to visualize velocity vectors:

Video: Sebastian Schwindt @ Hydro-Morphodynamics channel on YouTube.

Note how the velocity vectors evolve over time and that high flow velocities occur at ramps/sills in the river section (e.g., the two transversal maxima close to the upstream boundary or the transversal maximum close to the downstream boundary). Accordingly, the bedload transport at the ramps should also be pronounced. The following video shows qs bedload and to verify whether the model got the physical link between flow velocity and bedload right.

Video: Sebastian Schwindt @ Hydro-Morphodynamics channel on YouTube.

After watching the video, it can be concluded that the relationship between flow velocities and bedload is approximately correct, but the model may require some correction by adapting magnitude and direction parameters. The next section exemplarily illustrates how the physical soundness of the model can be analyzed and improved.


The above-shown results feature steady-state bedload and suspended load transport in an armored-bed river section at a low baseflow discharge of 35 m\(^{3}\)/s. The comparison of the flow velocity and the sediment transport videos suggests that the highest sediment transport rates occur where the flow velocity is high, too. Three sediment size classes were defined in the Basic Setup of Gaia with average grain diameters of 0.0005 m, 0.02 m, and 0.1 m. The simulation predicts that only the finest grain size class will move at baseflow (e.g., in the console output during the simulation). This fine sediment class of 0.5-mm diameters (sand) is transported in the form of bedload and in suspension with no measurable effect on bed elevation. Thus, the model can be assumed to be basically physically reasonable, in particular, considering that nearby no change of the riverbed elevation is modeled despite the local sediment transport peak for fine sediment. Still, to verify the physical plausibility of a morphodynamic model, higher (flood) discharges should be test-simulated. Then the coarser grain sizes of 0.02 m (gravel) and 0.1 m (cobble) should also move.

A physical plausibility check is not a model validation

The physical plausibility check serves for verification of whether the simulation results are physically sound. Physically non-meaningful results would be, for instance, when the water depth permanently increases in a steady simulation, when water flows over floodplains at baseflow or leaves the model at undefined boundary nodes, or when no sediment moves at a high discharge (e.g., a 100-years flood) over an alluvial riverbed. The model validation comes after the calibration (see next section).

Also water depth, flow velocity (vectors), and Topographic change should be analyzed (in QGIS or BlueKenue) since Gaia modifies riverbed elevations. For instance, if the model predicts Topographic change in the form of 10-m deep erosion (scour) at baseflow, the keyword definitions for the riverbed should be revised. Likewise, hydro-morphodynamically relevant parameters such as friction, or direction and magnitude (bedload) correctors should be verified.

When a model is finally and approximately physically meaningful, the model can be calibrated with observation data. The next section provides a list of keywords that may be used for calibrating Bedload and/or Suspended load simulations with Gaia.


This section assumes that the model is already hydrodynamically calibrated (e.g., regarding friction) as described in the steady modeling section. Gaia can then be used to model a flood hydrograph with an unsteady (quasi-steady) simulation. The calibration requires that riverbed elevation measurements from before and after the flood are available (i.e., an event-specific Topographic change map).

Bedload Calibration Parameters

The following list of parameters can be considered for calibrating bedload in Gaia:

  • Representative roughness length \(k'_{s}\) (cf. Equation (12)) with the keyword RATIO BETWEEN SKIN FRICTION AND MEAN DIAMETER \(f_{k'_{s}}\) (default: \(f_{k'_{s}}\)=3.). Note that this keyword is a multiplier of the characteristic grain size \(D_{50}\); thus: \(k'_{s}= f_{k'_{s}} \cdot D_{50}\) (goes into Equation (12)):

    • To use this calibration parameter, make sure that SKIN FRICTION CORRECTION : 1.

    • On dune-form sand riverbeds, start with \(f_{k'_{s}}\)=37. [MAL+17].

    • In alternating bar riverbeds, start with \(f_{k'_{s}}\)=3.6 [MAL+17].

  • For models based on the Meyer-Peter and Müller formula (i.e., using a Shields parameter for incipient sediment motion), the SHIELDS PARAMETERS keyword may be modified:

    • If erosion is overpredicted, increase SHIELDS PARAMETERS.

    • If erosion is underestimated, reduce SHIELDS PARAMETERS.

  • With slope correction enabled and using the Koch and Flokstra [KF80] correction formulae, adapt the BETA keyword from Equation (13) (default is BETA : 1.3).

    • If erosion in curved channel sections is overpredicted, decrease BETA.

    • If erosion in curved channel sections is underpredicted, increase BETA.

  • To adjust deposition and erosion pattern in curves (riverbends), enable the SECONDARY CURRENTS keyword and modify the SECONDARY CURRENTS ALPHA COEFFICIENT value (cf. Secondary Currents).

Suspended Load Calibration Parameters

The following list of parameters can be considered for calibrating suspended load transport and deposition-erosion pattern in Gaia:

What next?

The calibrated model will also require validation. The validation requires another set of riverbed elevation measurements from before and after another flood (i.e., an additional event-specific Topographic change map). Alas, Topographic change maps are expensive and it is rare to have at least three DEMs from different points in time for a river section, which would enable the creation of two Topographic change maps. For this reason, the calibration dataset is often split in practice. For instance, 2/3 of a Topographic change map may be used for model calibration and 1/3 for model validation. However, such splitting makes that the two datasets are not statistically independent and the validation quality figures will be biased.