doc/fr/using.rst

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