Debugging TELEMAC#

Since its early development, TELEMAC has become a robust and reliable tool for the numerically modeling of open surface flows. Yet there are a few little challenges and this always growing page provides some answers.

Keyword-research the TELEMAC docs

To look up the reference, implementation, and/or meaning of a variable, class, script, file, or module, visit the TELEMAC doxydocs.

Traceback errors#

If a simulation crashes and it is not clear why debugging with gdb is a good option. To do so, first install gdb:

sudo apt install gdb

Then launch the steering file in debugging mode as follows:

telemac2d.py -w tmp simulation_file.cas --split
telemac2d.py -w tmp simulation_file.cas -x
cd tmp
gdb ./out_telemac2d

In gdb tap:

(gdb) run

To end gdb tap:

(gdb) quit

This approach also works with Telemac3d (and other modules).

Error Message Quickfixes#

This section lists quick fixes for some frequent error messages.

RANDOM CRASH

If TELEMAC crashes for apparently random reasons, make sure that:

  • No line in the steering file has more than 72 (active characteristics). For instance, the line CLASSES CRITICAL SHEAR STRESS FOR MUD DEPOSITION = 0.011; 0.011; 0.011; 0.011 would be too long and needs a line break, such as:

CLASSES CRITICAL SHEAR STRESS FOR MUD DEPOSITION = 0.011; 0.011
; 0.011; 0.011

Steering (CAS) Files#

  • Prefer : over =

  • Place all model files in the same folder and only use file names without the directories of files.

Unstable Simulations#

Accuracy#

When the accuracy keywords are improperly defined, TELEMAC may not be able to end the simulation. In this case, make sure to comment out the accuracy keywords and let TELEMAC use its default values:

/ SOLVER ACCURACY : 1.E-4
/ ACCURACY FOR DIFFUSION OF TRACERS : 1.E-4
/ ACCURACY OF K : 1.E-6
/ ACCURACY OF EPSILON : 1.E-6
/ ACCURACY OF SPALART-ALLMARAS : 1.E-6

Variable Time-Steps and CFL Condition#

Unstable simulations may occur when the CFL condition is insufficiently fulfilled. To ensure that the CFL condition is respected, enable variable timestep calculation and use the DESIRED COURANT NUMBER keyword (default value 1), for example:

TIME STEP : 5
VARIABLE TIME-STEP : YES
DURATION : 5000
DESIRED COURANT NUMBER : 0.9

Note that the TIME STEP is still required because the GRAPHIC PRINTOUT PERIOD is a multiple of the defined TIME STEP.

Use the DURATION keyword

A variable timestep calculation may run eternally. Assigning the DURATION keyword avoids such eternal runs.

Implicitation#

To increase model stability, modify the following variables or make sure that the variables are within reasonable ranges in the CAS file:

  • IMPLICITATION FOR DEPTH should be between 0.5 and 0.6.

  • IMPLICITATION FOR VELOCITIES should be between 0.5 and 0.6.

  • IMPLICITATION FOR DIFFUSION should be 1. or smaller.

Surface Oscillations (Wiggles)#

When physically non-meaningful gradients or oscillations occur at the water surface or the bathymetry has steep slopes, the following keyword settings may help:

  • FREE SURFACE GRADIENT - default is 1.0, but it can be reduced to 0.1 to achieve stability (nevertheless, start with going incrementally down, such as a value of 0.9).

  • DISCRETIZATIONS IN SPACE : 12;11 - uses quasi-bubble spatial discretization with 4-node triangles for velocity.

Residual Mass Errors#

To reduce residual mass errors use in the steering file:

CONTINUITY CORRECTION : YES

Divergence#

To limit divergence issues, use the CONTROL OF LIMITS and LIMIT VALUES keywords. The LIMIT VALUES keyword is a list of 8 integers for minimum and maximum values for H, U, V, and T (tracers). The implementation in the steering file looks like this:

CONTROL OF LIMITS : YES / default is NO
LIMIT VALUES : -1000;9000;-1000;1000;-1000;1000;-1000;1000 / default mins and max for H, U, V, tracer

Tidal Flats#

Wetting and drying of grid cells, for instance, during a simulation of dam breaks or flood hydrographs, may lead to model instability. While the Tidal Flats section in the Telemac2d steady modeling tutorial suggests physically and computationally meaningful keyword option combinations, section 16.5 in the Telemac2d manual recommends using the following settings in the steering file as conservative choices from the BAW’s Wesel example (similar to /telemac/v8p2/examples/telemac2d/wesel/).

VELOCITY PROFILES : 4;0
TURBULENCE MODEL : 1
VELOCITY DIFFUSIVITY : 2.
TIDAL FLATS : YES
OPTION FOR THE TREATMENT OF TIDAL FLATS : 1
TREATMENT OF NEGATIVE DEPTHS : 2
FREE SURFACE GRADIENT COMPATIBILITY : 0.9
H CLIPPING : NO
TYPE OF ADVECTION : 1;5
SUPG OPTION : 0;0
TREATMENT OF THE LINEAR SYSTEM : 2
SOLVER : 2
PRECONDITIONING : 2
SOLVER ACCURACY : 1.E-5
CONTINUITY CORRECTION : YES

Discretization Scheme#

The default setting of DISCRETIZATIONS IN SPACE : 11;11 assigns a linear discretization for velocity and water depth, which is computationally fast but potentially unstable (read more in the section on general Telemac2d parameters). To overcome stability issues related to the discretization scheme, consider using DISCRETIZATIONS IN SPACE : 12;11. In addition, setting FREE SURFACE GRADIENT COMPATIBILITY : 0.01 (i.e., close to zero) may aid in troubleshooting stability issues related to the discretization of velocity and depth.

Exceeding Maximum Iterations#

This section is co-authored by Federica Scolari.

A simulation may print EXCEEDING MAXIMUM ITERATIONS warnings in the Terminal:

GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  0.7234532E-01
GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  NaN
GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  NaN
GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  NaN
GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  NaN
GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  NaN
GRACJG (BIEF) : EXCEEDING MAXIMUM ITERATIONS:    50 RELATIVE PRECISION:  NaN

EXCEEDING MAXIMUM ITERATIONS warnings may occur when using SCHEME FOR ADVECTION OF […] keywords with the values 3, 4, 5, 13, or 14. The reason is that these schemes yield CFL conditions of less than 1 by triggering iterative, adaptive timestepping. To troubleshoot EXCEEDING MAXIMUM ITERATIONS warnings, try the following options:

Computation Speed#

Some of the keywords in TELEMAC’s steering (*.cas) file affect computation speed.

  • Use the ACCURACY and MAXIMUM ITERATION keywords to yield faster convergence.

  • Deactivate TIDAL FLATS, even though deactivating tidal flats can not be recommended to yield physically meaningful and stable models.

  • When using the GMRES solver (SOLVER : 7), varying the solver options may aid to reduce the total calculation time.

  • Make sure to use the default MATRIX STORAGE : 3 keyword.

  • Use an earlier simulation (e.g., with a coarser mesh) to initiate the model with the COMPUTATION CONTINUED : YES and PREVIOUS COMPUTATION FILE : *.slf keywords (see section 4.1.3 in the Telemac2d manual).

Moreover, Telemac2d provides a way to stop a simulation (step) when fluxes stabilize. To enable this feature, add the following block in the steering (*.cas) file:

/ steady state stop criteria in steering.cas
STOP IF A STEADY STATE IS REACHED : YES / default is NO
STOP CRITERIA : 1.E-3;1.E-3;1.E-3 / use list of three values - defaults are 1.E-4

However, stop criteria are not functional for non-stationary flows (e.g., Von Karmàn [VK30] vortex street downstream of bridge piers). Read more about the convergence stop criteria in the Telemac2d manual (section 5.1).

Mesh File#

Fine High-resolution Meshes#

This section is co-authored by Federica Scolari.

For creating very fine meshes with a grid size smaller than 1.0 m, a selafin (*.slf) geometry file should be saved in double precision format (SERAFIND). Otherwise, model boundary edges may not be well represented in the computational mesh. Figure 187 illustrates the loss in boundary accuracy when single-precision (a) is used instead of double-precision (b).

telemac slf selafin single double precision serafind

Fig. 187 The loss boundary precision in a single-precision selafin mesh (a) compared to a double-precision selafin mesh (b).#

Built-in Mesh Consistency Check#

Hint

A 3d simulation may crash when it is used with the parameter CHECKING THE MESH : YES. Thus, in 3d, favorably use CHECKING THE MESH : NO.

To verify if TELEMAC can read the mesh, load the TELEMAC environment (e.g., source pysource.openmpi.sh) and go to the directory where the mesh to be checked lives and run mdump, for example:

cd ~/telemac/studies/test-case/
mdump mesh-to-test.med

Until the time of writing this tutorial, mdump asks for input variables in French, which mean the following:

  • Mode d’affichage de noeuds? which means in
    English: Node display mode?

    • Option 1: Interlaced mode

    • Option 2: Non-interlaced mode

  • Connectivité des éléments? which means in
    English: Element connectivity?

    • Option 1: Nodal

    • Option 2: Descending

  • Il y a 1 maillage(s) de type local dans ce fichier. Lequel voulez-vous lire (0 pour tous|1|2|3|…|n)? which means in
    English: There is 1 local mesh(es) in this file. Which one do you want to read (0 for all or |1|2|3|…|n)?

    • Option 0: Read all

    • Option i: Read mesh number i

A standard answer combination of 1 - 1 - 0 will result in a console print of all nodes and connections between the nodes in the mesh, given that TELEMAC can read the mesh file. Starting with:

(**********************************************************)
(* INFORMATIONS GENERALES SUR LE MAILLAGE DE CALCUL N°01: *)
(**********************************************************)

- Nom du maillage : <<Mesh_Hn_1>>
- Dimension du maillage : 2
- Type du maillage : MED_NON_STRUCTURE
- Description associee au maillage :

(**********************************************************************************)
(* MAILLAGE DE CALCUL |Mesh_Hn_1| n°01 A L'ETAPE DE CALCUL (n°dt,n°it)=(-01,-01): *)
(**********************************************************************************)
- Nombre de noeuds : 243
- Nombre de mailles de type MED_SEG2 : 80
- Nombre de mailles de type MED_TRIA3 : 404
- Nombre de familles : 15

[...]

What this output means: If mdump can read the mesh, the mesh file itself is OK and potential calculation errors stem from other files such as the steering file or the boundary conditions. Otherwise, revise the mesh file and resolve any potential issue.

Boundaries#

This section is co-authored by Federica Scolari.

No Water in the Model#

Erroneous simulations where no water is entering or exiting the domain have most likely improperly defined boundary conditions. For instance, consider the open boundaries shown in Fig. 188 with prescribed Q (4 5 5) upstream and prescribed H (5 4 4) downstream.

debugging boundary conditions cli bluekenue

Fig. 188 The definition of open (liquid) boundaries with prescribed Q (4 5 5) upstream and prescribed H (5 4 4) downstream.#

Intuitively, you may think that the upstream boundary is number (1) and the downstream boundary is number (2). However, the order of boundary numbering depends on the definition order during the setup of the boundaries (e.g., described in the BlueKenue pre-processing tutorial). If you do not remember the definition order, it can be read in the boundary (*.cli) file at any time. For instance, the boundary file for the above-shown mesh (Fig. 188) looks like the representation in Fig. 189 where the Outlet is defined above the Inlet. Therefore, the downstream (Outlet) open boundary is number (1) and the upstream (Inlet) open boundary is number (2) in this simulation.

debugging boundary conditions cli bluekenue

Fig. 189 Exemplary definition of a downstream (Outlet) and an upstream (Inlet) open boundary in a boundary.cli file corresponding to Fig. 188.#

Thus, these two boundaries must be referenced in the steering (*.cas) file as follows to prescribe a flow rate Q (e.g., 10 m\(^3\)/s) at the upstream and a depth H (e.g., 0.75 m) at the downstream boundary:

PRESCRIBED FLOWRATES : 0.;10
PRESCRIBED DEPTHS : 0.75;0.

Problem on Boundary Number (Simulation Stop)#

This section guides through debugging error messages such as:

DEBIMP_2D: PROBLEM ON BOUNDARY NUMBER       2
        GIVE A VELOCITY PROFILE
        IN THE BOUNDARY CONDITIONS FILE
        OR CHECK THE WATER DEPTHS
        OTHER POSSIBLE CAUSE:
        SUPERCRITICAL ENTRANCE WITH FREE DEPTH

To get a better appreciation of the cause of the error (e.g., to figure out if supercritical flow conditions at the entrance are the cause), add the Froude number to the output variables in the steering (*.cas) file. To this end, add F to the output variable keyword:

VARIABLES FOR GRAPHIC PRINTOUTS : U,V,H,S,Q,F

With a more precise of the cause for the error, try one of the following options:

Supercritical boundaries at the entrance

For supercritical flow conditions at the entrance, make sure that a prescribed Q and H boundary also gets a discharge and a depth assigned in the steering file. For instance, if the Inlet in Figures 188 and 189 was 5 5 5 (prescribed Q and H) instead of 4 5 5, the steering file needs to prescribe flowrates and depths. For instance, add a depth of 0.9 for the Inlet as follows:

PRESCRIBED FLOWRATES : 0.;10

PRESCRIBED DEPTHS : 0.75;0.9

Change the (vertical) velocity profile

The definition of a VELOCITY PROFILE keyword in the steering file is explained in the steady2d tutorial in this eBook. The addition VERTICAL applies to 3d models only (read more in the Telemac 3d (SLF) section).

3d models with supercritical boundaries

Too many vertical layers may result in very thin 3d mesh elements that cause supercritical flows locally. Thus, consider reducing the NUMBER OF HORIZONTAL LEVELS in the steering file to satisfy the CFL condition.

Gaia (Morphodynamics)#

UNKNOWN BOUNDARY CONDITIONS#

TELEMAC-Gaia may interrupt with an error message such as KEYWORD: ... UNKNOWN BOUNDARY CONDITIONS FILE .... This message means that the boundary condition type in the *.cli file does not match the boundary conditions defined in the *.cas file. For instance, if the tracer (suspended load) boundary column (9 in the Gaia *.cli file for CBOR) is set to 5, try using EQUILIBRIUM INFLOW CONCENTRATION : YES or double-check the numbers defined for the PRESCRIBED SUSPENDED SEDIMENTS CONCENTRATION VALUES keyword.

Read more about setting up boundary condition files for Gaia in the Gaia Basics section. The definition of boundary types in the Gaia steering file are described separately for bedload and suspended load.

BlueKenue#

This section is co-authored by Federica Scolari.

BlueKenue may throw errors or not correctly show when working with 3d meshes. Some of the issues can be resolved by using the latest version of BlueKenue (v3.12.2-alpha at the time of editing this article).

OnFileOpendata(): ERROR: on Activate()

Causes: The error message typically occurs with parallelized model runs when Telemac3d / PARTEL did not correctly merge the mesh at the end of the simulation.

Solution: Force TELEMAC to not delete the temporary simulation folder (a folder that is visible in the simulation directory by default only while a simulation is running). Keeping the temporary calculation directory is achieved through adding a -t flag at the end of the simulation run command. For instance, tap the following to keep the simulation folder for a Telemac3d simulation (read more in in Annex A of the Telemac3d manual): telemac3d.py steering-file.cas -t
The temporary folder contains T3DRES (mesh partition) files that can be merged and then opened in BlueKenue. To merge the T3DRES files run the following command (make sure the TELEMAC environment is still activated with source pysource.YOUR-ENV.sh):
runcode.py --merge -w temp_directory/ telemac3d file.cas
To get help with running this command, read this TELEMAC Forum entry.

For updates on this message, follow the BlueKenue thread in the TELEMAC Forum for troubleshooting updates on this error.

PostTelemac Plugin#

Some versions of QGIS may throw a Python error (yellow frame in the top region of the map viewport) and a click on Stack reveals an error message. At the bottom of the error message, it might be written import error: no module named gdal. The error probably stems from an import statement in one of the PostTelemac plugin’s Python scripts. To troubleshoot the gdal import error, find the Python script that is raising the error message. For instance, C:\Users\USERNAME\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\PostTelemac\meshlayerparsers\posttelemac_hdf_parser.py may cause the error with its import gdal statement. Therefore:

  • Open the concerned file, which is here: posttelemac_hdf_parser.py

  • Find the import gdal statement and **replace it with from osgeo import gdal (i.e., import gdal and write from osgeo import gdal)

  • Save and close the Python file.

Retry to start the PostTelemac plugin. It should run without issues now.

SALOME-HYDRO#

SALOME-HYDRO not starting (Kernel/Session)#

If an error message is raised by Kernel/Session in the Naming Service (typically ends up in [Errno 3] No such process … RuntimeError: Process NUMBER for Kernel/Session not found), there are multiple possible origins that partially root in potentially hard-coded library versions of the installer. To troubleshoot:

  • Manually create copies of newer libraries with names of older versions. For instance,

    • In the 4th line after running ./salome, Kernel/Session may prompt error while loading [...] libSOMETHING.so.20 cannot open [...] No such file or directory

    • Identify the version installed with whereis libSOMETHING.so.20 (replace libSOMETHING.so.20 with the missing library); for example, this may output /usr/lib/x86_64-linux-gnu/libSOMETHING.so.40

    • Create a copy of the newer library and rename the copy as needed by SALOME; for example, tap sudo cp /usr/lib/x86_64-linux-gnu/libSOMETHING.so.40 usr/lib/x86_64-linux-gnu/libSOMETHING.so.20

    • Most likely, the following files need to be copied:

sudo cp /usr/lib/x86_64-linux-gnu/libmpi.so.40 /usr/lib/x86_64-linux-gnu/libmpi.so.20
sudo cp /usr/lib/x86_64-linux-gnu/libicui18n.so.63 /usr/lib/x86_64-linux-gnu/libicui18n.so.57
sudo cp /usr/lib/x86_64-linux-gnu/libicuuc.so.63 /usr/lib/x86_64-linux-gnu/libicuuc.so.57
sudo cp /usr/lib/x86_64-linux-gnu/libicudata.so.63 /usr/lib/x86_64-linux-gnu/libicudata.so.57
sudo cp /usr/lib/x86_64-linux-gnu/libnetcdf.so.13 /usr/lib/x86_64-linux-gnu/libnetcdf.so.11
sudo cp /usr/lib/x86_64-linux-gnu/libmpi_usempif08.so.40 /usr/lib/x86_64-linux-gnu/libmpi_usempif08.so.20
sudo cp /usr/lib/x86_64-linux-gnu/libmpi_java.so.40 /usr/lib/x86_64-linux-gnu/libmpi_java.so.20
sudo cp /usr/lib/x86_64-linux-gnu/libmpi_cxx.so.40 /usr/lib/x86_64-linux-gnu/libmpi_cxx.so.20
sudo cp /usr/lib/x86_64-linux-gnu/libmpi_mpifh.so.40 /usr/lib/x86_64-linux-gnu/libmpi_mpifh.so.20
sudo cp /usr/lib/x86_64-linux-gnu/libmpi_usempi_ignore_tkr.so.40 /usr/lib/x86_64-linux-gnu/libmpi_usempi_ignore_tkr.so.20

  • Overwrite the SALOME-HYDRO’s internal version of Qt:

    • Copy /usr/lib/x86_64-linux-gnu/libQtCore.so.5

    • Paste in /Salome-V2_2/prerequisites/Qt-591/lib/ - confirm replacing libQtCore.so.5

GUI/Qt5 support (GTK version compatibility)#

With the newer versions of the Qt platform any menu entry in SALOME-HYDRO will not show up. To fix this issue, install and configure qt5ct styles:

  • sudo apt install qt5-style-plugins libnlopt0

  • sudo apt install qt5ct

  • Configure qt5ct (just tap qt5ct in Terminal)

    • Go to the Appearance tab

    • Set Style to gtk2 and Standard dialogs to GTK2

    • Click on Apply and OK

  • Open the file ~/.profile (e.g. use the file browser, go to the Home folder and press CTRL + H to toggle viewing hidden files) and add at the very bottom of the file:

export QT_STYLE_OVERRIDE=gtk2
export QT_QPA_PLATFORMTHEME=qt5ct

  • Save and close .profile and reboot (or just re-login).

Note

If a file called ~/.bash_profile (or ~/.bash_login) exists, the above lines should be written to this ~/.bash_profile/~/.bash_login because in this case, .profile will not be read when logging in.

Learn about Qt more at archlinux.org and in the arch wiki.