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 :ref:`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 :ref:`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    :lines: 38-42
  50
  51 Etude_Initialisation
  52 ====================
  53 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 :
  54
  55 - StudyCreation : noeud python
  56 - SetCurrentStudy : service du composant HOMARD
  57
  58 .. image:: ../images/yacs_b_01.png
  59    :align: center
  60    :alt: Etude_Initialisation
  61    :width: 323
  62    :height: 97
  63
  64 Le noeud python StudyCreation sert à initialiser l'étude SALOME qui est fournie en sortie :
  65
  66 .. literalinclude:: ../files/yacs_01.fr.xml
  67    :lines: 44-62
  68
  69 Le service SetCurrentStudy affecte cette étude à une instance de HOMARD.
  70
  71 .. literalinclude:: ../files/yacs_01.fr.xml
  72    :lines: 63-68
  73
  74
  75 Boucle_de_convergence
  76 =====================
  77 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.
  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 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.
  94
  95 .. literalinclude:: ../files/yacs_01.fr.xml
  96    :lines: 406-419
  97
  98
  99 La boucle de calculs
 100 ********************
 101 .. image:: ../images/yacs_c_02.png
 102    :align: center
 103    :alt: Boucle
 104    :width: 338
 105    :height: 152
 106
 107 Cette boîte est un bloc qui gère le calcul, l'adaptation et l'analyse.
 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 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.
 118
 119 .. literalinclude:: ../files/yacs_01.fr.xml
 120    :lines: 77-103
 121
 122 Dans cet exemple, il faut définir :
 123
 124 - rep_calc : le répertoire dans lequel sera exécuté le calcul.
 125 - 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
 126
 127 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"]
 128 ].
 129
 130 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 :
 131
 132 - "FileName" : le nom du fichier qui contient les résultats du calcul
 133 - "V_TEST" : la valeur dont on veut tester la convergence
 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 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.
 144
 145 Adaptation_HOMARD
 146 -----------------
 147 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.
 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 Cette boîte commence par créer le cas HOMARD en appelant le service CreateCase.
 158
 159 .. literalinclude:: ../files/yacs_01.fr.xml
 160    :lines: 208-215
 161
 162 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.
 163
 164 .. literalinclude:: ../files/yacs_01.fr.xml
 165    :lines: 443-446
 166
 167 .. literalinclude:: ../files/yacs_01.fr.xml
 168    :lines: 483-486
 169
 170 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 :ref:`tui_create_case`. En sortie, on récupère l'instance de l'itération correspondant à l'état initial du cas.
 171
 172 .. literalinclude:: ../files/yacs_01.fr.xml
 173    :lines: 216-228
 174
 175 Enfin, une hypothèse est créée en appelant le service CreateHypothese. Le paramètre de sortie est une instance d'hypothèse.
 176
 177 Homard_Exec
 178 ^^^^^^^^^^^
 179 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.
 180
 181 .. image:: ../images/yacs_c_09.png
 182    :align: center
 183    :alt: Homard_Exec
 184    :width: 153
 185    :height: 141
 186
 187 Le répertoire de calcul est récupéré. Le nom du maillage est rappelé.
 188
 189 .. literalinclude:: ../files/yacs_01.fr.xml
 190    :lines: 245-250
 191
 192 ../..
 193
 194 .. literalinclude:: ../files/yacs_01.fr.xml
 195    :lines: 325-333
 196
 197 L'hypothèse transmise en paramètre d'entrée est caractérisée (voir :ref:`tui_create_hypothese`) :
 198
 199 .. literalinclude:: ../files/yacs_01.fr.xml
 200    :lines: 254-278
 201
 202 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.
 203
 204 .. literalinclude:: ../files/yacs_01.fr.xml
 205    :lines: 280-290
 206
 207 L'itération est complétée : hypothèse, futur maillage, champ (voir :ref:`tui_create_iteration`) :
 208
 209 .. literalinclude:: ../files/yacs_01.fr.xml
 210    :lines: 292-311
 211
 212 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.
 213
 214 .. literalinclude:: ../files/yacs_01.fr.xml
 215    :lines: 313-324
 216
 217 Après cette exécution, le processus sort du noeud Adaptation_HOMARD, puis du noeud Adaptation. On arrive alors au noeud d'analyse.
 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 Aux passages suivants dans le bloc d'adaptation, il faut récupérer :
 228
 229 - la dernière itération créée pour la poursuivre : service LastIteration (voir :ref:`tui_create_iteration`)
 230 - l'hypothèse créée : service GetHypothesis (voir :ref:`tui_create_hypothese`)
 231
 232 On passe ensuite dans le noeud Homard_Exec pour calculer le nouveau maillage.
 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 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 :
 243
 244 .. literalinclude:: ../files/yacs_01.fr.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 Le bloc Analyse est un script python qui assure le contrôle complet du processus en examinant successivement les causes d'erreur possible.
 256
 257 .. literalinclude:: ../files/yacs_01.fr.xml
 258    :lines: 104-116
 259
 260 ../..
 261
 262 .. literalinclude:: ../files/yacs_01.fr.xml
 263    :lines: 162-170
 264
 265 On commence par analyser le retour du code de calcul :
 266
 267 .. literalinclude:: ../files/yacs_01.fr.xml
 268    :lines: 118-123
 269
 270 Vérification de la présence du nom du fichier de résultats dans le dictionnaire des résultats :
 271
 272 .. literalinclude:: ../files/yacs_01.fr.xml
 273    :lines: 125-132
 274
 275 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.
 276
 277 .. literalinclude:: ../files/yacs_01.fr.xml
 278    :lines: 134-152
 279
 280 Enfin, on vérifie que l'on ne dépasse pas un nombre maximal d'adaptations :
 281
 282 .. literalinclude:: ../files/yacs_01.fr.xml
 283    :lines: 154-159
 284
 285
 286 Utiliser ce schéma
 287 ******************
 288 Pour reproduire cet exemple, on pourra télécharger :
 289   * :download:`le schéma <../files/yacs_01.fr.xml>`
 290   * :download:`un exemple de script python <../files/yacs_script.py>`
 291   * :download:`un exemple de script python qui ne fait rien <../files/yacs_script_test.py>`
 292
 293 Il faut l'adapter à la simulation envisagée. En particulier, il faut :
 294
 295 - ajuster les noms des fichiers et des répertoires
 296 - fournir un script de lancement du calcul respectant les consignes évoquées ci-avant
 297 - choisir les hypothèses de pilotage de l'adaptation
 298 - mettre en place le test d'arrêt
 299
 300
 301