doc/en/yacs.rst

   1 .. _yacs:
   2
   3 YACS
   4 ####
   5 .. index:: single: YACS
   6
   7 Using a YACS scheme allows the coupling between a computation and an adaptation as described into :doc:`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!
   8
   9 In this part, an extensive description of a schema YACS is available.
  10
  11 .. note::
  12   The module HOMARD proposes an automatic creation of a schema YASC starting from a defined case. To do that, see :doc:`gui_create_yacs`
  13
  14 Introduction
  15 ************
  16
  17 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:
  18
  19 .. image:: ./images/yacs_01.png
  20    :align: center
  21    :alt: yacs - global view
  22    :width: 530
  23    :height: 281
  24
  25 .. note::
  26   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.
  27
  28 The boxes
  29 *********
  30
  31 The main boxes are:
  32
  33 - DataInit : initialisation of the initial mesh
  34 - Study_Initialisation : launching of the module HOMARD inside SALOME
  35 - Convergence_Loop : gestion of the loop computation/adaptation
  36 - Results : final information
  37
  38 DataInit
  39 ========
  40 .. image:: ./images/yacs_a_01.png
  41    :align: center
  42    :alt: DataInit
  43    :width: 158
  44    :height: 61
  45
  46 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.
  47
  48 .. literalinclude:: ../files/yacs_01.en.xml
  49    :language: xml
  50    :lines: 37-41
  51
  52 Study_Initialisation
  53 ====================
  54 The box Study_Initialisation launches the component HOMARD inside SALOME. It is a block consisted of two parts, that are invariable whatever is the envisaged application:
  55
  56 - StudyCreation : python node
  57 - UpdateStudy : service of the component HOMARD
  58
  59 .. image:: ./images/yacs_b_01.png
  60    :align: center
  61    :alt: Study_Initialisation
  62    :width: 322
  63    :height: 69
  64
  65 The python node StudyCreation initialize the SALOME study that is given through the output:
  66
  67 .. literalinclude:: ../files/yacs_01.en.xml
  68    :language: xml
  69    :lines: 43-59
  70
  71 The service UpdateStudy connects this study to an instance of HOMARD.
  72
  73 .. literalinclude:: ../files/yacs_01.en.xml
  74    :language: xml
  75    :lines: 60-64
  76
  77
  78 Convergence_Loop
  79 =====================
  80 The box Convergence_Loop is type WhileLoop. The condition is initialized with 1: the internal block Alternation_Computation_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 to 0. The loop ends and we pass in the following box, Results.
  81
  82 .. image:: ./images/yacs_c_01.png
  83    :align: center
  84    :alt: Boucle
  85    :width: 192
  86    :height: 141
  87
  88 Results
  89 =======
  90 .. image:: ./images/yacs_d_01.png
  91    :align: center
  92    :alt: Results
  93    :width: 157
  94    :height: 62
  95
  96 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.
  97
  98 .. literalinclude:: ../files/yacs_01.en.xml
  99    :language: xml
 100    :lines: 398-411
 101
 102
 103 Loop for the calculations
 104 *************************
 105 .. image:: ./images/yacs_c_02.png
 106    :align: center
 107    :alt: Boucle
 108    :width: 505
 109    :height: 114
 110
 111 This box is a block that manages the computation, the adaptation and the analysis.
 112
 113 Computation
 114 ===========
 115 .. image:: ./images/yacs_c_03.png
 116    :align: center
 117    :alt: Computation
 118    :width: 158
 119    :height: 90
 120
 121 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.
 122
 123 .. literalinclude:: ../files/yacs_01.en.xml
 124    :language: xml
 125    :lines: 70-90
 126
 127 In this example, we must define:
 128
 129 - rep_calc : the directory in which will be executed the calculation.
 130 - 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 Script from the file ScriptAster.py
 131
 132 The python Script 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", "--num=numCalc", "--mesh_file=MeshFile"]
 133 ].
 134
 135 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:
 136
 137 - "FileName" : the name of the file that contains the results of the calculation
 138 - "V_TEST" : the value the convergence of which we want to test
 139
 140 Adaptation
 141 ==========
 142 .. image:: ./images/yacs_c_04.png
 143    :align: center
 144    :alt: Adaptation
 145    :width: 667
 146    :height: 568
 147
 148 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 Loop_Stop.
 149
 150 Adaptation_HOMARD
 151 -----------------
 152 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 Iter_1.
 153
 154 Iter_1
 155 ^^^^^^
 156 .. image:: ./images/yacs_c_06.png
 157    :align: center
 158    :alt: Iter_1
 159    :width: 481
 160    :height: 151
 161
 162 This box begins by creating the case HOMARD by calling the CreateCase service.
 163
 164 .. literalinclude:: ../files/yacs_01.en.xml
 165    :language: xml
 166    :lines: 200-207
 167
 168 The name of the case CaseName is imposed on "Computation". The name of the case MeshName is imposed on "BOX". The parameters of input FileName arise from the output of the previous calculation. The parameter of output is an instance of case.
 169
 170 .. literalinclude:: ../files/yacs_01.en.xml
 171    :language: xml
 172    :lines: 435-438
 173
 174 .. literalinclude:: ../files/yacs_01.en.xml
 175    :language: xml
 176    :lines: 475-478
 177
 178 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 :doc:`tui_create_case`. In output, we get back the instance of the iteration corresponding to the initial state of the case.
 179
 180 .. literalinclude:: ../files/yacs_01.en.xml
 181    :language: xml
 182    :lines: 208-220
 183
 184 Finally, a hypothesis is created by calling the CreateHypothese service. The parameter of output is an instance of hypothese.
 185
 186 Homard_Exec
 187 ^^^^^^^^^^^
 188 Once initialized, the adaptation can be calculated. It is the goal of the Homard_Exec box, in the form of a script python.
 189
 190 .. image:: ./images/yacs_c_09.png
 191    :align: center
 192    :alt: Homard_Exec
 193    :width: 153
 194    :height: 141
 195
 196 The directory of calculation is recovered. The name of the mesh is given.
 197
 198 .. literalinclude:: ../files/yacs_01.en.xml
 199    :language: xml
 200    :lines: 237-242
 201
 202 ../..
 203
 204 .. literalinclude:: ../files/yacs_01.en.xml
 205    :language: xml
 206    :lines: 317-325
 207
 208 The hypothesis transmitted in input parameter characterized (look :doc:`tui_create_hypothese`) :
 209
 210 .. literalinclude:: ../files/yacs_01.en.xml
 211    :language: xml
 212    :lines: 246-270
 213
 214 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
 215
 216 .. literalinclude:: ../files/yacs_01.en.xml
 217    :language: xml
 218    :lines: 272-282
 219
 220 The iteration is supplemented : hypothesis, future mesh, field (look :doc:`tui_create_iteration`) :
 221
 222 .. literalinclude:: ../files/yacs_01.en.xml
 223    :language: xml
 224    :lines: 284-303
 225
 226 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.
 227
 228 .. literalinclude:: ../files/yacs_01.en.xml
 229    :language: xml
 230    :lines: 305-316
 231
 232 After this execution, the process leaves the Adaptation_HOMARD node, then Adaptation node. One arrives then at the node of analysis.
 233
 234 Iter_n
 235 ^^^^^^
 236 .. image:: ./images/yacs_c_07.png
 237    :align: center
 238    :alt: Iter_n
 239    :width: 323
 240    :height: 92
 241
 242 For the following passing in the block of adaptation, it is necessary to recover:
 243
 244 - the last created iteration: service LastIteration (look :doc:`tui_create_iteration`)
 245 - the created hypothesis: service GetHypothesis (look :doc:`tui_create_hypothese`)
 246
 247 One passes then in the Homard_Exec node to calculate the new mesh.
 248
 249 Loop_Stop
 250 ---------
 251 .. image:: ./images/yacs_c_08.png
 252    :align: center
 253    :alt: Loop_Stop
 254    :width: 161
 255    :height: 151
 256
 257 The Loop_Stop 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:
 258
 259 .. literalinclude:: ../files/yacs_01.en.xml
 260    :language: xml
 261    :lines: 165-176
 262
 263 Analysis
 264 ========
 265 .. image:: ./images/yacs_c_05.png
 266    :align: center
 267    :alt: Analysis
 268    :width: 158
 269    :height: 143
 270
 271 The Analysis block is a script python which ensures the complete control of the process by examining the causes of possible error successively.
 272
 273 .. literalinclude:: ../files/yacs_01.en.xml
 274    :language: xml
 275    :lines: 96-108
 276
 277 ../..
 278
 279 .. literalinclude:: ../files/yacs_01.en.xml
 280    :language: xml
 281    :lines: 154-162
 282
 283 One starts by analyzing the return of the computer code:
 284
 285 .. literalinclude:: ../files/yacs_01.en.xml
 286    :language: xml
 287    :lines: 110-115
 288
 289 Checking of the presence of the name of the result file in the dictionary of the results:
 290
 291 .. literalinclude:: ../files/yacs_01.en.xml
 292    :language: xml
 293    :lines: 117-124
 294
 295 Checking of convergence. That supposes that the value to be tested is present in the dictionary under the key 'V_TEST'. 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.
 296
 297 .. literalinclude:: ../files/yacs_01.en.xml
 298    :language: xml
 299    :lines: 126-146
 300
 301 Lastly, it is checked that a maximum nomber of adaptations is not exceeded:
 302
 303 .. literalinclude:: ../files/yacs_01.en.xml
 304    :language: xml
 305    :lines: 146-151
 306
 307
 308 Use this scheme
 309 ***************
 310 To reproduce this example, download:
 311   * :download:`the scheme <../files/yacs_01.en.xml>`
 312   * :download:`an example of python script <../files/yacs_script.py>`
 313   * :download:`an example of python script ... for nothing <../files/yacs_script_test.py>`
 314
 315 It should be adapted to simulation considered. In particular, it is necessary:
 316
 317 - to adjust the names of the files and the directories
 318 - to provide a script of launching of calculation respecting the instructions evoked herebefore
 319 - to choose the hypothesis of driving of the adaptation
 320 - to set up the test of stop
 321
 322
 323
 324