doc/fr/yacs.rst

   1 .. _yacs:
   2
   3 YACS
   4 ####
   5 .. index:: single: YACS
   6
   7 L'utilisation de schémas YACS va permettre de coupler un calcul et une adaptation comme il est décrit dans :doc:`intro`. Ce couplage peut être répété au sein d'une boucle jusqu'à l'obtention d'un critère de convergence par exemple. Il existe de nombreuses façons de programmer un schéma YACS. La solution proposée ici fonctionne mais on peut très bien faire autrement !
   8
   9 On trouvera ici la description exhaustive d'un schéma YACS.
  10
  11 .. note::
  12   Le module HOMARD propose une création automatique de schéma YASC à partir d'un cas précédemment créé. Pour la mettre en oeuvre, consulter :doc:`gui_create_yacs`
  13
  14 Présentation générale
  15 *********************
  16
  17 On va décrire ici un schéma s'appliquant à un calcul pour lequel on cherche à stabiliser une valeur. Le calcul démarre sur un maillage initial puis HOMARD enchaîne avec une adaptation. On refait un calcul sur ce nouveau maillage et son résultat est analysé. En fonction de cette analyse, le couplage continue ou non. L'allure générale du schéma est la suivante :
  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   Parmi l'ensemble des données manipulées, certaines sont immuables : le nom du répertoire de calcul, le nom du cas, le nom de l'hypothèse d'adaptation, etc. Il a été choisi de les imposer 'en dur' dans les différents paramètres de service ou au sein des scripts python. On pourrait également les définir a priori dans un noeud PresetNode et ensuite les transmettre par des liens. Nous n'avons pas retenu cette solution car elle augmente fortement le nombre de paramètres et de liens attachés à chaque noeud. Cela est très pénalisant pour la lisibilité du schéma. Les seules données qui vont circuler sont celles imposées par la description du service et celles qui évoluent au cours de l'exécution du schéma.
  27
  28 Les boîtes
  29 **********
  30
  31 Les boîtes principales sont :
  32
  33 - DataInit : initialisation du maillage initial
  34 - Etude_Initialisation : lancement du module HOMARD dans SALOME
  35 - Boucle_de_convergence : gestion de la boucle d'alternance calcul/adaptation
  36 - Bilan : affichage final
  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 Cette boîte est un noeud élémentaire de type PresetNode. Sa seule fonction est d'initialiser la variable MeshFile qui contient le nom du fichier du maillage initial.
  47
  48 .. literalinclude:: ../files/yacs_01.fr.xml
  49    :language: xml
  50    :lines: 37-41
  51
  52 Etude_Initialisation
  53 ====================
  54 La boîte Etude_Initialisation lance le composant HOMARD dans SALOME. C'est un bloc composé de deux parties, qui sont invariables quelle que soit l'application envisagée :
  55
  56 - StudyCreation : noeud python
  57 - UpdateStudy : service du composant HOMARD
  58
  59 .. image:: ./images/yacs_b_01.png
  60    :align: center
  61    :alt: Etude_Initialisation
  62    :width: 327
  63    :height: 73
  64
  65 Le noeud python StudyCreation sert à initialiser l'étude SALOME qui est fournie en sortie :
  66
  67 .. literalinclude:: ../files/yacs_01.fr.xml
  68    :language: xml
  69    :lines: 43-59
  70
  71 Le service UpdateStudy affecte cette étude à une instance de HOMARD.
  72
  73 .. literalinclude:: ../files/yacs_01.fr.xml
  74    :language: xml
  75    :lines: 60-64
  76
  77
  78 Boucle_de_convergence
  79 =====================
  80 La boîte Boucle_de_convergence est une boucle de type WhileLoop. La condition est initialisée à 1 : le bloc interne Alternance_Calcul_HOMARD est exécuté. Au sein de ce bloc, on calcule et on adapte le maillage ; quand le processus doit s'arrêter soit par suite d'erreur, soit par convergence, la condition passe à 0. La boucle s'achève et on passe à la boîte suivante, Bilan.
  81
  82 .. image:: ./images/yacs_c_01.png
  83    :align: center
  84    :alt: Boucle
  85    :width: 163
  86    :height: 93
  87
  88 Bilan
  89 =====
  90 .. image:: ./images/yacs_d_01.png
  91    :align: center
  92    :alt: Bilan
  93    :width: 158
  94    :height: 63
  95
  96 Cette boîte est un noeud python qui prend en entrée une chaîne de caractères, MessInfo. Si tout s'est bien passé, ce message est vide. Une fenêtre QT apparaît pour confirmer la convergence. S'il y a eu un problème, le message contient les messages émis au cours des calculs. La fenêtre QT affiche ce message.
  97
  98 .. literalinclude:: ../files/yacs_01.fr.xml
  99    :language: xml
 100    :lines: 398-411
 101
 102
 103 La boucle de calculs
 104 ********************
 105 .. image:: ./images/yacs_c_02.png
 106    :align: center
 107    :alt: Boucle
 108    :width: 496
 109    :height: 112
 110
 111 Cette boîte est un bloc qui gère le calcul, l'analyse et l'adaptation.
 112
 113 Calcul
 114 ======
 115 .. image:: ./images/yacs_c_03.png
 116    :align: center
 117    :alt: Calcul
 118    :width: 155
 119    :height: 87
 120
 121 Cette boîte est un noeud python qui va piloter le calcul. En entrée, on trouve le numéro du calcul (0 au départ) et le nom du fichier qui contient le maillage sur lequel calculer. En sortie, on trouve un entier qui représente l'erreur sur ce calcul (0 si tout va bien) et un dictionnaire python rassemblant les résultats du calcul. Le corps du noeud est constitué par le lancement d'un script python qui active le calcul.
 122
 123 .. literalinclude:: ../files/yacs_01.fr.xml
 124    :language: xml
 125    :lines: 70-90
 126
 127 Dans cet exemple, il faut définir :
 128
 129 - rep_calc : le répertoire dans lequel sera exécuté le calcul.
 130 - rep_script : le répertoire dans lequel se trouve le python qui lancera le calcul. Ce répertoire est à ajouter au PATH. Depuis ce répertoire, on importera 'Script' depuis le fichier ScriptAster.py
 131
 132 Le python Script est programmé comme l'utilisateur le souhaite pour que le calcul puisse être effectué sur le maillage courant. Selon le mode de lancement du code de calcul, on peut avoir besoin d'autres informations, comme le numéro du calcul ou le répertoire du calcul par exemple. La liberté est totale. Dans notre cas, les arguments d'entrée sont le nom du fichier de maillage, le numéro du calcul et le répertoire de calcul sous la forme de la liste python ["--rep_calc=rep_calc", "--num=numCalc", "--mesh_file=MeshFile"]
 133 ].
 134
 135 En revanche la sortie du script doit obéir à la règle suivante. On récupère un code d'erreur, un message d'erreur et un dictionnaire. Ce dictionnaire contient obligatoirement les clés suivantes :
 136
 137 - "FileName" : le nom du fichier qui contient les résultats du calcul
 138 - "V_TEST" : la valeur dont on veut tester la convergence
 139
 140 Adaptation
 141 ==========
 142 .. image:: ./images/yacs_c_04.png
 143    :align: center
 144    :alt: Adaptation
 145    :width: 661
 146    :height: 566
 147
 148 La boîte Adaptation est un noeud Switch piloté par le code d'erreur du calcul précédent. Si ce code est nul, YACS activera la boîte Adaptation_HOMARD qui lancera l'adaptation. Si le code n'est pas nul, on passe directement dans la boîte Arret_boucle.
 149
 150 Adaptation_HOMARD
 151 -----------------
 152 La première tâche à exécuter concerne l'initialisation des données nécessaires à HOMARD dans la boîte HOMARD_Initialisation. Cette boîte est un noeud switch piloté par le numéro du calcul. Au démarrage, le numéro est nul et YACS active la boîte 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 Cette boîte commence par créer le cas HOMARD en appelant le service CreateCase.
 163
 164 .. literalinclude:: ../files/yacs_01.fr.xml
 165    :language: xml
 166    :lines: 200-207
 167
 168 Le nom du cas CaseName est imposé à "Calcul". Le paramètre d'entrée MeshName est imposé à "BOX". Le paramètre d'entrée FileName est issu de la sortie du calcul précédent. Le paramètre de sortie est une instance de cas.
 169
 170 .. literalinclude:: ../files/yacs_01.fr.xml
 171    :language: xml
 172    :lines: 435-438
 173
 174 .. literalinclude:: ../files/yacs_01.fr.xml
 175    :language: xml
 176    :lines: 475-478
 177
 178 Les options de ce cas doivent maintenant être renseignées. C'est fait par le noeud python CaseOptions. Il est impératif de renseigner le répertoire de calcul. On regardera la description des fonctions dans :doc:`tui_create_case`. En sortie, on récupère l'instance de l'itération correspondant à l'état initial du cas.
 179
 180 .. literalinclude:: ../files/yacs_01.fr.xml
 181    :language: xml
 182    :lines: 208-220
 183
 184 Enfin, une hypothèse est créée en appelant le service CreateHypothese. Le paramètre de sortie est une instance d'hypothèse.
 185
 186 Homard_Exec
 187 ^^^^^^^^^^^
 188 Une fois initialisée, l'adaptation peut être calculée. C'est le but de la boîte Homard_Exec, sous forme d'un 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 Le répertoire de calcul est récupéré. Le nom du maillage est rappelé.
 197
 198 .. literalinclude:: ../files/yacs_01.fr.xml
 199    :language: xml
 200    :lines: 237-242
 201
 202 ../..
 203
 204 .. literalinclude:: ../files/yacs_01.fr.xml
 205    :language: xml
 206    :lines: 317-325
 207
 208 L'hypothèse transmise en paramètre d'entrée est caractérisée (voir :doc:`tui_create_hypothese`) :
 209
 210 .. literalinclude:: ../files/yacs_01.fr.xml
 211    :language: xml
 212    :lines: 246-270
 213
 214 Il faut établir un nom pour la future itération. Pour s'assurer que le nom n'a jamais été utilisé, on met en place un mécanisme de nommage incrémental à partir du nom de l'itération initiale. Comme ce nom initial est le nom du maillage initial, on obtient une succession de noms sous la forme : M_001, M_002, M_003, etc.
 215
 216 .. literalinclude:: ../files/yacs_01.fr.xml
 217    :language: xml
 218    :lines: 272-282
 219
 220 L'itération est complétée : hypothèse, futur maillage, champ (voir :doc:`tui_create_iteration`) :
 221
 222 .. literalinclude:: ../files/yacs_01.fr.xml
 223    :language: xml
 224    :lines: 284-303
 225
 226 L'itération est calculée. Si tout s'est bien passé, la variable OK vaut 1 : on pourra continuer l'exécution du schéma. S'il y a eu un problème, la variable OK vaut 0 pour signifier que le calcul doit s'arrêter ; on donne alors un message d'erreur.
 227
 228 .. literalinclude:: ../files/yacs_01.fr.xml
 229    :language: xml
 230    :lines: 305-316
 231
 232 Après cette exécution, le processus sort du noeud Adaptation_HOMARD, puis du noeud Adaptation. On arrive alors au noeud d'analyse.
 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 Aux passages suivants dans le bloc d'adaptation, il faut récupérer :
 243
 244 - la dernière itération créée pour la poursuivre : service LastIteration (voir :doc:`tui_create_iteration`)
 245 - l'hypothèse créée : service GetHypothesis (voir :doc:`tui_create_hypothese`)
 246
 247 On passe ensuite dans le noeud Homard_Exec pour calculer le nouveau maillage.
 248
 249 Arret_boucle
 250 ------------
 251 .. image:: ./images/yacs_c_08.png
 252    :align: center
 253    :alt: Arret_boucle
 254    :width: 163
 255    :height: 152
 256
 257 Le bloc Arret_boucle n'est présent que pour faire transiter des variables car les paramètres d'entrée des noeuds doivent toujours être remplis. C'est un python très simple :
 258
 259 .. literalinclude:: ../files/yacs_01.fr.xml
 260    :language: xml
 261    :lines: 165-176
 262
 263 Analyse
 264 =======
 265 .. image:: ./images/yacs_c_05.png
 266    :align: center
 267    :alt: Analyse
 268    :width: 156
 269    :height: 139
 270
 271 Le bloc Analyse est un script python qui assure le contrôle complet du processus en examinant successivement les causes d'erreur possible.
 272
 273 .. literalinclude:: ../files/yacs_01.fr.xml
 274    :language: xml
 275    :lines: 96-108
 276
 277 ../..
 278
 279 .. literalinclude:: ../files/yacs_01.fr.xml
 280    :language: xml
 281    :lines: 154-162
 282
 283 On commence par analyser le retour du code de calcul :
 284
 285 .. literalinclude:: ../files/yacs_01.fr.xml
 286    :language: xml
 287    :lines: 110-115
 288
 289 Vérification de la présence du nom du fichier de résultats dans le dictionnaire des résultats :
 290
 291 .. literalinclude:: ../files/yacs_01.fr.xml
 292    :language: xml
 293    :lines: 117-124
 294
 295 Vérification de la convergence. Cela suppose que la valeur à tester est présente dans le dictionnaire sous la clé 'V_TEST'. Ici, on a mis en place un test sur la variation de la valeur d'un calcul à l'autre. Au premier passage, on ne teste rien. Aux passages suivants, on teste si la variation relative est inférieure à 1 millième. On aurait pu mettre en place un test absolu si on avait récupéré un niveau global d'erreur par exemple.
 296
 297 .. literalinclude:: ../files/yacs_01.fr.xml
 298    :language: xml
 299    :lines: 126-146
 300
 301 Enfin, on vérifie que l'on ne dépasse pas un nombre maximal d'adaptations :
 302
 303 .. literalinclude:: ../files/yacs_01.fr.xml
 304    :language: xml
 305    :lines: 146-151
 306
 307
 308 Utiliser ce schéma
 309 ******************
 310 Pour reproduire cet exemple, on pourra télécharger :
 311   * :download:`le schéma <../files/yacs_01.fr.xml>`
 312   * :download:`un exemple de script python <../files/yacs_script.py>`
 313   * :download:`un exemple de script python qui ne fait rien <../files/yacs_script_test.py>`
 314
 315 Il faut l'adapter à la simulation envisagée. En particulier, il faut :
 316
 317 - ajuster les noms des fichiers et des répertoires
 318 - fournir un script de lancement du calcul respectant les consignes évoquées ci-avant
 319 - choisir les hypothèses de pilotage de l'adaptation
 320 - mettre en place le test d'arrêt
 321
 322
 323