The BOLST method

- Available translations on this page : français -

The BOLST method is a method for imposing U command changes from a .txt text file (eg, ASCII or ANSI text format). These changes are indicated according to the time at which they are desired. The time is not necessarily at regular time steps. The values will then be used in step mode (visible at the following time step, as for a law depending on the time entered at the interfaces: it is applied at time T and it is visible in the results at time T+DT, so if we want to see it at time T we have to shift it from DT, with Tlag for example) or in ramp mode (linear interpolation, in this case the values will be visible in the results at the indicated times). These are therefore modifications of the Open Loop type, since they are not calculated from controlled variables Y nor from measured variables Z.

Create a .txt command file in ASCII or ANSI or other text format

The text file .txt produced must contain the application times of the command in the first columns and the value of the various U commands in the last column. The formats of time and control are relatively free, or in any case can be indicated with an free format (see below) but must be indicated in FORTRAN format in a BOLST.TXT parameterization file. This time is indicated however in days, months, years, hours, minutes, seconds, even if the format can be chosen. Caution, reading in Fortran format is relatively strict, it is necessary to respect the columns indicated in the format, and decimal points preferably. If you are not used to these formats, it is better to read a documentation on the subject. Otherwise the module may have crashes, or unwanted behaviors.

Various BOLST controllers, each monovariable, can be used, and thus acting on a single control U, but the parameterization file BOLST.TXT is common to all these BOLST controllers, with a configuration line for each BOLST controller.

An example is provided under dat/ex8_bolst, with 2 BOLST modules. One of the 2 files acting on a U command in discharge (file QPRISE_02092001.TXT) contains 4 changes of values:

02:09:2001:00:00:00:0.000          

02:09:2001:05:00:00:-.100          

02:09:2001:15:00:00:0.100          

02:09:2001:21:00:00:0.300

Be careful not to leave empty lines at the bottom of this file, otherwise these lines will be read as if all the numbers are at 0, which will give T=0 and a-priori will create an error message according to which the times are not increasing (or empty line).

The format of the dates and times here is DD:MM:YY:HH:MM:SS, and the variable U in F10.3 format, as indicated on the corresponding line of the BOLST.TXT file with the FORTRAN standard format notations: (2(I2,1X),I4,1X,3(I2,1X),F10.3)

This file must be saved in a named file with a name of its choice, which will be specified in the BOLST.TXT file. In the example provided, there are 2 files: QPRISE_02092001.TXT and HCRUE_G_02092001.TXT located in the same folder as the project XML file. But even if you specify it in the BOLST.TXT file, these files can also be located elsewhere, in one or more other subdirectories, with the command "DIR=":

% This line is optional and ignored if it starts with DIR=DEF

DIR=DEFAUT

But, if you specify a subdirectory with the code "DIR=", then the following files read lower in the BOLST.TXT file will be searched in this other subdirectory. It is necessary to put the full name C:\ ..., or it is possible that it also accepts the relative paths relative to the subdirectory of the data ..\DAT2! It is also possible that under some OS it is necessary to double the \. To test if necessary ... You can put as much command "DIR=" as you want in a file BOLST.TXT, and so the following files will be searched and read in this or these subdirectories.

% In this case the data files of the BOLST modules (QPRISE_02092001.TXT and HCRUE_G_02092001.TXT) will be searched in the C:\DATA\SICBOLST

DIR = C:\DATA\SICBOLST

The latter case allows several SIC projects located in different subdirectories to read the same data files for BOLST modules in one or more subdirectories common to these various SIC projects.

Warning: for versions of Fluvia and Sirene programs compiled with the Digital compiler, the same .TXT file can not be opened simultaneously several times by several modules. In this case it is necessary to duplicate it with different names used by the corresponding BOLST modules (or use a version of Fluvia or Sirene compiled in Intel, this is indicated in the selection of the desired version).

Configuring the BOLST module in SIC

To configure a BOLST module in SIC, you must:

Select the BOLST module in the editing window of the control modules,
Choose the (only one, otherwise the others will be identical to the first one and only one read on the corresponding .txt file) command U. The Y, YT and Z variables are not used in this module because it is a module of Type Open Loop,
Define the specific parameters of the BOLST method.

Specific parameters of the BOLST module

The specific parameters are the same as those of the BOMAT or BOSCI method:

Scaling factor "a" (multiplicative factor, or called "homothety")
Additive constant "b" (then U = ax + b)
Ramp or Step Mode
Write or not the data of the file .txt read on the file Nom_Sirene.lst

Scaling Parameter

This is a multiplier that will be applied to the values in the .txt file before the command is applied.

A second multiplier can be added in the BOLST.TXT file which will multiply to that one to obtain a global modified factor. These coefficients will be written and indicated on the file Nom_Sirene.lst

Constant additive

This additive constant will be added to the value read, possibly modified by the multiplicative factor mentioned above. The variable U injected into the model will therefore be of the form U = ax + b where a is the multiplicative factor, b the additive constant and x the value read on the .TXT file (or rather interpolated for the current time in ramp mode) .

Interpolation method

The two available interpolation methods are the same as those of the laws of time.

Write to LST file

The data read from the .TXT files can be written to the File_Name.lst file to see if it is read correctly. In this case, the format is as follows:

Number of the BOLST    T-Tlag    Tbefore    Tafter    U(1)

BOLST n°    1    -3000.          0.       3600.       2.500

BOLST n°    2   -13800.      -3600.      14400.       0.000

The Number of the BOLST is the number as indicated in the BOLST file (end of the line, cf. bellow).
Tbefore and Tafter are the 2 times played in the .TXT file on 2 consecutive lines that frame or will frame the current time possibly offset by the delay time Tlag: T-Tlag

Restriction

One can have several controllers of this type (BOLST) for a simulation. Each BOLST is monovariable. All BOLST methods retrieve the file name and some parameters on a common BOLST.TXT file:

% We can put comment, with lines beginning by %, ! or /

DIR=DEFAUT                % This line is optional and ignored if starts by DIR=DEF

TLAG=3600.                % This line is optional. It gives a time shift (in s) to apply to the times (in F15.3)

% From version 5.38c3 the scaling factor format changes from 4.1 to 7.3

% The format is then : FORMAT(A20,1X,A36,1X,F7.3,1X,2(I2,1X),I4,1X,3(I2,1X),I2)

HCRUE_G_02092001.TXT      (2(I2,1X),I4,1X,3(I2,1X),F10.3)   1.000 02/09/2001 00:00:00  1

% Time Lag can be different for each BOLST module (as DIR also)

TLAG=14400.                % This line is optional. It gives a time shift (in s) to apply to the times (in F15.3)

QPRISE_02092001.TXT       (2(I2,1X),I4,1X,3(I2,1X),F10.3)   1.000 02/09/2001 01:00:00  2

TLAG= allows to shift the read values in time. If TLAG > 0 a delay is added. If TLAG < 0 change of value is anticipated. One can have several lines of definition of Tlag which will then apply to the files of the BOLST indicated following this line.

In the BOLST.TXT file, there are also as many rows of BOLST modules used to define the parameters of these modules. The format of this file must be respected. In particular it must be found on each line (illustrated in the example provided):

This line is read in the format: (A20,1X,A36,1X,F7.3,1X,2(I2,1X),I4,1X,3(I2,1X),I2)

QPRISE_02092001.TXT: the file name up to 20 characters

(2(I2,1X),I4,1X,3(I2,1X),F10.3): the read format with up to 36 characters

1.000: an additional scaling factor which will multiply to that of the specific parameters of this BOLST module, in F7.3 format.

02/09/2001 01:00:00: a reference time, which will be subtracted from the times read on the lines of the .TXT file, in format 2(I2,1X),I4,1X,3 (I2,1X)

2: the number of the BOLST module, since we can have several ones, in format I2

The number of the BOLST module is the number in the order of the control modules defined in the SIC interfaces. They can be in the natural order 1 to n, which is the most classic or in any order if for one reason or another it is simpler so. We can also put the number 0, for all, in this case they will be applied in the order of the lines read.

In the BOLST.TXT file you can put comment lines that begin with the characters %, ! or / in the first column.

The version of Fluvia and/or Sirene used is free except the above notice on Digital or Intel to have the possibility to use the same .TXT file several times by different BOLST modules.

The formats of the BOLST.TXT file and other files containing the data must be stricktly respected since Fortran programs Fluvia and Sirene are strict when reading such files.

Soon, the date and hour format will be able to be choosen among a large list of standart formats, such as for Matlab for example:

Table 1: Standard MATLAB Date format definitions

Number String =======================================
class='autobr' /> HH:MM:SS’ 01-Mar-2000 15:45:17
01-Mar-2000
03/01/00
Mar
M
03
03/01
01
Wed
W
2000
00
Mar00
15:45:17
3:45:17 PM
15:45
3:45 PM
Q1-96
Q1
01/03
01/03/00
HH:MM:SS’ Mar.01,2000 15:45:17
Mar.01,2000
03/01/2000
01/03/2000
00/03/01
2000/03/01
Q1-1996
Mar2000
2000-03-01
20000301T154517
2000-03-01 15:45:17

Table 2: Free-form date format symbols

Symbol Interpretation of format symbol
=======================================
yyyy full year, e.g. 1990, 2000, 2002
yy partial year, e.g. 90, 00, 02
mmmm full name of the month, according to the calendar locale, e.g.
"March", "April" in the UK and USA English locales.
mmm first three letters of the month, according to the calendar
locale, e.g. "Mar", "Apr" in the UK and USA English locales.
mm numeric month of year, padded with leading zeros, e.g. ../03/..
or ../12/..
m capitalized first letter of the month, according to the
calendar locale; for backwards compatibility.
dddd full name of the weekday, according to the calendar locale, eg.
"Monday", "Tueday", for the UK and USA calendar locales.
ddd first three letters of the weekday, according to the calendar
locale, eg. "Mon", "Tue", for the UK and USA calendar locales.
dd numeric day of the month, padded with leading zeros, e.g.
05/../.. or 20/../..
d capitalised first letter of the weekday; for backwards
compatibility
HH hour of the day, according to the time format. In case the time
format AM | PM is set, HH does not pad with leading zeros. In
case AM | PM is not set, display the hour of the day, padded
with leading zeros. e.g 10:20 PM, which is equivalent to 22:20;
9:00 AM, which is equivalent to 09:00.
MM minutes of the hour, padded with leading zeros, e.g. 10:15,
10:05, 10:05 AM.
SS second of the minute, padded with leading zeros, e.g. 10:15:30,
10:05:30, 10:05:30 AM.
FFF milliseconds field, padded with leading zeros, e.g.
10:15:30.015.
PM set the time format as time of morning or time of afternoon. AM
or PM is appended to the date string, as appropriate.

SIC^2: Simulation and Integration of Control for Canals