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 des informations disponibles en sortie
  30 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  31
  32 .. index:: single: UserPostAnalysis
  33 .. index:: single: algoResults
  34 .. index:: single: get
  35
  36 En sortie, après exécution d'une assimilation de données, d'une optimisation
  37 ou d'une vérification, on dispose de variables et d'informations issues du
  38 calcul. L'obtention de ces informations se fait ensuite de manière standardisée
  39 à l'aide de l'étape de post-processing du calcul.
  40
  41 L'étape est aisément identifiée par l'utilisateur dans son cas ADAO de
  42 définition (par la mot-clé "*UserPostAnalysis*") ou dans son schéma YACS
  43 d'exécution (par des noeuds ou blocs situés après le bloc de calcul, et reliés
  44 graphiquement au port de sortie "*algoResults*" du bloc de calcul):
  45
  46 #. 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.
  47 #. 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()``.
  48
  49 Dans tous les cas, le post-processing de l'utilisateur dispose dans l'espace de
  50 noms d'une variable dont le nom est "*ADD*", et dont l'unique méthode utilisable
  51 est nommée ``get``. Les arguments de cette méthode sont un nom d'information de
  52 sortie, comme décrit dans l':ref:`subsection_r_o_v_Inventaire`.
  53
  54 Par exemple, pour avoir l'état optimal après un calcul d'assimilation de données
  55 ou d'optimisation, on utilise l'appel suivant::
  56
  57     ADD.get("Analysis")
  58
  59 Cet appel renvoie une liste de valeurs de la notion demandée (ou, dans le cas
  60 de variables d'entrées qui ne sont par nature qu'en un unique exemplaire, la
  61 valeur elle-même). On peut alors demander un élément particulier de la liste par
  62 les commandes standards de liste (en particulier ``[-1]`` pour le dernier, et
  63 ``[:]`` pour tous les éléments).
  64
  65 Conditionnalité des informations disponibles en sortie
  66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  67
  68 .. index:: single: StoreInternalVariables
  69 .. index:: single: AlgorithmParameters
  70 .. index:: single: Stored
  71
  72 La disponibilité des informations après le calcul est conditionnée par le fait
  73 qu'elles aient été calculées ou demandées.
  74
  75 Chaque algorithme ne fournit pas obligatoirement les mêmes informations, et
  76 n'utilise par exemple pas nécessairement les mêmes quantités intermédiaires. Il
  77 y a donc des informations toujours présentes comme l'état optimal résultant du
  78 calcul. Les autres informations ne sont présentes que pour certains algorithmes
  79 et/ou que si elles ont été réclamées avant l'exécution du calcul.
  80
  81 On rappelle que l'utilisateur peut réclamer des informations supplémentaires
  82 lors de l'établissement de son cas ADAO, en utilisant l'option
  83 "*StoreInternalVariables*" de chaque algorithme à travers la commande
  84 optionnelle "*AlgorithmParameters*" du cas ADAO. On se reportera à la
  85 :ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette
  86 commande, et à la description de chaque algorithme pour les informations
  87 disponibles par algorithme. On peut aussi demander à conserver certaines
  88 informations en entrée en changeant le booléen "*Stored*" qui lui est associé
  89 dans l'édition du cas ADAO.
  90
  91 .. _subsection_r_o_v_Inventaire:
  92
  93 Inventaire des informations potentiellement disponibles en sortie
  94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  95
  96 L'ensemble des informations potentiellement disponibles en sortie est indiqué
  97 ici indépendamment des algorithmes, pour inventaire.
  98
  99 L'état optimal est une information qui est toujours naturellement disponible
 100 après un calcul d'assimilation de données ou d'optimisation. Il désigné par le
 101 mot-clé suivant:
 102
 103   Analysis
 104     *Liste de vecteurs*. Chaque élément est un état optimal :math:`\mathbf{x}*`
 105     en optimisation ou une analyse :math:`\mathbf{x}^a` en assimilation de
 106     données.
 107
 108     Exemple : ``Xa = ADD.get("Analysis")[-1]``
 109
 110 Les variables suivantes sont des variables d'entrée. Elles sont mises à
 111 disposition de l'utilisateur en sortie pour faciliter l'écriture des procédures
 112 de post-processing, et sont conditionnées par une demande utilisateur à l'aide
 113 d'un booléen "*Stored*" en entrée.
 114
 115   Background
 116     *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 117     C'est le vecteur d'ébauche :math:`\mathbf{x}^b`.
 118
 119     Exemple : ``Xb = ADD.get("Background")``
 120
 121   BackgroundError
 122     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 123     C'est la matrice :math:`\mathbf{B}` de covariances des erreurs *a priori*
 124     de l'ébauche.
 125
 126     Exemple : ``B = ADD.get("BackgroundError")``
 127
 128   EvolutionError
 129     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 130     C'est la matrice :math:`\mathbf{M}` de covariances des erreurs *a priori*
 131     de l'évolution.
 132
 133     Exemple : ``M = ADD.get("EvolutionError")``
 134
 135   Observation
 136     *Vecteur*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 137     C'est le vecteur d'observation :math:`\mathbf{y}^o`.
 138
 139     Exemple : ``Yo = ADD.get("Observation")``
 140
 141   ObservationError
 142     *Matrice*, dont la disponibilité est conditionnée par "*Stored*" en entrée.
 143     C'est la matrice :math:`\mathbf{R}` de covariances des erreurs *a priori*
 144     de l'observation.
 145
 146     Exemple : ``R = ADD.get("ObservationError")``
 147
 148 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
 149 demande utilisateur de disponibilité. Ce sont les suivantes, par ordre
 150 alphabétique:
 151
 152   APosterioriCovariance
 153     *Liste de matrices*. Chaque élément est une matrice :math:`\mathbf{A}*` de
 154     covariances des erreurs *a posteriori* de l'état optimal.
 155
 156     Exemple : ``A = ADD.get("APosterioriCovariance")[-1]``
 157
 158   BMA
 159     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 160     l'ébauche et l'état optimal.
 161
 162     Exemple : ``bma = ADD.get("BMA")[-1]``
 163
 164   CostFunctionJ
 165     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 166     :math:`J`.
 167
 168     Exemple : ``J = ADD.get("CostFunctionJ")[:]``
 169
 170   CostFunctionJb
 171     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 172     :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche.
 173
 174     Exemple : ``Jb = ADD.get("CostFunctionJb")[:]``
 175
 176   CostFunctionJo
 177     *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
 178     :math:`J^o`, c'est-à-dire de la partie écart à l'observation.
 179
 180     Exemple : ``Jo = ADD.get("CostFunctionJo")[:]``
 181
 182   CurrentState
 183     *Liste de vecteurs*. Chaque élément est un vecteur d'état courant utilisé
 184     au cours du déroulement de l'algorithme d'optimisation.
 185
 186     Exemple : ``Xs = ADD.get("CurrentState")[:]``
 187
 188   Innovation
 189     *Liste de vecteurs*. Chaque élément est un vecteur d'innovation, qui est
 190     en statique l'écart de l'optimum à l'ébauche, et en dynamique l'incrément
 191     d'évolution.
 192
 193     Exemple : ``d = ADD.get("Innovation")[-1]``
 194
 195   MahalanobisConsistency
 196     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 197     qualité de Mahalanobis.
 198
 199     Exemple : ``m = ADD.get("MahalanobisConsistency")[-1]``
 200
 201   ObservedState
 202     *Liste de vecteurs*. Chaque élément est un vecteur d'état observé,
 203     c'est-à-dire dans l'espace des observations.
 204
 205     Exemple : ``Ys = ADD.get("ObservedState")[-1]``
 206
 207   OMA
 208     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 209     l'observation et l'état optimal dans l'espace des observations.
 210
 211     Exemple : ``oma = ADD.get("OMA")[-1]``
 212
 213   OMB
 214     *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
 215     l'observation et l'état d'ébauche dans l'espace des observations.
 216
 217     Exemple : ``omb = ADD.get("OMB")[-1]``
 218
 219   SigmaBck2
 220     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 221     qualité :math:`(\sigma^b)^2` de la partie ébauche.
 222
 223     Exemple : ``sb2 = ADD.get("SigmaBck")[-1]``
 224
 225   SigmaObs2
 226     *Liste de valeurs*. Chaque élément est une valeur de l'indicateur de
 227     qualité :math:`(\sigma^o)^2` de la partie observation.
 228
 229     Exemple : ``so2 = ADD.get("SigmaObs")[-1]``
 230
 231   SimulationQuantiles
 232     *Liste de vecteurs*. Chaque élément est un vecteur correspondant à l'état
 233     observé qui réalise le quantile demandé, dans le même ordre que les
 234     quantiles requis par l'utilisateur.
 235
 236     Exemple : ``sQuantiles = ADD.get("SimulationQuantiles")[:]``