Documentation
/ User's manual in C++
: 
| Chapter IV. The Launcher module | ||
|---|---|---|
 |  | |
This chapter introduces the launcher module whose purpose is to get a complete response surface from a design-of-experiments. This can be done using the relauncher module as well (see Chapter VIII) whose goals are the same. The main difference lies in the way they both are dealing with parallelisation of computation: the launcher module relies on an automatic detection of a possible cluster Section IV.4 whereas the relauncher is designed for a local parallelisation (on the current machine with different technologies, as explained in Section VIII.4).
We present in this chapter the features of Uranie, related to the assessment of a design-of-experiments (matrix of
"
") to construct the output
variables (matrix of "
"). Uranie
can manage two kinds of computations: analytic functions and external codes.
In the first case of an analytic computation (Section IV.2), an analytic formula is used to compute outputs from inputs.
In the second case, Uranie calls an external computational code (Section IV.3). The definition of the code must contain:
the input files where the variables under study stand;
output files containing the computational results .
Input and output files can have multiple data storage formats (see Section IV.3.1).
Moreover, the code assessment can be either sequential or distributed (Section IV.4). In both cases, the same Uranie macro will be used.
To illustrate these features, let us consider the definition of the flowrate problem, that we will implement as an analytic function (see Section IV.1.2.2) as well as an external code (see Section IV.1.2.3).
This problem is handled in [fang2005design], page 35, with the mathematical formula to be treated.
![Sketch of the flowrate problem and its variables[BoreHole].](https://uranie.cea.fr/images/BoreholeIllustration)
The eight parameters shown both in Figure IV.1 and in equation Equation IV.1 are introduced below by describing their meaning along with their underlying hypothesis, bearing in mind that it is common, in the Uranie context, to remind in the statistical approach.
: radius of borehole
: radius of influence
: Transmitivity of the superior layer of water
: Transmitivity of the inferior layer of water
: Potentiometric "head" of the superior layer of water
: Potentiometric "head" of the inferior layer of water
: length of borehole
: hydraulic conductivity of borehole
This example has been treated by several authors in the dedicated literature, for instance in [worley1987deterministic].
We will focus on the flowrate benchmark (cf Section IV.1.2.1) to present the use of Uranie with an analytic function. In this case, the analytic function must be written with "C" format according to the following prototype:
void myFunction (Double_t *param, Double_t *res)
It is the classical prototype of ROOT for these objects TF1, TF2 and TF3. The flowrate function is written in the
macro file "UserFunctions.C" which can be found in
${URANIESYS}/share/uranie/macros and which looks like this:
#include "TMath.h"
void flowrateModel(double *x, Double_t *y)
{
Double_t drw = x[0], dr = x[1];
Double_t dtu = x[2], dtl = x[3];
Double_t dhu = x[4], dhl = x[5];
Double_t dl = x[6], dkw = x[7];
Double_t dnum = 2.0 * TMath::Pi() * dtu * ( dhu -dhl);
Double_t dlnronrw = TMath::Log( dr / drw);
Double_t dden = dlnronrw * ( 1.0 + ( 2.0 * dl * dtu ) / ( dlnronrw * drw * drw * dkw) + dtu / dtl );
y[0] = dnum / dden;
}
It is assumed that the code can be executed by the user; we will deal with the setup of the code on the machines
the user will use. Moreover, the environment variables PATH and
LD_LIBRARY_PATH must be properly set up to allow the execution of ROOT and/or Uranie
and/or any commands needed for the execution of the computational code.
Here we do not have an analytic function like described above anymore, but a computational code with its input files, with output variables being stored in ASCII files; these will be called output files.
We use the flowrate benchmark (cf Section IV.1.2.1) as this
computational code for this example. Users must give to the code the appropriate input files. The binary
corresponding to the benchmark, also named flowrate, is available in the bin directory of Uranie
installation directory. Users can see options of flowrate by executing the command flowrate -h.
flowrate -h Usage: flowrate [-d] [-s] [-k|-f|-r|-kf|-ff] [-h|-?] [file] -d: debug mode -s: silent mode -k: input file with keys [flowrate_input_with_keys.in] -f: input file with flags [flowrate_input_with_flags.in] -r: input file with only values in rows [flowrate_input_with_values_rows.in] -kf: input file with keys with failure mode [flowrate_input_with_keys.in] -ff: input file with flags with failure mode [flowrate_input_with_flags.in] -h,-?: this help message
-d option allows to give some intermediate values to users while executing flowrate, such as values read in input files, or to show steps or information in execution (opening of input files, number of lines of these input files...).
-s silent mode.
-k and -kf options allow to simulate the launch of flowrate with data files of "key=value" format (see Section IV.1.2.3.1.1). The -k simply executes the flowrate code. The -kf allows to determine a set of values for which flowrate is considered in failure. If user does not specify an input file, flowrate will look for both options the input file flowrate_input_file_with_keys.in whom "key=value" format is described below.
In the same way, -f and -ff options allow to simulate the launch of flowrate code with files with flags (see Section IV.1.2.3.1.2). When -f allows a simple execution of flowrate, -ff allows to simulate a code failure for a specific set of data. If the user does not specify an input file, flowrate will look for the input file flowrate_input_file_with_flags.in whom "flags" format is described below.
-r option allows to simulate the launch of flowrate code with files with values in rows (see Section IV.1.2.3.1.3). The default input file is flowrate_input_with_values_rows.in whom "values in rows" format is described below.
There are eight mandatory input variables (
, 
, 
,
, 
, 
, 
, 
)
described in (Section IV.1.2.1). User can also defines three
optional variables chu, chl and cr which allow to calculate a variable called d which is
written in output files. However, these three values have an incidence on the execution of flowrate only with
-kf and -ff options. The formula used to calculate d is the following:
d=(Hu - chu)*( Hu - chu) + (Hl - chl)*( Hl - chl)
This equality means d is the squared radius of the circle C of centre (chu,chl).
If -kf or -ff options are used, flowrate tests if
d < cr
i.e. we consider couples of values (hu,hl) which are inside the circle C as a set of values where flowrate fails. If this inequality is verified, flowrate crashes and no output file is produced. Without these options (-kf and -ff), this inequality is not checked.
In this section, we describe the file flowrate_input_with_keys.in. Executing flowrate with
options -k and -kf without specifying any input file, means that
flowrate_input_with_keys.in is taken as a default entry. If the user creates "*.in" input
files, the hereafter format must be kept, with the same variables names (, , , , , , , ).
# # # INPUT FILE with KEYS for the "FLOWREATE" code # \date 2008-04-22 12:53:35 # date = 123456 ; ######################### ## ## exclude points ## chu = 1050; chl = 770; cr = 1100; ## ######################### ######################### ## ## parameters : 8 ## Rw = 0.0500 ; R = 33366.67 ; Tu = 63070.0 ; Tl = 116.00 ; Hu = 1110.00 ; Hl = 768.57; L = 1200.0 ; Kw = 11732.14 ; ## ######################### ######################### ## ## to simulate CPU time ## ## normal 1 : ## min 10000000 : 1.160u 0.000s 0:01.16 100.0% ## max 100000000 : 11.600u 0.010s 0:11.61 100.0% ## nLoop = 1; ## ######################### end = 6;
When using this kind of input files, Uranie is able to make the parameters values vary so as to launch the code multiple times with different values. Note that all the variables of this file are not modified: the date and nLoop variables will remain unchanged during the study.
In this section, we describe the file flowrate_input_with_flags.in. Executing flowrate with options -f and -ff without specifying any input file, means that flowrate_input_with_flags.in is taken as a default entry. In the same way as for files with "key=value" format, if the user wants to create a "*.in" input files with "flag" format, the same format has to be kept as for the file flowrate_input_with_flags.in.
On the contrary of the "key=value" format, changes are necessary for Uranie to be able to modify the values. For example, if one has the following input file:
#
# INPUT FILE with FLAG for the "FLOWREATE" code
# \date 2008-04-22 12:55:17
#
new Implicit_Steady_State sch {
frottement_paroi { 0.071623 19712.541454 } // values of Rw and R
tinit 0.0
tmax 1000000.
nb_pas_dt_max 1500
dt_min 1051.972855 // value of Hu
dt_max 805.249178 // value of Hl
facsec 1000000.
kW 11401.611060 // value of Kw
information_Tu Champ_Uniforme 1 85927.853162 // value of Tu
information_Tl Champ_Uniforme 1 85.803614 // value of Tl
information_L {
precision 1162.689830 // value of L
}
convergence {
criterion relative_max_du_dt
precision 1.e-6
}
stop_criterium {
ch_abcsissa_hu 1050
ch_ordinate_hl 770
c_radius 1100
}
Solveur Newton3 {
max_iter_matrice 1
max_iter_implicite 1
date 5654321
seuil_convg_implicite 1.e-6
assemblage_implicite 10
solveur_lineaire BiCGS
preconditionneur ILU
seuil_resol_implicite 1.e-5
}
}
and one wants to change some values, then one shall replace these values with "flags", hinted with special characters. For example one can replace the values with their names surrounded by "@":
#
# INPUT FILE with FLAG for the "FLOWREATE" code
# \date 2008-04-22 12:55:17
#
new Implicit_Steady_State sch {
frottement_paroi { @Rw@ @R@ }
tinit 0.0
tmax 1000000.
nb_pas_dt_max 1500
dt_min @Hu@
dt_max @Hl@
facsec 1000000.
kW @Kw@
information_Tu Champ_Uniforme 1 @Tu@
information_Tl Champ_Uniforme 1 @Tl@
information_L {
precision @L@
}
convergence {
criterion relative_max_du_dt
precision @Rw@
}
stop_criterium {
ch_abcsissa_hu 1050
ch_ordinate_hl 770
c_radius 1100
}
Solveur Newton3 {
max_iter_matrice 1
max_iter_implicite 1
date 5654321
seuil_convg_implicite 1.e-6
assemblage_implicite 10
solveur_lineaire BiCGS
preconditionneur ILU
seuil_resol_implicite 1.e-5
}
}
This file is not directly (without Uranie) exploitable by the flowrate code anymore (contrary to the file flowrate_input_with_keys.in) because flags are not numerical values. Therefore, the flags we have in the modified file, such as @Rw@ for the variable rw or @R@ for the variable r, have to be replaced by numerical values before it becomes usable.
We describe here the shape of the default file flowrate_input_with_values_rows.in searched
by flowrate with the -r option. Typically, the expected input file looks like the following:
eight values which are the values of the eight variables defined above (, , , , , , , ). To define the three
optional variables, users must add three values just after other values. In the contrary, the three default
values are respectively chu=1050, chl=770 and
cr=1100.
0.0500 33366.67 63070.0 116.00 1110.00 768.57 1200.0 11732.14
The flowrate code generates two output files:
_output_flowrate_withRow_.dat: file with "column" format and with a header containing the names of the cost variable and the d variable. Then, the values of the cost variable and the d variable are displayed.
#COLUMN_NAMES: yhat | d 6.757218e+01 4.092561e+03
_output_flowrate_withKey_.dat: file with "key=value" format without an header;
yhat = 6.757218e+01; d = 4.092561e+03;
| | | |
| III.7. The Vectorial Quantification method |  | IV.2. Analytic function |