This tutorial guides the user step by step through the complete workflow of a TELEMAC-2D simulation, through the "Gouttedo" (droplet) test case, from domain geometry creation to result visualisation.
1. Domain geometry
The computational domain is a 20.1 m × 20.1 m square with a flat bottom. The coordinates of the four corners are defined in a .txt file that is imported into QGIS to build the geometric outline.
1.1 Folder preparation
Create the needed folders, in the terminal:
bashmkdir -p gouttedo/shape
mkdir -p gouttedo/user_fortranCreate the following text file in gouttedo/shape/geo.txt
txtx(m),y(m)
0,0
20.1,0
20.1,20.1
0,20.1
1.2 Opening QGIS and creating the project
1. Open QGIS.
2. Go to Project > New.
3. Save the project immediately: Project > Save As, navigate to gouttedo/shape, file name: q4ts_gouttedo
1.3 Importing the domain points
The coordinates in geo.txt are imported as a vector point layer.
4. Go to Layer > Add Layer > Add Delimited Text Layer.
5. Click ... to select gouttedo/shape/geo.txt
6. Under File Format, check Comma as the delimiter.
7. Verify that the X and Y fields are correctly filled. The CRS must be EPSG:4326. Click Add then Close.
1.4 Building the outline: Points → Line → Polygon
8. Open the Processing Toolbox (gear icon or Processing > Toolbox).
9. Search for Points to Path , select the imported point layer, then click Run. A polyline layer is created.
10. Search for Lines to polygons and apply it to the polyline layer. The closed domain boundary is created.
2. Mesh generation with Q4TS
Q4TS (QGIS for TELEMAC Suite) is a QGIS plugin that generates TELEMAC-compatible meshes, applies boundary conditions, and interpolates field data (bathymetry, velocities). Here it is used to create a triangular mesh with a characteristic size of 0.3 m.
2.1 Mesh parameters in Q4TS
11. Open the Q4TS panel.
12. Fill in the parameters in the Q4TS interface as follows:
- Contour layer: Polygons
- Mesh engine: netgen_1d_2d
- Mesh min./max. size: 0.3 m
- Result .slf: geo_gouttedo.slf
13. Click the green ▶ (Play) button at the bottom right to start mesh generation.
14. If the message "My work is done" appears, the mesh was successfully created.
The mesh layer now appears in the QGIS Layers panel.
3. Boundary condition definition
TELEMAC-2D boundary conditions are encoded in a .cli file. Q4TS automatically generates this file from the mesh. Only solid walls boundary conditions are considered in this example.
3.1 Generating the contour and boundaries in Q4TS
In Q4TS, navigate to the Create Boundary tab.
15. In the Input mesh field, select the mesh layer geo_gouttedo.slf created in the previous step.
16. In the Contour section, click the green + button to automatically extract the boundary nodes.
The layer ContourMesh is created.
17. Leave the Initial Boundaries field empty (no special initial boundaries in this simple case).
18. Click the green + in the Boundaries section to generate the boundary conditions.
The layer boundaries is created automatically.
By default, all boundaries generated by Q4TS are solid walls (code 2 2 2). No modification is needed for this example. To impose liquid boundaries, edit the "boundaries" layer (see the Q4TS documentation).
19. If QGIS asks to save a .gpkg file, save it in gouttedo/shape/
20. Click the green ▶ (Play) button to generate geo_gouttedo.cli.
This file is placed alongside geo_gouttedo.slf in the gouttedo/ folder.
4. Initial conditions
The fluid is initially at rest (U = V = 0 m/s). The free surface features a 2D Gaussian perturbation centred at the middle of the domain, at (10.05 m, 10.05 m).
4.1 Fortran user routine USER_CONDIN_H
TELEMAC-2D offers several methods for imposing initial conditions. Here, a Fortran user routine is used, providing full flexibility for arbitrary profiles. Create the file gouttedo/user_fortran/user_condin_h.f with the following content:
Fortranuser_condin_h.f — Fortran user routine
!> @brief USER INITIALISES THE PHYSICAL PARAMETERS H
SUBROUTINE USER_CONDIN_H
!
USE BIEF
USE DECLARATIONS_TELEMAC
USE DECLARATIONS_TELEMAC2D
!
USE DECLARATIONS_SPECIAL
IMPLICIT NONE
!
!+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
!
INTEGER IPOIN
DOUBLE PRECISION EIKON
INTRINSIC EXP
!
!---------------------------------------------------------------
!
DO IPOIN=1,NPOIN
EIKON = ((X(IPOIN)-10.05D0)**2 &
+ (Y(IPOIN)-10.05D0)**2) / 4.D0
H%R(IPOIN) = 2.4D0 * (1.D0 + EXP(-EIKON))
ENDDO
!
!---------------------------------------------------------------
!
RETURN
END
5. Steering file (.cas)
The .cas steering file centralises all physical, numerical and input/output parameters. All allowed keywords can be found in the corresponding reference guide module (see the latest version documentation. In gouttedo/ create the following t2d_gouttedo.cas file:
EQUATIONS : 'SAINT-VENANT FE'
/
FORTRAN FILE : 'user_fortran'
BOUNDARY CONDITIONS FILE : geo_gouttedo.cli
GEOMETRY FILE : geo_gouttedo.slf
RESULTS FILE : r2d_gouttedo.slf
/
/----------------------------------------------------------------------
/ OPTIONS GENERALES
/----------------------------------------------------------------------
TITLE = 'TELEMAC 2D: DROPLET IN A BASIN'
VARIABLES FOR GRAPHIC PRINTOUTS : 'U,V,H,T*'
TIME STEP = 0.04
NUMBER OF TIME STEPS = 100
GRAPHIC PRINTOUT PERIOD : 5
LISTING FOR PRINTOUT PERIOD = 10
LAW OF BOTTOM FRICTION : 3
FRICTION COEFFICIENT = 40.
/----------------------------------------------------------------------
/ PROPAGATION
/----------------------------------------------------------------------
TURBULENCE MODEL : 1
VELOCITY DIFFUSIVITY = 0.D0
SOLVER : 7
SOLVER OPTION : 3
MAXIMUM NUMBER OF ITERATIONS FOR SOLVER : 100
SOLVER ACCURACY = 1.E-4
IMPLICITATION FOR DEPTH = 0.6
IMPLICITATION FOR VELOCITY = 0.6
/---------------------------------------------------------------
MASS-BALANCE : YES
INITIAL CONDITIONS : 'PARTICULAR'
TYPE OF ADVECTION : 2;5
SUPG OPTION : 2;2
DISCRETIZATIONS IN SPACE: 11;11
/
/ DEFAULT VALUE UNTIL V8P1 MANDATORY WITH SUPG
TREATMENT OF THE LINEAR SYSTEM = 1
/
/ DEFAULT VALUE UNTIL V8P5 KEPT FOR NON REGRESSION
TREATMENT OF NEGATIVE DEPTHS = 16. Running the simulation
TELEMAC-2D simulation is launched from the terminal via the Python script telemac2d.py:
bash# 1. source TELEMAC environment
source /path/to/your/telemac/setenv_telemac.sh
# 2. Move to the case directory
cd /path/to/your/case/gouttedo/
# 3. Sequential run
telemac2d.py t2d_gouttedo.cas
# 4. or run in parallel (4 MPI cores)
telemac2d.py t2d_gouttedo.cas --ncsize=48. Post-processing and result visualisation
Once the simulation is complete, results are stored in the SERAFIN binary file r2d_gouttedo.slf. openTELEMAC results file can be post-processed with various tools, such as Python and ParaView.
8.1 Jupyter Notebooks
openTELEMAC provides a collection of Jupyter notebooks covering pre-processing, simulation launch, and post-processing for many application cases (see this article). These notebooks are an excellent starting point for understanding the TELEMAC Python APIs and building custom analysis scripts.
8.2 Python animation script
The script below generates an animated GIF of the water depth H(x,y,t), combining a plan view and a 3D view. Create the following plot.py file in the gouttedo folder:
pythonimport numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
import matplotlib.colors as mcolors
import matplotlib.cm as cm
from data_manip.extraction.telemac_file import TelemacFile
from postel.plot2d import plot2d_triangle_mesh, plot2d_scalar_map
plt.rcParams.update({'font.size': 18})
# load .slf file
filename = 'r2d_gouttedo.slf'
res = TelemacFile(filename)
# extract water depth
n = len(res.times)
h = np.array([res.get_data_value('WATER DEPTH', t) for t in range(n)])
# figure
fig = plt.figure(figsize=(16, 8))
gs = fig.add_gridspec(1, 3, width_ratios=[5, 6, 0.5])
ax1 = fig.add_subplot(gs[0]) #top view
ax2 = fig.add_subplot(gs[1], projection='3d') #3d view
cax = fig.add_subplot(gs[2])
ax1.set_aspect('equal')
vmin, vmax = h.min(), h.max()
norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
ax2.xaxis.labelpad = 10; ax2.yaxis.labelpad = 10; ax2.zaxis.labelpad = 10
# color
cmap = cm.get_cmap('jet')
sm = cm.ScalarMappable(cmap=cmap, norm=norm)
sm.set_array([])
fig.colorbar(sm, cax=cax, label="water depth (m)")
# initialisation
plot2d_scalar_map(fig, ax1, res.tri, h[0],
data_name="water_depth (m)", vmin=vmin, vmax=vmax, colorbar=False)
ax1.set_xlabel('x (m)'); ax1.set_ylabel('y (m)')
surf = [ax2.plot_trisurf(res.tri.x, res.tri.y, h[0],
triangles=res.tri.triangles, cmap=cmap, norm=norm,
antialiased=True)]
ax2.set_xlabel('x (m)'); ax2.set_ylabel('y (m)'); ax2.set_zlabel('z (m)')
ax2.set_zlim(vmin, vmax)
fig.suptitle(f't = {res.times[0]:.1f} s')
# animation loop
def update(frame):
plot2d_scalar_map(fig, ax1, res.tri, h[frame],
data_name="water depth (m)", vmin=vmin, vmax=vmax, colorbar=False)
ax1.set_xlabel('x (m)'); ax1.set_ylabel('y (m)')
surf[0].remove()
surf[0] = ax2.plot_trisurf(res.tri.x, res.tri.y, h[frame],
triangles=res.tri.triangles, cmap=cmap, norm=norm,
antialiased=True)
fig.suptitle(f't = {res.times[frame]:.1f} s')
fps = 5
ani = animation.FuncAnimation(fig, update, frames=n, interval=1000 // fps)
# save gif
ani.save('water_depth.gif', writer=animation.PillowWriter(fps=fps))8.3 Run the plotting script and visualize the results
In the terminal,
bash# Move to the gouttedo directory
cd path/to/your/case/gouttedo/
# Run the python script
python plot.py