- "ETKF" (Ensemble-Transform Kalman Filter), deterministic EnKF algorithm, allowing treatment of non-linear evolution operator with a lot less members (one recommends to use a number of members on the order of 10 or even sometimes less),
- "ETKF-N" (Ensemble-Transform Kalman Filter of finite size N), ETKF algorithm of "finite size N", yhat doesn't need inflation that is often required with the other algorithms,
- "MLEF" (Maximum Likelihood Kalman Filter, see [Zupanski05]_), deterministic EnKF scheme, allowing in addition the consistent treament of non-linear observation operator,
-- "IEnKF" (Iterative_EnKF), deterministic EnKF scheme, improving treament of operators non-linearities.
+- "IEnKF" (Iterative EnKF), deterministic EnKF scheme, improving treament of operators non-linearities.
Without being a universal recommandation, one recommend to use "EnKF" as a
reference algorithm, and the other algorithms (in this order) as means to
"CurrentIterationNumber",
"CurrentOptimum",
"CurrentState",
+ "ForecastCovariance",
"ForecastState",
"IndexOfOptimum",
"InnovationAtCurrentAnalysis",
.. include:: snippets/CurrentState.rst
+.. include:: snippets/ForecastCovariance.rst
+
.. include:: snippets/ForecastState.rst
.. include:: snippets/IndexOfOptimum.rst
"CurrentIterationNumber",
"CurrentOptimum",
"CurrentState",
+ "ForecastCovariance",
"ForecastState",
"IndexOfOptimum",
"InnovationAtCurrentAnalysis",
.. include:: snippets/CurrentState.rst
+.. include:: snippets/ForecastCovariance.rst
+
.. include:: snippets/ForecastState.rst
.. include:: snippets/IndexOfOptimum.rst
Some special variables, internal to the optimization process and used inside
calculation, can be monitored during an ADAO calculation. These variables can
be printed, plotted, saved, etc. by the user. This can be done using some
-"*observer*", sometimes also called "callback". They are Python scripts, each
-one associated to a given variable, and that are automatically activated for
-each variable modification.
+"*observer*", sometimes also called "callback" on a variable. They are special
+Python functions, each one associated with a given variable, as conceptually
+described in the following figure:
+
+ .. ref_observer_simple:
+ .. image:: images/ref_observer_simple.png
+ :align: center
+ :width: 75%
+ .. centered::
+ **Conceptual definition of an "observer" function**
+
+These "*observer*" functions are described in the next subsections.
+
+Register and activate of an "*observer*" function
++++++++++++++++++++++++++++++++++++++++++++++++++
In the graphical interface EFICAS of ADAO, there are 3 practical methods to
-provide an "*observer*" in an ADAO case. The method is chosen with the
+provide an "*observer*" function in an ADAO case. The method is chosen with the
"*NodeType*" keyword of each "*observer*" entry type, as shown in the following
figure:
:align: center
:width: 100%
.. centered::
- **Choosing for an "*observer*" its entry type**
+ **Choosing its entry type for an "observer" function**
-The "*observer*" 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
+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
: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
In the textual interface (TUI) of ADAO (see the part :ref:`section_tui`), the
same information can be given with the command "*setObserver*" applied to a
-specific variable indicated in the argument "*Variable*". The other arguments
-of this command allow to define the observer either as a template (argument
-"*Template*") representing one of the scripts detailed in the part
-:ref:`section_ref_observers_templates`, or as an explicit script (argument
-"*String*"), or as a script in an external file (argument "*Script*").
-
-General form for a script describing an *observer*
-++++++++++++++++++++++++++++++++++++++++++++++++++
-
-To use this capability, the user must have or build scripts that have on
-standard input (that is, in the naming space) the variables ``var`` and
-``info``. The variable ``var`` is to be used as an object of list/tuple type,
-that contains the variable of interest indexed by the updating step.
-
-As an example, here is a very simple script (similar to the model
-"*ValuePrinter*"), that can be used to print the value of the monitored
-variable::
+specific variable indicated using the "*Variable*" argument. The other
+arguments of this command allow to define an "*observer*" either as a template
+("*Template*" argument) representing one of the scripts detailed in the part
+:ref:`section_ref_observers_templates`, or as an explicit script ("*String*"
+argument), or as a script in an external file ("*Script*" argument).
+
+General form for a script describing an "*observer*" function
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+An "*observer*" function is a special Python script, associated with a given
+variable, and that is automatically activated for each variable modification
+during calculation. Every (carefully established) function that applies to the
+selected variable can be used. Many "*observer*" functions are available by
+default.
+
+To use directly this "*observer*" capability, the user must use or build a
+script that have on standard input (that is, in the naming space) the variables
+``var`` and ``info``. The variable ``var`` is to be used as an object of
+list/tuple type, that contains the history of the variable of interest, indexed
+by the iterating steps. Only the body of the "*observer*" function has to be
+specified by the user, not the function call itself.
+
+As an example, here is a very simple script (similar to the "*ValuePrinter*"
+template), that can be used to print the value of the monitored variable::
print(" --->",info," Value =",var[-1])
Stored as a Python file or as an explicit string, these script lines can be
associated to each variable found in the keyword "*SELECTION*" of the
"*Observers*" command of the ADAO case: "*Analysis*", "*CurrentState*",
-"*CostFunction*"... The current value of the variable will be printed at each
-step of the optimization or data assimilation algorithm. The "*observer*" can
-include graphical output, storage capacities, complex treatment, statistical
-analysis, etc.
-
-Hereinafter we give the identifier and the contents of each model available.
+"*CostFunction*"... The current value of the variable will for example be
+printed at each step of the optimization or data assimilation algorithm. The
+"*observer*" can include graphical output, storage capacities, complex
+treatment, statistical analysis, etc. If the variable, to which the
+"*observer*" is linked, is not required in the calculation and by the user, the
+execution of this "*observer*" is simply never activated.
+
+.. 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
+"*observer*" models.
.. _section_ref_observers_templates:
-Inventory of available *observer* models ("*Template*")
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Inventory of available "*observer*" function models ("*Template*")
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: ValuePrinter (Observer)
--- /dev/null
+.. index:: single: ForecastCovariance
+
+ForecastCovariance
+ *Liste of matrices*. Each element is a forecast state error covariance
+ matrix predicted by the model during the time iteration of the algorithm
+ used.
+
+ Example :
+ ``Pf = ADD.get("ForecastCovariance")[-1]``
- "EnKF" (Ensemble Kalman Filter, voir [Evensen94]_), algorithme stochastique original, permettant de traiter de manière consistante un opérateur d'évolution non-linéaire,
- "ETKF" (Ensemble-Transform Kalman Filter), algorithme déterministe d'EnKF, permettant de traiter un opérateur d'évolution non-linéaire avec beaucoup moins de membres (on recommande d'utiliser un nombre de membres de l'ordre de 10 ou même parfois moins),
-- "ETKF-N" (Ensemble-Transform Kalman Filter of finite size N), algorithme d'ETKF dit de "taille finie N", évitant de recourir à une inflation souvent nécessaire avec les autres algorithms
+- "ETKF-N" (Ensemble-Transform Kalman Filter of finite size N), algorithme d'ETKF dit de "taille finie N", évitant de recourir à une inflation souvent nécessaire avec les autres algorithmes,
- "MLEF" (Maximum Likelihood Kalman Filter, voir [Zupanski05]_), schéma déterministe d'EnKF, permettant en plus de traiter de manière consistante un opérateur d'observation non-linéaire),
-- "IEnKF" (Iterative_EnKF), schéma déterministe d'EnKF, améliorant le traitement des non-linéarités des opérateurs.
+- "IEnKF" (Iterative EnKF), schéma déterministe d'EnKF, améliorant le traitement des non-linéarités des opérateurs.
Sans pouvoir prétendre à l'universalité, on recommande d'utiliser l'"EnKF"
comme référence, et les autres algorithmes (dans l'ordre) comme des moyens pour
"CurrentIterationNumber",
"CurrentOptimum",
"CurrentState",
+ "ForecastCovariance",
"ForecastState",
"IndexOfOptimum",
"InnovationAtCurrentAnalysis",
.. include:: snippets/CurrentState.rst
+.. include:: snippets/ForecastCovariance.rst
+
.. include:: snippets/ForecastState.rst
.. include:: snippets/IndexOfOptimum.rst
"CurrentIterationNumber",
"CurrentOptimum",
"CurrentState",
+ "ForecastCovariance",
"ForecastState",
"IndexOfOptimum",
"InnovationAtCurrentAnalysis",
.. include:: snippets/CurrentState.rst
+.. include:: snippets/ForecastCovariance.rst
+
.. include:: snippets/ForecastState.rst
.. include:: snippets/IndexOfOptimum.rst
Certaines variables spéciales, internes à l'optimisation et utilisées au cours
des calculs, peuvent être surveillées durant un calcul ADAO. Ces variables
peuvent être affichées, tracées, enregistrées, etc. par l'utilisateur. C'est
-réalisable en utilisant des "*observer*", parfois aussi appelés des "callback".
-Ce sont des scripts Python, qui sont chacun associés à une variable donnée, et
-qui sont automatiquement activés à chaque modification de la variable.
+réalisable en utilisant des "*observer*", parfois aussi appelés des "callback"
+sur une variable. Ce sont des fonctions Python spéciales, qui sont chacune
+associées à une variable donnée, comme décrit conceptuellement dans la figure
+suivante :
+
+ .. ref_observer_simple:
+ .. image:: images/ref_observer_simple.png
+ :align: center
+ :width: 75%
+ .. centered::
+ **Définition conceptuelle d'une fonction "observer"**
+
+Ces fonctions "*observer*" sont décrites dans les sous-sections suivantes.
+
+Enregistrer et activer une fonction "*observer*"
+++++++++++++++++++++++++++++++++++++++++++++++++
Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour
-intégrer un "*observer*" dans un cas ADAO. La méthode est choisie à l'aide du
-mot-clé "*NodeType*" de chaque entrée de type "*observer*", comme montré dans
-la figure qui suit :
+intégrer une fonction "*observer*" dans un cas ADAO. La méthode est choisie à
+l'aide du mot-clé "*NodeType*" de chaque entrée de type "*observer*", comme
+montré dans la figure qui suit :
.. eficas_observer_nodetype:
.. image:: images/eficas_observer_nodetype.png
:align: center
:width: 100%
.. centered::
- **Choisir pour un "*observer*" son type d'entrée**
-
-L'"*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.
+ **Choisir son type d'entrée pour une fonction "observer"**
+
+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.
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ées indiquée dans l'argument
-"*Variable*". Les autres arguments de cette commande permettent de le définir
-soit comme un template (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*").
-
-Forme générale d'un script permettant de définir un *observer*
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Pour pouvoir utiliser cette capacité, l'utilisateur doit disposer ou construire
-des scripts utilisant en entrée standard (i.e. disponible dans l'espace de
-nommage) les variables ``var`` et ``info``. La variable ``var`` est à utiliser
-comme un objet de type liste/tuple, contenant la variable d'intérêt indicée par
-l'étape de mise à jour.
+"*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
+:ref:`section_ref_observers_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 une fonction "*observer*"
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Une fonction "*observer*" est un script Python spécial, associé à une variable
+donnée, et qui est automatiquement activée à chaque modification de la variable
+lors du calcul. Chaque fonction (soigneusement établie) qui s'applique à la
+variable sélectionnée peut être utilisée. De nombreuses fonctions "*observer*"
+sont disponibles par défaut.
+
+Pour pouvoir utiliser directement cette capacité "*observer*", l'utilisateur
+doit utiliser ou construire un script utilisant en entrée standard (i.e.
+disponible dans l'espace de nommage) les variables ``var`` et ``info``. La
+variable ``var`` est à utiliser comme un objet de type liste/tuple, contenant
+l'historique de la variable d'intérêt, indicé par les pas d'itérations. Seul le
+corps de la fonction "*observer*" doit être spécifié par l'utilisateur, pas
+l'appel de fonction lui-même.
A titre d'exemple, voici un script très simple (similaire au modèle
"*ValuePrinter*"), utilisable pour afficher la valeur d'une variable
lignes de script peuvent être associées à chaque variable présente dans le
mot-clé "*SELECTION*" de la commande "*Observers*" du cas ADAO : "*Analysis*",
"*CurrentState*", "*CostFunction*"... La valeur courante de la variable sera
-affichée à chaque étape de l'algorithme d'optimisation ou d'assimilation. Les
-"*observer*" peuvent inclure des capacités d'affichage graphique, de stockage,
-de traitement complexe, d'analyse statistique, etc.
-
-On donne ci-après l'identifiant et le contenu de chaque modèle disponible.
+par exemple affichée à chaque étape de l'algorithme d'optimisation ou
+d'assimilation. Les "*observer*" peuvent inclure des capacités d'affichage
+graphique, de stockage, de traitement complexe, d'analyse statistique, etc. Si
+une variable, à laquelle est lié un "*observer*", n'est pas requise dans le
+calcul et par l'utilisateur, l'exécution de cet "*observer*" n'est tout
+simplement jamais activée.
+
+.. warning::
+ Si les modèles disponibles par défaut ne sont pas utilisés, il revient à
+ l'utilisateur de faire des scripts de fonctions soigneusement établis ou
+ des programmes externes qui ne se plantent pas avant d'être enregistrés
+ comme une fonction "*observer*". Le débogage peut sinon être vraiment
+ difficile !
+
+On donne ci-après l'identifiant et le contenu de tous les modèles "*observer*"
+disponibles.
.. _section_ref_observers_templates:
-Inventaire des modèles d'*observer* disponibles ("*Template*")
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Inventaire des modèles de fonctions "*observer*" disponibles ("*Template*")
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: ValuePrinter (Observer)
--- /dev/null
+.. index:: single: ForecastCovariance
+
+ForecastCovariance
+ *Liste de matrices*. Chaque élément est une matrice de covariance d'erreur
+ sur l'état prévu par le modèle au cours du déroulement itératif temporel de
+ l'algorithme utilisé.
+
+ Exemple :
+ ``Pf = ADD.get("ForecastCovariance")[-1]``
