SIC^2: Simulation and Integration of Control for Canals

Change of the bathymetry with an external file

Pierre-Olivier Malaterre — 2017-11-24T16:42:48Z

We sometimes want to change the bathymetry of a canal, a channel or a river from an external program (eg Matlab script, Scilab, R, etc) to do the optimization of profiles for example, or to calculate the sensitivity of certain variables to bathymetry parameters.

This can be done with a file named changebathy.txt, which must be located with the xml project file. The example \dat\ex32_lacguiers\LacGuiers_v1.xml uses this feature.

This file has the following structure:

27 2 0.00000 0.00000 0.10000

28 2 0.00000 0.00000 0.10000

28 3 0.00000 0.00000 0.15000

We can have as many lines as we want. The format is free ('*' in Fortran format), that is to say that the numbers can be separated by as many spaces as desired, or a priori also tabs.

On each line:

the first number is the number of the reach
the second number is the number of the section in that reach
the third is the scaling factor in Y (lateral) that we want to apply
the fourth is the scaling factor in Z (vertical) that we want to apply
the fifth is the vertical offset of the bottom elevation, and therefore the entire section (in m)

When executing the calculation program (Fluvia or Sirene) the sections thus modified will be indicated in the control window.

Description of the offtakes

David Dorchies, Pierre-Olivier Malaterre — 2017-09-24T11:47:08Z

Access to the description of an offtake by double-clicking a node in the graph or in the tree view.

From SIC 5.20, intermediate nodes can have multiple offtakes.

Characteristics of an offtake

Each offtake has the following characteristics:

A downstream boundary condition which can be an imposed flow $Q(t)$, a fixed elevation $Z(t)$, a rating curve $Q(Z)$ (or rather $Z(Q)$ ), or a law function $Q=Z^{\alpha}$ (or rather $Q(t)=Q_{ref} [(Z(t)-Z_{0})/(Z_{ref}-Z_{0})]^{\alpha}$ to be more precise)

Optionally a first level of structure with one or more devices including one may be regulated in order to obtain a discharge goal.
Possibly a second level of structure downstream of the first containing one or more fixed devices.

Regulate an offtake for obtaining a targeted discharge

In steady (FLUVIA) and unsteady (SIRENE) calculation, it is possible to calculate a characteristic of a device (opening of a gate, sill of a weir...) situated in the first level of structure to obtain a defined discharge (called "targeted discharge" or maybe sometimes also "objective discharge") at the offtake.

Initial discharge

The initial discharges serves two purposes :

The initial discharge at the offtakes is used to calculate the distribution of the discharge in the reaches of the network for the steady calculation (See Verification of initial rates).
When an offtake is not in regulation "targeted discharge" mode, the discharge calculation is performed by dichotomy and requires an initial discharge to start the calculation.

Reference discharge

The reference discharge is not directly used in hydraulic calculations. In EdiSIC result mode, it is used to calculate indices of performance by comparing the distribution (calculated discharge) and the request (reference discharge).

The reference discharge can also be used as an input by the regulation modules.

Sign convention for discharge

Since the discharges can enter or leave the hydraulic system (at nodes or at sections through lateral discharges or seepage), a sign convention had to be choosen. All discharges entering into the hydraulic system are positive. All discharges leaving the hydraulic system are negative. This is true at all nodes and cross sections for lateral discharges at the data input stage and also at the result display stage. For cross structures (gates, weirs, etc) the sign convention is positive for flows from upstream to downstream and negative for downstream to upstream flow directions.

The boundary conditions

Pierre-Olivier Malaterre — 2017-09-24T10:20:45Z

The offtakes at nodes must have a boundary condition. The available boundary conditions are:

Flow rate (Pump): Q(t)
Fixed elevation: Z(t)
Rating curve function (tabulated): Q(Z) (or rather Z(Q))
Function Q power alpha: $Q(t)=Q_{ref} [(Z(t)-Z_{0})/(Z_{ref}-Z_{0})]^{\alpha}$

The upstream and downstream nodes are also considered as locations where "offtakes" must be defined in order to provide the boundary conditions for the hydraulic calculation algorithms. The terminology may seem abusive but it is necessary to choose a generic term. This is defensible in the sense that it is the points that allow injecting or withdrawing from the flow in the hydraulic network, at the upstream and downstream nodes as well as at the intermediate nodes.

The conditions at the upstream and downstream nodes can be chosen from this list. The details given for downstream nodes are also valid for upstream and intermediate nodes.

All combinations are possible in transient mode.

Some combinations are impossible in steady state: Q(t) upstream and downstream. Indeed in this case either there is no solution, or there is an infinity of solutions. The most traditional configuration is Q(t) upstream and Q(Z) downstream. Other options that do not explicitly specify upstream flow will involve iterations of the Fluvia calculation program to find the flow that satisfies the upstream conditions chosen.

Reminder: Incoming or outgoing flows in SIC follow a sign convention which is that incoming flows are positive and outgoing flows are negative. This is generally valid for external boundary conditions (upstream and downstream), internal (intakes-offtakes) and seepage/infiltrations or contributions distributed along the sections. But, to avoid the classic errors that we often encountered with users, we make exceptions to this convention when there is no ambiguity. For example, a downstream boundary condition of type Q(Z) can only be outgoing, and we therefore expect positive flows at the data entry interfaces whereas according to the convention we should choose them negative. The calculator will choose them positive, but they will indeed be outgoing flows.

Initialisation of the calculation at diffluences

Pierre-Olivier Malaterre — 2017-09-24T09:57:22Z

On a network with diffluences (classical on irrigation canals whereas rare for rivers), the calculation of the steady-state water line performs iterations to distribute the flow arriving from upstream into each reach downstream of the diffluence point.

By default, the distribution is initialized from the relative surface of reaches located downstream from the diffluence. When this default distribution would cause negative initial flow rates in some branches of the network, the user can change these settings by double-clicking the node causing the problem and change the distribution of the flow between the diversion reaches leaving from this node.

Definition of the calculation mode at nodes

Pierre-Olivier Malaterre — 2017-09-24T09:56:19Z

The resolution of the calculation of the hydraulic variables at the node can be done in two ways:

equality of the elevations (default mode)
equality of the hydraulic heads

In the case of equality of heads, it is possible to define a head loss at the entrance of the node (for upstreams reaches arriving at this node) and at the exit of the node (for the diversion reaches downstream). It is possible to have for the same node reaches arriving at or leaving this node with different modes (elevation for some and head for others). In this case of a head loss, a Borda type equation (proportional to the speed squared) is used.

Remark: In the case where the flow at a node is in supercritical regime on one or more of the reaches arriving or leaving this node, the calculation mode will be automatically switched to "equality of head" mode, even if the "equality of elevations" mode had been chosen here. This is indeed more physically realistic. For calculations in torrential regime to be authorized, the corresponding option must be activated in the permanent calculation parameters.

Import of .TAL and .FLU files in batch mode

Pierre-Olivier Malaterre — 2017-04-28T13:51:14Z

This feature allows you to launch EdiSIC, open a .TAL file, save it in Xml, launch the mesh with the Talweg program, and then if everything went right, import one or more .FLU files. These files are from those with the format of version SIC 4.**.

Syntax

EDISIC.EXE "working_directory" IMPORT "File.TAL" "File1.FLU" ["File2.FLU" ...]

Parameter Description

"EDISIC.EXE": The name of the executable program with the possibility to give its complete name if the third party program running the batch mode is not located in this directory, or if the executable program is not defined in the path
"Work_directory": Working directory (in which the output XML file and the .log file will be generated)
IMPORT: EdiSIC launch mode - opening and saving one or more files
"File.TAL": Name of a .TAL file (full path or relative to the working directory)
"File1.FLU", "File2.FLU" ...: Name of a .FLU file (full path or relative to the working directory)

The option works for as many .FLU files as you want. It is even possible to put several batch of .TAL followed by several .FLU.

Command line limitation: using EDISIC.MAC

Since the command line size is limited, it may be useful to set the command line in the EDISIC.MAC file and to run EdiSIC in "macro" mode.

Command Line Example

EDISIC.EXE "C:\Files\SicV5\dat\ex1" IMPORT Demo.tal Demo.flu

C:\Sic538f5\exe\Edisic.exe "C:\Fichiers\Sic V5\dat\ex1" Import Demo.tal Demo.flu

The following actions will be performed:

Opening of Demo.tal
Registration in xml format
Mesh of the xml file by Talweg
Import file Demo.flu

The Demo.flu file will be used to create a scenario. In order to better adapt to executions in batch mode, several things will be defined and activated for this scenario:

A variant will be created, in case we want to use it for example for an unsteady simulations (in batch mode we can import an initial condition in a scenario or a variant and then run a steady or unsteady calculation)
The management of the .par file will be positioned in the mode where this .par file will not be rewritten by Edisic. It will thus be possible to create it by a third-party program and to take it into account during the calculations (otherwise by default Edisir rewrites it each time the .xml file is saved).
The mode of steady state calculation for several time instants and not only for the first moment is also activated, to allow these multiple calculations in batch mode. We can actually think that this feature will be useful in batch mode. It will be possible anyway in the calculation parameters of the program Fluvia to specify the end times (TFIN=) and the time step (DT=) if we do not want to perform every possible moment.

In the case of using an edisic.mac file, it will be necessary to put:

"C:\Files\SicV5\dat\ex1" IMPORT Demo.tal Demo.flu

this file being positioned in the sub-directory of the project, where the files to be imported will also be present. And Edisic must also have this sub-directory as the current directory (open a file in this directory before and then close Edisic).

and just run in command line:

EDISIC.EXE

C:\Sic538f5\exe\Edisic.exe

Import sections in text format

Pierre-Olivier Malaterre — 2017-04-28T12:02:20Z

This feature allows you to launch EdiSIC, create a new blank document or modify an existing project, import files containing section data into text format and save it as TAL (for SIC Version 4.xx) or XML (for SIC version 5 .xx). For more information on the text import formats of the sections, see article dedicated.

Modifying an existing project allows you to keep all the data of hydraulic scenarios, quality modules and regulation modules. The reaches are then imported in the order of their numbering.

Syntax

EDISIC.EXE "Work_directory" Import_Mode "File to create" "File1.txt" ["File2.txt" ...]

Parameter Description

"Work_directory": Working directory (in which the output XML or TAL file and a .log file will be generated). This working directory can be different from the current subdirectory, cf below;
Import_Mode: this parameter can take 4 different values (and possible alternatives with _new or _update, see below) depending on the chosen import mode (see below import modes);
"File to create": Name of the XML or TAL file to be created at the end of the import without the extension. A file of the same name with the .log extension will be created and will contain error messages for the operation, if any;
"File1.txt" [, "File2.txt" ...]: Name of one or more file(s) .txt to import (full path or single name). Each .txt file represents a reach. The file order defines a branch from upstream to downstream. If the names of these files are not given with a full path, they will be searched by default in the current subdirectory, which is the last one used by Edisic (and stored in the sic.ini file under exe). If they are not found, the current subdirectory is changed into the working subdirectory defined above, which allows to have a library of txt files in a current subdirectory, and to create various XML or TAL files in subdirectories and with selected names as needed.

Import modes

There are 4 modes (and possible alternatives with _new or _update, see below) of choice to define the type of file created (Xml or Tal) and the format of the text file (normal or transposed):

Import mode	Text file format	Generated File Format
ImportXml	Normal	XML (SIC version 5.xx)
ImportTal	Normal	TAL (SIC version 4.xx)
ImportXmlTrans	Transposition	XML (SIC version 5.xx)
ImportTalTrans	Transposition	TAL (SIC version 4.xx)

If the project file already exists, the interface asks if the user wants to overwrite the project, modify the existing project or cancel the operation. It is possible to override this issue by adding either _NEW or _UPDATE to the import mode (Example: use IMPORTXML_NEW to overwrite an existing XML project file). Lowercase or uppercase can be used for these options.

Command line limitation: using EDISIC.MAC

Since the command line size is limited, it may be useful to set the command line in the EDISIC.MAC file and to run EdiSIC in "macro" mode.

Command Line Example

EDISIC.EXE "C:\Files\SicV5\dat\test" ImportXml "Demo" "bief1.txt" "bief2.txt"

The following actions will be performed:

Creation of the file C:\Files\SicV5\dat\test\Demo.xml;
Creation of the reach1 upstream;
Import the cross-section of the reach 1 and their cross section from the file C:\Files\SicV5\dat\test\bief1.txt; (Or the bief1.txt file located in the current subdirectory if it exists)
Creation of the reach 2 downstream of the reach 1;
Import of cross sections from C:\Files\SicV5\dat\test\bief2.txt file; (Or the bief2.txt file located in the current subdirectory if it exists)
Save the file C:\Files\SicV5\dat\test\Demo.xml. If this file already exists, a question is asked to allow overwriting.

How to perform a transient simulation (SIRENE)

Pierre-Olivier Malaterre — 2017-04-28T10:50:05Z

In order to perform a transient calculation, it is first necessary at least to have been able to carry out a steady-state calculation or another calculation in transient mode which will serve as an initial condition for the calculation. In addition, the calculation used as an initial condition must have been carried out with the parameter "Write in all calculation sections" checked. This parameter is checked by default for the permanent calculation parameters and is unchecked by default for transient calculation parameters.

Creating a new scenario or variant

The calculation of this new simulation will be carried out either in a new scenario or in a variant of the scenario serving as an initial condition. The first operation to be performed in the project explorer is therefore to choose:

Duplicate the initial condition scenario
Create a new variant in the initial condition scenario

Since transient computation requires an initial condition, it is important that the boundary conditions and the parameters of the start of the transient simulation are compatible with the initial waterline originating from a previous calculation. To obtain this guarantee, it is advisable to create a variant in the scenario where the calculation is used as the initial condition for the transient calculation.

Import of initial condition

In the Project Explorer, go to the line of the scenario or variant where the transient calculation is to be done and click on the " Import C.I." button (C.I. = Initial Condition). Choose from the list of results present the calculation results which will serve as initial condition.

Once this is done, the " Transient Calculation" button becomes active.

Edit Transitional Computing Events

The user will then enter the changes that will take place on the system over time (Variation of supplied or retrieved flow rates, operation of devices ...). This is done by the seizure of laws as a function of time.

If the types of boundary conditions do not change between the permanent scenario and the transient calculation, it is advisable to enter the time-dependent laws directly in the permanent scenario. The permanent calculation will be carried out on the first time step only and the transient calculation in a variant (which does not contain any modification with respect to the scenario) will calculate from the second time step on the data of the scenario.

Calculation Parameters

The user will have to define the time parameters of the simulation as presented on the page Time Settings. It may also possibly modify the parameters of the transient computation and the writing parameters of the results.

Start simulation

Follow the instructions on page Performing a Transient Calculation (SIRENE)

Geolocalisation

Pierre-Olivier Malaterre — 2017-04-28T10:07:38Z

This tool allows to manage the geolocation of the objects of the network (nodes, points of preemption of the reaches also called midpoints, cross sections).

The upper part of the "Geolocation" tab allows you to process the nodes and midpoints of the reaches (also called preemption points since they allow you to select a reach, to edit its parameters or view the results).

The "Compute pxl -> geo" option will use the pixel data (x-y position of the graphic objects on the 2D plan drawing) to calculate the geolocation (lat-lon) of the processed objects (nodes and preemption points here). This will be done using the geolocation of the upstream and downstream nodes of the selected area. You must therefore enter this before using this option. This is done by simple proportionality relationships between x-y and lat-lon (known as the rule of 3). This geolocation data will then be stored in the corresponding fields of the corresponding objects.

The "Compute geo -> pxl" option will do the opposite, that is to say position (x-y) the objects on the 2D plan drawing taking into account the geolocation data (lat-lon), while retaining the upstream nodes and downstream as references (x1-y1 and x2-y2) and using simple rules of 3 to calculate their positions. You must therefore position these upstream and downstream points where you want them, for example on a previously imported base map (see the dedicated page). This data will be stored and the node and midpoint objects will then be drawn at these locations on the 2D plane.

The lower part of the "Geolocation" tab allows you to process cross sections. This option is close to the previous one in the ideas behind "Compute pxl -> geo" and "Compute geo -> pxl". However, the reference points will be taken for each reach with its upstream node and its downstream node (and not, as previously, the upstream node of the selection and the downstream node of the selection). You must therefore have previously processed them with the options in the upper part of the tab, detailed above. In addition the positions (x-y) of the cross sections will be calculated with the "Compute geo -> pxl" option, and drawn thus just after launching this calculation (clicking on the corresponding button). But since the reaches are drawn on the 2D plane as 2 line segments between the upstream node and the midpoint then the midpoint and the downstream point, and that the cross sections are drawn and distributed on these segments according to their longitudinal abscissa within their reach (the coordinates of the x-y pixels will therefore be recalculated on each display), this detailed plan drawing of the sections will not be drawn like this on subsequent displays.

Further evolution of SIC allowing more segments and potentially as many as cross sections would handle this more aesthetically.

In this management of the geolocation of cross sections, we must also provide other information, since the entire cross section is geolocated (only 1 lat-lon data for each section) and not the various points of the section. However, a section seen up close is not a local object, but made up of a set of points (and can be several hundreds of m or km long). It is therefore necessary to indicate to what point the given geolocation corresponds, as well as how the section is located in relation to this geolocation point, laterally and angularly. The angle is given in relation to a reference indicated in the global geolocation options (Edit/Network Properties/Geolocation Settings), with the choices of Geographic North, the central line of the reach or the segment drawn within the reach . The “lateral abscissa Y” is given in the case of the choice “for a given lateral abscissa”). If we check the boxes for these values they will be filled in for the corresponding objects when launching the "Compute pxl -> geo" calculation. Currently this data is stored but is not taken into account when drawing cross sections (to be done in a later version). For the moment the angle used for the drawing is 90° relative to the segment, and the assumed geolocation point is the central one of the section.

At the bottom of the tab we indicate a scale in X and Y, making the correspondence between lat-lon and x-y. These fields allow you to visualize these scales after using one of the 2 modification options above, but not to force a drawing to a given scale (these are output variables, not calculation inputs). As indicated by the tooltip when positioning the mouse on the corresponding fields, the values indicated are the number of pixels for 1 degree of angle.

An example of geolocalized project is given at:
\dat\ex30_garonne\Garonne_benchmark_MinMoy_v4.xml

Modeling of an in-line pump

Pierre-Olivier Malaterre — 2017-04-27T15:32:39Z

Since version 4.12, an in-line pump can be modeled using a control module. Indeed, a control module is created in this case (with any method adapted to the method that it is desired to use for the variations of the pump discharge, for example the STOP, BOMAT, WDLANG, SCILAB or MATLAB method). At the site of the in-line pump a singular section is placed with a gate-type structure. For this same gate, the opening is declared as control U of the control module, in flow mode (slave controler). See doc on Regulation modules and General settings for U for further details. This solution is probably the best but requires the use of a control module.