SIR file format (SIC version 4.33)

This ASCII file is created by EDISIR or with any ASCII file editor. There are some sections that are handled by SIRENE but not entirely by EDISIR. EDISIR can read and write them but not enter them at the interfaces. These sections must therefore be entered with an ASCII file editor. It contains the hydraulic data for the transient flow calculation program SIRENE. This file is directly the one intended for SIRENE, there is no intermediate binary equivalent unlike the steady flow calculation (DON binary equivalent of the ASCII FLU file).

This file is for the old SIC 4.33 versions or earlier. These files can also be imported from SIC version 5 and later (in interface mode, but not in batch mode). Besides, if you have old SIC version 4 projects you may want to understand this format to enter the corresponding data in a SIC version 5 project. This is the reason why this format, now obsolete, is nevertheless described. Preliminary versions of version 5 used at one time files in this format, to support the transition between version 4 and version 5, but that is not the case anymore.

No special order is followed to write this data file. The various possible line types are described below, each line starting with a particular emblem. However, to import data to an object, this object must already be defined (e.g.: a gate must be defined before entering a time-dependent opening law in it).

This file contains all the hydraulic information needed for the transient flow calculation of the SIRENE program. The geometric data are in separate files, the same ones as for the steady flow. When the unit is not specified the SI units are used.

For the version 4 files all the time laws are understood relatively, that is to say that if there is a gap between the initial value in the initial water surface profile and the value at the initial time of this law, then the values of the law will all be shifted by this gap to have a continuity between the initial regime and the transient one that we want to simulate.

For the version 5 files this way of handling the laws in the calculation has changed and this shifting of the laws is no longer done, the laws then being considered as absolute. This is true for all the laws, except the time-dependent lateral flow laws which are always shifted by the initial gap, if any. For version 5 it is the data editors that handle the possible automatic re-alignment of the laws with respect to the initial values.

Study_title

TITM, VERFIC, IFLAGX, IFLAGQ FORMAT (‘!’, A40, 1X, F5.3, 1X, I1, 1X, I1)

TITM title of the study, VERFIC version of the file (3.0, 3.1, 4.0, 4.32, 4.33, etc.), IFLAGX large chainages mode (0 if no, 1 if yes, i.e. the longitudinal chainages will be multiplied by 1000), IFLAGQ large discharges mode (0 if no, 1 if yes, i.e. the discharges will be multiplied by 1000)

Reaches and Nodes

IB, N1, N2, TITB FORMAT (‘N’, 3I3, A40)

IB reach number, N1 upstream node number of the reach IB, N2 downstream node number of the reach IB, TITB title of the reach

From version 5 on the format is modified as follows: FORMAT (‘N’, 3I3, A40, 2I5, 2F10.5) with the same data as above and 4 new data: IFBPC(I,1), IFBPC(I,2), PCAM(I), PCAV(I) IFBPC(I,1)=1 if equality of the total heads at the upstream, =0 if equality of the elevations, IFBPC(I,2)=1 if equality of the total heads at the downstream, =0 if equality of the elevations, PCAM(I) head loss at the entry of the reach, PCAV(I) head loss at the exit of the reach

Calculation parameters 1

IFLTI, IREP, TREP, IDHA, NEWT, NQUAS, IDISCR FORMAT (‘B’, 1X, I1, 1X, I1, 1X, F10.0, 1X, I1,1X,I1,1X,I3,1X,I1)

IFLTI flag_inertia_term (1: with classical inertia term, 2: local supercritical, 0 global supercritical), IREP flag_continuation_files_res/rcs (0: no), TREP restart_time (hot start) in mn, IDHA index for automatic head loss at the expansions (0: no, 1: yes), this flag is passed on from the one indicated in the .flu file, NEWT = 0 if fixed point, 1 if Newton, 2 if Fixed point + Newton, NQUAS = 0 if pure Newton, N if Quasi-Newton: derivative calculation frequency, IDISCR discretization index (0: classical, 1: homogeneous with the steady one)

From version 5 on the format is modified as follows:

IFLTI, IREP, TREP, IDHA, INISV, NLSV, IDISCR

INISV=0 classical initialization with the value of the previous step, INISV=1 initialization with the variation of the previous step, NLSV=0 linear calculation, NLSV>0 nonlinear calculation, gives the Jacobian update every NLSV iterations

Calculation parameters 2

IPS, IFR, IRCS, DT, TDEB, TFIN, XX, WW, XLAMB, ITER1, ERZ0, ITER2, EPSI FORMAT (‘C’, I3, 1X, 2(I1, 1X), F10.2, 1X, 2(F10.0, 1X), 2(F4.2, 1X), F8.6, 1X, 2(I4, 1X, F8.6))

IPS result_storage_step (every 1 or n calculation steps, to limit the size of the .RES files), IFR regulation_flag (0: without use of a .reg regulation file, 1: with), IRCS full .RCS file flag (0: without creation of this file, 1: with creation of this file which is necessary for a later hot restart, i.e. a transient calculation starting from another transient calculation), DT time_step (in minutes), TDEB start_time of the calculation (in minutes), TFIN end_time of the calculation (in minutes), XX upper_limit of effective_discharge_at_the_offtakes, WW lower_limit of effective_discharge_at_the_offtakes, XLAMB contraction lambda coefficient (0<lambda<=1), ITER1 number of iterations (singular sections, ponds), ERZ0 numerical value of the precision of the nonlinear system, ITER2 number of iterations (oftakes), EPSI maximum error on the local iterations for the offtakes

Initial water surface profile (start_time)

IB, IS, IQL, Q, Z, QL, SK, SKM FORMAT (‘I’, 3I3, 2F10.5, F10.7, 2F10.5) in version 4.32 FORMAT (‘I’, I3, I4, I3, 2F10.5, F10.7, 2F10.5) in version 4.33

IB reach, IS relative_section_number_of_reach, IQL lateral_flow_indicator (0: without lateral flow, 1: with lateral flow), this flag comes from what has been entered in the .flu file, it is what will allow identifying the sections on which to possibly distribute the time-variable lateral flows (cf section below), Q discharge (m3/s), Z elevation (m), QL lateral_flow (m3/s/m, i.e. with a 10-6 factor with respect to what has been entered in the .flu file), SK strickler_medium_bed, SKM Strickler_minor_bed

Weirs or gates

IB, IS, KS, (CSG(NSG, I), I=1, 5), IFOL, ISF FORMAT (‘D’ ou ‘V’, 3I3, 5F13.6, 2I2) in version 4.32 FORMAT (‘D’ ou ‘V’, I3, I4, I3, 5F13.6, 2I2) in version 4.33

IB number of the reach, IS relative_section_number, KS relative_singularity_number, (CSG(NSG, I), I=1, 5) characteristics of the singularity NSG (1 sill_width, 2 sill_elevation, 3 opening, 4 discharge_coef, 5 overflow_height), IFOL = equation (0: Cemagref 88 sill-gate for V or sill-orifice for D, 1: Cunge 80, 2: Classical submerged for V or non-submerged for D, 3: Cemagref 88 sill-orifice for V or sill-gate for D, 4: MatLab, 5: Fortran), ISF = calculation mode (0: nonlinear, 1: linear)

Gec-Alsthom gates

IB, IS, KS, (CSG(NSG, I), I=1, 8), IDNS, IFOL, IFOC, IFLO, ISF FORMAT (‘G’, 3I3, 7F13.6, F7.1, I3, 2I2, I3, I2) in version 4.32 FORMAT (‘G’, I3, I4, I3, 7F13.6, F7.1, I3, 2I2, I3, I2) in version 4.33

IB number of the reach, IS relative_section_number, KS relative_singularity_number, (CSG(NSG, I), I=1, 8) characteristics of the singularity NSG (1 radius, 2 sill_elevation, 3 maximum opening, 4 Zamont_max, 5 decrement, 6 axis_elevation framed with respect to ZMIN, 7 actual opening, 8 ratio S1/S2 free surface / slot surface for AVIS, AVIO and mixed gate bays for Versions >= 4.17), IDNS=shift of the section for Z2 (useful for AVIS, AVIO and mixed gates) in number of computational sections (Versions >= 4.17), IFOL = equation (0: Goussard, 1: Goussard for position and Cemagref for discharge, 2: W given by the user and Cemagref for discharge), IFOC = type (0: Amil, 1: Avio High Head, 2: Avio BC, 3: Avis HC, 4: Avis BC), IFLO = model, ISF = calculation mode (0: nonlinear, 1: linear).

Names of the nodes, sum of discharges and elevations at the nodes

TC(NOMAX), ITN(NOMAX), QAE(NOMAX), ZNO(NOMAX), I FORMAT (‘S’, A6, I3, 2F10.5, 7X, I3)

TC node_name (alphanumeric), ITN node_type = 1 if model_upstream, 2 if intermediate_node, -2 if model_downstream, QAE sum_of_discharges = (Sum_Q_leaving - Sum_Q_arriving) at the non model_downstream node or leakage discharge at the model_downstream node, ZNO sum_of_elevations, I number of the node

Oftakes defined by their geometric characteristics

I, KP(I), KVP(I), QPO(I), QPR(I), X1P(I), X2P(I), X3P(I), X4P(I), X5P(I), X6P(I), X7P(I), X8P(I), X9P(I), IFPL(I) FORMAT (‘P’, 3I3, 2F7.3, F6.2, 3F10.5, 3F6.2, F7.3, F6.2, I2)

I node (non model_upstream and non model_downstream) (KP) offtake_case = 1 Q(t) gate calculate opening W 2 Q(t) weir calculate Z_sill 3 Q(t) weir calculate sill_width 4 gate calculate Q 5 weir Z(t) calculate Q 6 apm calculate Q 7 pipe calculate Q 8 Q(z) calculate Q 9 weir L (t) calculate Q (KVP) offtake_downstream_case = 1 offtake_downstream_elevation constant 2 offtake_downstream_weir 3 offtake_downstream_Q(z)

the Q(z) laws at the offtakes are introduced in analytical form: Q=Q_base*( (Z-Z_sill)/(Z_base-Z_sill) )**exponent

(QPO) offtake_target_discharge (QPR) offtake_actual_discharge (X1P) discharge_coefficient (KP=1, 2, 3, 4, 5, 6, 7, 9) or exponent (KP=8) (X2P) Z_sill (X3P) sill_width (KP=1, 2, 3, 4, 5, 6, 9) or diameter (KP=1, 4, 7) or Q_base (KP=8) (X4P) opening (KP=1, 4, 6) or Z_sill_min (KP=2) or Z_base (KP=8) (X5P) maximum_opening (KP=1, 4 and X5P>0) or indicates circular gate (KP=1, 4 and X5P=0) or Z_sill_max (KP=2) or maximum_sill_width (KP=3) or switch (KP=6, 7, 8) (X6P) offtake_downstream_discharge_coefficient (KVP=2) or offtake_downstream_exponent (KVP=3) (X7P) offtake_downstream_elevation (KVP=1) or offtake_downstream_sill_elevation (KVP=2, 3) (X8P) offtake_downstream_sill_width (KVP=2) or offtake_downstream_Q_base (KVP=3) (X9P) offtake_downstream_Z_base (KVP=3) IFPL = equation (0: Cemagref or 1: Cunge)

Q(z) laws at the model downstream node

I, Z, Q FORMAT (‘A’, I3, 6X, 2F10.3)

I downstream_node, Z downstream_elevation (m), Q downstream_discharge (m3/s)

Display parameters (display)

CODEM, BRANM, NAMEM, NBM, NSM, XLONG, ZREF FORMAT (‘Y’, A1, A8, A6, 2I3, F8.0, F8.2) in version 4.32 FORMAT (‘Y’, A1, A8, A6, I3, I4, F8.0, F8.2) in version 4.33

CODEM code, BRANM branch_name, NOEUDM node_name, NBM reach, NSM relative_section_number, XLONG chainage, ZREF reference_elevation

Variations of the gate openings

IB, IS, KS, IO, T, X, K, L, ITYPOUV FORMAT (‘U’, 4I3, 2F10.3,3I3)

IB reach, IS relative_section_number, KS relative_singularity_number, IO device type: 1 (Weir), 2 (Rectangular gate) and 3 (Gec-Alsthom gate) from version 4.07 included (before version 4.07 only the mobile device gates were handled) T time (mn), X opening, K number of the law, L number of the point of the law, ITYPOUV (0: step, 1: ramp)

Hydrograph or law at the offtake at the non downstream node of the model

CH1, J, T, X, I, L, IOD, NOE, ITYPOFF FORMAT (‘H’, A1, 2X, I3, 3X, 2F10.3, I3, I5, 3I3)

CH1 offtake_law_character: ‘Q’ offtake_discharge, ‘W’ offtake_opening, ‘S’ offtake_switch, ‘L’ offtake_sill_width, ‘Z’ offtake_Z_sill, J non_downstream_node, T time (mn), X law_value, I number of the law, L number of the point of the law, IOD(I) type of offtake, NOE(I,3) calculation mode at the offtake, ITYPOFF (0: step, 1: ramp)

Target discharges

J, T, Q, I, L FORMAT (‘O’, I3, 6X, 2F10.3, 2I3)

J node, T time (mn), Q target_discharge, I number of the law, L number of the point of the law

Pond (S(z) law at the node)

I, Z, S, X FORMAT (‘K’, I3, 6X, 3F10.3)

I node, Z elevation, S surface area (ha), X evaporation_rate (cm/day)

Lateral hydrograph (handled by Sirene but not by Edisir)

This section allows making the infiltration - evaporation term evolve (if the term is negative) or the inflow term (if the term is positive) as a function of time. In steady flow, this term was a constant, possibly different for each computational section. The value entered for the steady flow was expressed in l/s/km. In transient flow, this term can be defined as a function of time. The value entered is a total discharge (in m3/s) for the reach considered. This discharge will be distributed over the zones within the reach for which there is a lateral flow, proportionally to their lengths. A priori, by default, these zones correspond to the ones thus defined in steady flow. But it is possible to modify them by putting 0s or 1s in the corresponding column of the “I” lines of the .SIR file. The discharge is not modulated proportionally to the initial lateral flows. It will be distributed homogeneously over all the zones having a lateral flow. We therefore assume that in the reach there are zones with and zones without lateral flow, and that, in the zones where there is a lateral flow, the rate of lateral inflow or of lateral loss is identical over all these zones (in discharge/length unit). If this is not the case this reach must be split into several reaches.

If the total initial lateral flow indicated in this lateral hydrograph for this reach is not equal to the total initial lateral flow coming from the steady flow calculation, the hydrograph will be translated to ensure the continuity at the start between the steady flow and the transient regime. This is true for the version 4 of SIC but also for the version 5.

However, it is not possible, for the moment, to enter an infiltration - evaporation term as a function of the water depth. This can possibly be modeled approximately by a succession of offtakes in discharge calculation mode. This limitation seems to us not very constraining in the measure where an estimation of the infiltration - evaporation term is very delicate with a very important uncertainty factor and it is illusory to consider that a q=f(z) law will give a more realistic model.

This “time-dependent lateral hydrograph” section will soon be handled entirely by Edisir (entry at the graphic interfaces) in a later version. Edisir already allows reading and writing it to file, but not filling it through the interfaces (since version 3.8). Sirene handles it perfectly at the calculation level.

IB, K, T, Q FORMAT (‘L’, 2I3, 3X, 2F10.3)

IB reach number, K step (0) or ramp (1) flag T time (mn), Q lateral_flow (m3/s)

Limnigraph at the model downstream node (handled by Sirene but not by Edisir)

This section allows replacing the Q(z) law entered for the steady flow calculation by a z(t) law allowing for example to represent the downstream influence of a tide.

To be handled by Edisir in a later version. Edisir already allows reading and writing it to file, but not filling it through the interfaces.

The z values are handled relatively with respect to the first value. For example, if you want to increase the z elevation by 1m at the instant 2h=120mn, it is enough to enter:

Z 2 0 0.000 0.000 Z 2 0 120.000 1.000

Attention: if you enter a z(t) law you must remember to remove the Q(z) law because otherwise it will be kept because it is prioritary with respect to the z(t). A Q(z) law is also prioritary with respect to a pond that would close the channel. If this pond is entered from the interfaces, then the Q(z) will be correctly removed from the .SIR file. However, if this pond is entered by hand directly in the .SIR file then you must remember to remove the Q(z) so that it is no longer used.

The calculation with a z(t) is much faster than with a Q(z) because there are no nonlinear iterations for the calculation at the downstream node. However, this z(t) downstream condition is sometimes considered as “hard” hydraulically and can generate oscillations on the discharges in this zone, for example in the case where an upstream hydrograph arrives at a downstream node with a constant z(t). This z(t) downstream condition is indeed not very physical because the “surface pin” does not exist. The tide is physical but is not a simple imposition of an elevation, but a process that also links the discharges and the elevations via complex physical processes. In the case of a downstream sinusoidal z(t) mimicking a tide there is, a priori, no spurious oscillation.

Even if this is possible at the .SIR file level, it is not recommended to have both a pond and a z(t) for the same downstream node. In this case we would impose the discharge as well as the elevation, which causes numerical problems. In a later version this mode will be explicitly forbidden and in this case the z(t) will be effective and the pond inoperative.

I, K, T, Z

FORMAT (‘Z’, 2I3, 3X, 2F10.3)

I number of the downstream_node, K step (0) or ramp (1) flag [option since version 3.7] T time (mn), Z downstream_elevation