2 Copyright (C) 2008-2015 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
76 .. index:: single: AnalysisSaver
77 .. index:: single: AnalysisPrinterAndSaver
79 Ces exemples présentent des commandes ou scripts Python qui permettent d'obtenir
80 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 type
85 "*Script*") ou contenues dans une chaîne de caractères, y compris les retour à
86 la ligne (et insérées dans le cas ADAO par l'entrée de type "*String*"). De
87 nombreuses variantes peuvent être imaginées à partir de ces exemples simples,
88 l'objectif étant surtout d'aider l'utilisateur à effectuer le traitement exact
89 dont il a besoin en sortie.
91 Le premier exemple (appelé "*AnalysisPrinter*" dans les entrées de type
92 "*Template*") consiste à afficher, dans la sortie standard d'exécution, la
93 valeur de l'analyse ou de l'état optimal, noté :math:`\mathbf{x}^a` dans la
94 partie :ref:`section_theory`. Cela se réalise par les commandes::
97 xa=numpy.ravel(ADD.get('Analysis')[-1])
100 La fonction ``numpy.ravel`` assure simplement que la variable ``xa`` contienne
101 un vrai vecteur unidimensionnel, quels que soient les choix informatiques
104 Un second exemple (appelé "*AnalysisSaver*" dans les entrées de type
105 "*Template*") consiste à enregistrer sur fichier la valeur de l'analyse ou de
106 l'état optimal :math:`\mathbf{x}^a`. Cela se réalise par les commandes::
109 xa=numpy.ravel(ADD.get('Analysis')[-1])
110 f='/tmp/analysis.txt'
111 print 'Analysis saved in "%s"'%f
114 Le fichier d'enregistrement choisi est un fichier texte ``/tmp/analysis.txt``.
116 Il est aisé de combiner ces deux exemples pour en construire un troisième
117 (appelé "*AnalysisPrinterAndSaver*" dans les entrées de type "*Template*"). Il
118 consiste à simultanément afficher dans la sortie standard d'exécution et à
119 enregistrer sur fichier la valeur de :math:`\mathbf{x}^a`. Cela se réalise par
123 xa=numpy.ravel(ADD.get('Analysis')[-1])
125 f='/tmp/analysis.txt'
126 print 'Analysis saved in "%s"'%f
129 Pour faciliter l'extension de ces exemples selon les besoins utilisateurs, on
130 rappelle que l'ensemble des fonctions de SALOME sont disponibles au même niveau
131 que ces commandes. L'utilisateur peut en particulier requérir des actions de
132 représentation graphique avec le module PARAVIS [#]_ ou d'autres modules, des
133 actions de calcul pilotés par YACS [#]_ ou un autre module, etc.
135 D'autres exemples d'utilisation sont aussi donnés en :ref:`section_u_step4` de
136 la partie :ref:`section_using`, ou en partie :ref:`section_examples`.
138 Conditionnalité des informations disponibles en sortie
139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
141 .. index:: single: AlgorithmParameters
142 .. index:: single: Stored
144 La disponibilité des informations après le calcul est conditionnée par le fait
145 qu'elles aient été calculées ou demandées.
147 Chaque algorithme ne fournit pas obligatoirement les mêmes informations, et
148 n'utilise par exemple pas nécessairement les mêmes quantités intermédiaires. Il
149 y a donc des informations toujours présentes comme l'état optimal résultant du
150 calcul. Les autres informations ne sont présentes que pour certains algorithmes
151 et/ou que si elles ont été réclamées avant l'exécution du calcul.
153 On rappelle que l'utilisateur peut réclamer des informations supplémentaires
154 lors de l'établissement de son cas ADAO, en utilisant la commande optionnelle
155 "*AlgorithmParameters*" du cas ADAO. On se reportera à la
156 :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
157 commande, et à la description de chaque algorithme pour les informations
158 disponibles par algorithme. On peut aussi demander à conserver certaines
159 informations en entrée en changeant le booléen "*Stored*" qui lui est associé
160 dans l'édition du cas ADAO.
162 .. _subsection_r_o_v_Inventaire:
164 Inventaire des informations potentiellement disponibles en sortie
165 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
167 .. index:: single: Dry
168 .. index:: single: Forecast
170 L'ensemble des informations potentiellement disponibles en sortie est indiqué
171 ici indépendamment des algorithmes, pour inventaire.
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
178 *Liste de vecteurs*. Chaque élément est un état optimal :math:`\mathbf{x}*`
179 en optimisation ou une analyse :math:`\mathbf{x}^a` en assimilation de
182 Exemple : ``Xa = ADD.get("Analysis")[-1]``
184 Les variables suivantes sont des variables d'entrée. Elles sont mises à
185 disposition de l'utilisateur en sortie pour faciliter l'écriture des procédures
186 de post-processing, et sont conditionnées par une demande utilisateur à l'aide
187 d'un booléen "*Stored*" en entrée.
190 *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
191 C'est le vecteur d'ébauche :math:`\mathbf{x}^b`.
193 Exemple : ``Xb = ADD.get("Background")``
196 *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
197 C'est la matrice :math:`\mathbf{B}` de covariances des erreurs *a priori*
200 Exemple : ``B = ADD.get("BackgroundError")``
203 *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
204 C'est la matrice :math:`\mathbf{M}` de covariances des erreurs *a priori*
207 Exemple : ``M = ADD.get("EvolutionError")``
210 *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
211 C'est le vecteur d'observation :math:`\mathbf{y}^o`.
213 Exemple : ``Yo = ADD.get("Observation")``
216 *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
217 C'est la matrice :math:`\mathbf{R}` de covariances des erreurs *a priori*
220 Exemple : ``R = ADD.get("ObservationError")``
222 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
223 demande utilisateur de disponibilité. Ce sont les suivantes, par ordre
226 APosterioriCorrelations
227 *Liste de matrices*. Chaque élément est une matrice de corrélations des
228 erreurs *a posteriori* de l'état optimal, issue de la matrice
229 :math:`\mathbf{A}*` des covariances.
231 Exemple : ``C = ADD.get("APosterioriCorrelations")[-1]``
233 APosterioriCovariance
234 *Liste de matrices*. Chaque élément est une matrice :math:`\mathbf{A}*` de
235 covariances des erreurs *a posteriori* de l'état optimal.
237 Exemple : ``A = ADD.get("APosterioriCovariance")[-1]``
239 APosterioriStandardDeviations
240 *Liste de matrices*. Chaque élément est une matrice diagonale d'écarts-types
241 des erreurs *a posteriori* de l'état optimal, issue de la matrice
242 :math:`\mathbf{A}*` des covariances.
244 Exemple : ``S = ADD.get("APosterioriStandardDeviations")[-1]``
247 *Liste de matrices*. Chaque élément est une matrice diagonale de variances
248 des erreurs *a posteriori* de l'état optimal, issue de la matrice
249 :math:`\mathbf{A}*` des covariances.
251 Exemple : ``V = ADD.get("APosterioriVariances")[-1]``
254 *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
255 l'ébauche et l'état optimal.
257 Exemple : ``bma = ADD.get("BMA")[-1]``
260 *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
263 Exemple : ``J = ADD.get("CostFunctionJ")[:]``
266 *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
267 :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche.
269 Exemple : ``Jb = ADD.get("CostFunctionJb")[:]``
272 *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
273 :math:`J^o`, c'est-à-dire de la partie écart à l'observation.
275 Exemple : ``Jo = ADD.get("CostFunctionJo")[:]``
277 CostFunctionJAtCurrentOptimum
278 *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
279 :math:`J`. A chaque pas, la valeur correspond à l'état optimal trouvé depuis
282 Exemple : ``JACO = ADD.get("CostFunctionJAtCurrentOptimum")[:]``
284 CostFunctionJbAtCurrentOptimum
285 *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
286 :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche. A chaque pas, la
287 valeur correspond à l'état optimal trouvé depuis le début.
289 Exemple : ``JbACO = ADD.get("CostFunctionJbAtCurrentOptimum")[:]``
291 CostFunctionJoAtCurrentOptimum
292 *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
293 :math:`J^o`, c'est-à-dire de la partie écart à l'observation. A chaque pas,
294 la valeur correspond à l'état optimal trouvé depuis le début.
296 Exemple : ``JoACO = ADD.get("CostFunctionJoAtCurrentOptimum")[:]``
299 *Liste de vecteurs*. Chaque élément est le vecteur d'état optimal au pas de
300 temps courant au cours du déroulement de l'algorithme d'optimisation. Ce
301 n'est pas nécessairement le dernier état.
303 Exemple : ``Xo = ADD.get("CurrentOptimum")[:]``
306 *Liste de vecteurs*. Chaque élément est un vecteur d'état courant utilisé
307 au cours du déroulement de l'algorithme d'optimisation.
309 Exemple : ``Xs = ADD.get("CurrentState")[:]``
312 *Liste d'entiers*. Chaque élément est l'index d'itération de l'optimum
313 obtenu au cours du déroulement de l'algorithme d'optimisation. Ce n'est pas
314 nécessairement le numéro de la dernière itération.
316 Exemple : ``i = ADD.get("IndexOfOptimum")[-1]``
319 *Liste de vecteurs*. Chaque élément est un vecteur d'innovation, qui est
320 en statique l'écart de l'optimum à l'ébauche, et en dynamique l'incrément
323 Exemple : ``d = ADD.get("Innovation")[-1]``
325 InnovationAtCurrentState
326 *Liste de vecteurs*. Chaque élément est un vecteur d'innovation à l'état
329 Exemple : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
331 MahalanobisConsistency
332 *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
333 qualité de Mahalanobis.
335 Exemple : ``m = ADD.get("MahalanobisConsistency")[-1]``
338 *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
339 l'observation et l'état optimal dans l'espace des observations.
341 Exemple : ``oma = ADD.get("OMA")[-1]``
344 *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
345 l'observation et l'état d'ébauche dans l'espace des observations.
347 Exemple : ``omb = ADD.get("OMB")[-1]``
350 *Liste de valeurs*. Chaque élément est la valeur du résidu particulier
351 vérifié lors d'un algorithme de vérification, selon l'ordre des tests
354 Exemple : ``r = ADD.get("Residu")[:]``
357 *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
358 qualité :math:`(\sigma^b)^2` de la partie ébauche.
360 Exemple : ``sb2 = ADD.get("SigmaBck")[-1]``
363 *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
364 qualité :math:`(\sigma^o)^2` de la partie observation.
366 Exemple : ``so2 = ADD.get("SigmaObs")[-1]``
368 SimulatedObservationAtBackground
369 *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
370 partir de l'ébauche :math:`\mathbf{x}^b`. C'est la prévision à partir de
371 l'ébauche, et elle est parfois appellée "*Dry*".
373 Exemple : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
375 SimulatedObservationAtCurrentOptimum
376 *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
377 partir de l'état optimal au pas de temps courant au cours du déroulement de
378 l'algorithme d'optimisation, c'est-à-dire dans l'espace des observations.
380 Exemple : ``hxo = ADD.get("SimulatedObservationAtCurrentOptimum")[-1]``
382 SimulatedObservationAtCurrentState
383 *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
384 partir de l'état courant, c'est-à-dire dans l'espace des observations.
386 Exemple : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
388 SimulatedObservationAtOptimum
389 *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
390 partir de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`. C'est la
391 prévision à partir de l'analyse ou de l'état optimal, et elle est parfois
392 appellée "*Forecast*".
394 Exemple : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
397 *Liste de vecteurs*. Chaque élément est un vecteur correspondant à l'état
398 observé qui réalise le quantile demandé, dans le même ordre que les
399 quantiles requis par l'utilisateur.
401 Exemple : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``
403 .. [#] 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.
405 .. [#] 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.
