English Français

Documentation / User's manual in Python : PDF version

Chapter IV. The Launcher module

Chapter IV. The Launcher module

Abstract

This part describes the Launcher module whose main goal is to run code on the design-of-experiments defined thanks to the Sampler module.
The source files are stored in souRCE.git/launCHER/souRCE and the corresponding namespace is URANIE::Launcher.

IV.1. Introduction

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

IV.1.1. Presentation

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:

  1. the input files where the variables under study stand;

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

IV.1.2. Overview of a simple case

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

IV.1.2.1. Presentation of the problem

This problem is handled in [fang2005design], page 35, with the mathematical formula to be treated.

Figure IV.1. Sketch of the flowrate problem and its variables[BoreHole].

Sketch of the flowrate problem and its variables[BoreHole].

Equation IV.1. Flowrate function


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.

  1. : radius of borehole

  2. : radius of influence

  3. : Transmitivity of the superior layer of water

  4. : Transmitivity of the inferior layer of water

  5. : Potentiometric "head" of the superior layer of water

  6. : Potentiometric "head" of the inferior layer of water

  7. : length of borehole

  8. : hydraulic conductivity of borehole

This example has been treated by several authors in the dedicated literature, for instance in [worley1987deterministic].

IV.1.2.2. Case of an analytic function

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;
}

IV.1.2.3. Case of an external code

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.

IV.1.2.3.1. Flowrate input files
IV.1.2.3.1.1. Input files with "key=value" format

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.

IV.1.2.3.1.2. Input files with flag format

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.

IV.1.2.3.1.3. Input files with values in rows

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

IV.1.2.3.2. Flowrate output files

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;
    

/language/en