Friction (Roughness) Zones

Contributors

This chapter was co-written and developed by Federica Scolari Federica Scolari and Sebastian Schwindt Sebastian Schwindt.

Friction (Roughness) Zones#

Similar to the assignment of multiple friction coefficient values to multiple model regions featured in the BASEMENT tutorial, Telemac2d provides routines for domain-wise (i.e., zonal) friction area definitions in the geometry (.slf) mesh file. Specifically, if the study domain is characterized by regions of different roughness, it is not sufficient to define global friction through a FRICTION COEFFICIENT keyword in the steering (.cas) file. Defining roughness zones in the mesh (.slf) file requires an additional layer called BOTTOM FRICTION or FRIC_ID on top of the BOTTOM elevation. To this end, roughness values can be defined in a roughness .xyz file created with QGIS (recommended) or Closed Lines .i2s created with BlueKenue (see the meshing section). While QGIS is recommended to delineate roughness zones with correct and possibly precise georeferences, BlueKenue is still required for interpolating the roughness from the .xyz or .i2s file on the .slf file in the last step.

Requirements

Alternative: Draw Friction Zones in BlueKenue#

This procedure is an imprecise alternative to the above-described roughness.xyz creation because of BlueKenue’s weak geospatial referencing capacities, which is why the below instruction box is only provided for completeness.

Zonal Friction Mesh (BlueKenue)#

This section walks through the interpolation of friction values on an existing selafin (.slf) geometry file. The showcase builds on the .slf file created in the Telemac pre-processing tutorial (download qgismesh.slf). Start with opening BlueKenue and open the selafin .slf file: click on File > Open… > navigate to the directory where the .slf is stored, make sure to select Telemac Selafin File (*.slf), highlight qgismesh.slf, and press Open. Pull the BOTTOM (BOTTOM) layer from the workspace data items to Views > 2D View (1) to verify and visualize the correct import of the mesh (Fig. 215).

BlueKenue 2dmesh interpolated elevation

Fig. 215 The showcase qgismesh.slf selafin file opened in BlueKenue.#

Import Friction Zones#

As an alternative to the creation of zonal friction values stored in a .xyz file generated with QGIS, zones can also be directly drawn in BlueKenue through a series of Closed lines. However, because of BlueKenue’s very limited capacities to deal with geospatial references and coordinate systems (CRSs), the preferable option for creating friction zone input is the above-featured application of QGIS.

To open the above-created .xyz file in BlueKenue:

  • click on File > Open…

  • navigate to the project folder where the .xyz is stored

  • make sure to select All Files (*.*) next to the File name: field

  • highlight qgismesh.slf, and press Open.

bluekenue roughness friction visualize coefficients

Fig. 216 Assign a friction (roughness) value (here: a Strickler roughness of 50) to the delineated area by the closed line.#

Ignore the warning message (click OK). To verify and visualize the imported friction values right-click on the friction-pts (X) layer > Properties > go to the Data tab > select Z(double), press Apply. Then, go to the ColourScale tab, press Reset, Apply, and OK.

Verify the correct representation of the friction values by pulling the friction-pts (Z) layer from the workspace data items to Views > 2D View (1) (Fig. 217).

friction roughness coefficients bluekenue

Fig. 217 The imported friction-pts.xyz file (created with QGIS) visualized in BlueKenue.#

If not yet done, import the Closed lines delineating roughness zones in the form of .i2s / .i3s files.

Interpolate Friction on the Mesh#

In BlueKenue, go to File > New > 2D Interpolator, which will occur in the Work Space > Data Items. Drag & drop either the friction-pts .xyz points or the Closed line objects delineating roughness zones on the new 2D Interpolator (see Fig. 218).

bluekenue 2d interpolator roughness friction

Fig. 218 Drag & drop the friction-pts (or closed lines) on a new 2D Interpolator in BlueKenue.#

Next, add a new variable to the qgismesh.slf mesh by highlighting the Selafin qgismesh object (in Work Space > Data Items), and right-clicking on it. Click on Add Variable… and enter the following in the popup window (Fig. 219 or Fig. 220), depending on if you are working with friction values (as showcased here with Strickler roughness), or friction IDs (see below):

selafin add variable bluekenue roughness friction

Fig. 219 Add a new Variable to the Selafin object for direct friction values.#

  • Mesh: BOTTOM

  • Name: BOTTOM FRICTION (this example)

  • Units: keep clear (irrelevant field)

  • Default Node Value: 30 (in this example) for a default (Strickler) value to use when no xyz friction points can be found in the vicinity of a mesh node

selafin add variable bluekenue roughness friction

Fig. 220 Add a new Variable to the Selafin object for friction IDs.#

  • Mesh: BOTTOM

  • Name: FRIC_ID (must be entered, cannot be selected from list)

  • Units: keep clear (irrelevant field)

  • Default Node Value: 0 (ID to use when no xyz points can be found in the vicinity of a mesh node)

To interpolate the friction values on the mesh, highlight the new variable variable BOTTOM FRICTION (or FRIC_ID) of the qgismesh object in Work Space > Data Items. The Anonymous Attribute of the new variable can be ignored. To map the new variable onto the mesh:

  • Highlight the new BOTTOM FRICTION (or FRIC_ID) mesh variable (in Data Items)

  • Go to Tools > Map Object… (top menu in Fig. 221)

  • Select the new 2D Interpolator, and click OK, which opens the Processing… popup window

  • After the processing is completed, click OK.

map object 2dinterpolator roughness friction bluekenue

Fig. 221 Map the friction value on the new 2D Interpolator in BlueKenue.#

bottom friction colourscale selafin bluekenue

Fig. 222 Adjust the color scale for BOTTOM FRICTION.#

Verify the correct interpolation:

  • Define a relevant color scale:

    • In Work Space > Data Items > qgismesh, right-click on the new BOTTOM FRICTION variable > Properties.

    • In the properties, go to the ColourScale tab, and use, for example, a Linear scale with 10 Levels, a Min of 22, and an Interval of 1.8. The exemplary minima and interval are good choices for the showcase, but other settings might be preferable for other applications (e.g., prefer Min of 0 when using Manning’s \(n_m\)).

    • Press Apply > OK.

  • Drag & drop the BOTTOM FRICTION variable into Views > 2D View (1) to verify the correct interpolation of friction values (e.g., see Fig. 223 for the showcase).

selfin slf mesh bottom friction bluekenue

Fig. 223 The correctly interpolated new BOTTOM FRICTION variable of the qgismesh.slf mesh.#

To save the selafin mesh with interpolated the interpolated friction values, right-click on the qgismesh selafin object > Properties > go to the Meta Data tab, and enter a new Name, for example, qgismesh-friction. Next, highlight the selafin object (e.g., qgismesh-friction) and click on the disk ../../_images/bk-sym-save.png symbol. If renaming did no take effect on the file name, confirm replacing the existing file.

Download qgismesh-friction.slf (with BOTTOM FRICTION)

Download the updated qgismesh-friction.slf with BOTTOM FRICTION.

Telemac Bindings#

Implementation in the CAS File#

Friction Keywords#

The updated qgismesh-friction.slf mesh can be used just like in the steady 2d tutorial, but some keywords need to be modified, even though the BOTTOM FRICTION values assigned in the .slf mesh automatically overwrite the global FRICTION COEFFICIENT keyword in the .cas steering file. However, we need to make Telemac recognize the newly defined BOTTOM FRICTION zones as Strickler roughness type. To this end, change the LAW OF BOTTOM FRICTION to 3 (instead of 4 pointing to Manning’s \(n_m\)), and set the default FRICTION COEFFICIENT to 33 (inverse of \(n_m\) = 0.03). The definition of the FRICTION COEFFICIENT is for coherence and is not strictly needed as it will be overwritten by the BOTTOM FRICTION from the .slf mesh.

/ steady2d-zonal-ks.cas steering file
/ ...
/ Friction at the bed
LAW OF BOTTOM FRICTION : 3 / 3-Strickler
FRICTION COEFFICIENT : 33  / will be overwritten by zonal friction values

/ steady2d.cas steering file
/ ...
/ Friction at the bed
LAW OF BOTTOM FRICTION : 4  / 4-Manning
FRICTION COEFFICIENT : 0.03 / Roughness coefficient

Add the letter W to the graphic printouts for writing the friction coefficient to the results file:

/ steady2d-zonal-ks.cas steering file
/ ...
VARIABLES FOR GRAPHIC PRINTOUTS : 'U,V,H,S,Q,W' / add W for friction coefficient

Do you have more than 10 different friction zones?

To increase the number of friction zones recognized by Telemac, set the MAXIMUM NUMBER OF FRICTION DOMAINS keyword, for example, to 20:

/ steady2d-zonal-ks.cas steering file
/ ...
MAXIMUM NUMBER OF FRICTION DOMAINS : 20 / default is 10

Initial Hotstart Conditions (optional)#

The following descriptions refer to section 4.1.3 in the Telemac2d manual.

To speed up the simulation, this tutorial re-uses the output of the steady 2d simulation (though, re-created with a printout period of 2500 steps). This type of model initialization is also called hotstart, here, based on the steady results file r2dsteady-t15k.slf, which needs to be defined as PREVIOUS COMPUTATION FILE:

/ steady2d-zonal-ks.cas steering file
/ ...
COMPUTATION CONTINUED : YES
PREVIOUS COMPUTATION FILE : r2dsteady-t15k.slf / results of 35 CMS steady simulation after 15000 timesteps

With the hotstart conditions, the boundaries can be eased to:

/ steady2d-zonal-ks.cas steering file
/ ...
/ Liquid boundaries
PRESCRIBED FLOWRATES  : 35.; 0.
PRESCRIBED ELEVATIONS : 0.; 371.33

For these boundary conditions to take effect, the liquid boundaries file from the steady 2d simulation must be modified:

Finally, comment out any initial conditions keywords in the .cas steering file, for instance:

/ steady2d-zonal-ks.cas steering file
/ ...
/ INITIAL CONDITIONS : 'ZERO DEPTH'
/ INITIAL DEPTH : 0.005

Run Friction Zone Simulation#

Make sure all required files are placed in a simulation folder (e.g., /HOME/modeling/friction-tutorial/), notably:

Navigate (cd) to the Telemac installation directory (HOEMTEL) to activate (source) the Telemac environment in Terminal (use the same environment as for compiling Telemac):

cd ~/telemac/v8p4/configs
source pysource.gfortranHPC.sh

Next, cd into the simulation folder and run the simulation, potentially with the -s flag, to trace back flux convergence:

cd ~/modeling/friction-tutorial/
telemac2d.py steady2d-zonal-ks.cas -s

The successful simulation run will have finished with something like this:

Unfold to see the correct Terminal output

================================================================================
 ITERATION    10000    TIME:  6 H 56 MIN  40.0000 S   (    25000.0000 S)
--------------------------------------------------------------------------------

[...]

--------------------------------------------------------------------------------
                       BALANCE OF WATER VOLUME
     VOLUME IN THE DOMAIN :    268926.5     M3
     FLUX BOUNDARY    1:     35.00000     M3/S  ( >0 : ENTERING  <0 : EXITING )
     FLUX BOUNDARY    2:    -34.99963     M3/S  ( >0 : ENTERING  <0 : EXITING )
     RELATIVE ERROR IN VOLUME AT T =       0.2500E+05 S :    0.2327571E-14
--------------------------------------------------------------------------------
                   FINAL BALANCE OF WATER VOLUME

     RELATIVE ERROR CUMULATED ON VOLUME:    0.4112446E-14

     INITIAL VOLUME              :     268899.0     M3
     FINAL VOLUME                :     268926.5     M3
     VOLUME THAT ENTERED THE DOMAIN:     27.48362     M3  ( IF <0 EXIT )
     TOTAL VOLUME LOST             :    0.1105946E-08 M3

 END OF TIME LOOP

 EXITING MPI

                     *************************************
                     *    END OF MEMORY ORGANIZATION:    *
                     *************************************

 CORRECT END OF RUN

 ELAPSE TIME :
                              3  MINUTES
                              3  SECONDS
Note: The following floating-point exceptions are signalling: IEEE_UNDERFLOW_FLAG IEEE_DENORMAL
STOP 0

... merging separated result files

... handling result files

        moving: r2dsteady-ks-zonal.slf
      copying: steady2d-zonal-ks.cas_2030-07-28-14h55min04s.sortie
... deleting working dir



My work is done

The resulting flux convergence and convergence rates should look similar to this:

zonal friction telemac flux convergence pythomac

Fig. 224 Flux convergence plot across the two boundaries of the hotstarted steady Telemac2d simulation, starting at a simulation time of 15000 timesteps.#

zonal friction convergence rate fluxes telemac boundaries

Fig. 225 The convergence rate \(\iota\) as a function 15000 simulation timesteps of the hotstarted steady 2d simulation with friction zones.#

The required steady2d-zonal-ks.cas_2023-07-28-14h55min04s is available here for use with instructions from the spotlight chapter on convergence.

Look at the results in QGIS

Load the simulation results file (r2dsteady-ks-zonal.slf) in QGIS to verify the correctness of the used bottom friction and look at the slight changes in flow velocity and water depth resulting from the now different roughness (friction) values.

Working with Friction IDs#

The friction zones can also be assigned through friction IDs, which then require setting up a zones file and friction data file, for example, as showcased in the Donau example (HOMETEL/examples/telemac2d/donau/).

The Donau zonal friction ID example

The BAW’s Donau case study lives in HOMETEL/examples/telemac2d/donau/ and it was presented at the XXth Telemac-Mascaret user conference. The conference proceedings are available at the BAW’s HENRY portal (look for the contribution Reverse engineering of initial & boundary conditions with Telemac and algorithmic differentiation). However, this case uses an unnecessary complication in the form of a .bfr zone file. The geospatial reference system of this example is EPSG 31468 (GK4) (see this post in the Telemac Forum).

In the showcase of this tutorial, working with friction tables required assigning the friction IDs defined in Tab. 13 to the BOTTOM FRICTION variable of the .slf mesh. The according files can be downloaded from our repositories:

friction.tbl & CAS#

Create friction.tbl#

Create a friction table file called friction.tbl (consider this friction.tbl template) with the following content, where the no entries (here starting in line 36) must correspond to the FRIC_ID assigned to the mesh (recall Fig. 220):

Listing 1 Example for a friction(.tbl) ID table.#
 1* ----------------------------------------------------------------------------- 
 2*  EXAMPLE ADAPTED FROM HOMETEL/examples/telemac2d/donau/
 3*
 4*  Implemented roughness laws: 
 5*    NOFR : no friction         (number of values) 
 6*    HAAL : Haaland   law       (1 value  : rB) 
 7*    CHEZ : Chezy     law       (1 value  : rB) 
 8*    STRI : Strickler law       (1 value  : rB) 
 9*    MANN : Manning   law       (1 value  : rB) 
10*    NIKU : Nikuradse law       (1 value  : rB) 
11*    LOGW : Log Wall  law       (1 value  : rB) 
12*    COWH : Colebrook-White law (2 values : rB, nDef) 
13* 
14*  no             : FRIC_ID assigned to the SLF mesh
15* 
16*  Riverbed
17*  ------------- 
18*  typeB          : roughness law for riverbed
19*  rB             : friction value for riverbed
20*  nDefB          : Mannings n for shallow flow zones
21* 
22*  Later walls (only with k-epsilon model) 
23*  ----------------------------------------- 
24*  typeS          : roughness law for walls          (option) 
25*  rS             : friction value for walls         (option) 
26*  nDefS          : Mannings n for shallow waters    (option) 
27* 
28*  Non-submerged Vegetation (if needed) 
29*  ------------------------ 
30*  dp             : mean diameter                                (option) 
31*  sp             : averaged distance between roughness elements (option) 
32* 
33* ----------------------------------------------------------------------------- 
34* no        typeB  rB    NDefB  typeS  rS  NDefS   dp     sp 
35* 
36  0  STRI   33.0  NULL
37  1  STRI   34.6  NULL
38  2  STRI   27.7  NULL
39  3  STRI   40.3  NULL
40  4  STRI   22.7  NULL
41END

Run Telemac with Friction IDs#

To run Telemac with friction IDs, make sure the above-indicated keywords are activated in the .cas steering file. The required files now embrace:

With these files, activate and run Telemac as usual:

cd ~/telemac/v8p4/configs
source pysource.gfortranHPC.sh
cd ~/modeling/frictionID-tutorial/
telemac2d.py steady2d-zonal-ID.cas

Advanced Friction Routines#

Modifying the FRICTION_USER Fortran subroutines is not mandatory for working with friction zones but can be useful for implementing or adapting the behavior of roughness laws. To activate a FRICTION_USER subroutine, for example, to implement the variable power equation from Ferguson [Fer07]:

  • Copy the FICTION_USER subroutine template from HOMETEL/sources/telemac2d/friction_user.f into a new folder of your simulation directory, for example:

/HOME/modeling/frictionID-tutorial/user_fortran/friction_user.f

  • Modify and save edits of friction_user.f.

  • Tell the steering (.cas) file to use the modified FRICTION_USER Fortran file by adding the keyword FORTRAN FILE : 'user_fortran', which makes Telemac2d look up Fortran files in the /user_fortran/ subfolder.

Contents