Unsteady 2d

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 controlled rivers. To model the inherently unsteady flows of rivers, we can discretize time-dependent discharge (e.g., a flood hydrograph) in a numerical model as a series of steady discharges. Figure 1 illustrates the discretization of a natural flood hydrograph into steps of steady flows, which will be used in this chapter. Note that the hydrograph starts at Time = 15000, which is the result of the dry-initialized steady2d simulation.

This chapter features the implementation of a quasi-steady discharge hydrograph into a hydrodynamic Telemac2d simulation through the definition of an inflow sequence (red circles in Fig. 1). 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:32633 - ETRS 89 / UTM zone 33N).

• The boundary definitions boundaries.cli file.

• The results file r2dsteady.slf of the dry initialized steady 2d simulation ending at t=15000 for 35 m$^3$/s.

Consider saving the files in a new folder, such as /unsteady2d-tutorial/.

Model Adaptations¶

The implementation 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 Initial Conditions 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

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 /) the INITIAL CONDITIONS keyword:

/ INITIAL CONDITIONS : 'ZERO DEPTH'

General Parameters¶

To simulate the hydrograph shown in Fig. 1, the simulation must run for at least another 15000 time steps (i.e., from t=15000 to t=30000). Since printing out (intermediate) results has a significant effect on computing time, 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).

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. 1, 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. 1 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 the time T ($t$) and upstream inflow rate Q(1).

• Separate the columns 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.

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

• Use find-and-replace (e.g., CTRL + H keys in Notepad++, or CTRL + F keys in other text editors):

  • Find 5 5 5

  • Replace with 4 5 5

  • Click on Replace all upstream boundary nodes.

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

To verify the correct settings download boundaries-unsteady.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-unsteady.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 requires a list consisting of 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

#
# 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.;0.
/ PRESCRIBED ELEVATIONS : 374.80565;371.33

Numerical Parameters¶

The predictor-corrector schemes (SCHEME FOR ... keywords defined with 3, 4, 5, or 15 rely on a parameter defining the number of iterations at every timestep for convergence (see the steady2d tutorial). 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

# 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/v9.0.0/configs/) and load the environment (e.g., pysource.openmpi.sh - use the same as for compiling TELEMAC).

cd ~/telemac/v9.0.0/configs
source pysource.gfortranHPC.sh

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/v9.0.0/mysimulations/unsteady2d-tutorial/) and run the *.cas file by calling the telemac2d.py script.

cd ~/telemac/v9.0.0/mysimulations/unsteady2d-tutorial/
telemac2d.py unsteady2d.cas

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:

• get r2dunsteady.slf, and

• get r-control-sections.txt.

Post-processing¶

Open Boundary Flows¶

The unsteady simulation intends to model time-variable flows (fluxes) over the upstream and downstream liquid 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 2 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.

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, similar as explained in the steady2d post-processing. Specifically, the latest QGIS releases 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 3 shows the imported r2dunsteady mesh layer in QGIS with a Softlight blending (set in the Symbology) on google satellite imagery.

The simulation output parameters (e.g., U, V, or Q) at a selected timestep 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 Time Controller (see activation in Fig. 4). The frequency of images can be set through clicking on the cogwheel of the time controller, and image sequences played by clicking in the Play button. Additionally, Fig. 5 uses an overlay of water depth pixel colors (contour plot), and flow velocity vectors, defined in the Layer Styling panel. The North and discharge arrows, and the title are Decorators, which can be found in View > Decorators.

The exported series of images can be converted to a video with video-editing software, such as the easy and free-to-use OpenShot (good for Windows) or kdenlive (good for Linux) tools. The below-shown box features an exemplary video created with kdenlive.