Steady 3d (MED and Salome)

Steady 3d (MED and Salome)#

About SALOME-HYDRO

This tutorial uses the SALOME-HYDRO software that is available at https://www.salome-platform.org/?page_id=318. This eBook does not feature the installation of SALOME-HYDRO and this tutorial is kept alive for the records, though rumor has it that SALOME-HYDRO will be essentially replaced by a QGIS plugin in the future.

telemac3d salome med results

This tutorial describes setting up and running a simple three-dimensional (3d) model of a flume based on the MED file library provided by salome-platform.org. The explanations build on the telemac3d user manual (v8p1) and more documentation can be found on opentelemac.org/doku.

Requirements

This tutorial is designed for advanced beginners and the case featured in this tutorial was established on Debian Linux (buster) with:

Download supplemental tutorial materials

All files created in this tutorial can be downloaded here (zip-download or clone the repository).

To explore example cases of Telemac3d, check out the TELEMAC installation folder, for instance, /telemac/v8p2/examples/telemac3d/.

SALOME-HYDRO#

With SALOME-HYDRO being installed in a directory called /home/salome-hydro/appli_V2_2/ (adapt according to the installation directory and version of SALOME-HYDRO), launch SALOME-HYDRO (give it a moment to start up):

/home/salome-hydro/appli_V2_2/salome

HYDRO Module#

Create Contours (Polyline)#

After starting SALOME-HYDRO, activate the HYDRO module, then find the Object Browser on the right side of the window and the POLYLINE folder symbol (Fig. 135).

telemac3d salome hydro start

Fig. 135 The empty viewport (OCC scene) of the HYDRO module.#

Right-click on the POLYLINE folder, select Create polyline and a popup window will open. In the popup window:

  • For Name enter: Contour

  • Click on the Insert new section button (Fig. 136)

telemac salome hydro polyline

Fig. 136 Create a new Polyline in SALOME-HYDRO.#

Define a new Polyline section (Fig. 137):

  • For Name enter: Section_1

  • For Type select Polyline

  • Ensure that the Closed box is checked

  • Press Add

telemac salome create polyline

Fig. 137 Add Polyline element.#

  • Click on the Addition mode button (Fig. 138) to draw a polygon: Start with the first point in the upper left corner and move in clock-wise direction to draw the other three points.

telemac salome hydro polygon addition

Fig. 138 Enable the Addition mode.#

  • The polygon should show up in the viewport as shown below (qualitative match with Fig. 139 is sufficient, but the drawing direction shown in Fig. 140)

telemac salome hydro polygon qualitative

Fig. 139 The final sketch of the Polyline.#

telemac salome hydro polygon qualitative

Fig. 140 The drawing direction of the Polyline.#

  • Press Apply and close

In the viewport, right-click on the polyline > Edit polyline (Fig. 141) and select Modification mode.

telemac salome hydro edit polygon

Fig. 141 The Edit polyline menu.#

In the popup window, modify the points so that a 500-m long and 100-m wide rectangle occurs as illustrated in Fig. 142 (the section Index numbers will change, so pay attention to not create crossing lines).

telemac salome hydro edit polygon modification

Fig. 142 Edit the X and the Y coordinates of the polylines.#

To get the data table (Section / Index) visible in the lower part of the popup window, highlight the four edges of the polygon in the viewport with the mouse. Figure 143 shows the finally edited polyline that now forms a rectangle.

telemac salome hydro edit polygon

Fig. 143 The finalized polyline.#

Save the project

Save the project by clicking on the File (top menu) > Save As… (Fig. 144). In the popup window (Fig. 145), select the simulation target folder and define a name such as flume3d. Press Save to save the project in HDF format and regularly press the save button (disk symbol) in the next steps to avoid losing work. Thus, the project can be saved, closed, and re-opened any time.

telemac salome hydro save study as hdf

Fig. 144 The Save As… menu for saving the project.#

telemac salome hydro save study hdf

Fig. 145 Navigate to a target directory and save the project.#

Create Natural Object#

From the HYDRO top menu, select Create immersible zone (Fig. 146) to define a wetted area for the later created mesh.

telemac salome hydro create immersible zone

Fig. 146 Initiate a Create immersible zone.#

In the popup window (Fig. 147), make the following settings:

  • Name: wetted_contour

  • Polyline: Select the previously created Contour rectangle (double-click in the field).

  • Bathymetry: Leave empty.

telemac salome hydro create wetted area zone

Fig. 147 Define the Create immersible zone.#

  • Press Apply and close.

Bottom elevations

A bathymetry file assigns bottom elevations to the geometry and can either be directly added in the HYDRO module or later with the STBTEL software that comes along with TELEMAC. Not providing a bathymetry file like in this tutorial will set the bottom level to zero.

Create Calculation Case#

One or more calculation cases can be created to define elements for the later simulation. Here, define one calculation case, by clicking on the HYDRO top-menu > Create calculation case. A popup window opens and guides through setting up the calculation case.

Step 1 (Fig. 148): Define the framework:

  • Name: Hydrodynamic

  • Limits: Contour

  • Mode: Select Manual.

  • Highlight wetted_contour and Contour in the Objects frame and press Include >> to add it to the list of Included objects.

  • Press Next > (button at the bottom)

telemac salome hydro contour create

Fig. 148 Create a calculation case.#

Step 2 (Fig. 149): Include >> wetted_contour_Outerand press Next >.

telemac salome hydro contour zone

Fig. 149 Include the polyline as wetted contour line.#

Step 3 (Fig. 150): Leave the boundary polygons window as-is and just click Next >

telemac salome hydro contour boundary

Fig. 150 The empty boundary polygon window (leave as-is).#

Step 4 (Fig. 151): Omit the definition of a Strickler [Str23] table and press Next >.

telemac salome hydro contour strickler

Fig. 151 Skip the definition of a Strickler table, which may be useful to define zones with different roughness attributes.#

Step 5 (Fig. 152): Finalize the calculation case creation by clicking on the Finish button.

telemac salome hydro calculation case

Fig. 152 Finalize the calculation case.#

Export the calculation case by right-clicking on the Hydrodynamic calculation case in the Object Browser, then Export calculation case (Fig. 153). As a result, a Geometry entry becomes visible in the Object Browser.

telemac salome hydro calculation case export menu

Fig. 153 Export the calculation case.#

Save the project

Save the project by clicking on the disk symbol.

GEOMETRY Module#

This section guides through the creation of a rectangular geometry surface representing a flume and its boundaries defined with edges (lines). To get ready, activate the Geometry module, right-click on HYDRO_Hydrodynamic_1, and select Show Only (Fig. 154).

telemac salome hydro calculation case exported geometry

Fig. 154 The Geometry module in the Object Browser.#

The Surface group in earlier versions of SALOME-HYDRO

Earlier versions of SALOME-HYDRO will also require to create a surface group, which already exists in this case with Hydrodynamic_Reg_1.

Right-click on HYDRO_Hydrodynamic_1 and select Create Group from the context menu. The four boundary edges of the surface will represent an upstream (inflow), a downstream (outflow), a left wall, and a right wall of the flume. To create the four boundary edges repeat the following steps for every edge (Fig. 155):

  • Shape Type (radio buttons in the upper part): select Edge (line symbol)

  • Name: upstream (then downstream, leftwall, and rightwall)

  • Main Shape: select HYDRO_Hydrodynamic_1

  • Click on Show all sub-shapes > Select line in the viewport. In the white frame of the Create Group window, make sure to select the good edge only. Add the correct edge and Remove all others.

telemac salome geometry group faces

Fig. 155 Define the upstream edge of the surface.#

  • For defining the other edges (downstream, leftwall, and rightwall), use the indications in Fig. 156.

telemac salome rectangular flume

Fig. 156 Boundaries of the rectangular flume.#

  • Click Apply to create the edge boundary and proceed with the next. After the last (fourth) edge, click Apply and Close.

Ultimately, the Geometry block in the Object Browser should look as shown in Fig. 157.

telemac salome geometry group object browser

Fig. 157 The created groups in the object browser.#

Mesh Module#

To work with the geometry in a numerical model, the geometry needs to be defined as a triangular computational mesh that Telemac3d will extrapolate to a tetrahedral mesh. The Mesh module in SALOME-HYDRO enables the creation of a mesh with just a view clicks. The mesh is generated first for the surface (2d), then for every boundary edge (1d), and eventually computed and verified. To get ready, activate the Mesh module from the top menu.

Two-dimensional (2d) Mesh of the Flume#

Highlight HYDRO_Hydrodynamic_1 in the Object Browser. Then, go to the Mesh top menu (do not confuse with the Mesh module), and select Create Mesh (Fig. 158).

telemac salome mesh create

Fig. 158 The Create Mesh menu in SALOME-HYDRO.#

In the Create mesh popup window set the following:

  • Name: Mesh_Hn_1

  • Geometry: HYDRO_Hydrodynamic_1

  • Leave the Mesh type as Any

  • In the 2D tab:

    • Choose Netgen 1D-2D for Algorithm

    • Find the cogwheel symbol behind the Hypothesis field and click on it to construct hypotheses for Netgen 2D Parameters.

    • In the Hypothesis Construction popup window (Fig. 159):

      • Define Name as NETGEN 2D Parameters 10_30

      • Set Max. Size to 30

      • Set Min. Size to 10

      • Set Fineness to Very Fine,

      • Leave all other field’s default values and click OK.

  • Back in the Create mesh window (Fig. 160), set the just created NETGEN 2D Parameters 10_30 as Hypothesis.

  • Click on Apply and Close (Create mesh popup window)

telemac salome mesh create netgen 2d hypothesis

Fig. 159 Construct NETGEN 2D Hypothesis.#

telemac salome mesh create netgen 1d-2d

Fig. 160 The Create Mesh menu with define hypothesis.#

One-dimensional (1d) Meshes of Boundary Edges#

The 1d meshes of the boundary edges will represent sub-meshes of the 2d mesh. To create the sub-meshes, highlight the previously created Mesh_Hn_1 in the Object Browser (click on it), then go to the Mesh top menu and select Create Sub-Mesh (Fig. 161).

telemac salome mesh create

Fig. 161 The Create Sub-mesh menu.#

In the Create sub-mesh popup window, start with creating the upstream boundary edge’s mesh:

  • Name: upstream

  • Mesh: Mesh_Hn_1

  • Leave the Mesh type as Any

  • In the 1D tab:

    • Choose Wire Discretisation for Algorithm

    • Find the cogwheel symbol behind the Hypothesis field and click on it to construct hypotheses for Number of Segments.

    • In the Hypothesis Construction popup window (Fig. 162):

      • Define Name as Segments_10

      • Set Number of Segments to 10

      • Set Type of distribution to Equidistant distribution.

  • Back in the Create Mesh window (Fig. 163), set the just created Segments10 as Hypothesis.

  • Click on Apply in the Create sub-mesh popup window, which will remain open for the definition of the three other boundary edge’s meshes.

telemac salome submesh create number of segments hypothesis

Fig. 162 Construct Segment hypothesis.#

telemac salome submesh create wire discretisation

Fig. 163 Assign a wire discretisation to the submesh.#

Repeat the above steps for creating sub-meshes for the downstream, left wall, and right wall edges, but with different construction hypotheses.

  • For the downstream sub-mesh use Name downstream and construct the following hypothesis (Fig. 164):

    • Type: Number of Segments

    • Define Name as Segments_05

    • Set Number of Segments to 5

    • Set Type of distribution to Equidistant distribution.

  • For the left wall sub-mesh (Fig. 165) use Name leftwall and construct the following hypothesis:

    • Type: Arithmetic Progression 1D

    • Define Name as Arithmetic1d10_30

    • Set Start length to 10

    • Set End length to 30.

telemac salome submesh create arithmetic progression hypothesis

Fig. 164 Construct an Arithmetic hypothesis.#

telemac salome submesh create wire discretisation arithmetic

Fig. 165 Assign the wire discretisation algorithm and the arithmetic hypothesis.#

  • For the right wall sub-mesh use Name rightwall and construct the following hypothesis:

    • Type: Arithmetic Progression 1D

    • Define Name as Arithmetic1d15_10

    • Set Start length to 15

    • Set End length to 10.

To this end, the Object Browser should include the 5 hypotheses and the non-computed meshes (warning triangles in the below figure indicating the Compute menu).

Save the project

Save the project by clicking on the disk symbol.

If a Define Order warning pops up…

If info or warning windows pops up and asks for defining the order to apply, that means the geometry groups contain too many elements. In this case, go back to the geometry creation and make sure that always only one element is added per group. For more complex models, the order of mesh hypotheses may not be an error, but in this simple case it must not appear being an issue.

Compute Mesh#

In the Object Browser, extend (un-collapse) the new Mesh block, right-click on Mesh_Hn_1, and select Compute (Fig. 166).

telemac salome compute mesh menu

Fig. 166 The Compute entry in the Mesh context menu (object browser).#

This will automatically also compute all sub-meshes. After the successful computation of the mesh, SALOME-HYDRO informs about the mesh properties in a popup window (Fig. 167).

smesh compute netgen 2d 3d

Fig. 167 Illustration of a successful mesh computation (numbers of elements, nodes, edges, faces, and volumes may slightly vary).#

In the viewport (VTK scene tab in Fig. 168), find the -OZ button to switch to plane view. If the mesh is not visible even though the computation was successful, right-click on the mesh in the Object Browser and click on Show.

smesh show only

Fig. 168 The computed mesh in the VTK scene viewport.#

Verify Mesh#

Orientation of faces and volumes

This step will ensure that the mesh is correctly oriented for the simulation with Telemac3d. In the Object Browser, highlight Mesh_Hn_1 and then go to the Modification top menu > Orientation. In the popup window (Fig. 169), check the Apply to all box. Click the Apply and close button. The mesh should have changed from darker blue to a lighter tone of blue (if the inverse is the case, repeat the application of the orientation tool).

mesh modification orientation

Fig. 169 The Modification of orientation window.#

Identify and reconcile over-constraint elements

In the Object Browser, highlight Mesh_Hn_1. Then go to the Controls top menu > Face Controls > Over-constraint faces. Over-constrained triangles in the Mesh_Hn_1 will turn red in the viewport (VTK scene:1) and at the bottom of the viewport, the note Over-constrained faces: 3 will appear (Fig. 170).

mesh over constrained constraint faces

Fig. 170 Overconstrained faces (red elements) highlighted in the viewport.#

To reconcile the edge cause the triangle’s over-constrain, go to the Modification top menu > Diagonal inversion (Fig. 171), and select the internal edge of the concerned triangles.

mesh over-constrained diagonal inversion internal edges triangle

Fig. 171 Define edges between neighboring triangles to reconcile by diagonal inversion.#

Over-constrained triangles might be hidden by the axes arrows in the corner. Thus, pay attention to sufficiently zoom into the corner (Fig. 172) unless the Over-constrained faces notification in the viewport shows 0.

mesh over-constrained diagonal inversion hidden edges faces

Fig. 172 Zoom into the axis corners to view slightly hidden triangles for diagonal inversion.#

Save the project

Save the project by clicking on the disk symbol.

Export MED File#

Exporting the mesh to a MED file requires the definition of mesh groups. To do so, highlight Mesh_Hn_1 in the object browser and right-click on it. Select Create Groups from Geometry from the mesh context menu (Fig. 173).

mesh export create groups context menu

Fig. 173 Select the Create Groups from Geometry in the Mesh context menu.#

In the popup window, select all groups and sub shapes of the FLUME geometry and all groups of mesh elements and mesh nodes. For selecting multiple geometries, hold down the CTRL (Strg) and Shift keys on the keyboard and select the geometry/mesh groups. The tool will automatically add all nodes selected (Fig. 174). Press Apply and close to finalize the creation of groups.

mesh export create groups select

Fig. 174 Select geometry elements to create groups.#

Verify the created groups by right-clicking on the top of the project tree in the Object Browser and selecting Show only with the option Auto Color (Fig. 175).

mesh export create groups final control

Fig. 175 Make sure that the Mesh in the object browser contains Groups of Nodes, Edges, and Faces.#

Unique elements only

Make sure that every group element is unique within every group. If an element appears twice in one group, the next step (export mesh) will through a warning message about double-defined group elements, which will lead to an error later.

If the groups seems correct (see above figure), export them with File (top menu) > Export > MED (Fig. 176).

mesh export med context menu

Fig. 176 The Export mesh to MED file context menu.#

In the Export mesh popup window (Fig. 177), define:

  • File name Mesh_Hn_1 (or whatever you prefer)

  • Files of type MED 4.1 files
    Note: The installation of TELEMAC described in the TELEMAC installation chapter requires to use MED 3.2 files.

  • Choose a convenient directory (Quick path) for saving the MED file

  • Leave all other default settings.

  • Click on Save to save the MED file.

telemac salome save med file

Fig. 177 The Export mesh popup window.#

Save the project

Save the project by clicking on the disk symbol.

Boundary Conditions#

Basic Setup with the HydroSolver Module#

Activate the HydroSolver module from the top menu and click on the Edit boundary conditions file button to create a new boundary condition file (Fig. 178).

telemac salome hydrosolver create edit boundary conditions menu

Fig. 178 The Edit boundary conditions file button in the HydroSolver module.#

In the opening popup window, select the just exported MED file containing the mesh and leave the Boundary conditions file field in the Input files frame free. In the Output files frame, click on … and define a boundary conditions file (e.g., flume3d_bc.bnd).

Put all files in 1 folder

Make sure that all model files (MED, BND, and others such as the later defined *.cas file) are all located in the same folder.

Make the following definitions in the Boundary conditions frame (Fig. 179):

  • Group Hydrodynamic_wetted_contour_Outer: Set Preset to Custom and all values to 0

  • Group downstream: Set Preset to Prescribed H / free T

  • Group leftwall: Set Preset to Closed boundaries/walls

  • Group rightwall: Set Preset to Closed boundaries/walls

  • Group upstream: Set Preset to Prescribed Q / free T

telemac salome hydrosolver create edit boundary conditions

Fig. 179 Define wall and liquid boundary conditions in the BND file.#

Then click on Apply and Close.

Modify the Boundary File#

The boundary file created with the HydroSolver involves a couple of issues that need to be resolved to enable TELEMAC assigning the correct boundary conditions. For this purpose, open the boundary condition file in a text editor (e.g., on Xfce desktop use right-click > mousepad) and make the following adaptations.

  • Only 4 edge boundaries are needed:

    • Set the single number in the first line to 4

    • Remove the entire line (2) describing Group Hydrodynamic_wetted_contour_Outer

  • To enable the coherent use of flow rates for liquid boundaries, make sure that:

    • Line 2 defines LIHBOR with 5 (prescribed depth), LIUBOR and LIVBOR with 4 (free velocity), and LITBOR with 4 (free tracer) for the downstream boundary edge.

    • Line 3 defines LIHBOR with 4 (free depth), LIUBOR and LIVBOR with 5 (prescribed flow rate), and LITBOR with 4 (free tracer) for the upstream boundary edge. Note that the line needs to be copied from the bottom to the top when using the bnd file created with the HydroSolver module.

  • Assign wall friction (i.e., zero velocities) to the left and right wall edges:

    • In Line 4, set LIUBOR and LIVBOR to 0 (zero U and V velocities, respectively) for the leftwall boundary edge.

    • In Line 5, set LIUBOR and LIVBOR to 0 (zero U and V velocities, respectively) for the rightwall boundary edge.

The boundary file should now resemble the block below (can also be downloaded here). Save and close the *.bnd file. The below-shown box also shows how the boundary file should look like.

4
5 4 4 4 downstream
4 5 5 4 upstream
2 0 0 2 leftwall
2 0 0 2 rightwall

Boundary condition files for SLF geometries

SLF geometry files require more complex (node-wise) definitions of boundaries, which need to be setup with Blue Kenue and Fudaa-PrePro.

Simulation Steering Case File (CAS)#

The steering (*.cas) file is the control (or steering) file for any TELEMAC simulation and links all model parameters. This section guides through setting up a simple *.cas file for Telemac3d simulations either manually based on a template or with the HydroSolver module in SALOME-HYDRO. Because of program instabilities and incoherent linking of file names (directories) in SALOME-HYDRO, it is recommended to work with the manual CAS file setup (or with Fudaa PrePro).

Tip

Copy a sample case from the TELEMAC folder (/telemac/v8p2/examples/telemac3d/) and edit it for convenience.

Windows

The *.cas file can also be edited/created with Fudaa PrePro) - or any text editor software - for use with Salome-Hydro on a Linux system later.

Computation Environment#

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

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

  • Geometry file format: MED - omit this parameter when use a SLF geometry file

  • Boundary conditions file: flume3d_bc.bnd - with a SLF file, use a CLI boundary file

The output can be defined with the following keywords:

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

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

  • 3D RESULT FILE FORMAT: 'MED' - can be omitted when using SLF output files

  • 2D RESULT FILE FORMAT: 'MED' - can be omitted when using SLF output files

  • VARIABLES FOR 3D GRAPHIC PRINTOUTS: Z,U,V,W - 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 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: 5000 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 : 100 time step at which graphic variables are written (in this example 5000 / (100 · 1.0) = 50 graphic printouts will be produced, i.e., every 100 · 1.0 = 100 seconds)

    • LISTING PRINTOUT PERIOD: 100 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.

Vertical (3d) Parameters#

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 initial conditions).

  • MESH TRANSFORMATION: 1 is the kind of level for the distribution (default is 1, a homogenous sigma distribution). For unsteady 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).

Tip

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.

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.

Numerical Parameters#

This section defines internal numerical parameters for the Advection and Diffusion solvers, which are also sometimes listed in the hydrodynamic parameters section in the Telemac3d manual.

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 t3d_template.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.

Hydrodynamic Parameters#

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 t3d_template.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 : 50.;50. assigns a flow rate of 50 m\(^3\)/s to the downstream and the upstream boundary edges.

  • The list parameter PRESCRIBED ELEVATIONS : 2.;0. assigns an elevation (i.e., water depth) of two m to the downstream boundary and a water depth of 0.0 m to the upstream boundary.

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 (flume3d_bc.bnd) 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 t3d_template.cas steering 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.     5.0
500.        100.     5.0
5000.       150.     5.0

Tip

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.

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 for Telemac 3d (med)

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

  • INITIAL ELEVATION: 50. corresponds to depth here, but would be different in an external liquid boundary file (see above).

  • INITIAL DEPTH: 2. is not used in this tutorial.

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

Tip

In this scenario, INITIAL ELEVATION: 50 makes that the computational mesh is 50 m high, which makes sense in the context of a 100-m wide and 500-m long flume. However, this setting requires careful revision in other cases.

Read more about the initial conditions in section 4.2 of the Telemac3d manual.

Turbulence#

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].

Read more about turbulence in TELEMAC in section 5.2 and the mixing length in section 5.2.2 of the Telemac3d manual.

HydroSolver CAS File Setup (Unstable)#

Tip

Skip this section if you already set up the CAS file manually.

A *.cas file can be created with the HydroSolver module in SALOME-HYDRO as follows:

  1. Go to the Hydro top menu > Edit cas file (English) and a popup window along with a new frame will open. The popup window will ask for the version of TELEMAC (i.e., the solver) to use. Select Telemac3d and clock Ok.

  2. In the new frame (Eficas Telemac viewport), go to File > New for creating a new *.cas (case or French cas).

  3. Save the new *.cas file (e.g., flume3d-steady.cas) in the same directory where all other simulation files live.

telemac salome hydro hydrosolver new cas file save as

A new unnamed file1 case is created and opens up in the Computation environment frame. To make sure that no information will be lost, save the *.cas file regularly. The HydroSolver module guides through parameter definitions as above shown (starting with the COMPUTATION_ENVIRONMENT block), with built-in explanations on the sidebar.

Attention

After finalizing the *.cas file with HydroSolver, open the *.cas file in a text editor and make sure that all parameters are coherently defined as described above. In particular, pay attention to the non-use of file directories.

Run Simulation (Compute)#

Stand-alone TELEMAC installation#

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/modelling/flume3d-tutorial/) and run the *.cas file by calling the telemac3d.py script.

cd ~/modelling/flume3d-tutorial/
telemac3d.py flume3d.cas

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

[...]
BOUNDARY FLUXES FOR WATER IN M3/S ( >0 : ENTERING )
FLUX BOUNDARY      1                          :    -49.85411
FLUX BOUNDARY      2                          :     50.00000
--------------------------------------------------------------------------------
                FINAL MASS BALANCE
T =        5000.0000

--- WATER ---
INITIAL MASS                        :     2500000.
FINAL MASS                          :     100343.0
MASS LEAVING THE DOMAIN (OR SOURCE) :     2384217.
MASS LOSS                           :     15440.06

 END OF TIME LOOP

 EXITING MPI
                     *************************************STOP 0
                     *    END OF MEMORY ORGANIZATION:    *
                     *************************************

 CORRECT END OF RUN

 ELAPSE TIME :
                             44  SECONDS
... merging separated result files

... handling result files
        moving: r3d_canal-t3d.med
        moving: r2d3d_canal-t3d.med
... deleting working dir

My work is done

Thus, Telemac3d produced the files r3d_canal-t3d.med and r2d3d_canal-t3d.med, which can now be analyzed in the post-processing with SALOME.

SALOME-HYDRO & HydroSolver#

Warning

On newer systems (e.g., Debian 10), it is highly likely, that the local libraries are newer than the ones used for compiling TELEMAC in the SALOME-HYDRO environment. Thus, simulations may fail, for example when SALOME-HYDRO tries to communicate with the local openmpi libraries. For this reason, it is recommended to use a TELEMAC stand-alone installation for running simulations.

If the new PYTEL case is not showing up in the Object Browser, save the project (e.g., tetrahedral_3d.hdf), close, and restart SALOME-HYDRO. Re-open the project HDF file and re-activate the HydroSolver module.

  • In the Object Browser, click on tetrahedral_steering (highlights in blue).

  • With the steering file highlighted, find the Edit Pytel case for execution button in the menu bar and click on it.

  • Enable the PYTEL radio button

  • In the Object Browser, right-click on HydroSolver and click Refresh. An EXE sign next to tetrahedral steering should show up*.

  • Right-click on the new EXE tetrahedral steering item in the Object Browser, then click on Compute

Post-Processing with SALOME and ParaVis#

Go to the installation folder where SALOME is installed (e.g., /home/SALOME-9.6.0/) and launch SALOME (recall the installation instructions for SALOME - different from SALOME-HYDRO).

cd ~/SALOME-9.6.0/
source env_launch.sh
./salome

Once SALOME opened up, activate the ParaVis module from the top menu.

Why SALOME and not SALOME-HYDRO?

In theory, also SALOME-HYDRO does the job, but the ParaVis module may run unstable here. Moreover, ParaView can handle similar data formats, but the default installation of ParaView cannot handle MED files. For these reasons, working with the latest official SALOME release is the best option to post-process MED files.

Both the 3d (r3d_canal-t3d.med) and 2d (r2d3d_canal-t3d.med) results files can be loaded the same way and data export works similarly. Thus, the following sections illustrate loading and extracting data from the 3d (r3d_canal-t3d.med) results file only.

Load Results (MED file)#

To open a results (or any other) MED file, right-click on the builtin: symbol in the Pipeline Browser on the top-left of the window and select Open (Fig. 180).

telemac salome open med file pipelinebrowser

Fig. 180 The Open entry in the context menu of the builtin: element in ParaVis’ Pipeline Browser.#

In the popup window (Fig. 181), use the frames on the left to navigate to the folder where the simulation and its results live. Select r3d_canal-t3d.med and click OK.

telemac salome open 3d med file

Fig. 181 Select the results MED file in the Open File window.#

The file r3d_canal-t3d.med appears in the Pipeline Browser (Fig. 182). Click on the green Apply button in the Properties tab.

telemac salome apply 3d med file

Fig. 182 The results MED file in the Pipeline Browser and the Apply button.#

The model block (i.e., the flume, or channel - French: canal) becomes visible in the viewport. Click on the block in the viewport (left mouse button), hold down and move the mouse to get an impression of the flume. To visualize the results, find the variable drop-down menu in the upper part of the window (initially shows Solid Color), and select VELOCITY U (Fig. 183).

telemac salome load results velocity

Fig. 183 Load the VELOCITY U data in ParaVis.#

Click on the Play > button (top-right of the window, indicated by the mouse cursor in Fig. 184) to animate the results illustration to the last time step (50 - which is the result of 5000 times steps divided by the graphical printout period of 100).

telemac salome visualize results

Fig. 184 The VELOCITY U parameter at the final time step plotted in the ParaView scene.#

Set the visualization to Surface with Edges (instead of Surface), next to the VELOCITY U drop-down menu, and export the current visualization by click on the Capture screenshot … button in the viewport (Fig. 185).

telemac salome save screenshot surface with edges

Fig. 185 Make a screenshot of the ParaView scene showing the VELOCITY U visualization and the 3d mesh.#

Export Data#

To export data from a results file, go to File > *Save Data… (Fig. 186).

telemac3d salome save export data

Fig. 186 The Save Data… entry in ParaVis’ File menu.#

In the popup window (Fig. 187) define a file name and ending, which can be either CSV (including *.tsv) or txt. The selected ending will call the appropriate assistant to define export details. In this example, use CSV by typing flume3d-export.csv.

telemac3d salome save export data csv paravis

Fig. 187 Export the model results to a CSV file.#

After clicking OK, the Configure Writer (CSVWriter) window (Fig. 188) opens. Select relevant data (e.g., U, V, W, and Z) by checking the Choose Arrays to Write box and enable Add Time. Click OK to finalize the data export.

telemac3d salome export data csv paravis configure

Fig. 188 Configure the CSV Writer for exporting relevant data such as ELEVATION Z and 3d VELOCITY (U, V, and W).#

Figure 189 shows an example for an exported CSV file.

telemac3d salome exported data csv file

Fig. 189 An example of an exported CSV file containing timesteps, elevation, point coordinates, and 3d velocities.#

Recall that many other variables can be exported by defining them in the *.cas file as above described in the computational environment. A full list of 2d and 3d output parameters in available sections 3.13 and 3.12, respectively, of the Telemac3d docs.

Discover more ParaVis Filters

There is much more to discover in ParaVis. For instance, apply Filters (right-click on r3d_canal-t3d.med in the Pipeline Browser and go to Add Filter) to extract particular data at particular sections.