Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

About Telemac3d

Telemac3d solves the Navier-Stokes equations along a three-dimensional (3d) computational grid using a finite element scheme. Telemac3d mounts the tetrahedral 3d mesh from a triangular 2d mesh in a user-defined number of vertical layers. The number of vertical layers to use is defined in the TELEMAC steering (CAS) file.

Steady 3d Simulations with Telemac

This tutorial shows how a steady discharge can be simulated with Telemac3d using the SLF geometry format. The tutorial builds on the steady2d simulation of the 35-m3^3/s discharge and requires the following data from the pre-processing and steady2d tutorials, which can be downloaded by clicking on the filenames:

Consider saving the files in a new folder, such as /steady3d-tutorial/.

Re-use the 2d Model

The simulation of 3d flow phenomena flows requires the adaptation of keywords and additional keywords (e.g., for linking liquid boundary files) in the steering (*.cas) file from the steady2d tutorial (download steady2d.cas).

Steering File

This tutorial features a steady, hydrodynamic model with an inflow rate of 35 m3^3/s (prescribed upstream flow rate boundary) and an outflow depth of 2 m (prescribed downstream elevation). The simulation uses 5 vertical layers that constitute a numerical grid of prisms. 3d outputs of U (x-direction), V (y-direction), and W (z-direction) velocities, as well as the elevation Z, are written to a file named r3dsteady.slf. 2d outputs of depth-averaged U velocity (x-direction), depth-averaged V velocity (y-direction), and water depth h are written to a file named r2d3dsteady.slf.

The below code block shows the steering file t3d_flume.cas and details for every parameter are provided after the code block. The slash / character comments out lines (i.e., TELEMAC will ignore anything in a line the / character). The : character separates VARIABLE NAME and VALUEs. Alternatively to the :, also a = sign may be used. The &ETA at the end of the file makes TELEMAC printing out a list of keywords applied (in the DAMOCLES routine).

Expand to view the steady3d.cas steering file
/ steady3d.cas
/------------------------------------------------------------------/
/			COMPUTATION ENVIRONMENT
/------------------------------------------------------------------/
/
TITLE : '3d steady'
MASS-BALANCE : YES
/
BOUNDARY CONDITIONS FILE : boundaries.cli
GEOMETRY FILE            : qgismesh.slf
3D RESULT FILE           : r3dsteady.slf
2D RESULT FILE           : r2d3dsteady.med
/ FILE FOR 2D CONTINUATION : r2dsteady.slf / activates 2d-init automatically since v9.0 (no extra keyword needed)
/
VARIABLES FOR 2D GRAPHIC PRINTOUTS : U,V,H,S,Q,F / Q enables boundary flux equilibrium controls
VARIABLES FOR 3D GRAPHIC PRINTOUTS : Z,U,V,W
/
/------------------------------------------------------------------/
/			GENERAL PARAMETERS
/------------------------------------------------------------------/
/
TIME STEP : 1.
NUMBER OF TIME STEPS : 8000
GRAPHIC PRINTOUT PERIOD : 500
LISTING PRINTOUT PERIOD : 200
/
/------------------------------------------------------------------/
/			VERTICAL
/------------------------------------------------------------------/
/ vertical cell height defined by initial condition x no. of levels
/ will be adapted for every time step
NUMBER OF HORIZONTAL LEVELS : 5 / default and minimum is 2, upward vertical direction
MESH TRANSFORMATION : 1 / 0-CALCOT (user defined) 1-SIGMA (default) 3-user defined
ELEMENT : 'PRISM' / default is 'PRISM' but preferably use 'TETRAHEDRON'
/
/------------------------------------------------------------------/
/			NUMERICAL PARAMETERS
/------------------------------------------------------------------/
/
/ ADVECTION-DIFFUSION
/------------------------------------------------------------------
SCHEME FOR ADVECTION OF VELOCITIES : 5
SCHEME FOR ADVECTION OF K-EPSILON : 5
SCHEME FOR ADVECTION OF TRACERS : 5
SCHEME OPTION FOR ADVECTION OF VELOCITIES : 4 / use 2 for without tidal flats for speed
SCHEME OPTION FOR ADVECTION OF K-EPSILON : 4
SCHEME OPTION FOR ADVECTION OF TRACERS : 4
/
MATRIX STORAGE : 3 / 1 (element-by-element), 3 (segment-wise faster)
SUPG OPTION : 1  / 0=none 1=classical SUPG (default) 2=Courant-scaled; single integer since v9.0
/
/ PROPAGATION HEIGHT AND STABILITY
/ ------------------------------------------------------------------
IMPLICITATION FOR DEPTH : 0.55 / should be between 0.55 and 0.6
IMPLICITATION FOR VELOCITIES : 0.55 / should be between 0.55 and 0.6
IMPLICITATION FOR DIFFUSION : 1.
FREE SURFACE GRADIENT COMPATIBILITY : 0.1  / default 1.
/
/ MASS LUMPING - enable to fasten calculations (smoothens) - possibly avoid in 3d
/ ------------------------------------------------------------------
/ MASS-LUMPING FOR DIFFUSION : 1 / 1 is ON - 0 is OFF (default)
/ MASS-LUMPING FOR DEPTH : 1.  / VELOCITY has no effect
/ MASS-LUMPING FOR WEAK CHARACTERISTICS : 1
/
/------------------------------------------------------------------/
/			HYDRODYNAMICS
/------------------------------------------------------------------/
/
/ HYDRODYNAMIC SOLVER
/------------------------------------------------------------------
NON-HYDROSTATIC VERSION : YES
/ solver options are
/ 1-conjugate method 2-conjugate residual method 3-conjugate gradient
/ 4-minimum error 5-square conjugate gradient 6-stabilized conjugate gradient CGSTAB
/ 7-Generalised Minimum RESidual GMRES is the favorite for improperly conditioned systems - RECOMMENDED in 3d
/ 8-direct solver YSMP (Yale) is not working with parallel versions
SOLVER FOR DIFFUSION OF VELOCITIES : 1 / 1-default
SOLVER FOR PROPAGATION : 7 / 7-default
SOLVER FOR PPE : 7 / 7-default
/ SOLVER FOR DIFFUSION OF TRACERS : 1 / one value per tracer
SOLVER FOR DIFFUSION OF K-EPSILON : 1 / 1-default
/
/ Set OPTIONS for GMRES
/ Increasing values for precision, but also more memory consumption
OPTION OF SOLVER FOR DIFFUSION OF VELOCITIES : 5 / 5-default since v8
OPTION OF SOLVER FOR PROPAGATION : 5 / 5-default since v8
OPTION OF SOLVER FOR PPE : 5 / 5-default since v8
OPTION OF SOLVER FOR DIFFUSION OF K-EPSILON : 5 / 5-default since v8
/
/ Solver ACCURACY
ACCURACY FOR DIFFUSION OF VELOCITIES : 1.E-8 / default is 1.E-8
ACCURACY FOR PROPAGATION : 1.E-8 / default is 1.E-8
ACCURACY FOR PPE : 1.E-4 / default is 1.E-4
ACCURACY FOR DIFFUSION OF K-EPSILON : 1.E-8 / default is 1.E-8
/
/ Solver MAXIMUM ITERATIONS
MAXIMUM NUMBER OF ITERATIONS FOR DIFFUSION OF VELOCITIES : 100 / default is 60
MAXIMUM NUMBER OF ITERATIONS FOR PROPAGATION : 200 / default is 100
MAXIMUM NUMBER OF ITERATIONS FOR PPE : 100 / default is 100
MAXIMUM NUMBER OF ITERATIONS FOR DIFFUSION OF K-EPSILON : 200 / default is 200
/
/ PRECONDITIONING - DEFAULT Value is 2 for all
PRECONDITIONING FOR DIFFUSION OF VELOCITIES : 2
PRECONDITIONING FOR PROPAGATION : 2
PRECONDITIONING FOR PPE : 2
PRECONDITIONING FOR DIFFUSION OF TRACERS : 2
PRECONDITIONING FOR DIFFUSION OF K-EPSILON : 2
/
/ BOUNDARY CONDITIONS
/------------------------------------------------------------------
/ Use Nikuradse roughness law - all others are not 3D compatible
LAW OF BOTTOM FRICTION : 5
LAW OF FRICTION ON LATERAL BOUNDARIES : 5  / for natural banks - 0 for symmetry
FRICTION COEFFICIENT FOR THE BOTTOM : 0.1 / 3 times d90 according to van Rijn
/
/ Liquid boundaries - avoid Thompson (invalid in 3d)
PRESCRIBED FLOWRATES  : 35.;35.
PRESCRIBED ELEVATIONS : 0.;371.33
/
/ INITIAL CONDITIONS
/ ------------------------------------------------------------------
INITIAL CONDITIONS : 'CONSTANT DEPTH' / or CONSTANT DEPTH see docs sec. 4.2
INITIAL DEPTH : 0.1
INITIAL GUESS FOR DEPTH : 1 / INTEGER for speeding up calculations
/
/ Other
/------------------------------------------------------------------
VELOCITY VERTICAL PROFILES : 2;2 / 0 (user-defined), 1 (Constant), 2 (Log)
VELOCITY PROFILES : 1;1 / horizontal profile
/
/------------------------------------------------------------------/
/			TIDAL FLATS
/------------------------------------------------------------------/
TIDAL FLATS : YES / default is YES - disable for faster model runs
/ TREATMENT OF NEGATIVE DEPTHS : 2 / requires mass lumping for depth set to 1
TREATMENT ON TIDAL FLATS FOR TRACERS : 1 / ensure conservation
/ more in section docs 6.6
/
/------------------------------------------------------------------/
/			TURBULENCE
/------------------------------------------------------------------/
/ in 3d use k-epsilon model, alternatively Spalart-Allmaras (5) or
/  Smagorinsky (4) for highly non-linear flow
HORIZONTAL TURBULENCE MODEL : 3
VERTICAL TURBULENCE MODEL : 3
MIXING LENGTH MODEL : 3 / telemac docs sec. 5.2.2
COEFFICIENT FOR HORIZONTAL DIFFUSION OF VELOCITIES : 1.E-6 / is default
COEFFICIENT FOR VERTICAL DIFFUSION OF VELOCITIES   : 1.E-6 / is default
/
/------------------------------------------------------------------/
/			PARALLELISM
/------------------------------------------------------------------/
PARALLEL PROCESSORS : 0 / default is 0 - all others define number of processors
/ PARTIONING TOOL : METIS / default is METIS, others are SCOTCH, PARMETIS, PTSCOTCH
/
/ ENABLE COMMAND PRINTS IN TERMINAL
&ETA

Computation Environment

The following descriptions refer to section 3 in the Telemac3d manual.

The computation environment defines a Title (e.g., TELEMAC 3D FLUME). The most important parameters involve the input files:

The output can be defined with the following keywords:

In addition, the MASS-BALANCE : YES setting will printout the mass fluxes and errors in the computation region, which is an important parameter for verifying the plausibility of the model.

General Parameters

The following descriptions refer to section 3.2 in the Telemac3d manual.

The General parameters specify time and location settings for the simulation:

Modify the time parameters to examine the effect in the simulation later.

Numerical Parameters

The following descriptions refer to section 6 in the Telemac3d manual.

This section defines internal numerical parameters for the Advection and Diffusion solvers.

In Telemac3d, it is recommended to use the so-called distributive predictor-corrector (PSI) scheme (read more at the BAW’s hydraulic engineering repository) with local implication for tidal flats (for velocity, tracers, and k-epsilon):

These values (5 for the scheme and 4 for the scheme option) are default values since v8p1, but it still makes sense to define these parameters for enabling backward compatibility of the steering file. If the occurrence of tidal flats can be excluded (note that already a little backwater upstream of a barrier can represent a tidal flat), the SCHEME OPTIONS can generally set to 2 for speeding up the simulation.

Similar to Advection, the above keywords can be used to define Diffusion steps (replace ADVECTION with DIFFUSION in the keywords), where a value of 0 can be used to override the default value of 1 and disable diffusion.

The SUPG OPTION (Streamline Upwind Petrov Galerkin) keyword controls whether upwinding applies and what type of upwinding is used. Since v9.0, this keyword takes a single integer (earlier versions accepted a four-element list; that form is no longer valid):

Read more in section 6.2.2 of the Telemac3d manual.

An additional option for speeding up is to enable mass lumping for diffusion, depth, and/or weak characteristics. Mass lumping results in faster convergence, but it introduces artificial dispersion in the results, which is why enabling mass lumping is discouraged by the TELEMAC developers. The provided steady3d.cas includes the keywords for mass lumping, though they are disabled through the / at the beginning of the line.

Implicitation parameters (IMPLICITATION FOR DEPTH and IMPLICITATION FOR VELOCITIES) should be set between 0.55 and 0.60 (default is 0.55 since v8p1) and control the degree of time-level weighting in the discretisation. IMPLICITATION FOR DIFFUSION is set to 1.0 by default. Read more in section 6.4 of the Telemac3d manual.

The parameter FREE SURFACE GRADIENT COMPATIBILITY can be used to increase model stability. Its default value is 1.0, but it can be reduced to 0.1 to suppress spurious oscillations in models with steep bathymetry gradients.

For river hydraulics, activating the non-hydrostatic pressure correction is recommended: NON-HYDROSTATIC VERSION : YES. This adds a pressure Poisson equation (PPE) solve at each time step, whose solver is controlled by SOLVER FOR PPE, OPTION OF SOLVER FOR PPE, ACCURACY FOR PPE, MAXIMUM NUMBER OF ITERATIONS FOR PPE, and PRECONDITIONING FOR PPE. The CAS file’s default solver (7, GMRES) and the accuracy target of 1.E-4 are appropriate for most river models. Read more about solver parameters in section 6.5 of the Telemac3d manual.

Vertical (3d) Parameters

The following descriptions refer to section 4.1 in the Telemac3d manual.

Telemac3d will add Horizontal levels (i.e., layers) that correspond to copies of the 2d-mesh to build a 3d-mesh of prisms (default) or tetrahedrons. These parameters can be defined with:

To get started with writing subroutines (it is no magic neither), have a look at the bottom_bc example (~/telemac/v9.0.0/examples/telemac3d/bottom_bc/). In particular, examine the user fortran file /user_fortran-source/user_mesh_transf.f and its call in the steering file t3d_bottom_source.cas through the definition of the FORTRAN FILE keyword and setting of MESH TRANSFORMATION : 2.

Open (Liquid) Boundaries

The following descriptions refer to section 4.2 in the Telemac3d manual.

Parameters for Boundary Conditions enable the definition of roughness laws and properties of liquid boundaries.

With respect to roughness, TELEMAC developers recommend using the Nikuradse (1933) roughness law in 3d (number 5), because all others are not meaningful or not integrally implemented in the 3d version. To apply the Nikuradse (1933) roughness law to the bottom and the boundaries use:

The liquid boundary definitions for PRESCRIBED FLOWRATES and PRESCRIBED ELEVATIONS correspond to the definitions of the downstream boundary edge in line 2 and the upstream boundary edge in line 3. From the boundary file, TELEMAC will understand the downstream boundary as edge number 1 (first list element) and the upstream boundary as edge number 2 (second list element). Hence:

The 0. value for the water does physically not make sense at the upstream boundary, but because they do not make sense, and because the boundary file (boundaries.cli) only defines (prescribes) a flow rate (by setting LIUBOR and LIVBOR to 5), TELEMAC will ignore the zero-water depth at the upstream boundary.

Instead of a list in the steering *.cas file, the liquid boundary conditions can also be defined with a liquid boundary condition file in ASCII text format. For this purpose, a LIQUID BOUNDARIES FILE or a STAGE-DISCHARGE CURVES FILE (sections 4.3.8 and 4.3.10 in the Telemac3d manual, respectively can be defined. The steady3d.cas file includes these keywords in the COMPUTATION ENVIRONMENT section, though they are disabled through the / character at the beginning of the line. A liquid boundary file (QSL) may look like this:

# t3d_canal.qsl
# time-dependent inflow upstream-discharge Q(2) and outflow downstream-depth SL(1)
T           Q(2)     SL(1)
s           m3/s     m
0.            0.     374.0
500.        100.     375.0
5000.       150.     575.7

With a prescribed flow rate, a horizontal and a vertical velocity profile can be prescribed for all liquid boundaries. With only a downstream and an upstream liquid boundary (in that order according to the above-defined boundary file), the velocity profile keywords are lists of two elements each, where the first entry refers to the downstream and the second element to upstream boundary edges:

Read more about options for defining velocity profiles in section 4.3.12 of the Telemac3d manual.

Initial Conditions

The initial conditions describe the condition at the beginning of the simulation. This tutorial uses a constant elevation (corresponding to a constant water depth) of 2., and enables using an initial guess for the water depth to speed up the simulation:

Turbulence

The following descriptions refer to section 5.2 in the Telemac3d manual.

The fundamental principles of turbulence and its application to the Navier-Stokes equations are explained in the steady Telemac2d tutorial. In 3d, TELEMAC developers recommend the k−ϵk-\epsilon model (3) for most river applications. The following model numbers are available for both HORIZONTAL TURBULENCE MODEL and VERTICAL TURBULENCE MODEL:

The steering file uses the k−ϵk-\epsilon model for both horizontal and vertical directions:

If VERTICAL TURBULENCE MODEL is set to 2 (mixing length), a MIXING LENGTH MODEL value can be assigned. Since v9.0, the default is 3 (Nezu & Nakagawa (1993), recommended for river flow). A value of 1 (Prandtl mixing length) remains available and is preferable for strongly tidal environments.

Run Telemac3d

Go to the configuration folder of the local TELEMAC installation (e.g., ~/telemac/v9.0.0/configs/) and launch the environment (e.g., pysource.openmpi.sh - use the same as for compiling TELEMAC).

cd ~/telemac/v9.0.0/configs
source pysource.openmpi.sh
If you are using the Hydro-Informatics (Hyfo) Mint VM

If you are working with the Mint Hyfo VM, load the TELEMAC environment as follows:

cd ~/telemac/v8p2/configs
source pysource.hyfo-dyn.sh

With the TELEMAC environment loaded, change to the directory where the above-created 3d-flume simulation lives (e.g., /home/telemac/v9.0.0/mysimulations/steady3d-tutorial/) and run the *.cas file by calling the telemac3d.py script.

cd ~/telemac/v9.0.0/mysimulations/steady3d-tutorial/
telemac3d.py steady3d.cas

As a result, a successful computation should end with the following lines (or similar) in Terminal:

[...]
                    *************************************
                    *    END OF MEMORY ORGANIZATION:    *
                    *************************************

CORRECT END OF RUN

ELAPSE TIME :
                            10  MINUTES
                            17  SECONDS
... merging separated result files

... handling result files
       moving: r3dsteady.slf
... deleting working dir

My work is done
References
  1. Nikuradse, J. (1933). Strömungsgesetze in rauhen Rohren [Laws of flow in rough pipes]. VDI Forschungsheft, Beilage Zu “Forschung Auf Dem Gebiete Des Ingenieurwesens,” Ausgabe B, Band 4(361), 26.
  2. van Rijn, L. C. (2019). Critical movement of large rocks in currents and waves. International Journal of Sediment Research, 34(4), 387–398. 10.1016/j.ijsrc.2018.12.005
  3. Spalart, P., & Allmaras, S. (1992). A one-equation turbulence model for aerodynamic flows. In 30th Aerospace Sciences Meeting and Exhibit (p. 22). American Institute of Aeronautics. 10.2514/6.1992-439
  4. Nezu, I., & Nakagawa, H. (1993). Turbulence in Open-Channel Flows (1st ed.). Routledge. 10.1201/9780203734902
Numerical Simulations
Unsteady 2d
Numerical Simulations
Gaia (Morphodynamics)