2 Copyright (C) 2008-2014 EDF R&D
4 This file is part of SALOME ADAO module.
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.
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.
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
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
26 ================================================================================
27 **[DocU]** Utiliser le module ADAO
28 ================================================================================
30 .. |eficas_new| image:: images/eficas_new.png
33 .. |eficas_save| image:: images/eficas_save.png
36 .. |eficas_saveas| image:: images/eficas_saveas.png
39 .. |eficas_yacs| image:: images/eficas_yacs.png
42 .. |yacs_compile| image:: images/yacs_compile.png
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`.
52 Procédure logique pour construire un cas ADAO
53 ---------------------------------------------
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.
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.
64 **Fondamentalement, la procédure d'utilisation de ADAO comprend les étapes
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.**
73 Chaque étape est détaillée dans la section suivante.
75 ÉTAPE 1 : Activer le module ADAO et utiliser l'interface graphique d'édition (GUI)
76 ----------------------------------------------------------------------------------
78 Comme toujours pour un module, il doit être préalablement activé en
79 sélectionnant le bouton de module approprié (ou le menu) dans la barre d'outils
80 de SALOME. S'il n'existe aucune étude SALOME chargée, un menu contextuel
81 apparaît, permettant de choisir entre la création d'une nouvelle étude, ou
82 l'ouverture d'une étude déjà existante:
85 .. image:: images/adao_activate.png
88 **Activation du module ADAO dans SALOME**
90 En choisissant le bouton "*Nouveau*", un éditeur intégré de cas EFICAS [#]_ sera
91 ouvert, en même temps que le "*navigateur d'objets*" standard. On peut alors
92 cliquer sur le bouton "*Nouveau*"(ou choisir l'entrée "*Nouveau*" dans le dans
93 le menu principal "*ADAO*") pour créer un nouveau cas ADAO, et on obtient :
96 .. image:: images/adao_viewer.png
100 **L'éditeur EFICAS pour la définition des cas dans le module ADAO**
102 ÉTAPE 2 : Créer et modifier le cas ADAO, et l'enregistrer
103 ---------------------------------------------------------
105 Pour construire un cas en utilisant EFICAS, on doit passer par une série de
106 sous-étapes, en choisissant, à chaque étape, un mot-clé puis en remplissant ses
107 valeurs. On note que c'est dans cette étape qu'il faut, entre autres, définir
108 l'**appel au code de simulation** utilisé dans les opérateurs d'observation ou
109 d'évolution décrivant le problème [#]_.
111 L'éditeur structuré indique des types hiérarchiques, des valeurs ou des
112 mots-clés autorisés. Les mots-clés incomplets ou incorrects sont identifiés par
113 un indicateur d'erreur visuel rouge. Les valeurs possibles sont indiquées pour
114 les mots-clés par la définition d'une liste limitée de valeurs, et les entrées
115 adaptées sont données pour les autres mots-clés. Des messages d'aide sont
116 fournis de manière contextuelle aux places réservées de l'éditeur.
118 Un nouveau cas est mis en place avec la liste minimale des commandes. Toutes les
119 commandes ou les mots-clés obligatoires sont déjà présents, aucun d'eux ne peut
120 être supprimé. Des mots-clés optionnels peuvent être ajoutés en les choisissant
121 dans une liste de suggestions de ceux autorisés pour la commande principale, par
122 exemple la commande "*ASSIMILATION_STUDY*". À titre d'exemple, on peut ajouter
123 un mot-clé "*AlgorithmParameters*", comme décrit dans la dernière partie de la
124 section :ref:`section_examples`.
126 A la fin de ces actions, lorsque tous les champs ou les mots-clés ont été
127 correctement définis, chaque ligne de l'arborescence des commandes doit
128 présenter un drapeau vert. Cela signifie que l'ensemble du cas est valide et
129 dûment rempli (et qu'il peut être sauvegardé).
131 .. _adao_jdcexample00:
132 .. image:: images/adao_jdcexample01.png
136 **Exemple d'un cas ADAO valide**
138 Au final, il faut enregistrer le cas ADAO en utilisant le bouton "*Enregistrer*"
139 |eficas_save|, ou le bouton "*Enregistrer sous*" |eficas_saveas|, ou en
140 choisissant l'entrée "*Enregistrer/ Enregistrer sous*" dans le menu "*ADAO*". Il
141 est alors demandé un emplacement, à choisir dans l'arborescence des fichiers, et
142 un nom, qui sera complété par l'extension "*.comm*" utilisée pour les fichiers
143 JDC d'EFICAS. Cette action va générer une paire de fichiers décrivant le cas
144 ADAO, avec le même nom de base, le premier présentant une extension "*.comm*" et
145 le second une extension "*.py*" [#]_.
147 ÉTAPE 3 : Exporter le cas ADAO comme un schéma YACS
148 ---------------------------------------------------
150 Lorsque le cas ADAO est complété, il doit être converti ou exporté sous la forme
151 d'un schéma YACS [#]_ pour pouvoir exécuter le calcul d'assimilation de
152 données. Cela peut être réalisé facilement en utilisant le bouton "*Exporter
153 vers YACS*" |eficas_yacs|, ou de manière équivalente en choisissant l'entrée
154 "*Exporter vers YACS*" dans le menu principal "*ADAO*", ou dans le menu
155 contextuel du cas dans le navigateur d'objets SALOME.
157 .. _adao_exporttoyacs01:
158 .. image:: images/adao_exporttoyacs.png
162 **Sous-menu "Exporter vers YACS" pour générer le schéma YACS à partir d'un cas ADAO**
164 Cela conduit à générer automatiquement un schéma YACS, et à activer le module
165 YACS sur ce schéma. Le fichier YACS, associé au schéma, est stocké dans le même
166 répertoire et avec le même nom de base de fichier que le cas ADAO enregistré,
167 changeant simplement son extension en "*.xml*". Attention, *si le nom de fichier
168 XML existe déjà, le fichier est écrasé sans avertissement sur le remplacement du
171 ÉTAPE 4 : Compléter et modifier le schéma YACS, et l'enregistrer
172 ----------------------------------------------------------------
174 .. index:: single: Analysis
176 Lorsque le schéma YACS est généré et ouvert dans SALOME à travers le l'interface
177 graphique du module YACS, on peut modifier ou compléter le schéma comme tout
178 schéma YACS standard. Des noeuds ou des blocs peuvent être ajoutés, copiés ou
179 modifiés pour élaborer une analyse complexe, ou pour insérer des capacités
180 d'assimilation de données ou d'optimisation dans des schémas de calculs YACS
183 Le principal complément nécessaire dans un schéma YACS est une étape de
184 post-processing. L'évaluation du résultat doit être réalisé dans le contexte
185 physique de simulation utilisé par la procédure d'assimilation de données. Le
186 post-processing peut être fournit à travers le mot-clé "*UserPostAnalysis*"
187 d'ADAO sous la forme d'un fichier de script ou d'une chaîne de caractères, par
188 des patrons ("templates"), ou peut être construit comme des noeuds YACS. Ces
189 deux manières de construire le post-processing peuvent utiliser toutes les
192 Dans le détail, le schéma YACS dispose d'un port de sortie "*algoResults*" dans
193 le bloc de calcul, qui donne accès à un objet de type "*pyobj*" nommé ci-aprés
194 "*ADD*", qui contient tous les résultats de calcul. Ces résultats peuvent être
195 obtenus en récupérant les variables nommées stockées au cours des calculs.
196 L'information principale est la variable "*Analysis*", qui peut être obtenue par
197 une commande python (par exemple dans un noeud script intégré ("in-line script
198 node") ou un script fourni à travers le mot-clé "*UserPostAnalysis*"::
200 Analysis = ADD.get("Analysis")[:]
202 "*Analysis*" est un objet complexe, similaire à une liste de valeurs calculées à
203 chaque étape du calcul d'assimilation. Pour obtenir et afficher l'évaluation
204 optimale de l'état par assimilation de données, dans un script fournit par
205 l'intermédiaire du mot-clé "*UserPostAnalysis*", on peut utiliser::
207 Xa = ADD.get("Analysis")[-1]
208 print "Optimal state:", Xa
211 Cette variable ``Xa`` est un vecteur de valeurs, qui représente la solution du
212 problème d'évaluation par assimilation de données ou par optimisation, notée
213 :math:`\mathbf{x}^a` dans la section :ref:`section_theory`.
215 Une telle méthode peut être utilisée pour imprimer les résultats, ou pour les
216 convertir dans des structures qui peuvent être nécessaires à un post-processing
217 natif ou externe à SALOME. Un exemple simple est disponible dans la section
218 :ref:`section_examples`.
220 ÉTAPE 5 : Exécuter le schéma YACS et obtenir les résultats
221 ----------------------------------------------------------
223 Le schéma YACS est maintenant complet et peut être exécuté. La paramétrisation
224 et l'exécution de ce cas YACS est entièrement compatible avec la manière
225 standard de traiter un schéma YACS, comme décrit dans le *Guide de l'utilisateur
228 Pour rappeler la manière la plus simple de procéder, le schéma YACS doit être
229 compilé en utilisant le bouton |yacs_compile|, ou l'entrée équivalente du menu
230 YACS, pour préparer le schéma à son exécution. Ensuite, le schéma compilé peut
231 être démarré, exécuté pas à pas ou en utilisant des points d'arrêt, etc.
233 La sortie standard est restituée dans la "*fenêtre de sortie de YACS*" (ou
234 "*YACS Container Log*"), à laquelle on accède par un clic droit sur la fenêtre
235 "*proc*" dans l'interface graphique YACS. Les erreurs sont présentées soit
236 dans la "*fenêtre de sortie de YACS*", ou à la ligne de commande dans la fenêtre
237 de commandes (si l'environnement SALOME a été lancé par une commande explicite,
238 et non par un menu ou une icône de bureau). Par exemple, la sortie de l'exemple
239 simple ci-dessus est de la forme suivante::
241 Entering in the assimilation study
242 Name is set to........: Test
243 Algorithm is set to...: Blue
244 Launching the analyse
246 Optimal state: [0.5, 0.5, 0.5]
248 présentée dans la "*fenêtre de sortie de YACS*".
250 L'exécution peut aussi être conduite en utilisant un script de commandes shell,
251 comme décrit dans la section :ref:`section_advanced`.
253 .. [#] Pour de plus amples informations sur EFICAS, voir le *module EFICAS* et son aide disponible dans l'environnement SALOME.
255 .. [#] 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.
257 .. [#] Pour de plus amples informations sur YACS, voir le *Guide utilisateur du module YACS* disponible dans le menu principal *Aide* de l'environnement SALOME.
259 .. [#] Ce fichier python intermédiaire peut aussi être utilisé comme décrit dans la section :ref:`section_advanced`.
