The case featured in this tutorial was established with the following software:
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 91 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).
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. 91). 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:
The computational mesh qgismesh.slf file (uses EPSG:6173 - ETRS 89 / UTM zone 33N).
The boundary definitions boundaries.cli file.
Consider saving the files in a new folder, such as
Unsteady simulation file repository
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).
View the unsteady steering file
To view the integration of the unsteady simulation keywords in the steering file, download unsteady2d.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
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
To simulate the hydrograph shown in Fig. 91, the simulation must run for at least 15000 time steps (i.e., from
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
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).
Define a Quasi-steady Hydrograph
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. 91, 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. 91 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
Twith 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:
5 5 5
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.
Verify the correct settings by downloading boundaries-544.cli for the unsteady simulation.
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:
0is the default that deactivates the usage of a stage-discharge curve.
1applies prescribed elevations as a function of calculated flow rate (discharge).
2applies 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
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
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
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.
Expand to view an example for multiple stage-discharge curve definitions
The following file block would prescribe Stage-discharge relations to the upstream and downstream boundary conditions in this tutorial. However, the file cannot be used here unless the upstream boundary type is changed to
5 5 5 (
prescribed H and Q) in the
boundaries.cli file (read more in the pre-processing tutorial).
# # Downstream Rating Curve # Z(2) Q(2) m m3/s 371.33 35 371.45 50 371.86 101 375.73 1130 379.08 2560 # # Upstream Rating Curve # Q(1) Z(1) m3/s m 35 371.33 50 371.45 101 371.86 1130 375.73 2560 379.08
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
The predictor-corrector schemes (SCHEME FOR … keywords defined with
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
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.,
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
Expand to view an example for coordinate-based control sections
The following control section file uses point coordinates rather than node ID numbers to define three sections. Read more in Gifford-Miears and Leon [GML13] (i.e., section 4.1.2 in the Baxter tutorial).
# control section file using coordinates 3 0 affluent_creek 19572355.895577 626823.06664 1952347.2733 626923.9554 main_river_upstream 1946449.824 635349.6070 194.919 635209.807 main_river_downstream 1967737.56993 620784.415608 1967998.16429 620638.17849
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.
Run Telemac2d Unsteady¶
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
If you are using the Hydro-Informatics (Hyfo) Mint VM
If you are working with the Mint Hyfo VM, load the TELEMAC environment as follows:
cd ~/telemac/v8p2/configs source pysource.hyfo-dyn.sh
With the TELEMAC environment loaded, change to the directory where the 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/ telemac2d.py unsteady2d.cas
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
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: r2dunsteady.slf 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:
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 92 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.
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.
Resolve volume balance issues in unsteady simulations
The total inflow and outflow volumes in the here featured simulation amount to 3479930.958 m\(^3\) and 3430100.437 m\(^3\), respectively. Thus, there is a total volume error of 1.4\(%\). To overcome such issues, the Telemac2d manual recommends using a minimum value for water depth to define when a cell is wet or dry. At the same time, the developers do not recommend using a minimum water depth for most simulations and emphasize to use this option only for unsteady (quasi-steady) simulations. Defining a minimum water depth requires setting the TREATMENT OF THE TIDAL FLATS keyword to
2 (read more in the steady2d tutorial), which is neither compatible with parallelization routines, nor with the here used
SCHEME FOR ADVECTION ... : 14 settings. Thus, better results, but long non-parallelized quasi-steady calculations could be supposedly yielded with the following keywords in the steering file:
OPTION FOR THE TREATMENT OF TIDAL FLATS : 2 / use segment-wise flux control MINIMUM VALUE OF DEPTH : 0.1 / in meters
Visualization with QGIS¶
The results of the unsteady simulation can be visualized and snapshots exported to raster (e.g., GeoTIFF) or shapefile formats in QGIS with the PostTelemac plugin the same way as explained in the steady2d tutorial (read the steady2d post-processing). The latest QGIS releases additionally enable to load the Selafin results mesh file (here: r2dunsteady.slf) as a QGIS mesh layer. Therefore, launch QGIS, go to the Layer menu and click on Add Layer > Add Mesh Layer…. In the popup window (Data Source Manager / Mesh), select r2dunsteady.slf, click Add, and Close. Figure 93 shows the imported r2dunsteady mesh layer in QGIS with a Softlight blending (set in the Symbology) on google satellite imagery.
r2dunsteady.slf (results file) not correctly showing in QGIS
Is the results file
r2dunsteady.slf not showing up in QGIS? Make sure to import it with its correct georeference: EPSG:6173 (ETRS 89 / UTM zone 33N).
The simulation output parameters (e.g.,
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.
Expand to view the resulting video
Sebastian Schwindt @ Hydro-Morphodynamics channel on YouTube.
- 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.