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 la 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 l'utilisateur,
  81 ils sont directement disponibles dans l'interface, à la construction du cas ADAO
  82 dans EFICAS, dans les champs de type "*Template*". De manière équivalente, ces
  83 commandes peuvent être contenues dans un script utilisateur externe (et insérées
  84 dans le cas ADAO par l'entrée de type "*Script*") ou contenues dans une chaîne
  85 de caractères, y compris les retour à la ligne (et insérées dans le cas ADAO par
  86 l'entrée de type "*String*"). De nombreuses variantes peuvent être imaginées à
  87 partir de ces exemples simples, l'objectif étant surtout d'aider l'utilisateur à
  88 effectuer le traitement exact dont il a besoin en sortie.
  89
  90 Le premier exemple (appelé "*AnalysisPrinter*" dans les entrées de type
  91 "*Template*") consiste à afficher, dans la sortie standard d'exécution, la
  92 valeur de l'analyse ou de l'état optimal, noté :math:`\mathbf{x}^a` dans la
  93 partie :ref:`section_theory`. Cela se réalise par les commandes::
  94
  95     import numpy
  96     xa=numpy.ravel(ADD.get('Analysis')[-1])
  97     print 'Analysis:',xa"
  98
  99 La fonction ``numpy.ravel`` assure simplement que la variable ``xa`` contienne
 100 un vrai vecteur unidimensionnel, quels que soient les choix informatiques
 101 précédents.
 102
 103 Un second exemple (appelé "*AnalysisSaver*" dans les entrées de type
 104 "*Template*") consiste à enregistrer sur fichier la valeur de l'analyse ou de
 105 l'état optimal :math:`\mathbf{x}^a`. Cela se réalise par les commandes::
 106
 107     import numpy
 108     xa=numpy.ravel(ADD.get('Analysis')[-1])
 109     f='/tmp/analysis.txt'
 110     print 'Analysis saved in "%s"'%f
 111     numpy.savetxt(f,xa)"
 112
 113 Le fichier d'enregistrement choisi est un fichier texte ``/tmp/analysis.txt``.
 114
 115 Il est aisé de combiner ces deux exemples pour en construire un troisième
 116 (appelé "*AnalysisPrinterAndSaver*" dans les entrées de type "*Template*"). Il
 117 consiste à simultanément afficher dans la sortie standard d'exécution et à
 118 enregistrer sur fichier la valeur de :math:`\mathbf{x}^a`. Cela se réalise par
 119 les commandes::
 120
 121     import numpy
 122     xa=numpy.ravel(ADD.get('Analysis')[-1])
 123     print 'Analysis:',xa
 124     f='/tmp/analysis.txt'
 125     print 'Analysis saved in "%s"'%f
 126     numpy.savetxt(f,xa)
 127
 128 Pour faciliter l'extension de ces exemples selon les besoins utilisateurs, on
 129 rappelle que l'ensemble des fonctions de SALOME sont disponibles au même niveau
 130 que ces commandes. L'utilisateur peut en particulier requérir des actions de
 131 représentation graphique avec le module PARAVIS [#]_ ou d'autres modules, des
 132 actions de calcul pilotés par YACS [#]_ ou un autre module, etc.
 133
 134 D'autres exemples d'utilisation sont aussi donnés en :ref:`section_u_step4` de
 135 la partie :ref:`section_using`, ou en partie :ref:`section_examples`.
 136
 137 Conditionnalité des informations disponibles en sortie
 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 139
 140 .. index:: single: AlgorithmParameters
 141 .. index:: single: Stored
 142
 143 La disponibilité des informations après le calcul est conditionnée par le fait
 144 qu'elles aient été calculées ou demandées.
 145
 146 Chaque algorithme ne fournit pas obligatoirement les mêmes informations, et
 147 n'utilise par exemple pas nécessairement les mêmes quantités intermédiaires. Il
 148 y a donc des informations toujours présentes comme l'état optimal résultant du
 149 calcul. Les autres informations ne sont présentes que pour certains algorithmes
 150 et/ou que si elles ont été réclamées avant l'exécution du calcul.
 151
 152 On rappelle que l'utilisateur peut réclamer des informations supplémentaires
 153 lors de l'établissement de son cas ADAO, en utilisant la commande optionnelle
 154 "*AlgorithmParameters*" du cas ADAO. On se reportera à la
 155 :ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette
 156 commande, et à la description de chaque algorithme pour les informations
 157 disponibles par algorithme. On peut aussi demander à conserver certaines
 158 informations en entrée en changeant le booléen "*Stored*" qui lui est associé
 159 dans l'édition du cas ADAO.
 160
 161 .. _subsection_r_o_v_Inventaire:
 162
 163 Inventaire des informations potentiellement disponibles en sortie
 164 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 165
 166 L'ensemble des informations potentiellement disponibles en sortie est indiqué
 167 ici indépendamment des algorithmes, pour inventaire.
 168
 169 L'état optimal est une information qui est toujours naturellement disponible
 170 après un calcul d'assimilation de données ou d'optimisation. Il désigné par le
 171 mot-clé suivant:
 172
 173   Analysis
 174     *Liste de vecteurs*. Chaque élément est un état optimal :math:`\mathbf{x}*`
 175     en optimisation ou une analyse :math:`\mathbf{x}^a` en assimilation de
 176     données.
 177
 178     Exemple : ``Xa = ADD.get("Analysis")[-1]``
 179
 180 Les variables suivantes sont des variables d'entrée. Elles sont mises à
 181 disposition de l'utilisateur en sortie pour faciliter l'écriture des procédures
 182 de post-processing, et sont conditionnées par une demande utilisateur à l'aide
 183 d'un booléen "*Stored*" en entrée.
 184
 185   Background
 186     *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 187     C'est le vecteur d'ébauche :math:`\mathbf{x}^b`.
 188
 189     Exemple : ``Xb = ADD.get("Background")``
 190
 191   BackgroundError
 192     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 193     C'est la matrice :math:`\mathbf{B}` de covariances des erreurs *a priori*
 194     de l'ébauche.
 195
 196     Exemple : ``B = ADD.get("BackgroundError")``
 197
 198   EvolutionError
 199     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 200     C'est la matrice :math:`\mathbf{M}` de covariances des erreurs *a priori*
 201     de l'évolution.
 202
 203     Exemple : ``M = ADD.get("EvolutionError")``
 204
 205   Observation
 206     *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 207     C'est le vecteur d'observation :math:`\mathbf{y}^o`.
 208
 209     Exemple : ``Yo = ADD.get("Observation")``
 210
 211   ObservationError
 212     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 213     C'est la matrice :math:`\mathbf{R}` de covariances des erreurs *a priori*
 214     de l'observation.
 215
 216     Exemple : ``R = ADD.get("ObservationError")``
 217
 218 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
 219 demande utilisateur de disponibilité. Ce sont les suivantes, par ordre
 220 alphabétique:
 221
 222   APosterioriCovariance
 223     *Liste de matrices*. Chaque élément est une matrice :math:`\mathbf{A}*` de
 224     covariances des erreurs *a posteriori* de l'état optimal.
 225
 226     Exemple : ``A = ADD.get("APosterioriCovariance")[-1]``
 227
 228   BMA
 229     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 230     l'ébauche et l'état optimal.
 231
 232     Exemple : ``bma = ADD.get("BMA")[-1]``
 233
 234   CostFunctionJ
 235     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 236     :math:`J`.
 237
 238     Exemple : ``J = ADD.get("CostFunctionJ")[:]``
 239
 240   CostFunctionJb
 241     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 242     :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche.
 243
 244     Exemple : ``Jb = ADD.get("CostFunctionJb")[:]``
 245
 246   CostFunctionJo
 247     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 248     :math:`J^o`, c'est-à-dire de la partie écart à l'observation.
 249
 250     Exemple : ``Jo = ADD.get("CostFunctionJo")[:]``
 251
 252   CurrentState
 253     *Liste de vecteurs*. Chaque élément est un vecteur d'état courant utilisé
 254     au cours du déroulement de l'algorithme d'optimisation.
 255
 256     Exemple : ``Xs = ADD.get("CurrentState")[:]``
 257
 258   Innovation
 259     *Liste de vecteurs*. Chaque élément est un vecteur d'innovation, qui est
 260     en statique l'écart de l'optimum à l'ébauche, et en dynamique l'incrément
 261     d'évolution.
 262
 263     Exemple : ``d = ADD.get("Innovation")[-1]``
 264
 265   MahalanobisConsistency
 266     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 267     qualité de Mahalanobis.
 268
 269     Exemple : ``m = ADD.get("MahalanobisConsistency")[-1]``
 270
 271   OMA
 272     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 273     l'observation et l'état optimal dans l'espace des observations.
 274
 275     Exemple : ``oma = ADD.get("OMA")[-1]``
 276
 277   OMB
 278     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 279     l'observation et l'état d'ébauche dans l'espace des observations.
 280
 281     Exemple : ``omb = ADD.get("OMB")[-1]``
 282
 283   SigmaBck2
 284     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 285     qualité :math:`(\sigma^b)^2` de la partie ébauche.
 286
 287     Exemple : ``sb2 = ADD.get("SigmaBck")[-1]``
 288
 289   SigmaObs2
 290     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 291     qualité :math:`(\sigma^o)^2` de la partie observation.
 292
 293     Exemple : ``so2 = ADD.get("SigmaObs")[-1]``
 294
 295   SimulatedObservationAtBackground
 296     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
 297     partir de l'ébauche :math:`\mathbf{x}^b`.
 298
 299     Exemple : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 300
 301   SimulatedObservationAtCurrentState
 302     *Liste de vecteurs*. Chaque élément est un vecteur observé à l'état courant,
 303     c'est-à-dire dans l'espace des observations.
 304
 305     Exemple : ``Ys = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 306
 307   SimulatedObservationAtOptimum
 308     *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé à
 309     partir de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`.
 310
 311     Exemple : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 312
 313   SimulationQuantiles
 314     *Liste de vecteurs*. Chaque élément est un vecteur correspondant à l'état
 315     observé qui réalise le quantile demandé, dans le même ordre que les
 316     quantiles requis par l'utilisateur.
 317
 318     Exemple : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``
 319
 320 .. [#] 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.
 321
 322 .. [#] 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.