Steady 3d (SLF - Selafin)

Tutorial under construction

This tutorial is still growing and provides currently only rough guidance to constructing a 3d steady, hydrodynamic model with TELEMAC.

Requirements

This tutorial is designed for advanced beginners and before diving into this tutorial make sure to complete the TELEMAC pre-processing tutorial.

The case featured in this tutorial was established with the following software:

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-m\(^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/.

3d-steady simulation file repository

The simulation files used in this tutorial are available at https://github.com/hydro-informatics/telemac/tree/main/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).

View the steady3d steering file

To view the integration of the steady3d simulation keywords in the steering file, the steady3d.cas file can be downloaded here.

Steering File

This tutorial features a steady, hydrodynamic model with an inflow rate of 35 m\(^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).

Tip

To facilitate setting up the steering (CAS) file for this tutorial, download the template (right-click on the link > Save Link As… > navigate to the local tutorial folder), which contains more descriptions and options for simulation parameters.

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:

  • GEOMETRY FILE: qgismesh.slf - alternatively, select a serafin (SLF) geometry file

  • Boundary conditions file: boundaries.cli - with a SLF file, use a CLI boundary file

The output can be defined with the following keywords:

  • 3D RESULT FILE: r3dsteady.slf - can be either a MED file or a SLF file

  • 2D RESULT FILE: r2d3dsteady.slf - can be either a MED file or a SLF file

  • VARIABLES FOR 3D GRAPHIC PRINTOUTS: U,V,H,S,Q,F - many more options can be found in section 3.12 of the Telemac3d manual

  • VARIABLES FOR 2D GRAPHIC PRINTOUTS: U,V,H - many more options can be found in section 3.13 of the Telemac3d manual

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:

  • Location can be used for geo-referencing of outputs (not to set in this tutorial).

  • Time:

    • TIME STEP: 1.0 defines the time step as a multiple of graphic/listing printout periods.
      Use small enough and sufficient time steps to achieve/increase computational stability and increase to yield computational efficiency.

    • NUMBER OF TIME STEPS: 8000 defines the overall simulation length.
      Limit the number of time steps to a minimum (e.g., until equilibrium conditions are reached in a steady simulation).

    • GRAPHIC PRINTOUT PERIOD : 500 time step at which graphic variables are written,

    • LISTING PRINTOUT PERIOD: 500 time step multiplier at which listing variables are printed (in this example, listings are printed every 100 · 1 = 100 seconds)

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

Attention

Graphic printouts, just like all other data printouts, are time consuming and will slow down the simulation.

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):

  • Set the PSI scheme:

    • SCHEME FOR ADVECTION OF VELOCITIES: 5

    • SCHEME FOR ADVECTION OF K-EPSILON: 5

    • SCHEME FOR ADVECTION OF TRACERS: 5

  • Enable predictor-corrector with local implication:

    • SCHEME OPTION FOR ADVECTION OF VELOCITIES: 4

    • SCHEME OPTION FOR ADVECTION OF K-EPSILON: 4

    • SCHEME OPTION FOR ADVECTION OF TRACERS: 4

These values (5 for the scheme and 4 for the scheme option) are default values since TELEMAC 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 is a list of four integers that define if upwinding applies and what type of upwinding applies. The integers may take the following values:

  • 0 disables upwinding,

  • 1 enables upwinding with a classical SUPG scheme (recommended when the CFL condition is unknown), and

  • 2 enables upwinding with a modified SUPG scheme, where upwinding corresponds to the Courant number.

The default is SUPG OPTION : 1;0;1;1, where the first list element refers to flow velocity (default 1), the second to water depth (default 0), the third to tracers (default 1), and the last to the k-epsilon model (default 1). 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.

Implication parameters (IMPLICITATION FOR DEPTH and IMPLICITATION FOR VELOCITIES) should be set between 0.55 and 0.60 (default is 0.55 since TELEMAC v8p1) and can be considered as a degree of implicitation. 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 can be used for increasing the stability of a model. Its default value is 1.0, but it can be reduced to 0.1 to achieve stability.

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:

  • NUMBER OF HORIZONTAL LEVELS: 5 where the default and minimum is 2 and the horizontal levels point in upward vertical direction. The thickness of vertical layers results from the water depth, which can be user-defined through the INITIAL ELEVATION parameter (see the section on 3d initial conditions).

  • MESH TRANSFORMATION: 1 is the kind of level for the distribution (default is 1, a homogenous sigma distribution). For unsteady (quasi-steady) simulations, set this value to 2 (or 0 - calcot) and implement a ZSTAR array in a user Fortran file (USER_MESH_TRANSFORM subroutine).

  • ELEMENT: 'PRISM' (default) and prisms can optionally split into tetrahedrons by settings this parameter to 'TETRAHEDRON' (can potentially crash the simulation).

Unsteady (quasi-steady) simulations

For unsteady simulations (time-variable inflow/outflow rates), pre-define the thickness of vertical layers with the ZSTAR parameter in a user Fortran file (subroutine) as described in section 4.1 of the Telemac3d manual. Read more about setting up an unsteady simulation with TELEMAC in the Telemac2d unsteady tutorial.

To get started with writing subroutines (it is no magic neither), have a look at the bottom_bc example (~/telemac/v8p2/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.

In river analyses, the non-hydrostatic version of TELEMAC should be used through the following keyword: NON-HYDROSTATIC VERSION : YES.

Depending on the type of analysis, the solver-related parameters of SOLVER, SOLVER OPTIONS, MAXIMUM NUMBER OF ITERATION, ACCURACY, and PRECONDITIONING may be modified. The provided steady3d.cas includes solver keywords and comments for modifications, but the default options already provide a coherent a stable setup. Read more about solver parameters in section 6.5 of 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 [Nik33] roughness law in 3d (number 5), because all others are not meaningful or not integrally implemented in the 3d version. To apply the Nikuradse [Nik33] roughness law to the bottom and the boundaries use:

  • LAW OF BOTTOM FRICTION: 5

  • LAW OF FRICTION ON LATERAL BOUNDARIES: 5, which can well be applied to model natural banks, or set to 0 (no-slip) for symmetry.
    *Note that the boundary conditions file sets the LIUBOR and LIVBOR for the leftwall and rightwall boundary edges to zero, to enable friction.

  • FRICTION COEFFICIENT FOR THE BOTTOM: 0.1 corresponds to 3 times a hypothetical d90 (grain diameter of which 90% of the surface grain mixture are finer) according to [vR19].

  • FRICTION COEFFICIENT FOR LATERAL SOLID BOUNDARIES: 0.1 corresponds to 3 times a hypothetical d90, similar as for the bottom.

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 (see boundary definitions section). 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 list parameter PRESCRIBED FLOWRATES : 35.;35. assigns a flow rate of 35 m\(^3\)/s to the downstream and the upstream boundary edges.

  • The list parameter PRESCRIBED ELEVATIONS : 0.;371.33 assigns no elevation to the upstream boundary (number 1) and an elevation of 371.3 m a.s.l. to the downstream boundary (number 2). To recall how TELEMAC counts open boundaries read the comment box in the steady2d tutorial.

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

ELEVATION versus DEPTH

The ELEVATION parameter in the *.cas file denotes water depth, while the ELEVATION keyword in an external liquid boundary file (e.g. stage-discharge curve) refers to absolute (geodetic) elevation (Z plus H).

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:

  • VELOCITY PROFILES: 1;1 is the default option for the horizontal profiles. If set to 2;2, the velocity profiles will be read from the boundary condition file.

  • VELOCITY VERTICAL PROFILES: 2;2 sets the vertical velocity profiles to logarithmic. The default is 1;1 (constant). Alternatively, a user-defined USER_VEL_PROF_Z subroutine can be implemented in a Fortran file.

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:

  • INITIAL CONDITIONS: 'CONSTANT ELEVATION' can alternatively be set to 'CONSTANT DEPTH'

  • INITIAL DEPTH: 0.1 corresponds to water depth.

  • INITIAL GUESS FOR DEPTH: 1 must be an integer value and speeds up the calculation (convergence).

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 using either the \(k-\epsilon\) model (3) or the Spalart and Allmaras [SA92] model (5) in lieu of the mixing length model (2):

  • HORIZONTAL TURBULENCE MODEL: 3

  • VERTICAL TURBULENCE MODEL: 3

If the VERTICAL TURBULENCE MODEL is set to 2 ('MIXING LENGTH'), a MIXING LENGTH MODEL can be assigned. The default is 1, which is preferable for strong tidal influences and a value of 3 sets the length for computing vertical diffusivity to Nezu and Nakagawa [NN93].

Run Telemac3d

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

cd ~/telemac/v8p2/configs
source pysource.openmpi.sh

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

cd ~/telemac/v8p2/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