doc/fr/ref_output_variables.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_ref_output_variables:
  25
  26 Variables et informations disponibles en sortie
  27 -----------------------------------------------
  28
  29 Comment obtenir les informations disponibles en sortie
  30 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  31
  32 .. index:: single: UserPostAnalysis
  33 .. index:: single: algoResults
  34 .. index:: single: getResults
  35 .. index:: single: get
  36 .. index:: single: ADD
  37
  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.
  42
  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):
  47
  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()``.
  50
  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`.
  57
  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::
  60
  61     ADD.get("Analysis")
  62
  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).
  68
  69 .. _subsection_r_o_v_Template:
  70
  71 Exemples de scripts Python pour obtenir ou traiter les sorties
  72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  73
  74 .. index:: single: Template
  75 .. index:: single: AnalysisPrinter
  76 .. index:: single: AnalysisSaver
  77 .. index:: single: AnalysisPrinterAndSaver
  78
  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.
  90
  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::
  95
  96     import numpy
  97     xa=numpy.ravel(ADD.get('Analysis')[-1])
  98     print 'Analysis:',xa"
  99
 100 La fonction ``numpy.ravel`` assure simplement que la variable ``xa`` contienne
 101 un vrai vecteur unidimensionnel, quels que soient les choix informatiques
 102 précédents.
 103
 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::
 107
 108     import numpy
 109     xa=numpy.ravel(ADD.get('Analysis')[-1])
 110     f='/tmp/analysis.txt'
 111     print 'Analysis saved in "%s"'%f
 112     numpy.savetxt(f,xa)"
 113
 114 Le fichier d'enregistrement choisi est un fichier texte ``/tmp/analysis.txt``.
 115
 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
 120 les commandes::
 121
 122     import numpy
 123     xa=numpy.ravel(ADD.get('Analysis')[-1])
 124     print 'Analysis:',xa
 125     f='/tmp/analysis.txt'
 126     print 'Analysis saved in "%s"'%f
 127     numpy.savetxt(f,xa)
 128
 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.
 134
 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`.
 137
 138 Conditionnalité des informations disponibles en sortie
 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 140
 141 .. index:: single: AlgorithmParameters
 142 .. index:: single: Stored
 143
 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.
 146
 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.
 152
 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.
 161
 162 .. _subsection_r_o_v_Inventaire:
 163
 164 Inventaire des informations potentiellement disponibles en sortie
 165 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 166
 167 L'ensemble des informations potentiellement disponibles en sortie est indiqué
 168 ici indépendamment des algorithmes, pour inventaire.
 169
 170 L'état optimal est une information qui est toujours naturellement disponible
 171 après un calcul d'assimilation de données ou d'optimisation. Il désigné par le
 172 mot-clé suivant:
 173
 174   Analysis
 175     *Liste de vecteurs*. Chaque élément est un état optimal :math:`\mathbf{x}*`
 176     en optimisation ou une analyse :math:`\mathbf{x}^a` en assimilation de
 177     données.
 178
 179     Exemple : ``Xa = ADD.get("Analysis")[-1]``
 180
 181 Les variables suivantes sont des variables d'entrée. Elles sont mises à
 182 disposition de l'utilisateur en sortie pour faciliter l'écriture des procédures
 183 de post-processing, et sont conditionnées par une demande utilisateur à l'aide
 184 d'un booléen "*Stored*" en entrée.
 185
 186   Background
 187     *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 188     C'est le vecteur d'ébauche :math:`\mathbf{x}^b`.
 189
 190     Exemple : ``Xb = ADD.get("Background")``
 191
 192   BackgroundError
 193     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 194     C'est la matrice :math:`\mathbf{B}` de covariances des erreurs *a priori*
 195     de l'ébauche.
 196
 197     Exemple : ``B = ADD.get("BackgroundError")``
 198
 199   EvolutionError
 200     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 201     C'est la matrice :math:`\mathbf{M}` de covariances des erreurs *a priori*
 202     de l'évolution.
 203
 204     Exemple : ``M = ADD.get("EvolutionError")``
 205
 206   Observation
 207     *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 208     C'est le vecteur d'observation :math:`\mathbf{y}^o`.
 209
 210     Exemple : ``Yo = ADD.get("Observation")``
 211
 212   ObservationError
 213     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 214     C'est la matrice :math:`\mathbf{R}` de covariances des erreurs *a priori*
 215     de l'observation.
 216
 217     Exemple : ``R = ADD.get("ObservationError")``
 218
 219 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
 220 demande utilisateur de disponibilité. Ce sont les suivantes, par ordre
 221 alphabétique:
 222
 223   APosterioriCorrelations
 224     *Liste de matrices*. Chaque élément est une matrice de corrélations des
 225     erreurs *a posteriori* de l'état optimal, issue de la matrice
 226     :math:`\mathbf{A}*` des covariances.
 227
 228     Exemple : ``C = ADD.get("APosterioriCorrelations")[-1]``
 229
 230   APosterioriCovariance
 231     *Liste de matrices*. Chaque élément est une matrice :math:`\mathbf{A}*` de
 232     covariances des erreurs *a posteriori* de l'état optimal.
 233
 234     Exemple : ``A = ADD.get("APosterioriCovariance")[-1]``
 235
 236   APosterioriStandardDeviations
 237     *Liste de matrices*. Chaque élément est une matrice diagonale d'écarts-types
 238     des erreurs *a posteriori* de l'état optimal, issue de la matrice
 239     :math:`\mathbf{A}*` des covariances.
 240
 241     Exemple : ``S = ADD.get("APosterioriStandardDeviations")[-1]``
 242
 243   APosterioriVariances
 244     *Liste de matrices*. Chaque élément est une matrice diagonale de variances
 245     des erreurs *a posteriori* de l'état optimal, issue de la matrice
 246     :math:`\mathbf{A}*` des covariances.
 247
 248     Exemple : ``V = ADD.get("APosterioriVariances")[-1]``
 249
 250   BMA
 251     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 252     l'ébauche et l'état optimal.
 253
 254     Exemple : ``bma = ADD.get("BMA")[-1]``
 255
 256   CostFunctionJ
 257     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 258     :math:`J`.
 259
 260     Exemple : ``J = ADD.get("CostFunctionJ")[:]``
 261
 262   CostFunctionJb
 263     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 264     :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche.
 265
 266     Exemple : ``Jb = ADD.get("CostFunctionJb")[:]``
 267
 268   CostFunctionJo
 269     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 270     :math:`J^o`, c'est-à-dire de la partie écart à l'observation.
 271
 272     Exemple : ``Jo = ADD.get("CostFunctionJo")[:]``
 273
 274   CurrentOptimum
 275     *Liste de vecteurs*. Chaque élément est le vecteur d'état optimal au pas de
 276     temps courant au cours du déroulement de l'algorithme d'optimisation. Ce
 277     n'est pas nécessairement le dernier état.
 278
 279     Exemple : ``Xo = ADD.get("CurrentOptimum")[:]``
 280
 281   CurrentState
 282     *Liste de vecteurs*. Chaque élément est un vecteur d'état courant utilisé
 283     au cours du déroulement de l'algorithme d'optimisation.
 284
 285     Exemple : ``Xs = ADD.get("CurrentState")[:]``
 286
 287   IndexOfOptimum
 288     *Liste d'entiers*. Chaque élément est l'index d'itération de l'optimum
 289     obtenu au cours du déroulement de l'algorithme d'optimisation. Ce n'est pas
 290     nécessairement le numéro de la dernière itération.
 291
 292     Exemple : ``i = ADD.get("IndexOfOptimum")[-1]``
 293
 294   Innovation
 295     *Liste de vecteurs*. Chaque élément est un vecteur d'innovation, qui est
 296     en statique l'écart de l'optimum à l'ébauche, et en dynamique l'incrément
 297     d'évolution.
 298
 299     Exemple : ``d = ADD.get("Innovation")[-1]``
 300
 301   InnovationAtCurrentState
 302     *Liste de vecteurs*. Chaque élément est un vecteur d'innovation à l'état
 303     courant.
 304
 305     Exemple : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
 306
 307   MahalanobisConsistency
 308     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 309     qualité de Mahalanobis.
 310
 311     Exemple : ``m = ADD.get("MahalanobisConsistency")[-1]``
 312
 313   OMA
 314     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 315     l'observation et l'état optimal dans l'espace des observations.
 316
 317     Exemple : ``oma = ADD.get("OMA")[-1]``
 318
 319   OMB
 320     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 321     l'observation et l'état d'ébauche dans l'espace des observations.
 322
 323     Exemple : ``omb = ADD.get("OMB")[-1]``
 324
 325   SigmaBck2
 326     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 327     qualité :math:`(\sigma^b)^2` de la partie ébauche.
 328
 329     Exemple : ``sb2 = ADD.get("SigmaBck")[-1]``
 330
 331   SigmaObs2
 332     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 333     qualité :math:`(\sigma^o)^2` de la partie observation.
 334
 335     Exemple : ``so2 = ADD.get("SigmaObs")[-1]``
 336
 337   SimulatedObservationAtBackground
 338     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
 339     partir de l'ébauche :math:`\mathbf{x}^b`.
 340
 341     Exemple : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 342
 343   SimulatedObservationAtCurrentOptimum
 344     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
 345     partir de l'état optimal au pas de temps courant au cours du déroulement de
 346     l'algorithme d'optimisation, c'est-à-dire dans l'espace des observations.
 347
 348     Exemple : ``hxo = ADD.get("SimulatedObservationAtCurrentOptimum")[-1]``
 349
 350   SimulatedObservationAtCurrentState
 351     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
 352     partir de l'état courant, c'est-à-dire dans l'espace des observations.
 353
 354     Exemple : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 355
 356   SimulatedObservationAtOptimum
 357     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
 358     partir de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`.
 359
 360     Exemple : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 361
 362   SimulationQuantiles
 363     *Liste de vecteurs*. Chaque élément est un vecteur correspondant à l'état
 364     observé qui réalise le quantile demandé, dans le même ordre que les
 365     quantiles requis par l'utilisateur.
 366
 367     Exemple : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``
 368
 369 .. [#] 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.
 370
 371 .. [#] 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.