doc/fr/gui_in_salome.rst

   1 ..
   2    Copyright (C) 2008-2021 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. _section_gui_in_salome:
  25
  26 ================================================================================
  27 **[DocR]** Interface graphique pour l'utilisateur (GUI/EFICAS)
  28 ================================================================================
  29
  30 .. |eficas_new| image:: images/eficas_new.png
  31    :align: middle
  32    :scale: 50%
  33 .. |eficas_save| image:: images/eficas_save.png
  34    :align: middle
  35    :scale: 50%
  36 .. |eficas_saveas| image:: images/eficas_saveas.png
  37    :align: middle
  38    :scale: 50%
  39 .. |eficas_yacs| image:: images/eficas_yacs.png
  40    :align: middle
  41    :scale: 50%
  42 .. |yacs_compile| image:: images/yacs_compile.png
  43    :align: middle
  44    :scale: 50%
  45
  46 Cette section présente l'usage du module ADAO dans la plateforme SALOME. On
  47 décrit ici le cheminement général pour établir un cas ADAO, les détails étant
  48 fournis dans les chapitres suivants. Il est complété par la description
  49 détaillée de l'ensemble des commandes et mots-clés dans la section
  50 :ref:`section_reference`, par des procédures avancées d'usage dans la section
  51 :ref:`section_advanced`, et par des exemples dans la section
  52 :ref:`section_tutorials_in_salome`.
  53
  54 Procédure logique pour construire un cas ADAO
  55 ---------------------------------------------
  56
  57 La construction d'un cas ADAO suit une démarche simple pour définir l'ensemble
  58 des données d'entrée, et ensuite générer un diagramme complet d'exécution
  59 utilisé dans YACS [#]_. De nombreuses variations existent pour la définition
  60 des données d'entrée, mais la séquence logique reste inchangée.
  61
  62 De manière générale, l'utilisateur doit connaître ses données d'entrées,
  63 requises pour mettre au point une étude d'assimilation de données, en suivant la
  64 :ref:`section_methodology`. Ces données peuvent déjà être disponibles dans
  65 SALOME ou non.
  66
  67 Fondamentalement, la procédure d'utilisation de ADAO comprend les étapes
  68 suivantes:
  69
  70 - :ref:`section_u_step1`
  71 - :ref:`section_u_step2`
  72 - :ref:`section_u_step3`
  73 - :ref:`section_u_step4`
  74 - :ref:`section_u_step5`
  75
  76 Chaque étape est détaillée dans la section suivante.
  77
  78 Procédure détaillée pour construire un cas ADAO
  79 -----------------------------------------------
  80
  81 .. _section_u_step1:
  82
  83 ÉTAPE 1 : Activer le module ADAO et utiliser l'interface graphique d'édition (GUI)
  84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  85
  86 Comme toujours pour un module, il doit être préalablement activé en
  87 sélectionnant le bouton de module approprié (ou le menu) dans la barre d'outils
  88 de SALOME. S'il n'existe aucune étude SALOME chargée, un menu contextuel
  89 apparaît, permettant de choisir entre la création d'une nouvelle étude, ou
  90 l'ouverture d'une étude déjà existante:
  91
  92   .. _adao_activate1:
  93   .. image:: images/adao_activate.png
  94     :align: center
  95   .. centered::
  96     **Activation du module ADAO dans SALOME**
  97
  98 En choisissant le bouton "*Nouveau*", un éditeur intégré de cas [#]_ sera
  99 ouvert, en même temps que le "*navigateur d'objets*" standard. On peut alors
 100 cliquer sur le bouton "*Nouveau*" (ou choisir l'entrée "*Nouveau*"  dans le dans
 101 le menu principal "*ADAO*") pour créer un nouveau cas ADAO, et on obtient :
 102
 103   .. _adao_viewer:
 104   .. image:: images/adao_viewer.png
 105     :align: center
 106     :width: 100%
 107   .. centered::
 108     **L'éditeur intégré pour la définition des cas dans le module ADAO**
 109
 110 .. _section_u_step2:
 111
 112 ÉTAPE 2 : Créer et modifier le cas ADAO, et l'enregistrer
 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 114
 115 Pour construire un cas en utilisant l'éditeur intégré, on doit passer par une
 116 série de sous-étapes, en choisissant, à chaque étape, un mot-clé puis en
 117 remplissant ses valeurs. On note que c'est dans cette étape qu'il faut, entre
 118 autres, définir l'**appel au code de simulation** utilisé dans les opérateurs
 119 d'observation ou d'évolution décrivant le problème [#]_.
 120
 121 L'éditeur structuré indique des types hiérarchiques, des valeurs ou des
 122 mots-clés autorisés. Les mots-clés incomplets ou incorrects sont identifiés par
 123 un indicateur d'erreur visuel rouge. Les valeurs possibles sont indiquées pour
 124 les mots-clés par la définition d'une liste limitée de valeurs, et les entrées
 125 adaptées sont données pour les autres mots-clés. Des messages d'aide sont
 126 fournis de manière contextuelle aux places réservées de l'éditeur.
 127
 128 Un nouveau cas est mis en place avec la liste minimale des commandes. Toutes les
 129 commandes ou les mots-clés obligatoires sont déjà présents, aucun d'eux ne peut
 130 être supprimé. Des mots-clés optionnels peuvent être ajoutés en les choisissant
 131 dans une liste de suggestions de ceux autorisés pour la commande principale, par
 132 exemple la commande "*ASSIMILATION_STUDY*". À titre d'exemple, on peut ajouter
 133 des paramètres dans le mot-clé "*AlgorithmParameters*", comme décrit dans la
 134 dernière partie de la section :ref:`section_tutorials_in_salome`.
 135
 136 A la fin de ces actions, lorsque tous les champs ou les mots-clés ont été
 137 correctement définis, chaque ligne de l'arborescence des commandes doit
 138 présenter un drapeau vert. Cela signifie que l'ensemble du cas est valide et
 139 dûment rempli (et qu'il peut être sauvegardé).
 140
 141   .. _adao_jdcexample00:
 142   .. image:: images/adao_jdcexample01.png
 143     :align: center
 144     :scale: 75%
 145   .. centered::
 146     **Exemple d'un cas ADAO valide**
 147
 148 Au final, il faut enregistrer le cas ADAO en utilisant le bouton "*Enregistrer*"
 149 |eficas_save|, ou le bouton "*Enregistrer sous*" |eficas_saveas|, ou en
 150 choisissant l'entrée "*Enregistrer/ Enregistrer sous*" dans le menu "*ADAO*". Il
 151 est alors demandé un emplacement, à choisir dans l'arborescence des fichiers, et
 152 un nom, qui sera complété par l'extension "*.comm*" utilisée pour les fichiers
 153 de l'éditeur intégré de cas. Cette action va générer une paire de fichiers
 154 décrivant le cas ADAO, avec le même nom de base, le premier présentant une
 155 extension "*.comm*" et le second une extension "*.py*" [#]_.
 156
 157 .. _section_u_step3:
 158
 159 ÉTAPE 3 : Exporter le cas ADAO comme un schéma YACS
 160 +++++++++++++++++++++++++++++++++++++++++++++++++++
 161
 162 Lorsque le cas ADAO est complété, il doit être converti ou exporté sous la forme
 163 d'un schéma YACS pour pouvoir exécuter le calcul d'assimilation de données. Cela
 164 peut être réalisé facilement en utilisant le bouton "*Exporter vers YACS*"
 165 |eficas_yacs|, ou de manière équivalente en choisissant l'entrée "*Exporter vers
 166 YACS*" dans le menu principal "*ADAO*", ou dans le menu contextuel du cas dans
 167 le navigateur d'objets SALOME.
 168
 169   .. _adao_exporttoyacs01:
 170   .. image:: images/adao_exporttoyacs.png
 171     :align: center
 172     :scale: 75%
 173   .. centered::
 174     **Sous-menu "Exporter vers YACS" pour générer le schéma YACS à partir d'un cas ADAO**
 175
 176 Cela conduit à générer automatiquement un schéma YACS, et à activer le module
 177 YACS sur ce schéma. Le fichier YACS, associé au schéma, est stocké dans le même
 178 répertoire et avec le même nom de base de fichier que le cas ADAO enregistré,
 179 changeant simplement son extension en "*.xml*". Attention, *si le nom de fichier
 180 XML existe déjà, le fichier est écrasé sans avertissement sur le remplacement du
 181 fichier XML*.
 182
 183 .. _section_u_step4:
 184
 185 ÉTAPE 4 : Compléter et modifier le schéma YACS, et l'enregistrer
 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 187
 188 .. index:: single: Analysis
 189
 190 Lorsque le schéma YACS est généré et ouvert dans SALOME à travers l'interface
 191 graphique du module YACS, on peut modifier ou compléter le schéma comme tout
 192 schéma YACS standard. Des noeuds ou des blocs peuvent être ajoutés, copiés ou
 193 modifiés pour élaborer une analyse complexe, ou pour insérer des capacités
 194 d'assimilation de données ou d'optimisation dans des schémas de calculs YACS
 195 plus complexes.
 196
 197 Le principal complément nécessaire dans un schéma YACS est une étape de
 198 post-processing. L'évaluation du résultat doit être réalisée dans le contexte
 199 physique de simulation utilisé par la procédure d'assimilation de données. Le
 200 post-processing peut être fourni à travers le mot-clé "*UserPostAnalysis*"
 201 d'ADAO sous la forme d'un fichier de script ou d'une chaîne de caractères, par
 202 des patrons ("templates"), ou peut être construit comme des noeuds YACS. Ces
 203 deux manières de construire le post-processing peuvent utiliser toutes les
 204 capacités de SALOME. On se reportera à la partie traitant des
 205 :ref:`section_ref_output_variables`, ou à l'aide de chaque algorithme, pour la
 206 description complète de ces éléments.
 207
 208 En pratique, le schéma YACS dispose d'un port de sortie "*algoResults*" dans le
 209 bloc de calcul, qui donne accès à un objet structuré nommé ci-après "*ADD*" par
 210 exemple, qui contient tous les résultats de calcul. Ces résultats peuvent être
 211 obtenus en récupérant les variables nommées stockées au cours des calculs.
 212 L'information principale est la variable "*Analysis*", qui peut être obtenue par
 213 une commande python (par exemple dans un noeud script intégré ("in-line script
 214 node") ou un script fourni à travers le mot-clé "*UserPostAnalysis*"::
 215
 216     Analysis = ADD.get("Analysis")[:]
 217
 218 "*Analysis*" est un objet complexe, similaire à une liste de valeurs calculées à
 219 chaque étape du calcul d'assimilation. Pour obtenir et afficher l'évaluation
 220 optimale de l'état par assimilation de données, dans un script fourni par
 221 l'intermédiaire du mot-clé "*UserPostAnalysis*", on peut utiliser::
 222
 223     Xa = ADD.get("Analysis")[-1]
 224     print("Optimal state:", Xa)
 225     print()
 226
 227 Cette variable ``Xa`` est un vecteur de valeurs, qui représente la solution du
 228 problème d'évaluation par assimilation de données ou par optimisation, notée
 229 :math:`\mathbf{x}^a` dans la section :ref:`section_theory`.
 230
 231 Une telle méthode peut être utilisée pour imprimer les résultats, ou pour les
 232 convertir dans des structures qui peuvent être nécessaires à un post-processing
 233 natif ou externe à SALOME. Un exemple simple est disponible dans la section
 234 :ref:`section_tutorials_in_salome`.
 235
 236 .. _section_u_step5:
 237
 238 ÉTAPE 5 : Exécuter le schéma YACS et obtenir les résultats
 239 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 240
 241 Le schéma YACS est maintenant complet et peut être exécuté. La paramétrisation
 242 et l'exécution de ce cas YACS est entièrement compatible avec la manière
 243 standard de traiter un schéma YACS, comme décrit dans le *Guide de l'utilisateur
 244 du module YACS*.
 245
 246 Pour rappeler la manière la plus simple de procéder, le schéma YACS doit être
 247 compilé en utilisant le bouton |yacs_compile|, ou l'entrée équivalente du menu
 248 YACS, pour préparer le schéma à son exécution. Ensuite, le schéma compilé peut
 249 être démarré, exécuté pas à pas ou en utilisant des points d'arrêt, etc.
 250
 251 La sortie standard est restituée dans la "*fenêtre de sortie de YACS*" (ou
 252 "*YACS Container Log*"), à laquelle on accède par un clic droit sur la fenêtre
 253 "*proc*" dans l'interface graphique YACS. Les erreurs sont présentées soit
 254 dans la "*fenêtre de sortie de YACS*", ou à la ligne de commande dans la fenêtre
 255 de commandes (si l'environnement SALOME a été lancé par une commande explicite,
 256 et non par un menu ou une icône de bureau). Par exemple, la sortie de l'exemple
 257 simple ci-dessus est de la forme suivante::
 258
 259    Entering in the assimilation study
 260    Name is set to........: Test
 261    Algorithm is set to...: Blue
 262    Launching the analysis
 263
 264    Optimal state: [0.5, 0.5, 0.5]
 265
 266 présentée dans la "*fenêtre de sortie de YACS*".
 267
 268 L'exécution peut aussi être conduite en utilisant un script de commandes Shell,
 269 comme décrit dans la section :ref:`section_advanced`.
 270
 271 .. [#] Pour de plus amples informations sur YACS, voir le *module YACS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
 272
 273 .. [#] Pour de plus amples informations sur l'éditeur intégré de cas, voir le *module EFICAS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
 274
 275 .. [#] L'utilisation du code de simulation physique dans les opérateurs de base de l'assimilation de données est illustrée ou décrite dans les parties principales qui suivent.
 276
 277 .. [#] Ce fichier python intermédiaire peut aussi être utilisé comme décrit dans la section :ref:`section_advanced`.