2 Copyright (C) 2008-2024 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
24 .. _section_ref_output_variables:
26 Variables et informations disponibles en sortie
27 -----------------------------------------------
29 Comment obtenir les informations disponibles en sortie
30 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
32 .. index:: single: UserPostAnalysis
33 .. index:: single: algoResults
34 .. index:: single: getResults
35 .. index:: single: get
36 .. index:: single: ADD
38 En sortie, après exécution d'une assimilation de données, d'une optimisation
39 ou d'une vérification, on dispose de variables et d'informations issues du
40 calcul. L'obtention de ces informations se fait ensuite de manière standardisée
41 à l'aide de l'étape de post-processing du calcul.
43 L'étape est aisément identifiée par l'utilisateur dans son cas ADAO de
44 définition (par le mot-clé "*UserPostAnalysis*") ou dans son schéma YACS
45 d'exécution (par des noeuds ou blocs situés après le bloc de calcul, et reliés
46 graphiquement au port de sortie "*algoResults*" du bloc de calcul):
48 #. Dans le cas où l'utilisateur définit le post-processing dans son cas ADAO, il utilise un fichier script externe ou des commandes dans le champ de type "*String*" ou "*Template*". Le script qu'il fournit dispose d'une variable fixe "*ADD*" dans l'espace de noms.
49 #. Dans le cas où l'utilisateur définit le post-processing dans son schéma YACS par un noeud Python situé après le bloc de calcul, il doit ajouter un port d'entrée de type "*pyobj*" nommé par exemple "*Study*", relié graphiquement au port de sortie "*algoResults*" du bloc de calcul. Le noeud Python de post-processing doit ensuite débuter par ``ADD = Study.getResults()``.
51 Des patrons (ou "templates") sont donnés ci-après en
52 :ref:`subsection_r_o_v_Template`. Dans tous les cas, le post-processing de
53 l'utilisateur dispose dans l'espace de noms d'une variable dont le nom est
54 "*ADD*", et dont l'unique méthode utilisable est nommée ``get``. Les arguments
55 de cette méthode sont un nom d'information de sortie, comme décrit dans
56 l':ref:`subsection_r_o_v_Inventaire`.
58 Par exemple, pour avoir l'état optimal après un calcul d'assimilation de données
59 ou d'optimisation, on utilise l'appel suivant::
63 Cet appel renvoie une liste de valeurs de la notion demandée (ou, dans le cas
64 de variables d'entrées qui ne sont par nature qu'en un unique exemplaire, la
65 valeur elle-même). On peut alors demander un élément particulier de la liste par
66 les commandes standards de liste (en particulier ``[-1]`` pour le dernier, et
67 ``[:]`` pour tous les éléments).
69 .. _subsection_r_o_v_Template:
71 Exemples de scripts Python pour obtenir ou traiter les sorties
72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
74 .. index:: single: Template
75 .. index:: single: AnalysisPrinter (UserPostAnalysis)
76 .. index:: single: AnalysisSaver (UserPostAnalysis)
77 .. index:: single: AnalysisPrinterAndSaver (UserPostAnalysis)
79 Ces exemples présentent des commandes ou scripts Python qui permettent
80 d'obtenir ou de traiter les sorties d'une exécution d'algorithme. Pour aider
81 l'utilisateur, ils sont directement disponibles dans l'interface, à la
82 construction du cas ADAO dans l'éditeur intégré de cas, dans les champs de type
83 "*Template*". De manière équivalente, ces commandes peuvent être contenues dans
84 un script utilisateur externe (et insérées dans le cas ADAO par l'entrée de
85 type "*Script*") ou contenues dans une chaîne de caractères, y compris les
86 retours à la ligne (et insérées dans le cas ADAO par l'entrée de type
87 "*String*"). De nombreuses variantes peuvent être imaginées à partir de ces
88 exemples simples, l'objectif étant surtout d'aider l'utilisateur à effectuer le
89 traitement exact dont il a besoin en sortie.
91 Le premier exemple (appelé "*AnalysisPrinter*" dans les entrées de type
92 "*Template*" pour la section "*UserPostAnalysis*") consiste à afficher, dans la
93 sortie standard d'exécution, la valeur de l'analyse ou de l'état optimal, noté
94 :math:`\mathbf{x}^a` dans la partie :ref:`section_theory`. Cela se réalise par
98 xa=numpy.ravel(ADD.get('Analysis')[-1])
101 La fonction ``numpy.ravel`` assure simplement que la variable ``xa`` contienne
102 un vrai vecteur unidimensionnel, quels que soient les choix informatiques
105 Un second exemple (appelé "*AnalysisSaver*" dans les entrées de type
106 "*Template*" pour la section "*UserPostAnalysis*") consiste à enregistrer sur
107 fichier la valeur de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`. Cela
108 se réalise par les commandes::
111 xa=numpy.ravel(ADD.get('Analysis')[-1])
112 f='/tmp/analysis.txt'
113 print('Analysis saved in "%s"'%f)
116 Le fichier d'enregistrement choisi est un fichier texte ``/tmp/analysis.txt``.
118 Il est aisé de combiner ces deux exemples pour en construire un troisième
119 (appelé "*AnalysisPrinterAndSaver*" dans les entrées de type "*Template*" pour
120 la section "*UserPostAnalysis*"). Il consiste à simultanément afficher dans la
121 sortie standard d'exécution et à enregistrer sur fichier la valeur de
122 :math:`\mathbf{x}^a`. Cela se réalise par les commandes::
125 xa=numpy.ravel(ADD.get('Analysis')[-1])
126 print('Analysis:',xa)
127 f='/tmp/analysis.txt'
128 print('Analysis saved in "%s"'%f)
131 Pour faciliter l'extension de ces exemples selon les besoins utilisateurs, on
132 rappelle que l'ensemble des fonctions de SALOME sont disponibles au même niveau
133 que ces commandes. L'utilisateur peut en particulier requérir des actions de
134 représentation graphique avec le module PARAVIS [#]_ ou d'autres modules, des
135 actions de calcul pilotés par YACS [#]_ ou un autre module, etc.
137 D'autres exemples d'utilisation sont aussi donnés en :ref:`section_u_step4` de
138 la partie :ref:`section_gui_in_salome`, ou en partie :ref:`section_tutorials_in_salome`.
140 Conditionnalité des informations disponibles en sortie
141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
143 .. index:: single: AlgorithmParameters
144 .. index:: single: Stored
146 La disponibilité des informations après le calcul est conditionnée par le fait
147 qu'elles aient été calculées ou demandées.
149 Chaque algorithme ne fournit pas obligatoirement les mêmes informations, et
150 n'utilise par exemple pas nécessairement les mêmes quantités intermédiaires. Il
151 y a donc des informations toujours présentes comme l'état optimal résultant du
152 calcul. Les autres informations ne sont présentes que pour certains algorithmes
153 et/ou que si elles ont été réclamées avant l'exécution du calcul.
155 On rappelle que l'utilisateur peut réclamer des informations supplémentaires
156 lors de l'établissement de son cas ADAO, en utilisant la commande optionnelle
157 "*AlgorithmParameters*" du cas ADAO. On se reportera à la
158 :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
159 commande, et à la description de chaque algorithme pour les informations
160 disponibles par algorithme. On peut aussi demander à conserver certaines
161 informations en entrée en changeant le booléen "*Stored*" qui lui est associé
162 dans l'édition du cas ADAO.
164 .. _subsection_r_o_v_Inventaire:
166 Inventaire des informations potentiellement disponibles en sortie
167 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
169 Les principales informations potentiellement disponibles en sortie sont
170 indiquées ici indépendamment des algorithmes, pour inventaire. On se reportera
171 directement aux détails des algorithmes pour avoir l'inventaire exhaustif.
173 L'état optimal est une information qui est toujours naturellement disponible
174 après un calcul d'assimilation de données ou d'optimisation. Il désigné par le
177 .. include:: snippets/Analysis.rst
179 Les variables suivantes sont des variables d'entrée que l'on peut aussi obtenir
180 en sortie. Elles sont mises à disposition de l'utilisateur en sortie pour
181 faciliter l'écriture des procédures de post-processing, et sont conditionnées
182 par une demande utilisateur explicite à l'aide d'un booléen "*Stored*" en
183 entrée. Toutes ces variables d'entrée restituées sont obtenables par la
184 commande standard ".get(...)", qui s'applique à refournir l'unique objet donné
187 .. include:: snippets/Background.rst
189 .. include:: snippets/BackgroundError.rst
191 .. include:: snippets/EvolutionError.rst
193 .. include:: snippets/Observation.rst
195 .. include:: snippets/ObservationError.rst
197 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
198 demande utilisateur de disponibilité. Les principales sont les suivantes, par
201 .. include:: snippets/APosterioriCorrelations.rst
203 .. include:: snippets/APosterioriCovariance.rst
205 .. include:: snippets/APosterioriStandardDeviations.rst
207 .. include:: snippets/APosterioriVariances.rst
209 .. include:: snippets/BMA.rst
211 .. include:: snippets/CostFunctionJ.rst
213 .. include:: snippets/CostFunctionJb.rst
215 .. include:: snippets/CostFunctionJo.rst
217 .. include:: snippets/CostFunctionJAtCurrentOptimum.rst
219 .. include:: snippets/CostFunctionJbAtCurrentOptimum.rst
221 .. include:: snippets/CostFunctionJoAtCurrentOptimum.rst
223 .. include:: snippets/CurrentOptimum.rst
225 .. include:: snippets/CurrentState.rst
227 .. include:: snippets/IndexOfOptimum.rst
229 .. include:: snippets/Innovation.rst
231 .. include:: snippets/InnovationAtCurrentState.rst
233 .. include:: snippets/OMA.rst
235 .. include:: snippets/OMB.rst
237 .. include:: snippets/Residu.rst
239 .. include:: snippets/SimulatedObservationAtBackground.rst
241 .. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
243 .. include:: snippets/SimulatedObservationAtCurrentState.rst
245 .. include:: snippets/SimulatedObservationAtOptimum.rst
247 .. include:: snippets/SimulationQuantiles.rst
249 .. [#] Pour de plus amples informations sur PARAVIS, voir le *module PARAVIS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
251 .. [#] 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.