doc/fr/ref_output_variables.rst

   1 ..
   2    Copyright (C) 2008-2021 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_gui_in_salome`, ou en partie :ref:`section_tutorials_in_salome`.
 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 Les principales informations potentiellement disponibles en sortie sont
 168 indiquées ici indépendamment des algorithmes, pour inventaire. On se reportera
 169 directement aux détails des algorithmes pour avoir l'inventaire exhaustif.
 170
 171 L'état optimal est une information qui est toujours naturellement disponible
 172 après un calcul d'assimilation de données ou d'optimisation. Il désigné par le
 173 mot-clé suivant:
 174
 175   .. include:: snippets/Analysis.rst
 176
 177 Les variables suivantes sont des variables d'entrée que l'on peut aussi obtenir
 178 en sortie. Elles sont mises à disposition de l'utilisateur en sortie pour
 179 faciliter l'écriture des procédures de post-processing, et sont conditionnées
 180 par une demande utilisateur explicite à l'aide d'un booléen "*Stored*" en
 181 entrée. Toutes ces variables d'entrée restituées sont obtenables par la
 182 commande standard ".get(...)", qui s'applique à refournir l'unique objet donné
 183 en entrée.
 184
 185   .. include:: snippets/Background.rst
 186
 187   .. include:: snippets/BackgroundError.rst
 188
 189   .. include:: snippets/EvolutionError.rst
 190
 191   .. include:: snippets/Observation.rst
 192
 193   .. include:: snippets/ObservationError.rst
 194
 195 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
 196 demande utilisateur de disponibilité. Les principales sont les suivantes, par
 197 ordre alphabétique:
 198
 199   .. include:: snippets/APosterioriCorrelations.rst
 200
 201   .. include:: snippets/APosterioriCovariance.rst
 202
 203   .. include:: snippets/APosterioriStandardDeviations.rst
 204
 205   .. include:: snippets/APosterioriVariances.rst
 206
 207   .. include:: snippets/BMA.rst
 208
 209   .. include:: snippets/CostFunctionJ.rst
 210
 211   .. include:: snippets/CostFunctionJb.rst
 212
 213   .. include:: snippets/CostFunctionJo.rst
 214
 215   .. include:: snippets/CostFunctionJAtCurrentOptimum.rst
 216
 217   .. include:: snippets/CostFunctionJbAtCurrentOptimum.rst
 218
 219   .. include:: snippets/CostFunctionJoAtCurrentOptimum.rst
 220
 221   .. include:: snippets/CurrentOptimum.rst
 222
 223   .. include:: snippets/CurrentState.rst
 224
 225   .. include:: snippets/IndexOfOptimum.rst
 226
 227   .. include:: snippets/Innovation.rst
 228
 229   .. include:: snippets/InnovationAtCurrentState.rst
 230
 231   .. include:: snippets/OMA.rst
 232
 233   .. include:: snippets/OMB.rst
 234
 235   .. include:: snippets/Residu.rst
 236
 237   .. include:: snippets/SimulatedObservationAtBackground.rst
 238
 239   .. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
 240
 241   .. include:: snippets/SimulatedObservationAtCurrentState.rst
 242
 243   .. include:: snippets/SimulatedObservationAtOptimum.rst
 244
 245   .. include:: snippets/SimulationQuantiles.rst
 246
 247 .. [#] 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.
 248
 249 .. [#] 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.