doc/fr/ref_output_variables.rst

   1 ..
   2    Copyright (C) 2008-2023 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 (UserPostAnalysis)
  76 .. index:: single: AnalysisSaver (UserPostAnalysis)
  77 .. index:: single: AnalysisPrinterAndSaver (UserPostAnalysis)
  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*" pour la section "*UserPostAnalysis*") consiste à afficher, dans la
  93 sortie standard d'exécution, la valeur de l'analyse ou de l'état optimal, noté
  94 :math:`\mathbf{x}^a` dans la partie :ref:`section_theory`. Cela se réalise par
  95 les commandes::
  96
  97     import numpy
  98     xa=numpy.ravel(ADD.get('Analysis')[-1])
  99     print('Analysis:',xa)
 100
 101 La fonction ``numpy.ravel`` assure simplement que la variable ``xa`` contienne
 102 un vrai vecteur unidimensionnel, quels que soient les choix informatiques
 103 précédents.
 104
 105 Un second exemple (appelé "*AnalysisSaver*" dans les entrées de type
 106 "*Template*" pour la section "*UserPostAnalysis*") consiste à enregistrer sur
 107 fichier la valeur de l'analyse ou de l'état optimal :math:`\mathbf{x}^a`. Cela
 108 se réalise par les commandes::
 109
 110     import numpy
 111     xa=numpy.ravel(ADD.get('Analysis')[-1])
 112     f='/tmp/analysis.txt'
 113     print('Analysis saved in "%s"'%f)
 114     numpy.savetxt(f,xa)"
 115
 116 Le fichier d'enregistrement choisi est un fichier texte ``/tmp/analysis.txt``.
 117
 118 Il est aisé de combiner ces deux exemples pour en construire un troisième
 119 (appelé "*AnalysisPrinterAndSaver*" dans les entrées de type "*Template*" pour
 120 la section "*UserPostAnalysis*"). Il consiste à simultanément afficher dans la
 121 sortie standard d'exécution et à enregistrer sur fichier la valeur de
 122 :math:`\mathbf{x}^a`. Cela se réalise par les commandes::
 123
 124     import numpy
 125     xa=numpy.ravel(ADD.get('Analysis')[-1])
 126     print('Analysis:',xa)
 127     f='/tmp/analysis.txt'
 128     print('Analysis saved in "%s"'%f)
 129     numpy.savetxt(f,xa)
 130
 131 Pour faciliter l'extension de ces exemples selon les besoins utilisateurs, on
 132 rappelle que l'ensemble des fonctions de SALOME sont disponibles au même niveau
 133 que ces commandes. L'utilisateur peut en particulier requérir des actions de
 134 représentation graphique avec le module PARAVIS [#]_ ou d'autres modules, des
 135 actions de calcul pilotés par YACS [#]_ ou un autre module, etc.
 136
 137 D'autres exemples d'utilisation sont aussi donnés en :ref:`section_u_step4` de
 138 la partie :ref:`section_gui_in_salome`, ou en partie :ref:`section_tutorials_in_salome`.
 139
 140 Conditionnalité des informations disponibles en sortie
 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 142
 143 .. index:: single: AlgorithmParameters
 144 .. index:: single: Stored
 145
 146 La disponibilité des informations après le calcul est conditionnée par le fait
 147 qu'elles aient été calculées ou demandées.
 148
 149 Chaque algorithme ne fournit pas obligatoirement les mêmes informations, et
 150 n'utilise par exemple pas nécessairement les mêmes quantités intermédiaires. Il
 151 y a donc des informations toujours présentes comme l'état optimal résultant du
 152 calcul. Les autres informations ne sont présentes que pour certains algorithmes
 153 et/ou que si elles ont été réclamées avant l'exécution du calcul.
 154
 155 On rappelle que l'utilisateur peut réclamer des informations supplémentaires
 156 lors de l'établissement de son cas ADAO, en utilisant la commande optionnelle
 157 "*AlgorithmParameters*" du cas ADAO. On se reportera à la
 158 :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
 159 commande, et à la description de chaque algorithme pour les informations
 160 disponibles par algorithme. On peut aussi demander à conserver certaines
 161 informations en entrée en changeant le booléen "*Stored*" qui lui est associé
 162 dans l'édition du cas ADAO.
 163
 164 .. _subsection_r_o_v_Inventaire:
 165
 166 Inventaire des informations potentiellement disponibles en sortie
 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 168
 169 Les principales informations potentiellement disponibles en sortie sont
 170 indiquées ici indépendamment des algorithmes, pour inventaire. On se reportera
 171 directement aux détails des algorithmes pour avoir l'inventaire exhaustif.
 172
 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
 175 mot-clé suivant:
 176
 177   .. include:: snippets/Analysis.rst
 178
 179 Les variables suivantes sont des variables d'entrée que l'on peut aussi obtenir
 180 en sortie. Elles sont mises à disposition de l'utilisateur en sortie pour
 181 faciliter l'écriture des procédures de post-processing, et sont conditionnées
 182 par une demande utilisateur explicite à l'aide d'un booléen "*Stored*" en
 183 entrée. Toutes ces variables d'entrée restituées sont obtenables par la
 184 commande standard ".get(...)", qui s'applique à refournir l'unique objet donné
 185 en entrée.
 186
 187   .. include:: snippets/Background.rst
 188
 189   .. include:: snippets/BackgroundError.rst
 190
 191   .. include:: snippets/EvolutionError.rst
 192
 193   .. include:: snippets/Observation.rst
 194
 195   .. include:: snippets/ObservationError.rst
 196
 197 Toutes les autres informations sont conditionnées par l'algorithme et/ou par la
 198 demande utilisateur de disponibilité. Les principales sont les suivantes, par
 199 ordre alphabétique:
 200
 201   .. include:: snippets/APosterioriCorrelations.rst
 202
 203   .. include:: snippets/APosterioriCovariance.rst
 204
 205   .. include:: snippets/APosterioriStandardDeviations.rst
 206
 207   .. include:: snippets/APosterioriVariances.rst
 208
 209   .. include:: snippets/BMA.rst
 210
 211   .. include:: snippets/CostFunctionJ.rst
 212
 213   .. include:: snippets/CostFunctionJb.rst
 214
 215   .. include:: snippets/CostFunctionJo.rst
 216
 217   .. include:: snippets/CostFunctionJAtCurrentOptimum.rst
 218
 219   .. include:: snippets/CostFunctionJbAtCurrentOptimum.rst
 220
 221   .. include:: snippets/CostFunctionJoAtCurrentOptimum.rst
 222
 223   .. include:: snippets/CurrentOptimum.rst
 224
 225   .. include:: snippets/CurrentState.rst
 226
 227   .. include:: snippets/IndexOfOptimum.rst
 228
 229   .. include:: snippets/Innovation.rst
 230
 231   .. include:: snippets/InnovationAtCurrentState.rst
 232
 233   .. include:: snippets/OMA.rst
 234
 235   .. include:: snippets/OMB.rst
 236
 237   .. include:: snippets/Residu.rst
 238
 239   .. include:: snippets/SimulatedObservationAtBackground.rst
 240
 241   .. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
 242
 243   .. include:: snippets/SimulatedObservationAtCurrentState.rst
 244
 245   .. include:: snippets/SimulatedObservationAtOptimum.rst
 246
 247   .. include:: snippets/SimulationQuantiles.rst
 248
 249 .. [#] 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.
 250
 251 .. [#] 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.