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