Requirements

This tutorial is designed for advanced modelers and before diving into this tutorial make sure to complete the TELEMAC pre-processing and Telemac2d steady hydrodynamic modeling tutorials.

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

Get Started¶

The steady 2d tutorial hypothesizes that the discharge of a river is constant over time. However, the discharge of a river is never truly constant (i.e., never steady) and varies slightly from second to second, even in flow-controlled rivers. Alas, the inherently unsteady flow regime of rivers cannot realistically be modeled with most software. As a result, we must discretize time-dependent discharge (e.g., a flood hydrograph) in a numerical model as a series of steady discharges. Figure 85 illustrates the discretization of a natural flood hydrograph into steps of steady flows, which will be used in this tutorial. Note that the hydrograph starts at Time = 15000, which is the result of the steady2d simulation end state with dry initialization. Thus, the end time of T=15000 represents the end of the dry steady model initialization, as described in the Re-Initialize Dry section (results can be downloaded, see below).

Fig. 85 The discretization of a natural hydrograph into steps of steady flows (qualitative hydrograph for this tutorial).

This tutorial shows how a quasi-steady discharge hydrograph can be implemented in a hydrodynamic Telemac2d simulation through the definition of an inflow sequence (red circles in Fig. 85). The tutorial builds on the steady simulation of a discharge of 35 m$$^3$$/s 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 /unsteady2d-tutorial/.

The simulation files used in this tutorial are available at https://github.com/hydro-informatics/telemac/tree/main/unsteady2d-tutorial/.

The integration of unsteady 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).

Hotstart Initial Conditions¶

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

To speed up the calculations and provide a well-converging baseline for the quasi-steady calculations, this tutorial re-uses the output of the steady 2d simulation with dry initial conditions (see the Re-Initialize Dry section). This type of model initialization is also called hotstart. To hotstart the simulation, the steady results file r2dsteady.slf needs to be defined as PREVIOUS COMPUTATION FILE:

COMPUTATION CONTINUED : YES
PREVIOUS COMPUTATION FILE : r2dsteady.slf / results of 35 CMS steady simulation
/ INITIAL TIME SET TO ZERO : 0 / avoid restarting at 15000


In addition, an INITIAL TIME SET TO ZERO keyword may be defined to reset the time from the previous computation file from 15000 to 0. However, this tutorial does not use this option and continues at timestep 15000. To avoid ambiguous definitions of initial conditions, deactivate (i.e., delete or comment out lines with a /) a little further down in the steering file the INITIAL … keywords:

/ INITIAL CONDITIONS : 'CONSTANT DEPTH'
/ INITIAL DEPTH : 1


General Parameters¶

To simulate the hydrograph shown in Fig. 85, the simulation must run for at least 15000 time steps (i.e., from T=15000 to T=30000). Since printing out (intermediate) results has a significant effect on computational speed, increase the graphic printout timestep to 500 (i.e., decrease the printout frequency compared to 200 used for the steady simulation):

TIME STEP : 1.
NUMBER OF TIME STEPS : 15000
GRAPHIC PRINTOUT PERIOD : 500
LISTING PRINTOUT PERIOD : 500


Open Boundaries¶

This section features the implementation of quasi-steady (unsteady) flow conditions at the open liquid boundaries with a time-dependent inflow hydrograph and a downstream Stage-discharge relation (recall the rationales behind the choice of boundary types from the pre-processing tutorial).

With the dry-initialized model ending at T=15000, the hydrograph needs to start at 15000, even though the model start will represent time zero of the unsteady simulation. To implement the triangular-shaped hydrograph shown in Fig. 85, create a new file called inflows.liq in the simulation folder. Open the new inflows.liq file in a text editor and add the red-circled points in Fig. 85 as time-dependent flow information at the upstream (1) and downstream (2) open (liquid) boundaries. In this file:

• Add a file header starting with # signs (commented lines ignored by TELEMAC).

• Implement 2 columns (for time T and upstream inflow rate Q(1)).

• Separate the columns either with spaces.

• The first column must be time T with strictly monotonously increasing values and the last time value must be greater than or equal to the last simulation timestep.

How does TELEMAC count open (liquid) boundaries?

Recall the information provided in the comment box in the steady2d tutorial.

Thus, the inflows.liq file should look similar to this:

# Inflow hydrograph
#
T	Q(1)
s	m3/s
15000	35
16000	35
17000	50
19000	1130
22000	101
25000	35
99000	35


The original boundaries.cli file describes the downstream boundary with prescribed Q and H (type 5 5 5). However, in the unsteady calculation, Q needs to be free (otherwise, Q(2) needed to be defined in inflows.liq with an additional column) and for this reason, the boundaries.cli file requires some adaptions:

• Open the provided boundaries.cli file with a text editor (e.g., NotepadPlusPlus (Text Editor) on Windows or Atom).

• Use find-and-replace (e.g., CTRL + H keys in NotepadPlusPlus (Text Editor), or CTRL + F keys in Atom):

• Find 5 5 5

• Replace with 5 4 4

• Click on Replace all downstream boundary nodes.

• Similarly, make sure the upstream boundary nodes are all set to 4 5 5.

• Save the file as boundaries-544.cli and close it.

In the steering file, adapt the file name for the boundary conditions and add the link to inflows.liq:

BOUNDARY CONDITIONS FILE : boundaries-544.cli
/ ...
LIQUID BOUNDARIES FILE : inflows.liq


Rating Curve (Stage-Discharge Relation) To activate the use of a Stage-discharge relation for an open (liquid) boundary, the STAGE-DISCHARGE CURVES keyword needs to be added to the steering file. This keyword accepts the following integers:

• 0 is the default that deactivates the usage of a stage-discharge curve.

• 1 applies prescribed elevations as a function of calculated flow rate (discharge).

• 2 applies prescribed flow rates (discharge) as a function of calculated elevation.

The STAGE-DISCHARGE CURVES keyword is a list that assigns one of the three integers (i.e., either 0, 1, or 2) to the open (liquid) boundaries. In this tutorial, the setting STAGE-DISCHARGE CURVES : 0;1 activates the use of a Stage-discharge relation for the downstream boundary only where the upstream open boundary number 1 is set to 0 and the downstream open boundary number 1 is set to 0.

The form (curve) of the Stage-discharge relation needs to be defined in a stage-discharge file (ASCII text format). Such files typically apply to the downstream boundary of a model at control sections (e.g., a free overflow weir). This tutorial uses the following relationship that is stored in a file called ratingcurve.txt (download):

# Downstream ratingcurve.txt
#
Z(2)	Q(2)
m	m3/s
371.33	35
371.45	50
371.86	101
375.73	1130
379.08	2560


To define Stage-discharge relations for multiple open boundaries (e.g., at river diversions or tributaries), add the curves to the same file. TELEMAC automatically recognizes where the curves apply by the number given in parentheses after the parameter name in the column header. For instance, in the above example for this tutorial, the column headers Z(2) and Q(2) tell TELEMAC to use these values for the second (i.e., here, the downstream) open boundary. The column order is not important because TELEMAC reads the curve type (i.e., either $$Q(Z)$$ or $$Z(Q)$$) from the STAGE-DISCHARGE CURVES keyword.

To use the stage-discharge file, define the STAGE-DISCHARGE … keywords in the steering file:

/ steering.cas
STAGE-DISCHARGE CURVES : 0;1
STAGE-DISCHARGE CURVES FILE : ratingcurve.txt


Remove Ambiguous Open Boundary Definition Keywords

To avoid ambiguous definitions of the open boundaries conditions, deactivate (i.e., delete or comment out lines with a /) the PRESCRIBED … keywords in the steering file:

/ PRESCRIBED FLOWRATES  : 35.;35.
/ PRESCRIBED ELEVATIONS : 0.;371.33


Numerical Parameters¶

The predictor-corrector schemes (SCHEME FOR … keywords defined with 3, 4, 5, or 15 as explained in the steady2d tutorial) rely on a parameter defining the number of iterations at every timestep for convergence. For quasi-steady simulations, TELEMAC developers recommend setting this parameter to 2 or slightly larger (section 7.2.1 in the Telemac2d manual). Therefore, add the following line to the steering file:

NUMBER OF CORRECTIONS OF DISTRIBUTIVE SCHEMES : 2


Control Sections¶

A consistent way to verify fluxes at open boundaries or other particular lines (e.g., tributary inflows or diversions) is to use the CONTROL SECTIONS keyword. A control section is defined by a sequence of neighboring node numbers. For instance, to verify the fluxes over the open boundaries in this tutorial, check out the node numbers in the boundaries.cli file (e.g., 144 to 32 for the upstream and 34 to 5 for the downstream boundary). Then, create a new text file (e.g., control-sections.txt) and:

• Add one comment line with some short information (e.g., # control sections input file). Note that this line is mandatory.

• In the second line add a space-separated list of 2 integers where

• the first integer defines the number of cross-sections, and

• the second integer defines if node numbers (i.e., IDs from boundaries.cli or qgismesh.slf) or coordinates will be defined. A negative number enables the node ID-mode, and a positive number enables the coordinates-mode.

• Define as many cross sections as defined with the first integer. Every cross-section definition consists of two lines:

• The first line is a string (text) without spaces that is naming the cross-section (e.g., inflow_cs).

• The second line consists of two numbers defining the start and end points of the cross-sections. If the second integer in the file line is negative, provide two space-separated integers. If the second integer is positive, provide two space-separated pairs of coordinates (put a space between coordinates).

For example, the following control-sections.txt file can be used with the steady simulation in this tutorial (download control-sections.txt).

# control sections steady2d
2 -1
Inflow_boundary
144 32
Outflow_boundary
34 5


The second line in this file tells TELEMAC to use 2 control sections, which are defined by node IDs (-1). To use the control sections for the simulation add the following to the steering file:

/ steady2d.cas
/ ...
SECTIONS INPUT FILE :  control-sections.txt
SECTIONS OUTPUT FILE : r-control-flows.txt


Thus, re-running the simulation will write the fluxes across the two define control sections to a file called r-control-flows.txt. The Telemac2d manual provides explanations in section 5.2.2.

Go to the configuration folder of the local TELEMAC installation (e.g., ~/telemac/v8p2/configs/) and load 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 unsteady simulation lives (e.g., /home/telemac/v8p2/mysimulations/unsteady2d-tutorial/) and run the *.cas file by calling the telemac2d.py script.

cd ~/telemac/v8p2/mysimulations/unsteady2d-tutorial/


Speed up

With parallelism enabled (e.g., in the Mint Hyfo Virtual Machine), speed up the calculation by using multiple cores through the --ncsize=N flag. For instance, the following line runs the unsteady simulation on N=2 cores:

telemac2d.py unsteady2d.cas --ncsize=2


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
32  SECONDS
... merging separated result files

... handling result files
moving: r-control-sections.txt
... deleting working dir

My work is done


Telemac2d will write the files r2dunsteady.slf and r-control-sections.txt. Both results files are also available in the this eBook’s TELEMAC repository to enable accomplishing the post-processing tutorial:

Post-processing¶

Open Boundary Flows¶

The unsteady simulation intends to model time-variable flows over the open upstream and downstream open boundaries. The above-defined control sections enable insights into the correct adaptation of the flow at the upstream inflow boundary (prescribed Q through inflows.liq) and the downstream outflow boundary (prescribed H through ratingcurve.txt). Figure 86 shows the modeled flow rates where the Inflow_boundary shows perfect agreement with inflows.liq and the Outflow_boundary reflects the flattening of the discharge curve in the modeled meandering gravel-cobble bed river.

Fig. 86 The simulated flows over the upstream Inflow_boundary and the downstream Outflow_boundary control sections.

The peak inflow corresponds to the specified 1130 m$$^3$$/s while the outflow peak discharge is only 889 m$$^3$$/s and the peak takes about 1070 seconds (inflow at $$T=19000$$ and outflow at $$T\approx 20070$$) to travel through the section.

Visualization with QGIS¶

The simulation output parameters (e.g., U, V, or Q) and the timestep shown can be controlled in the layer properties of the r2dunsteady layer (double-click on it in the Layers panel).

To create a video of simulation results, use the Crayfish plugin that enables the animated visualization of meshes and their attributes (e.g., change of node values over time). Get the Crayfish plugin from QGIS Plugins menu > Manage and Install Plugins… > tap crayfish in the All tab and click on Install Plugin. The plugin is now ready to create a video by clicking through QGIS Mesh menu > Crayfish Export Animation …. In the Crayfish popup window, toggle through the three tabs, and adapt video settings (e.g., define a file name such as velocity-video.avi in the General tab). Note that Crayfish will automatically export the frame and active variable (here, the default is U) selected on the mesh (Layer Properties). When all settings are made, click on OK to start the export.

Crayfish first time use

The first time that a video is exported, Crayfish will require the definition of an FFmpeg video encoder and guide through the installation (if required). Follow the instructions (preferably use automatic installers). If Crayfish did not automatically continue the video export, re-start exporting the video after the FFmpeg installation.

The below-shown box features an exemplary video output of flow velocity.

What next?

This tutorial ends with the graphical output of modeled flow parameters, but there are a couple more steps to accomplish in practice. For instance, the time that the flow peak takes to travel through the modeled river section might be too short (i.e., flow is too fast) or too long (i.e., flow is too slow) compared to observation data (e.g., from stream gauges). In these cases, model calibration through variations of the FRICTION COEFFICIENT keyword might be a solution.