doc/en/yacs.rst

   1 .. _yacs:
   2
   3 YACS
   4 ####
   5 .. index:: single: yacs
   6
   7 Introduction
   8 ************
   9
  10 Using a YACS scheme allows the coupling between a computation and an adaptation as described into :ref:`intro`. This coupling can be repeated inside a loop as long as a criteria for the convergence is reached for instance. Many ways are available to program a YACS scheme. The solution that is shown here is correct but many others are too!
  11
  12 Here is the description of a scheme for a computation in which a value is to be stabilized. The computation starts over an initial mesh, then HOMARD makes an adaptation. A new computation is done over this new mesh and its result is analyzed. Depending on this analysis, the coupling goes on or does not. The general look of the scheme is this one:
  13
  14 .. image:: ../images/yacs_01.png
  15    :align: center
  16    :alt: yacs - allure générale
  17    :width: 535
  18    :height: 362
  19
  20 .. note::
  21   Among all the treated data, certain are unchanging: the name of the directory of calculation, the name of the case, the name of the hypothesis of adaptation, etc. It was chosen to impose them 'hard' in the various parameters of service or within the scripts python. We could also define them a priori in a node PresetNode and then pass on them by links. We did not hold this solution because it increases strongly the number of parameters and links attached to every node. It is very penalizing for the legibility of the scheme. The only data which are going to circulate are the ones been imperative by the description of the service and those that evolve during the execution of the scheme.
  22
  23 The boxes
  24 *********
  25
  26 The main boxes are:
  27
  28 - DataInit : initialisation of the initial mesh
  29 - Etude_Initialisation : launching of the module HOMARD inside SALOME
  30 - Tant_que_le_calcul_n_a_pas_converge : gestion of the loop computation/adaptation
  31 - Bilan : final information
  32
  33 DataInit
  34 ========
  35 .. image:: ../images/yacs_a_01.png
  36    :align: center
  37    :alt: DataInit
  38    :width: 158
  39    :height: 61
  40
  41 This box is type PresetNode's elementary node. Its only function is to initialize the variable MeshFile that contains the name of the file of the initial mesh.
  42
  43 .. literalinclude:: ../files/yacs_01.xml
  44    :lines: 38-42
  45
  46 Etude_Initialisation
  47 ====================
  48 The box Etude_Initialisation launches the component HOMARD inside SALOME. It is a block consisted of two parts, that are invariable whatever is the envisaged application:
  49
  50 - StudyCreation : python node
  51 - SetCurrentStudy : service of the component HOMARD
  52
  53 .. image:: ../images/yacs_b_01.png
  54    :align: center
  55    :alt: Etude_Initialisation
  56    :width: 323
  57    :height: 97
  58
  59 The python node StudyCreation initialize the SALOME study that is given through the output:
  60
  61 .. literalinclude:: ../files/yacs_01.xml
  62    :lines: 44-62
  63
  64 The service SetCurrentStudy connects this study to an instance of HOMARD.
  65
  66 .. literalinclude:: ../files/yacs_01.xml
  67    :lines: 63-68
  68
  69
  70 Tant_que_le_calcul_n_a_pas_converge
  71 ===================================
  72 The box Tant_que_le_calcul_n_a_pas_converge is type WhileLoop. The condition is initialized in 1: the internal block Alternance_Calcul_HOMARD is executed. Within this block, we calculate and we adapt the mesh; when the process has to stop either as a result of error, or by convergence, the condition passes in 0. The loop ends and we pass in the following box, Bilan.
  73
  74 .. image:: ../images/yacs_c_01.png
  75    :align: center
  76    :alt: Boucle
  77    :width: 195
  78    :height: 142
  79
  80 Bilan
  81 =====
  82 .. image:: ../images/yacs_d_01.png
  83    :align: center
  84    :alt: Bilan
  85    :width: 158
  86    :height: 63
  87
  88 This box is a node python that takes in input a character string, MessInfo. If everything passed well, this message is empty. A window QT appears to confirm the convergence. If there was a problem, the message contains messages emitted during the calculations. The window QT shows this message.
  89
  90 .. literalinclude:: ../files/yacs_01.xml
  91    :lines: 424-437
  92
  93
  94 Loop for the calculations
  95 *************************
  96 .. image:: ../images/yacs_c_02.png
  97    :align: center
  98    :alt: Boucle
  99    :width: 323
 100    :height: 158
 101
 102 This box is a block that manages the computation, the adaptation and the analysis.
 103
 104 Calcul
 105 ======
 106 .. image:: ../images/yacs_c_03.png
 107    :align: center
 108    :alt: Calcul
 109    :width: 155
 110    :height: 87
 111
 112 This box is a node python that is going to drive the calculation. In input, we find the number of the calculation (0 at first) and the name of the file which contains the mesh on which to calculate. In output, we find an integer which represents the error on this calculation (0 so everything goes well) and a dictionary python gathering the results of the calculation. The body of the node is established by the launch of a script python that activates the calculation.
 113
 114 .. literalinclude:: ../files/yacs_01.xml
 115    :lines: 77-104
 116
 117 In this example, we must define:
 118
 119 - rep_calc : the directory in which will be executed the calculation.
 120 - rep_script : the directory in which is the python that will launch the calculation. This directory is to be added to the PATH. From this directory, we shall import LanceCas from the file LanceCas.py
 121
 122 The python LanceCas is programmed as the user wishes it so that the calculation can be made on the current mesh. According to the mode of launch of the code of calculation, we can need other information, as the number of the calculation or the directory of the calculation for example. The freedom is total. In our case, the arguments of input are the name of the file of mesh, the number of the calculation and the directory of calculation. They are given in a list python: ["--rep_calc=rep_calc", "--numero=numCalc", "--mesh_file=MeshFile"]
 123 ].
 124
 125 On the other hand the output of the script has to obey the following rule. We get back a code of error, an error message and a dictionary. This dictionary contains necessarily the following keys:
 126
 127 - "FileName" : the name of the file that contains the results of the calculation
 128 - "MeshName" : the name of the used mesh
 129 - "V00" : the value the convergence of which we want to test
 130
 131 Adaptation
 132 ==========
 133 .. image:: ../images/yacs_c_04.png
 134    :align: center
 135    :alt: Adaptation
 136    :width: 672
 137    :height: 569
 138
 139 The box Adaptation is a Switch node driven by the code of error of the previous calculation. If this code is nil, YACS will activate the box Adaptation_HOMARD that will launch the adaptation. If the code is not nil, we pass directly in the box Arret_boucle.
 140
 141 Adaptation_HOMARD
 142 -----------------
 143 The first task tries to execute concern the initialization of the data necessary for HOMARD in the box HOMARD_Initialisation. This box is a switch node driven by the number of the calculation. In the starting up, the number is nil and YACS activates the box Homard_init_au_debut.
 144
 145 Homard_init_au_debut
 146 ^^^^^^^^^^^^^^^^^^^^
 147 .. image:: ../images/yacs_c_06.png
 148    :align: center
 149    :alt: Homard_init_au_debut
 150    :width: 481
 151    :height: 150
 152
 153 This box begins by creating the case HOMARD by calling the CreateCase service.
 154
 155 .. literalinclude:: ../files/yacs_01.xml
 156    :lines: 220-227
 157
 158 The name of the case CaseName is imposed on "Calculation". The parameters of input MeshName and FileName arises from the output of the previous calculation. The parameter of output is an instance of case.
 159
 160 .. literalinclude:: ../files/yacs_01.xml
 161    :lines: 461-464
 162
 163 The options of this case must be now given. It is made by the node python CaseOptions. It is imperative to give the directory of calculation. We shall look at the description of the functions in:ref: ' tui_create_case '. In output, we get back the instance of the iteration corresponding to the initial state of the case.
 164
 165 .. literalinclude:: ../files/yacs_01.xml
 166    :lines: 228-242
 167
 168 Finally, a hypothesis is created by calling the CreateHypothèse service. The parameter of output is an instance of hypothese.
 169
 170 Homard_Exec
 171 ^^^^^^^^^^^
 172 Once initialized, the adaptation can be calculated. It is the goal of the Homard_Exec box, in the form of a script python.
 173
 174 .. image:: ../images/yacs_c_09.png
 175    :align: center
 176    :alt: Homard_Exec
 177    :width: 153
 178    :height: 141
 179
 180 The directory of calculation is recovered.
 181
 182 .. literalinclude:: ../files/yacs_01.xml
 183    :lines: 258-263
 184
 185 ../..
 186
 187 .. literalinclude:: ../files/yacs_01.xml
 188    :lines: 339-347
 189
 190 The hypothesis transmitted in input parameter characterized (look :ref:`tui_create_hypothese`) :
 191
 192 .. literalinclude:: ../files/yacs_01.xml
 193    :lines: 267-291
 194
 195 It is necessary to establish a name for the future iteration. To make sure that the name was never used, one installs a mechanism of incremental naming starting from the name of the initial iteration. As this initial name is the name of the initial mesh, one obtains a succession of names in the form: M_001, M_002, M_003, etc
 196
 197 .. literalinclude:: ../files/yacs_01.xml
 198    :lines: 293-303
 199
 200 The iteration is supplemented : hypothesis, future mesh, field (look :ref:`tui_create_iteration`) :
 201
 202 .. literalinclude:: ../files/yacs_01.xml
 203    :lines: 305-325
 204
 205 The iteration is calculated. If it were correct, variable OK equals 1: one will be able to continue the execution of the scheme. If there were a problem, variable OK equals 0 to mean that calculation must stop; an error message then is given.
 206
 207 .. literalinclude:: ../files/yacs_01.xml
 208    :lines: 327-338
 209
 210 After this execution, the process leaves the Adaptation_HOMARD node, then Adaptation node. One arrives then at the node of analysis.
 211
 212 Homard_init_ensuite
 213 ^^^^^^^^^^^^^^^^^^^
 214 .. image:: ../images/yacs_c_07.png
 215    :align: center
 216    :alt: Homard_init_ensuite
 217    :width: 323
 218    :height: 97
 219
 220 For the following passing in the block of adaptation, it is necessary to recover:
 221
 222 - the last created iteration: service LastIteration (look :ref:`tui_create_iteration`)
 223 - the created hypothesis: service GetHypothesis (look :ref:`tui_create_hypothese`)
 224
 225 One passes then in the Homard_Exec node to calculate the new mesh.
 226
 227 Arret_boucle
 228 ------------
 229 .. image:: ../images/yacs_c_08.png
 230    :align: center
 231    :alt: Arret_boucle
 232    :width: 163
 233    :height: 152
 234
 235 The Arret_boucle block is present to only make forward variables because the input parameters of the nodes must always be filled. It is a very simple python:
 236
 237 .. literalinclude:: ../files/yacs_01.xml
 238    :lines: 185-196
 239
 240 Analyse
 241 =======
 242 .. image:: ../images/yacs_c_05.png
 243    :align: center
 244    :alt: Analyse
 245    :width: 155
 246    :height: 169
 247
 248 The Analyse block is a script python which ensures the complete control of the process by examining the causes of possible error successively.
 249
 250 .. literalinclude:: ../files/yacs_01.xml
 251    :lines: 105-118
 252
 253 ../..
 254
 255 .. literalinclude:: ../files/yacs_01.xml
 256    :lines: 173-182
 257
 258 One starts by analyzing the return of the computer code:
 259
 260 .. literalinclude:: ../files/yacs_01.xml
 261    :lines: 120-125
 262
 263 Checking of the presence of the name of the mesh in the dictionary of the results:
 264
 265 .. literalinclude:: ../files/yacs_01.xml
 266    :lines: 127-134
 267
 268 Checking of the presence of the name of the result file in the dictionary of the results:
 269
 270 .. literalinclude:: ../files/yacs_01.xml
 271    :lines: 136-143
 272
 273 Checking of convergence. That supposes that the value to be tested is present in the dictionary under the key 'V00'. Here, one set up a test on the variation of the value of one calculation at the other. With the first passage, nothing is tested. In the following passing, one tests if the relative variation is lower than 1 thousandths. One could have set up an absolute test if one had recovered a total level of error for example.
 274
 275 .. literalinclude:: ../files/yacs_01.xml
 276    :lines: 145-163
 277
 278 Lastly, it is checked that a maximum nomber of adaptations is not exceeded:
 279
 280 .. literalinclude:: ../files/yacs_01.xml
 281    :lines: 165-170
 282
 283
 284 Use this scheme
 285 ***************
 286 To reproduce this example, download:
 287   * :download:`the scheme <../files/yacs_01.xml>`
 288   * :download:`an example of python script <../files/yacs_script.tgz>`
 289
 290 It should be adapted to simulation considered. In particular, it is necessary:
 291
 292 - to adjust the names of the files and the directories
 293 - to provide a script of launching of calculation respecting the instructions evoked herebefore
 294 - to choose the hypothesis of driving of the adaptation
 295 - to set up the test of stop
 296
 297
 298
 299