used for these checkings.
An **observation operator** is always required, in complement of the simulation
-operator. This observation operator, denoted as :math:`H` or included in, has to
-convert the numerical simulation outputs into something that is directly
-comparable to observations. It is an essential operator, as it is the practical
-way to compare simulations and observations. It is usually done by sampling,
-projection or integration, of the simulation outputs, but it can be more
-complicated. Often, because the observation operator directly follows the
-simulation one in simple data assimilation schemes, this observation operator
-heavily use the postprocessing and extraction capacities of the simulation code.
+operator, or sometimes directly included in. This observation operator, denoted
+as :math:`H`, has to convert the numerical simulation outputs into something
+that is directly comparable to observations. It is an essential operator, as it
+is the real practical way to compare simulations and observations. It is
+usually done by sampling, projection or integration, of the simulation outputs,
+but it can be more complicated. Often, because the observation operator
+directly follows the simulation one in simple data assimilation schemes, this
+observation operator heavily use the postprocessing and extraction capacities
+of the simulation code.
.. _section_m_step2:
The "*observer*" function can be given as an explicit script (entry of type
"*String*"), as a script in an external file (entry of type "*Script*"), or by
-using a template or pattern (entry of type"*Template*") available by default in
-ADAO when using the graphical editor and detailed in the following part
+using a template or pattern (entry of type"*Template*"). The templates are
+available by default in ADAO using the graphical interface EFICAS or the text
+interface TUI, and are detailed in the following
:ref:`section_ref_observers_templates`. These templates are simple scripts that
can be tuned by the user, either in the integrated edition stage of the case
with ADAO EFICAS, or in the edition stage of the schema before execution, to
.. index:: single: ValuePrinter (Observer)
-Template **ValuePrinter** :
-...........................
+Template **ValuePrinter**
+.........................
Print on standard output the current value of the variable.
.. index:: single: ValueAndIndexPrinter (Observer)
-Template **ValueAndIndexPrinter** :
-...................................
+Template **ValueAndIndexPrinter**
+.................................
Print on standard output the current value of the variable, adding its index.
.. index:: single: ValueSeriePrinter (Observer)
-Template **ValueSeriePrinter** :
-................................
+Template **ValueSeriePrinter**
+..............................
Print on standard output the value series of the variable.
.. index:: single: ValueSaver (Observer)
-Template **ValueSaver** :
-.........................
+Template **ValueSaver**
+.......................
Save the current value of the variable in a file of the '/tmp' directory named 'value...txt' from the variable name and the saving step.
.. index:: single: ValueSerieSaver (Observer)
-Template **ValueSerieSaver** :
-..............................
+Template **ValueSerieSaver**
+............................
Save the value series of the variable in a file of the '/tmp' directory named 'value...txt' from the variable name and the saving step.
.. index:: single: ValuePrinterAndSaver (Observer)
-Template **ValuePrinterAndSaver** :
-...................................
+Template **ValuePrinterAndSaver**
+.................................
Print on standard output and, in the same time save in a file of the '/tmp' directory, the current value of the variable.
.. index:: single: ValueIndexPrinterAndSaver (Observer)
-Template **ValueIndexPrinterAndSaver** :
-........................................
+Template **ValueIndexPrinterAndSaver**
+......................................
Print on standard output and, in the same time save in a file of the '/tmp' directory, the current value of the variable, adding its index.
.. index:: single: ValueSeriePrinterAndSaver (Observer)
-Template **ValueSeriePrinterAndSaver** :
-........................................
+Template **ValueSeriePrinterAndSaver**
+......................................
Print on standard output and, in the same time, save in a file of the '/tmp' directory, the value series of the variable.
.. index:: single: ValueGnuPlotter (Observer)
-Template **ValueGnuPlotter** :
-..............................
+Template **ValueGnuPlotter**
+............................
Graphically plot with Gnuplot the current value of the variable.
.. index:: single: ValueSerieGnuPlotter (Observer)
-Template **ValueSerieGnuPlotter** :
-...................................
+Template **ValueSerieGnuPlotter**
+.................................
Graphically plot with Gnuplot the value series of the variable.
.. index:: single: ValuePrinterAndGnuPlotter (Observer)
-Template **ValuePrinterAndGnuPlotter** :
-........................................
+Template **ValuePrinterAndGnuPlotter**
+......................................
Print on standard output and, in the same time, graphically plot with Gnuplot the current value of the variable.
.. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
-Template **ValueSeriePrinterAndGnuPlotter** :
-.............................................
+Template **ValueSeriePrinterAndGnuPlotter**
+...........................................
Print on standard output and, in the same time, graphically plot with Gnuplot the value series of the variable.
.. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
-Template **ValuePrinterSaverAndGnuPlotter** :
-.............................................
+Template **ValuePrinterSaverAndGnuPlotter**
+...........................................
Print on standard output and, in the same, time save in a file of the '/tmp' directory and graphically plot the current value of the variable.
.. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
-Template **ValueSeriePrinterSaverAndGnuPlotter** :
-..................................................
+Template **ValueSeriePrinterSaverAndGnuPlotter**
+................................................
Print on standard output and, in the same, time save in a file of the '/tmp' directory and graphically plot the value series of the variable.
.. index:: single: ValueMean (Observer)
-Template **ValueMean** :
-........................
+Template **ValueMean**
+......................
Print on standard output the mean of the current value of the variable.
.. index:: single: ValueStandardError (Observer)
-Template **ValueStandardError** :
-.................................
+Template **ValueStandardError**
+...............................
Print on standard output the standard error of the current value of the variable.
.. index:: single: ValueVariance (Observer)
-Template **ValueVariance** :
-............................
+Template **ValueVariance**
+..........................
Print on standard output the variance of the current value of the variable.
.. index:: single: ValueL2Norm (Observer)
-Template **ValueL2Norm** :
-..........................
+Template **ValueL2Norm**
+........................
Print on standard output the L2 norm of the current value of the variable.
.. index:: single: ValueRMS (Observer)
-Template **ValueRMS** :
-.......................
+Template **ValueRMS**
+.....................
Print on standard output the root mean square (RMS), or quadratic mean, of the current value of the variable.
--- /dev/null
+..
+ Copyright (C) 2008-2021 EDF R&D
+
+ This file is part of SALOME ADAO module.
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
+
+ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
+
+.. _section_ref_userpostanalysis_requirements:
+
+Requirements to describe a post-processing after an ADAO calculation
+--------------------------------------------------------------------
+
+.. index:: single: Post-processing
+.. index:: single: UserPostAnalysis
+.. index:: single: setUserPostAnalysis
+.. index:: single: UserPostAnalysis Template
+
+Results processing is usually needed after an ADAO calculation, to insert it in
+a complete study. After execution of a calculation case, the main information
+is the variable "*Analysis*" which contains a result of optimal estimation. In
+addition, all calculation variables that have been requested in intermediate
+storage are also available by means of the special algorithm variable
+"*StoreSupplementaryCalculations*".
+
+The simplest processing is often represented by a few lines of Python, which
+can easily be repeated or carried over between studies. But more complex
+processing of results, in the full SALOME study environment, is often done by
+explicit parts of additional post-processing, either in YACS nodes or by Python
+commands in TUI, or other methods. It is therefore often interesting to
+identify at least part of the calculations following the ADAO estimation, and
+to associate them in the calculation case.
+
+ADAO thus gives the ability to define a general post-processing for each
+calculation case. This definition is done by indicating the commands to be
+performed at the output of the ADAO calculation.
+
+Save a dedicated post-processing
+++++++++++++++++++++++++++++++++
+
+In the graphical interface EFICAS for ADAO, there are 3 convenient methods to
+integrate a dedicated post-processing for an ADAO case. The method is chosen
+using the "*FROM*" keyword of the main entry "*UserPostAnalysis*", as shown in
+the following figure:
+
+ .. eficas_userpostanalysis_nodetype:
+ .. image:: images/eficas_userpostanalysis_nodetype.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Choose your input type for the recorded post-processing**
+
+Post-processing can be provided as an explicit script (input of type
+"*String*"), as a script contained in an external file (input of type
+"*Script*"), or by using a template (input of type "*Template*"). Templates are
+provided by default when using the graphical editor EFICAS for ADAO or the TUI
+interface, and are detailed in the
+:ref:`section_ref_userpostanalysis_templates` section that follows. These are
+simple scripts that can be adapted by the user, either in the integrated case
+editing step with EFICAS for ADAO, or in the schema editing step before
+execution, to improve the performance of the ADAO calculation in the SALOME
+execution supervisor.
+
+In the ADAO TUI textual interface (see the :ref:`section_tui` section), the
+same information can be given using the "*setUserPostAnalysis*" command. The
+arguments of this command allow to define the treatment either as a template
+(argument "*Template*") referring to one of the scripts detailed in the part
+:ref:`section_ref_userpostanalysis_templates`, or as an explicit script
+(argument "*String*"), or as a script contained in an external file (argument
+"*Script*")
+
+General form of a script to define a dedicated post-processing
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+A set of post-processing commands is a special Python script, which is
+automatically activated at the end of the estimation calculations in ADAO. Any
+Python commands, which a user can add after a TUI calculation in ADAO, can be
+part of this post-processing. Several command set templates are available by
+default.
+
+To be usable in an automatic way, it is required that any call of the ADAO
+calculation case, to recover a variable, is done only with the reserved name
+"*ADD*". As an example, here is a very simple script (similar to the
+"*ValuePrinter*" template), usable to display the value of the optimal
+estimate::
+
+ print('# Post-analysis')
+ import numpy
+ xa = numpy.ravel(ADD.get('Analysis')[-1])
+ print('Analysis',xa)
+
+If the command "*ADD.get(...)*", used to obtain a result variable, does not use
+the reserved name "*ADD*" for the calculation case, then the call will lead to
+a runtime error and will warn about the missing case name.
+
+To illustrate, the declaration of a model, in TUI interface, is done by using
+the command::
+
+ ADD.setUserPostAnalysis(Template = "AnalysisPrinter")
+
+.. warning::
+ If not using the default available templates, it is up to the user to make
+ carefully established function scripts or external programs that do not
+ crash before being registered as an "*observer*" function. The debugging
+ can otherwise be really difficult!
+
+Hereinafter we give the identifier and the contents of all the available
+simple templates.
+
+.. _section_ref_userpostanalysis_templates:
+
+Inventory of simple templates of post-processing ("*Template*")
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: AnalysisPrinter (Observer)
+
+Modèle **AnalysisPrinter**
+..........................
+
+Print on standard output the optimal value.
+
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa=numpy.ravel(ADD.get('Analysis')[-1])
+ print('Analysis',xa)
+
+.. index:: single: AnalysisSaver (Observer)
+
+Modèle **AnalysisSaver**
+........................
+
+Save the optimal value in a file of the '/tmp' directory named 'analysis.txt'.
+
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa=numpy.ravel(ADD.get('Analysis')[-1])
+ f='/tmp/analysis.txt'
+ print('Analysis saved in "%s"'%f)
+ numpy.savetxt(f,xa)
+
+.. index:: single: AnalysisPrinterAndSaver (Observer)
+
+Modèle **AnalysisPrinterAndSaver**
+..................................
+
+Print on standard output and, in the same time save in a file of the '/tmp' directory, the optimal value.
+
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa=numpy.ravel(ADD.get('Analysis')[-1])
+ print 'Analysis',xa
+ f='/tmp/analysis.txt'
+ print('Analysis saved in "%s"'%f)
+ numpy.savetxt(f,xa)
.. _section_reference_special_entry:
========================================================================================
-**[DocR]** Special entries: functions, matrices, "*observer*"
+**[DocR]** Special entries: functions, matrices, "*observer*", post-processing
========================================================================================
This section describes the special entries, as the functional or matrix forms,
ref_operator_requirements
ref_covariance_requirements
ref_observers_requirements
+ ref_userpostanalysis_requirements
.. _section_reference_assimilation:
.. warning::
- It is recommended to check text or binary files before using them as an
- input of this type. Various checks are carried out on loading, but the
- variety of potential errors is great. In practice, by respecting the
+ It is recommended, before using them as an input of this type, to carefully
+ check text or binary files . Various checks are carried out on loading, but
+ the variety of potential errors is great. In practice, by respecting the
requirements for naming variables and comments, text files from programs or
spreadsheets are (most of the time) compatible.
Its value is defined either as a predefined pattern name, or as a script file
name, or as a string, allowing to put post-processing code directly inside
the ADAO case. Common templates are provided to help the user to start or to
- quickly make his case. Important note: this processing is only performed when
- the case is executed in TUI or exported to YACS.
+ quickly make his case. We refer to the description of
+ :ref:`section_ref_userpostanalysis_requirements` for the list of templates
+ and their format. Important note: this processing is only performed when the
+ case is executed in TUI or exported to YACS.
"*AnalysisPrinter*", "*AnalysisSaver*" and "*AnalysisPrinterAndSaver*"). In
the case of a definition by "*Script*", the specified file must contain
only the commands that could have been put after the execution of the
- calculation. Important note: this processing is only performed when the
- case is executed in TUI or exported to YACS.
+ calculation. We refer to the description of
+ :ref:`section_ref_userpostanalysis_requirements` for the list of templates
+ and their format. Important note: this processing is only performed when
+ the case is executed in TUI or exported to YACS.
Perform the calculation
+++++++++++++++++++++++
The objective is to perform in TUI the setting of data for an ADAO calculation
case, its execution, and then the retrieving of the results to follow on a
independent holding of these results (this last step not being described here,
-because it depends on the the user).
+because it depends on the user).
The hypothesis of the user case are the following ones. It is assumed:
ces vérifications.
Un **opérateur d'observation** est toujours requis, en complément à l'opérateur
-de simulation. Cet opérateur d'observation, noté :math:`H` ou inclus dedans,
-doit convertir les sorties de la simulation numérique en quelque-chose qui est
-directement comparable aux observations. C'est un opérateur essentiel, car il
-est le moyen pratique de comparer les simulations et les observations. C'est
-usuellement réalisé par échantillonnage, projection ou intégration, des sorties
-de simulation, mais cela peut être plus compliqué. Souvent, du fait que
-l'opérateur d'observation fasse directement suite à celui de simulation dans un
-schéma simple d'assimilation de données, cet opérateur d'observation utilise
-fortement les capacités de post-traitement et d'extraction du code de
-simulation.
+de simulation, ou parfois directement inclus dedans. Cet opérateur
+d'observation, noté :math:`H`, doit convertir les sorties de la simulation
+numérique en quelque-chose qui est directement comparable aux observations.
+C'est un opérateur essentiel, car il est le moyen réel pratique de comparer les
+simulations et les observations. C'est usuellement réalisé par échantillonnage,
+projection ou intégration, des sorties de simulation, mais cela peut être plus
+compliqué. Souvent, du fait que l'opérateur d'observation fasse directement
+suite à celui de simulation dans un schéma simple d'assimilation de données,
+cet opérateur d'observation utilise fortement les capacités de post-traitement
+et d'extraction du code de simulation.
.. _section_m_step2:
Cela peut être réalisé soit par un vecteur ou une matrice Numpy, soit par une
liste de listes de valeurs (c'est-à-dire une liste de lignes). Par exemple, une
matrice simple diagonale unitaire de covariances des erreurs d'ébauche
-:math:`\mathbf{B}` peut être décrite dans un fichier de script Python par::
+:math:`\mathbf{B}` peut être décrite dans un fichier de script Python par :
+::
BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
est négatif, ce qui est impossible car une matrice de covariance est positive,
il est convertit en nombre positif). Par exemple, une simple matrice diagonale
unitaire de covariances des erreurs d'ébauche :math:`\mathbf{B}` peut être
-décrite dans un fichier de script Python par::
+décrite dans un fichier de script Python par :
+::
BackgroundError = 1.
si certaines valeurs sont négatives, elles sont converties en valeurs
positives). Par exemple, un matrice simple diagonale unitaire des covariances
des erreurs d'ébauche :math:`\mathbf{B}` peut être décrite dans un fichier de
-script Python par::
+script Python par :
+::
BackgroundError = [1, 1 ... 1]
-ou::
+ou:
+::
BackgroundError = numpy.ones(...)
Une fonction "*observer*" peut être fourni sous la forme d'un script explicite
(entrée de type "*String*"), d'un script contenu dans un fichier externe
(entrée de type "*Script*"), ou en utilisant un modèle (entrée de type
-"*Template*") fourni par défaut dans ADAO lors de l'usage de l'éditeur
-graphique EFICAS d'ADAO et détaillé dans la partie
-:ref:`section_ref_observers_templates` qui suit. Ces derniers sont des scripts
-simples qui peuvent être adaptés par l'utilisateur, soit dans l'étape d'édition
-intégrée du cas avec EFICAS d'ADAO, soit dans l'étape d'édition du schéma avant
-l'exécution, pour améliorer la performance du calcul ADAO dans le superviseur
-d'exécution de SALOME.
+"*Template*"). Les modèles sont fournis par défaut dans ADAO lors de l'usage de
+l'éditeur graphique EFICAS d'ADAO ou de l'interface TUI, et sont détaillés dans
+la partie :ref:`section_ref_observers_templates` qui suit. Ces derniers sont
+des scripts simples qui peuvent être adaptés par l'utilisateur, soit dans
+l'étape d'édition intégrée du cas avec EFICAS d'ADAO, soit dans l'étape
+d'édition du schéma avant l'exécution, pour améliorer la performance du calcul
+ADAO dans le superviseur d'exécution de SALOME.
Dans l'interface textuelle (TUI) d'ADAO (voir la partie :ref:`section_tui`),
les mêmes informations peuvent être données à l'aide de la commande
"*setObserver*" appliquée pour une variable donnée indiquée en utilisant
l'argument "*Variable*". Les autres arguments de cette commande permettent de
-définir un "*observer*" soit comme un template (argument "*Template*")
-désignant l'un des scripts détaillés dans la partie
+définir un "*observer*" soit comme un modèle (argument "*Template*") désignant
+l'un des scripts détaillés dans la partie
:ref:`section_ref_observers_templates`, soit comme un script explicite
(argument "*String*"), soit comme un script contenu dans un fichier externe
(argument "*Script*").
A titre d'exemple, voici un script très simple (similaire au modèle
"*ValuePrinter*"), utilisable pour afficher la valeur d'une variable
-surveillée::
+surveillée :
+::
print(" --->",info," Value =",var[-1])
.. index:: single: ValuePrinter (Observer)
-Modèle **ValuePrinter** :
-.........................
+Modèle **ValuePrinter**
+.......................
Imprime sur la sortie standard la valeur courante de la variable.
.. index:: single: ValueAndIndexPrinter (Observer)
-Modèle **ValueAndIndexPrinter** :
-.................................
+Modèle **ValueAndIndexPrinter**
+...............................
Imprime sur la sortie standard la valeur courante de la variable, en ajoutant son index.
.. index:: single: ValueSeriePrinter (Observer)
-Modèle **ValueSeriePrinter** :
-..............................
+Modèle **ValueSeriePrinter**
+............................
Imprime sur la sortie standard la série des valeurs de la variable.
.. index:: single: ValueSaver (Observer)
-Modèle **ValueSaver** :
-.......................
+Modèle **ValueSaver**
+.....................
Enregistre la valeur courante de la variable dans un fichier du répertoire '/tmp' nommé 'value...txt' selon le nom de la variable et l'étape d'enregistrement.
.. index:: single: ValueSerieSaver (Observer)
-Modèle **ValueSerieSaver** :
-............................
+Modèle **ValueSerieSaver**
+..........................
Enregistre la série des valeurs de la variable dans un fichier du répertoire '/tmp' nommé 'value...txt' selon le nom de la variable et l'étape.
.. index:: single: ValuePrinterAndSaver (Observer)
-Modèle **ValuePrinterAndSaver** :
-.................................
+Modèle **ValuePrinterAndSaver**
+...............................
Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable.
.. index:: single: ValueIndexPrinterAndSaver (Observer)
-Modèle **ValueIndexPrinterAndSaver** :
-......................................
+Modèle **ValueIndexPrinterAndSaver**
+....................................
Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable, en ajoutant son index.
.. index:: single: ValueSeriePrinterAndSaver (Observer)
-Modèle **ValueSeriePrinterAndSaver** :
-......................................
+Modèle **ValueSeriePrinterAndSaver**
+....................................
Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp', la série des valeurs de la variable.
.. index:: single: ValueGnuPlotter (Observer)
-Modèle **ValueGnuPlotter** :
-............................
+Modèle **ValueGnuPlotter**
+..........................
Affiche graphiquement avec Gnuplot la valeur courante de la variable.
.. index:: single: ValueSerieGnuPlotter (Observer)
-Modèle **ValueSerieGnuPlotter** :
-.................................
+Modèle **ValueSerieGnuPlotter**
+...............................
Affiche graphiquement avec Gnuplot la série des valeurs de la variable.
.. index:: single: ValuePrinterAndGnuPlotter (Observer)
-Modèle **ValuePrinterAndGnuPlotter** :
-......................................
+Modèle **ValuePrinterAndGnuPlotter**
+....................................
Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la valeur courante de la variable.
.. index:: single: ValueSeriePrinterAndGnuPlotter (Observer)
-Modèle **ValueSeriePrinterAndGnuPlotter** :
-...........................................
+Modèle **ValueSeriePrinterAndGnuPlotter**
+.........................................
Imprime sur la sortie standard et, en même temps, affiche graphiquement avec Gnuplot la série des valeurs de la variable.
.. index:: single: ValuePrinterSaverAndGnuPlotter (Observer)
-Modèle **ValuePrinterSaverAndGnuPlotter** :
-...........................................
+Modèle **ValuePrinterSaverAndGnuPlotter**
+.........................................
Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp' et affiche graphiquement la valeur courante de la variable.
.. index:: single: ValueSeriePrinterSaverAndGnuPlotter (Observer)
-Modèle **ValueSeriePrinterSaverAndGnuPlotter** :
-................................................
+Modèle **ValueSeriePrinterSaverAndGnuPlotter**
+..............................................
Imprime sur la sortie standard et, en même temps, enregistre dans un fichier du répertoire '/tmp' et affiche graphiquement la série des valeurs de la variable.
.. index:: single: ValueMean (Observer)
-Modèle **ValueMean** :
-......................
+Modèle **ValueMean**
+....................
Imprime sur la sortie standard la moyenne de la valeur courante de la variable.
.. index:: single: ValueStandardError (Observer)
-Modèle **ValueStandardError** :
-...............................
+Modèle **ValueStandardError**
+.............................
Imprime sur la sortie standard l'écart-type de la valeur courante de la variable.
.. index:: single: ValueVariance (Observer)
-Modèle **ValueVariance** :
-..........................
+Modèle **ValueVariance**
+........................
Imprime sur la sortie standard la variance de la valeur courante de la variable.
.. index:: single: ValueL2Norm (Observer)
-Modèle **ValueL2Norm** :
-........................
+Modèle **ValueL2Norm**
+......................
Imprime sur la sortie standard la norme L2 de la valeur courante de la variable.
.. index:: single: ValueRMS (Observer)
-Modèle **ValueRMS** :
-.....................
+Modèle **ValueRMS**
+...................
Imprime sur la sortie standard la racine de la moyenne des carrés (RMS), ou moyenne quadratique, de la valeur courante de la variable.
--- /dev/null
+..
+ Copyright (C) 2008-2021 EDF R&D
+
+ This file is part of SALOME ADAO module.
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
+
+ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
+
+.. _section_ref_userpostanalysis_requirements:
+
+Exigences pour décrire un post-traitement dédié après calcul ADAO
+-----------------------------------------------------------------
+
+.. index:: single: Post-Traitement
+.. index:: single: UserPostAnalysis
+.. index:: single: setUserPostAnalysis
+.. index:: single: UserPostAnalysis Template
+
+Des traitements de résultats sont usuellement nécessaires après un calcul ADAO,
+pour l'insérer dans une étude complète. Après exécution d'un cas de calcul,
+l'information principale est la variable "*Analysis*" qui contient un résultat
+d'estimation optimale. On dispose en plus aussi de toutes les variables de
+calcul qui ont été demandées en stockage intermédiaire à l'aide de la variable
+spéciale d'algorithme "*StoreSupplementaryCalculations*".
+
+Les traitements les plus simples se représentent souvent par quelques lignes de
+Python, qu'il est aisé de reprendre ou reporter entre deux études. Mais les
+traitements plus complexes de résultats, dans l'environnement d'étude complet
+SALOME, sont souvent effectués par des parties explicites de post-traitements
+complémentaires, que ce soit dans des noeuds YACS ou par des commandes Python
+en TUI, ou d'autres méthodes. Il est donc souvent intéressant d'identifier une
+partie au moins des calculs à la suite de l'estimation ADAO, et de les associer
+dans le cas de calcul.
+
+ADAO donne ainsi la possibilité de définir un post-traitement général pour
+chaque cas de calcul. Cette définition se fait en indiquant les commandes à
+réaliser en sortie de calcul ADAO.
+
+Enregistrer un post-traitement dédié
+++++++++++++++++++++++++++++++++++++
+
+Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour
+intégrer un post-traitement dédié à un cas ADAO. La méthode est choisie à
+l'aide du mot-clé "*FROM*" de l'entrée principale "*UserPostAnalysis*", comme
+montré dans la figure qui suit :
+
+ .. eficas_userpostanalysis_nodetype:
+ .. image:: images/eficas_userpostanalysis_nodetype.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Choisir son type d'entrée pour le post-traitement enregistré**
+
+Le post-traitement peut être fourni sous la forme d'un script explicite (entrée
+de type "*String*"), d'un script contenu dans un fichier externe (entrée de
+type "*Script*"), ou en utilisant un modèle (entrée de type "*Template*"). Les
+modèles sont fournis par défaut dans ADAO lors de l'usage de l'éditeur
+graphique EFICAS pour ADAO ou de l'interface TUI, et sont détaillés dans la
+partie :ref:`section_ref_userpostanalysis_templates` qui suit. Ces derniers
+sont des scripts simples qui peuvent être adaptés par l'utilisateur, soit dans
+l'étape d'édition intégrée du cas avec EFICAS d'ADAO, soit dans l'étape
+d'édition du schéma avant l'exécution, pour améliorer la performance du calcul
+ADAO dans le superviseur d'exécution de SALOME.
+
+Dans l'interface textuelle TUI d'ADAO (voir la partie :ref:`section_tui`), les
+mêmes informations peuvent être données à l'aide de la commande
+"*setUserPostAnalysis*". Les arguments de cette commande permettent de définir
+le traitement soit comme un modèle (argument "*Template*") désignant l'un des
+scripts détaillés dans la partie :ref:`section_ref_userpostanalysis_templates`,
+soit comme un script explicite (argument "*String*"), soit comme un script
+contenu dans un fichier externe (argument "*Script*").
+
+Forme générale d'un script permettant de définir un post-traitement dédié
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Une série de commandes de post-traitement est un script Python spécial, qui est
+automatiquement activée à la fin des calculs d'estimation dans ADAO. Toutes les
+commandes Python, qu'un utilisateur peut ajouter après un calcul ADAO en
+interface graphique TUI, peuvent faire partie de ce post-traitement. Plusieurs
+modèles de série de commandes sont disponibles par défaut.
+
+Pour être utilisable de manière automatique, il est requis tout appel du cas de
+calcul ADAO, pour récupérer une variable, se fasse uniquement avec le nom
+réservé "*ADD*". A titre d'exemple, voici un script très simple (similaire au
+modèle "*ValuePrinter*"), utilisable pour afficher la valeur de l'estimation
+optimale :
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa = numpy.ravel(ADD.get('Analysis')[-1])
+ print('Analysis',xa)
+
+Si la commande "*ADD.get(...)*", utilisée pour l'obtention d'une variable
+résultat, n'utilise pas le nom réservé "*ADD*" pour le cas de calcul, alors
+l'appel conduira à une erreur d'exécution et préviendra de l'absence du nom du
+cas.
+
+Pour illustration, la déclaration d'un modèle, en interface TUI, se fait en
+utilisant la commande :
+::
+
+ ADD.setUserPostAnalysis(Template = "AnalysisPrinter")
+
+.. warning::
+ Si les modèles disponibles par défaut ne sont pas utilisés, il revient à
+ l'utilisateur de faire des scripts soigneusement établis et vérifiés, ou
+ des programmes externes qui ne se plantent pas, avant d'être enregistrés
+ comme un post-traitement. Le débogage peut sinon être vraiment difficile !
+
+On donne ci-après l'identifiant et le contenu de tous les modèles simples
+disponibles.
+
+.. _section_ref_userpostanalysis_templates:
+
+Inventaire des modèles simples de post-traitement disponibles ("*Template*")
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: AnalysisPrinter (Observer)
+
+Modèle **AnalysisPrinter**
+..........................
+
+Imprime sur la sortie standard la valeur optimale.
+
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa=numpy.ravel(ADD.get('Analysis')[-1])
+ print('Analysis',xa)
+
+.. index:: single: AnalysisSaver (Observer)
+
+Modèle **AnalysisSaver**
+........................
+
+Enregistre la valeur optimale dans un fichier du répertoire '/tmp' nommé 'analysis.txt'.
+
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa=numpy.ravel(ADD.get('Analysis')[-1])
+ f='/tmp/analysis.txt'
+ print('Analysis saved in "%s"'%f)
+ numpy.savetxt(f,xa)
+
+.. index:: single: AnalysisPrinterAndSaver (Observer)
+
+Modèle **AnalysisPrinterAndSaver**
+..................................
+
+Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur optimale.
+
+::
+
+ print('# Post-analysis')
+ import numpy
+ xa=numpy.ravel(ADD.get('Analysis')[-1])
+ print 'Analysis',xa
+ f='/tmp/analysis.txt'
+ print('Analysis saved in "%s"'%f)
+ numpy.savetxt(f,xa)
.. _section_reference_special_entry:
========================================================================================
-**[DocR]** Entrées spéciales : fonctions, matrices, "*observer*"
+**[DocR]** Entrées spéciales : fonctions, matrices, "*observer*", post-traitement
========================================================================================
Cette section décrit les entrées spéciales, comme les formes fonctionnelles ou
ref_operator_requirements
ref_covariance_requirements
ref_observers_requirements
+ ref_userpostanalysis_requirements
.. _section_reference_assimilation:
.. warning::
- Il est recommandé de vérifier les fichiers textes ou binaires, avant de les
- utiliser en entrée de ce type. Diverses vérifications sont effectuées au
- chargement, mais la variété des erreurs potentielles est grande. Dans la
- pratique, en respectant les exigences de nommage des variables et de
- commentaires, des fichiers textes issus de programmes ou de tableurs sont
- (la plupart du temps) compatibles.
+ Il est recommandé, avant de les utiliser en entrée de ce type, de bien
+ vérifier les fichiers textes ou binaires. Diverses vérifications sont
+ effectuées au chargement, mais la variété des erreurs potentielles est
+ grande. Dans la pratique, en respectant les exigences de nommage des
+ variables et de commentaires, des fichiers textes issus de programmes ou de
+ tableurs classiques sont (la plupart du temps) compatibles.
chaîne de caractères, permettant de produire directement du code de
post-processing dans un cas ADAO. Des exemples courants (squelettes ou
"templates") sont fournis pour aider l'utilisateur ou pour faciliter
- l'élaboration d'un cas. Remarque importante : ce traitement n'est exécuté que
+ l'élaboration d'un cas. On se reportera à la description des
+ :ref:`section_ref_userpostanalysis_requirements` pour avoir la liste des
+ modèles et leur format. Remarque importante : ce traitement n'est exécuté que
lorsque le cas est exécuté en TUI ou exporté en YACS.
"*AnalysisPrinter*", "*AnalysisSaver*" et "*AnalysisPrinterAndSaver*").
Dans le cas d'une définition par "*Script*", le fichier indiqué doit
contenir uniquement les commandes que l'on aurait pu mettre à la suite de
- l'exécution du calcul. Remarque importante : ce traitement n'est exécuté
+ l'exécution du calcul. On se reportera à la description des
+ :ref:`section_ref_userpostanalysis_requirements` pour avoir la liste des
+ modèles et leur format. Remarque importante : ce traitement n'est exécuté
que lorsque le cas est exécuté en TUI ou exporté en YACS.
Effectuer le calcul
définies dans le même script, mais l'utilisateur peut choisir de séparer le
fichier en plusieurs autres, ou de mélanger une définition explicite des
données dans l'interface textuelle ADAO et une définition implicite dans des
-fichiers externes. Le fichier script actuel ressemble à:
+fichiers externes. Le fichier script actuel ressemble à :
::
import numpy
