]> SALOME platform Git repositories - modules/homard.git/blob - doc/en/yacs.rst
Salome HOME
Revert "Synchronize adm files"
[modules/homard.git] / 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 :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!
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 :ref:`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 - allure générale
22    :width: 512
23    :height: 306
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 - Etude_Initialisation : launching of the module HOMARD inside SALOME
35 - Boucle_de_convergence : gestion of the loop computation/adaptation
36 - Bilan : 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    :lines: 38-42
50
51 Etude_Initialisation
52 ====================
53 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:
54
55 - StudyCreation : python node
56 - SetCurrentStudy : service of the component HOMARD
57
58 .. image:: ../images/yacs_b_01.png
59    :align: center
60    :alt: Etude_Initialisation
61    :width: 323
62    :height: 97
63
64 The python node StudyCreation initialize the SALOME study that is given through the output:
65
66 .. literalinclude:: ../files/yacs_01.en.xml
67    :lines: 44-62
68
69 The service SetCurrentStudy connects this study to an instance of HOMARD.
70
71 .. literalinclude:: ../files/yacs_01.en.xml
72    :lines: 63-68
73
74
75 Boucle_de_convergence
76 =====================
77 The box Boucle_de_convergence 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.
78
79 .. image:: ../images/yacs_c_01.png
80    :align: center
81    :alt: Boucle
82    :width: 163
83    :height: 93
84
85 Bilan
86 =====
87 .. image:: ../images/yacs_d_01.png
88    :align: center
89    :alt: Bilan
90    :width: 158
91    :height: 63
92
93 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.
94
95 .. literalinclude:: ../files/yacs_01.en.xml
96    :lines: 406-419
97
98
99 Loop for the calculations
100 *************************
101 .. image:: ../images/yacs_c_02.png
102    :align: center
103    :alt: Boucle
104    :width: 338
105    :height: 152
106
107 This box is a block that manages the computation, the adaptation and the analysis.
108
109 Calcul
110 ======
111 .. image:: ../images/yacs_c_03.png
112    :align: center
113    :alt: Calcul
114    :width: 155
115    :height: 87
116
117 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.
118
119 .. literalinclude:: ../files/yacs_01.en.xml
120    :lines: 77-103
121
122 In this example, we must define:
123
124 - rep_calc : the directory in which will be executed the calculation.
125 - 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
126
127 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"]
128 ].
129
130 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:
131
132 - "FileName" : the name of the file that contains the results of the calculation
133 - "V_TEST" : the value the convergence of which we want to test
134
135 Adaptation
136 ==========
137 .. image:: ../images/yacs_c_04.png
138    :align: center
139    :alt: Adaptation
140    :width: 661
141    :height: 566
142
143 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.
144
145 Adaptation_HOMARD
146 -----------------
147 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.
148
149 Iter_1
150 ^^^^^^
151 .. image:: ../images/yacs_c_06.png
152    :align: center
153    :alt: Iter_1
154    :width: 481
155    :height: 151
156
157 This box begins by creating the case HOMARD by calling the CreateCase service.
158
159 .. literalinclude:: ../files/yacs_01.en.xml
160    :lines: 208-215
161
162 The name of the case CaseName is imposed on "Calcul". 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.
163
164 .. literalinclude:: ../files/yacs_01.en.xml
165    :lines: 443-446
166
167 .. literalinclude:: ../files/yacs_01.en.xml
168    :lines: 483-486
169
170 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.
171
172 .. literalinclude:: ../files/yacs_01.en.xml
173    :lines: 216-228
174
175 Finally, a hypothesis is created by calling the CreateHypothese service. The parameter of output is an instance of hypothese.
176
177 Homard_Exec
178 ^^^^^^^^^^^
179 Once initialized, the adaptation can be calculated. It is the goal of the Homard_Exec box, in the form of a script python.
180
181 .. image:: ../images/yacs_c_09.png
182    :align: center
183    :alt: Homard_Exec
184    :width: 153
185    :height: 141
186
187 The directory of calculation is recovered. The name of the mesh is given.
188
189 .. literalinclude:: ../files/yacs_01.en.xml
190    :lines: 245-250
191
192 ../..
193
194 .. literalinclude:: ../files/yacs_01.en.xml
195    :lines: 325-333
196
197 The hypothesis transmitted in input parameter characterized (look :ref:`tui_create_hypothese`) :
198
199 .. literalinclude:: ../files/yacs_01.en.xml
200    :lines: 254-278
201
202 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
203
204 .. literalinclude:: ../files/yacs_01.en.xml
205    :lines: 280-290
206
207 The iteration is supplemented : hypothesis, future mesh, field (look :ref:`tui_create_iteration`) :
208
209 .. literalinclude:: ../files/yacs_01.en.xml
210    :lines: 292-311
211
212 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.
213
214 .. literalinclude:: ../files/yacs_01.en.xml
215    :lines: 313-324
216
217 After this execution, the process leaves the Adaptation_HOMARD node, then Adaptation node. One arrives then at the node of analysis.
218
219 Iter_n
220 ^^^^^^
221 .. image:: ../images/yacs_c_07.png
222    :align: center
223    :alt: Iter_n
224    :width: 323
225    :height: 92
226
227 For the following passing in the block of adaptation, it is necessary to recover:
228
229 - the last created iteration: service LastIteration (look :ref:`tui_create_iteration`)
230 - the created hypothesis: service GetHypothesis (look :ref:`tui_create_hypothese`)
231
232 One passes then in the Homard_Exec node to calculate the new mesh.
233
234 Arret_boucle
235 ------------
236 .. image:: ../images/yacs_c_08.png
237    :align: center
238    :alt: Arret_boucle
239    :width: 163
240    :height: 152
241
242 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:
243
244 .. literalinclude:: ../files/yacs_01.en.xml
245    :lines: 173-184
246
247 Analyse
248 =======
249 .. image:: ../images/yacs_c_05.png
250    :align: center
251    :alt: Analyse
252    :width: 156
253    :height: 139
254
255 The Analyse block is a script python which ensures the complete control of the process by examining the causes of possible error successively.
256
257 .. literalinclude:: ../files/yacs_01.en.xml
258    :lines: 104-116
259
260 ../..
261
262 .. literalinclude:: ../files/yacs_01.en.xml
263    :lines: 162-170
264
265 One starts by analyzing the return of the computer code:
266
267 .. literalinclude:: ../files/yacs_01.en.xml
268    :lines: 118-123
269
270 Checking of the presence of the name of the result file in the dictionary of the results:
271
272 .. literalinclude:: ../files/yacs_01.en.xml
273    :lines: 125-132
274
275 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.
276
277 .. literalinclude:: ../files/yacs_01.en.xml
278    :lines: 134-152
279
280 Lastly, it is checked that a maximum nomber of adaptations is not exceeded:
281
282 .. literalinclude:: ../files/yacs_01.en.xml
283    :lines: 154-159
284
285
286 Use this scheme
287 ***************
288 To reproduce this example, download:
289   * :download:`the scheme <../files/yacs_01.en.xml>`
290   * :download:`an example of python script <../files/yacs_script.py>`
291   * :download:`an example of python script ... for nothing <../files/yacs_script_test.py>`
292
293 It should be adapted to simulation considered. In particular, it is necessary:
294
295 - to adjust the names of the files and the directories
296 - to provide a script of launching of calculation respecting the instructions evoked herebefore
297 - to choose the hypothesis of driving of the adaptation
298 - to set up the test of stop
299
300
301
302