DOCLANG = fr
SPHINXOPTS =
SPHINXBUILD = sphinx-build
-PAPER =
+PAPER = a4
BUILDDIR = $(top_builddir)/doc/build/$(DOCLANG)
SRCDIR = $(top_srcdir)/doc/$(DOCLANG)
-EXTRA_DIST = conf.py advanced.rst examples.rst index.rst intro.rst theory.rst using.rst \
+EXTRA_DIST = conf.py advanced.rst index.rst intro.rst theory.rst tutorials_in_salome.rst gui_in_salome.rst \
resources/ADAO.png \
resources/ADAO_small.png \
resources/ADAO_small_rouge.png \
# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
+PAPEROPT_a4 = -D latex_elements.papersize='a4paper'
+PAPEROPT_letter = -D latex_elements.papersize='letterpaper'
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
.. [Chakraborty08] Chakraborty U.K., *Advances in differential evolution*, Studies in computational intelligence, Vol.143, Springer, 2008
-.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using monte carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), 10,143–10,162, 1994
+.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using Monte Carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), 10,143–10,162, 1994
.. [Evensen03] Evensen G., *The Ensemble Kalman Filter: theoretical formulation and practical implementation*, Seminar on Recent developments in data assimilation for atmosphere and ocean, ECMWF, 8 to 12 September 2003
+.. [Glover89] Glover F., *Tabu Search-Part I*, ORSA Journal on Computing, 1(2), pp.190-206, 1989
+
+.. [Glover90] Glover F., *Tabu Search-Part II*, ORSA Journal on Computing, 2(1), pp.4-32, 1990
+
.. [Ide97] Ide K., Courtier P., Ghil M., Lorenc A. C., *Unified notation for data assimilation: operational, sequential and variational*, Journal of the Meteorological Society of Japan, 75(1B), pp.181-189, 1997
.. [Johnson08] Johnson S. G., *The NLopt nonlinear-optimization package*, http://ab-initio.mit.edu/nlopt
.. [WikipediaTI] Wikipedia, *Tikhonov regularization*, https://en.wikipedia.org/wiki/Tikhonov_regularization
+.. [WikipediaTS] Wikipedia, *Tabu search*, https://en.wikipedia.org/wiki/Tabu_search
+
.. [WikipediaUKF] Wikipedia, *Unscented Kalman Filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter
.. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 23(4), pp.550-560, 1997
+++ /dev/null
-..
- Copyright (C) 2008-2019 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_examples:
-
-================================================================================
-**[DocU]** Tutoriaux sur l'utilisation du module ADAO
-================================================================================
-
-.. |eficas_new| image:: images/eficas_new.png
- :align: middle
- :scale: 50%
-.. |eficas_save| image:: images/eficas_save.png
- :align: middle
- :scale: 50%
-.. |eficas_saveas| image:: images/eficas_saveas.png
- :align: middle
- :scale: 50%
-.. |eficas_yacs| image:: images/eficas_yacs.png
- :align: middle
- :scale: 50%
-
-Cette section présente quelques exemples d'utilisation du module ADAO dans
-SALOME. Le premier montre comment construire un cas simple d'assimilation de
-données définissant explicitement toutes les données d'entrée requises à travers
-l'interface graphique d'édition (GUI). Le second montre, sur le même cas,
-comment définir les données d'entrée à partir de sources externes à travers des
-scripts. On présente ici toujours des scripts Python car ils sont directement
-insérables dans les noeuds de script de YACS, mais les fichiers externes peuvent
-utiliser d'autres langages.
-
-Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
-:ref:`section_theory`.
-
-Construire un cas d'estimation avec une définition explicite des données
-------------------------------------------------------------------------
-
-Cet exemple simple est un cas de démonstration, et il décrit comment mettre au
-point un environnement d'estimation par BLUE de manière à obtenir un *état
-estimé par méthode de moindres carrés pondérés* d'un système à partir d'une
-observation de l'état et d'une connaissance *a priori* (ou ébauche) de cet état.
-En d'autres termes, on cherche l'intermédiaire pondéré entre les vecteurs
-d'observation et d'ébauche. Toutes les valeurs numériques de cet exemple sont
-arbitraires.
-
-Conditions d'expérience
-+++++++++++++++++++++++
-
-On choisit d'opérer dans un espace à 3 dimensions. La 3D est choisie de manière
-à restreindre la taille des objets numériques à entrer explicitement par
-l'utilisateur, mais le problème n'est pas dépendant de la dimension et peut être
-posé en dimension 10, 100, 1000... L'observation :math:`\mathbf{y}^o` vaut 1
-dans chaque direction, donc::
-
- Yo = [1 1 1]
-
-L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
-priori* ou une régularisation mathématique, vaut 0 dans chaque direction, ce qui
-donne donc::
-
- Xb = [0 0 0]
-
-La mise en oeuvre de l'assimilation de données requiert des informations sur les
-covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`, respectivement
-pour les variables d'observation et d'ébauche. On choisit ici des erreurs
-décorrélées (c'est-à-dire des matrices diagonales) et d'avoir la même variance
-de 1 pour toutes les variables (c'est-à-dire des matrices identité). On pose
-donc::
-
- B = R = [1 0 0 ; 0 1 0 ; 0 0 1]
-
-Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
-convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
-dimensions d'espace sont les mêmes, on peut choisir l'identité comme opérateur
-d'observation::
-
- H = [1 0 0 ; 0 1 0 ; 0 0 1]
-
-Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
-vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
-*analysis*, noté :math:`\mathbf{x}^a`, et valant::
-
-
- Xa = [0.5 0.5 0.5]
-
-Pour étendre cet exemple, on peut modifier les variances représentées par
-:math:`\mathbf{B}` ou :math:`\mathbf{R}` indépendamment, et l'analyse
-:math:`\mathbf{x}^a` se déplacera vers :math:`\mathbf{y}^o` ou vers
-:math:`\mathbf{x}^b`, en proportion inverse des variances dans
-:math:`\mathbf{B}` et :math:`\mathbf{R}`. Comme autre extension, on peut aussi
-dire qu'il est équivalent de rechercher l'analyse à l'aide d'un algorithme de
-BLUE ou d'un algorithme de 3DVAR.
-
-Utiliser l'interface graphique (GUI) pour construire le cas ADAO
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-En premier lieu, il faut activer le module ADAO en choisissant le bouton ou le
-menu approprié de module de SALOME, et on voit :
-
- .. _adao_activate2:
- .. image:: images/adao_activate.png
- :align: center
- :width: 100%
- .. centered::
- **Activation du module ADAO dans SALOME**
-
-Choisir le bouton "*Nouveau*" dans cette fenêtre. On obtient directement
-l'interface de l'éditeur intégré de cas pour la définition de variables, en même
-temps que l'"*Arbre d'étude*" de SALOME. On peut alors choisir le bouton
-"*Nouveau*" |eficas_new| pour créer un nouveau cas ADAO, et on voit :
-
- .. _adao_viewer:
- .. image:: images/adao_viewer.png
- :align: center
- :width: 100%
- .. centered::
- **L'éditeur intégré pour la définition de cas dans le module ADAO**
-
-Ensuite, il faut remplir les variables pour construire le cas ADAO en utilisant
-les conditions d'expérience décrites ci-dessus. L'ensemble des informations
-techniques données au-dessus sont à insérer directement dans la définition du
-cas ADAO, en utilisant le type *String* pour toutes les variables. Lorsque la
-définition du cas est prête, il faut l'enregistrer comme un fichier natif de ype
-"*JDC (\*.comm)*" à un endroit quelconque dans l'arborescence de l'utilisateur.
-Il faut bien se rappeler que d'autres fichiers seront aussi créés à côté de ce
-premier, donc il est judicieux de faire un répertoire spécifique pour ce cas, et
-d'enregistrer dedans le fichier. Le nom du fichier apparaît dans la fenêtre de
-l'"*Arbre d'étude*", sous le menu "*ADAO*". La définition finale du cas
-ressemble à :
-
- .. _adao_jdcexample01:
- .. image:: images/adao_jdcexample01.png
- :align: center
- :width: 100%
- .. centered::
- **Définition des conditions d'expérience choisies pour le cas ADAO**
-
-Pour poursuivre, on a besoin de générer le schéma YACS à partir de la définition
-du cas ADAO. Pour faire cela, on peut activer le menu contextuel par click droit
-sur le nom du cas dans la fenêtre de l'"*Arbre d'étude*", et choisir le
-sous-menu "*Exporter vers YACS*" (ou le bouton "*Exporter vers YACS*"
-|eficas_yacs|) comme ci-dessous :
-
- .. _adao_exporttoyacs00:
- .. image:: images/adao_exporttoyacs.png
- :align: center
- :scale: 75%
- .. centered::
- **Sous-menu contextuel "*Exporter vers YACS*" pour générer le schéma YACS à partir du cas ADAO**
-
-Cette commande conduit à la génération d'un schéma YACS, à l'activation du module
-YACS dans SALOME, et à ouvrir le nouveau schéma dans l'interface graphique du
-module YACS [#]_. Après avoir éventuellement réorganisé les noeuds en utilisant
-le sous-menu contextuel "*arranger les noeuds locaux*" de la vue graphique du
-schéma YACS, on obtient la représentation suivante du schéma ADAO généré :
-
- .. _yacs_generatedscheme:
- .. image:: images/yacs_generatedscheme.png
- :align: center
- :width: 100%
- .. centered::
- **Schéma YACS généré à partir du cas ADAO**
-
-Après ce point, toutes les modifications, exécutions et post-processing du
-schéma d'assimilation de données seront effectués dans le module YACS. De
-manière à vérifier les résultats d'une manière simple, on utilise le noeud
-"*UserPostAnalysis*" (ou on crée ici un nouveau noeud YACS par le sous-menu
-"*Noeud de script in-line*" dans la vue graphique de YACS).
-
-Ce noeud de script va récupérer l'analyse issue de l'assimilation de données
-depuis le port de sortie "*algoResults*" du bloc de calcul (qui donne accés à un
-objet Python SALOME), et va l'afficher à la sortie standard.
-
-Pour obtenir ceci, ce noeud de script doit comporter un port d'entrée de type
-"*pyobj*", nommé "*Study*" par exemple, qui doit être relié graphiquement au
-port de sortie "*algoResults*" du bloc de calcul. Ensuite, le code pour remplir
-le noeud de script est::
-
- Xa = Study.getResults().get("Analysis")[-1]
-
- print()
- print("Analysis =",Xa)
- print()
-
-Le schéma YACS (initial ou complété) peut être enregistré (en écrasant le schéma
-généré si la commande ou le bouton "*Enregistrer*" sont utilisés, ou sinon avec
-un nom nouveau par la commande "*Enregistrer sous*"). De manière pratique, la
-mise au point d'une telle procédure de post-processing peut être réalisée dans
-YACS pour la tester, et ensuite entièrement enregistrée dans un script Python
-qui peut être intégré au cas ADAO en utilisant le mot-clé "*UserPostAnalysis*".
-
-Ensuite, de manière classique dans YACS, le schéma doit être compilé, et ensuite
-être exécuté. Après la fin de l'exécution, les affichages sur la sortie standard
-sont disponibles dans la fenêtre "*fenêtre de sortie de YACS*" (ou "*YACS
-Container Log*"), obtenue par clic droit à l'aide du menu contextuel de la
-fenêtre "*proc*" du schéma YACS comme montré ci-dessous:
-
- .. _yacs_containerlog:
- .. image:: images/yacs_containerlog.png
- :align: center
- :width: 100%
- .. centered::
- **Menu YACS de la fenêtre de sortie, et boite de dialogue montrant la sortie**
-
-On vérifie que le résultat est correct en observant si la fenêtre de sortie
-contient la ligne suivante::
-
- Analysis = [0.5, 0.5, 0.5]
-
-comme montré dans l'image précédente.
-
-Pour étendre cet exemple, on peut remarquer que le même problème résolu par un
-algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi lors
-de l'étape de construction du cas ADAO, avant d'entrer dans l'étape YACS. Le cas
-ADAO en 3DVAR est entièrement similaire au cas algorithmique du BLUE, comme
-montré dans la figure suivante:
-
- .. _adao_jdcexample02:
- .. image:: images/adao_jdcexample02.png
- :align: center
- :width: 100%
- .. centered::
- **Définir un cas ADAO en 3DVAR est entièrement similaire à un cas en BLUE**
-
-Il n'y a qu'une seule commande qui change, avec "*3DVAR*" dans le champ
-"*Algorithm*" à la place de "*Blue*".
-
-Construire un cas d'estimation avec une définition de données externes par scripts
-----------------------------------------------------------------------------------
-
-Il est utile d'acquérir une partie ou la totalité des données depuis une
-définition externe, en utilisant des scripts Python pour donner accès à ces
-données. À titre d'exemple, on construit ici un cas ADAO présentant le même
-dispositif expérimental que dans l'exemple ci-dessus `Construire un cas
-d'estimation avec une définition explicite des données`_, mais en utilisant des
-données issues d'un unique fichier script Python externe.
-
-En premier lieu, on écrit le fichier script suivant, utilisant des noms
-conventionnels pour les variables requises. Ici toutes les variables sont
-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 graphique ADAO et une définition implicite dans des fichiers
-externes. Le fichier script actuel ressemble à::
-
- import numpy
- #
- # Definition of the Background as a vector
- # ----------------------------------------
- Background = [0, 0, 0]
- #
- # Definition of the Observation as a vector
- # -----------------------------------------
- Observation = "1 1 1"
- #
- # Definition of the Background Error covariance as a matrix
- # ---------------------------------------------------------
- BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
- #
- # Definition of the Observation Error covariance as a matrix
- # ----------------------------------------------------------
- ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
- #
- # Definition of the Observation Operator as a matrix
- # --------------------------------------------------
- ObservationOperator = numpy.identity(3)
-
-Les noms des variables Python sont obligatoires, de manière à définir les bonnes
-variables dans le cas, mais le script Python peut être plus conséquent et
-définir des classes, des fonctions, des accès à des fichiers ou des bases de
-données, etc. avec des noms différents. De plus, le fichier ci-dessus présente
-différentes manières de définir des vecteurs ou des matrices, utilisant des
-listes, des chaînes de caractères (comme dans Numpy ou Octave), des types
-vecteur ou matrice de Numpy, et des fonctions spéciales de Numpy. Toutes ces
-syntaxes sont valides.
-
-Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
-l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
-utilise l'interface graphique (GUI) pour construire le cas ADAO. La procédure
-pour compléter le cas est similaire à celle de l'exemple précédent à part le
-fait que, au lieu de choisir l'option "*String*" pour le mot-clé "*FROM*" de
-chaque variable, on choisit l'option "*Script*". Cela conduit à une entrée
-"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique, permettant de choisir un
-fichier de la manière suivante:
-
- .. _adao_scriptentry01:
- .. image:: images/adao_scriptentry01.png
- :align: center
- :width: 100%
- .. centered::
- **Définir une variable d'entrée en utilisant un fichier script externe**
-
-Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
-précédent `Construire un cas d'estimation avec une définition explicite des
-données`_.
-
-Dans la pratique, cette démarche par scripts est la manière la plus facile pour
-récupérer des information depuis des calculs en ligne ou préalables, depuis des
-fichiers statiques, depuis des bases de données ou des flux informatiques,
-chacun pouvant être dans ou hors SALOME. Cela permet aussi de modifier aisément
-des données d'entrée, par exemple à des fin de débogage ou pour des traitements
-répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
-d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
-"sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
-peuvent être directement introduites dans l'exécution du schéma YACS.
-L'utilisateur doit vérifier avec attention le contenu de ses scripts.**
-
-Ajout de paramètres pour contrôler l'algorithme d'assimilation de données
--------------------------------------------------------------------------
-
-On peut ajouter des paramètres optionnels pour contrôler le calcul de
-l'algorithme d'assimilation de données. Ceci se fait en utilisant les paramètres
-optionnels dans la commande "*AlgorithmParameters*" de la définition du cas
-ADAO, qui est un mot-clé de la commande générale "*ASSIMILATION_STUDY*". Ce
-mot-clé nécessite une définition explicite des valeurs à partir de valeurs par
-défaut, ou à partir d'un dictionnaire Python, contenant des paires clé/valeur.
-La liste des paramètres optionnels possibles sont donnés dans la section
-:ref:`section_reference` et ses sous-sections. On recommande d'utiliser la
-définition explicite de valeurs à partir de la liste par défaut de paramètres
-optionnels, comme ici avec le "*MaximumNumberOfSteps*":
-
- .. _adao_scriptentry02:
- .. image:: images/adao_scriptentry02.png
- :align: center
- :width: 100%
- .. centered::
- **Ajouter des paramètres pour contrôler l'algorithme et les sorties**
-
-Le dictionnaire peut être défini, par exemple, dans un fichiers externe de
-script Python, en utilisant le nom obligatoire de variable
-"*AlgorithmParameters*" pour le dictionnaire. Toutes les clés dans le
-dictionnaire sont optionnelles, elles disposent toutes d'une valeur par défaut,
-et elles peuvent être présentes sans être utiles. Par exemple::
-
- AlgorithmParameters = {
- "Minimizer" : "LBFGSB", # Recommended
- "MaximumNumberOfSteps" : 10,
- }
-
-Si aucune borne n'est requise sur les variables de contrôle, alors on peut
-choisir les algorithmes de minimisation "*BFGS*" ou "*CG*" pour tous les
-algorithmes variationnels d'assimilation de données ou d'optimisation. Pour
-l'optimisation sous contraintes, l'algorithme "*LBFGSB*" est bien souvent plus
-robuste, mais le "*TNC*" est parfois plus performant. De manière générale, le
-choix de l'algorithme "*LBFGSB*" est recommandé. Ensuite le script peut être
-ajouté au cas ADAO, dans une entrée de type fichier associé au format "*Dict*"
-dans le mot-clé "*Parameters*".
-
-Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
-précédent `Construire un cas d'estimation avec une définition explicite des
-données`_. Le dictionnaire peut aussi être donné directement dans le champ
-d'entrée de type chaîne de caractères pour le mot-clé.
-
-Construire un cas complexe avec une définition de données externes par scripts
-------------------------------------------------------------------------------
-
-Cet exemple plus complexe et complet peut être considéré comme un cadre de base
-pour le traitement des entrées de l'utilisateur, qui doit ensuite être adapté à
-chaque application réelle. Néanmoins, les squelettes de fichiers sont
-suffisamment généraux pour avoir été utilisés pour des applications variées en
-neutronique, mécanique des fluides... Ici, on ne s'intéresse pas aux résultats,
-mais plus sur le contrôle de l'utilisateur des entrées et sorties dans un cas
-ADAO. Comme précédemment, toutes les valeurs numériques de cet exemple sont
-arbitraires.
-
-L'objectif est de configurer les entrées et les sortie d'un problème physique
-d'estimation par des scripts externes Python, en utilisant un opérateur
-non-linéaire général, en ajoutant un contrôle sur les paramètres et ainsi de
-suite... Les scripts complets peuvent être trouvés dans le répertoire des
-exemples de squelettes ADAO sous le nom de
-"*External_data_definition_by_scripts*".
-
-Conditions d'expérience
-+++++++++++++++++++++++
-
-On continue à opérer dans un espace à 3 dimensions, afin de limiter la taille de
-l'objet numérique indiqué dans les scripts, mais le problème ne dépend pas de la
-dimension.
-
-On choisit un contexte d'expériences jumelles, en utilisant un état vrai
-:math:`\mathbf{x}^t` connu, mais de valeur arbitraire::
-
- Xt = [1 2 3]
-
-L'état d'ébauche :math:`\mathbf{x}^b`, qui représentent une connaissance *a
-priori* de l'état vrai, est construit comme une perturbation aléatoire
-gaussienne de 20% de l'état vrai :math:`\mathbf{x}^t` pour chaque composante,
-qui est::
-
- Xb = Xt + normal(0, 20%*Xt)
-
-Pour décrire la matrice des covariances d'erreur d'ébauche math:`\mathbf{B}`, on
-fait comme précédemment l'hypothèse d'erreurs décorrélées (c'est-à-dire, une
-matrice diagonale, de taille 3x3 parce-que :math:`\mathbf{x}^b` est de taille 3)
-et d'avoir la même variance de 0,1 pour toutes les variables. On obtient::
-
- B = 0.1 * diagonal( length(Xb) )
-
-On suppose qu'il existe un opérateur d'observation :math:`\mathbf{H}`, qui peut
-être non linéaire. Dans une procédure réelle de recalage ou de problème inverse,
-les codes de simulation physique sont intégrés dans l'opérateur d'observation.
-On a également besoin de connaître son gradient par rapport à chaque variable
-estimée, ce qui est une information rarement connu avec les codes industriels.
-Mais on verra plus tard comment obtenir un gradient approché dans ce cas.
-
-Étant en expériences jumelles, les observations :math:`\mathbf{y}^o` et leur
-matrice de covariances d'erreurs :math:`\mathbf{R}` sont générées en utilisant
-l'état vrai :math:`\mathbf{x}^t` et l'opérateur d'observation
-:math:`\mathbf{H}`::
-
- Yo = H( Xt )
-
-et, avec un écart-type arbitraire de 1% sur chaque composante de l'erreur::
-
- R = 0.0001 * diagonal( length(Yo) )
-
-Toutes les informations requises pour l'estimation par assimilation de données
-sont maintenant définies.
-
-Squelettes des scripts décrivant les conditions d'expérience
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-On donne ici les éléments essentiels de chaque script utilisé par la suite pour
-construire le cas ADAO. On rappelle que l'utilisation de ces scripts dans de
-réels fichiers Python nécessite de définir correctement le chemin de modules ou
-des codes importés (même si le module est dans le même répertoire que le fichier
-Python qui l'importe. On indique le chemin à renseigner en utilisant la mention
-``"# INSERT PHYSICAL SCRIPT PATH"``), l'encodage si nécessaire, etc. Les noms de
-fichiers indiqués pour les scripts qui suivent sont arbitraires. Des exemples
-complets de fichiers scripts sont disponibles dans le répertoire standard des
-exemples ADAO.
-
-On définit en premier lieu l'état vrai :math:`\mathbf{x}^t` et une fonction
-utiles à la construction de matrices, dans un fichier script Python nommé
-``Physical_data_and_covariance_matrices.py``::
-
- import numpy
- #
- def True_state():
- """
- Arbitrary values and names, as a tuple of two series of same length
- """
- return (numpy.array([1, 2, 3]), ['Para1', 'Para2', 'Para3'])
- #
- def Simple_Matrix( size, diagonal=None ):
- """
- Diagonal matrix, with either 1 or a given vector on the diagonal
- """
- if diagonal is not None:
- S = numpy.diag( diagonal )
- else:
- S = numpy.matrix(numpy.identity(int(size)))
- return S
-
-On définit ensuite l'état d'ébauche :math:`\mathbf{x}^b` comme une perturbation
-aléatoire de l'état vrai, en ajoutant une *variable ADAO requise* à la fin du
-script de définition, de manière à exporter la valeur définie. C'est réalisé
-dans un fichier de script Python nommé ``Script_Background_xb.py``::
-
- from Physical_data_and_covariance_matrices import True_state
- import numpy
- #
- xt, names = True_state()
- #
- Standard_deviation = 0.2*xt # 20% for each variable
- #
- xb = xt + abs(numpy.random.normal(0.,Standard_deviation,size=(len(xt),)))
- #
- # Creating the required ADAO variable
- # ------------------------------------
- Background = list(xb)
-
-De la même manière, on définit la matrice des covariances de l'erreur d'ébauche
-:math:`\mathbf{B}` comme une matrice diagonale, de la même longueur de diagonale
-que l'ébauche de la valeur vraie, en utilisant la fonction d'aide déjà définie.
-C'est réalisé dans un fichier script Python nommé
-``Script_BackgroundError_B.py``::
-
- from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
- #
- xt, names = True_state()
- #
- B = 0.1 * Simple_Matrix( size = len(xt) )
- #
- # Creating the required ADAO variable
- # -----------------------------------
- BackgroundError = B
-
-Pour poursuivre, on a besoin de l'opérateur d'observation :math:`\mathbf{H}`
-comme une fonction de l'état. Il est ici défini dans un fichier externe nommé
-``"Physical_simulation_functions.py"``, qui doit contenir une fonction appelée
-``"DirectOperator"``. Cette fonction est une une fonction utilisateur,
-représentant de manière programmée l'opérateur :math:`\mathbf{H}`. On suppose
-que cette fonction est donnée par l'utilisateur. Un squelette simple est donné
-ici par facilité::
-
- def DirectOperator( XX ):
- """ Direct non-linear simulation operator """
- #
- # --------------------------------------> EXAMPLE TO BE REMOVED
- if type(XX) is type(numpy.matrix([])): # EXAMPLE TO BE REMOVED
- HX = XX.A1.tolist() # EXAMPLE TO BE REMOVED
- elif type(XX) is type(numpy.array([])): # EXAMPLE TO BE REMOVED
- HX = numpy.matrix(XX).A1.tolist() # EXAMPLE TO BE REMOVED
- else: # EXAMPLE TO BE REMOVED
- HX = XX # EXAMPLE TO BE REMOVED
- # --------------------------------------> EXAMPLE TO BE REMOVED
- #
- return numpy.array( HX )
-
-On n'a pas besoin des opérateurs linéaires associés ``"TangentOperator"`` et
-``"AdjointOperator"`` car ils vont être approximés en utilisant les capacités
-d'ADAO.
-
-On insiste sur le fait que ces opérateurs non-linéaire ``"DirectOperator"``,
-linéaire tangent ``"TangentOperator"`` et linéaire adjoint ``"AdjointOperator"``
-proviennent de la connaissance de la physique, incluant le code de simulation de
-référence physique, et doivent être soigneusement mis au point par l'utilisateur
-de l'assimilation de données ou de l'optimisation. Les erreurs de simulation ou
-d'usage des opérateurs ne peuvent pas être détectés ou corrigés par
-l'environnement seul ADAO d'assimilation de données et d'optimisation.
-
-Dans cet environnement d'expériences jumelles, l'observation
-:math:`\mathbf{y}^o` et sa matrice des covariances d'erreur :math:`\mathbf{R}`
-peuvent être générées. C'est réalisé dans deux fichiers de script Python, le
-premier étant nommé ``Script_Observation_yo.py``::
-
- from Physical_data_and_covariance_matrices import True_state
- from Physical_simulation_functions import DirectOperator
- #
- xt, noms = True_state()
- #
- yo = DirectOperator( xt )
- #
- # Creating the required ADAO variable
- # -----------------------------------
- Observation = list(yo)
-
-et le second nommé ``Script_ObservationError_R.py``::
-
- from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
- from Physical_simulation_functions import DirectOperator
- #
- xt, names = True_state()
- #
- yo = DirectOperator( xt )
- #
- R = 0.0001 * Simple_Matrix( size = len(yo) )
- #
- # Creating the required ADAO variable
- # -----------------------------------
- ObservationError = R
-
-Comme dans les exemples précédents, il peut être utile de définir certains
-paramètres pour l'algorithme d'assimilation de données. Par exemple, si on
-utilise l'algorithme standard de "*3DVAR*", les paramètres suivants peuvent être
-définis dans un fichier de script Python nommé
-``Script_AlgorithmParameters.py``::
-
- # Creating the required ADAO variable
- # -----------------------------------
- AlgorithmParameters = {
- "Minimizer" : "LBFGSB", # Recommended
- "MaximumNumberOfSteps" : 15, # Number of global iterative steps
- "Bounds" : [
- [ None, None ], # Bound on the first parameter
- [ 0., 4. ], # Bound on the second parameter
- [ 0., None ], # Bound on the third parameter
- ],
- }
-
-Enfin, il est courant de post-traiter les résultats, en les récupérant aprés la
-phase d'assimilation de données de manière à les analyser, les afficher ou les
-représenter. Cela nécessite d'utiliser un fichier script Python intermédiaire de
-manière à extraire ces résultats à la fin de la procédure d'assimilation de
-données ou d'optimisation. L'exemple suivant de fichier script Python, nommé
-``Script_UserPostAnalysis.py``, illustre le fait::
-
- from Physical_data_and_covariance_matrices import True_state
- import numpy
- #
- xt, names = True_state()
- xa = ADD.get("Analysis")[-1]
- x_series = ADD.get("CurrentState")[:]
- J = ADD.get("CostFunctionJ")[:]
- #
- # Verifying the results by printing
- # ---------------------------------
- print()
- print("xt = %s"%xt)
- print("xa = %s"%numpy.array(xa))
- print()
- for i in range( len(x_series) ):
- print("Etape %2i : J = %.5e et X = %s"%(i, J[i], x_series[i]))
- print()
-
-Finalement, on obtient la description de l'ensemble des conditions
-d'expériences à travers la série de fichiers listée ici:
-
-#. ``Physical_data_and_covariance_matrices.py``
-#. ``Physical_simulation_functions.py``
-#. ``Script_AlgorithmParameters.py``
-#. ``Script_BackgroundError_B.py``
-#. ``Script_Background_xb.py``
-#. ``Script_ObservationError_R.py``
-#. ``Script_Observation_yo.py``
-#. ``Script_UserPostAnalysis.py``
-
-On insiste ici sur le fait que tous ces scripts sont écrits par l'utilisateur et
-ne peuvent être testés automatiquement par ADAO. Ainsi, l'utilisateur est tenu
-de vérifier les scripts (et en particulier leurs entrées/sorties) afin de
-limiter les difficultés de débogage. On rappelle que: **la méthodologie par
-scripts n'est pas une procédure "sûre", en ce sens que des données erronées ou
-des erreurs dans les calculs, peuvent être directement introduites dans
-l'exécution du schéma YACS.**
-
-Construire la cas avec une définition de données externes par scripts
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Tous ces scripts peuvent ensuite être utilisés pour définir le cas ADAO avec une
-définition de données externes par des fichiers de script Python. Cela se
-réalise de manière tout à fait similaire à la méthode décrite dans la partie
-précédente `Construire un cas d'estimation avec une définition de données
-externes par scripts`_. Pour chaque variable à définir, on sélectionne l'option
-"*Script*" du mot-clé "*FROM*", ce qui conduit à une entrée
-"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique. Pour le mot-clé
-"*ObservationOperator*", on choisit la forme "*ScriptWithOneFunction*" et on
-conserve la valeur par défaut de l'incrément différentiel.
-
-Les autres étapes pour construire le cas ADAO sont exactement les mêmes que dans
-la partie précédente `Construire un cas d'estimation avec une définition
-explicite des données`_.
-
-En utilisant l'opérateur linéaire simple :math:`\mathbf{H}` du fichier script
-Python ``Physical_simulation_functions.py`` disponible dans le répertoire
-standard des exemples, les résultats ressemblent à::
-
- xt = [1 2 3]
- xa = [ 1.000014 2.000458 3.000390]
-
- Etape 0 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
- Etape 1 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
- Etape 2 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
- Etape 3 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
- Etape 4 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
- Etape 5 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
- Etape 6 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
- Etape 7 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
- Etape 8 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
- Etape 9 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
- Etape 10 : J = 1.81568e+00 et X = [1.000013, 2.000458, 3.000390]
- ...
-
-L'état au premier pas est l'état d'ébauche :math:`\mathbf{x}^b` généré
-aléatoirement. Au cours du calcul, ces affichages sur la sortie standard sont
-disponibles dans la fenêtre "*fenêtre de sortie de YACS*", que l'on obtient par
-clic droit sur la fenêtre "*proc*" du schéma YACS exécuté.
-
-.. [#] 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.
--- /dev/null
+..
+ Copyright (C) 2008-2019 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_gui_in_salome:
+
+================================================================================
+**[DocR]** Interface graphique pour l'utilisateur (GUI/EFICAS)
+================================================================================
+
+.. |eficas_new| image:: images/eficas_new.png
+ :align: middle
+ :scale: 50%
+.. |eficas_save| image:: images/eficas_save.png
+ :align: middle
+ :scale: 50%
+.. |eficas_saveas| image:: images/eficas_saveas.png
+ :align: middle
+ :scale: 50%
+.. |eficas_yacs| image:: images/eficas_yacs.png
+ :align: middle
+ :scale: 50%
+.. |yacs_compile| image:: images/yacs_compile.png
+ :align: middle
+ :scale: 50%
+
+Cette section présente l'usage du module ADAO dans la plateforme SALOME. On
+décrit ici le cheminement général pour établir un cas ADAO, les détails étant
+fournis dans les chapitres suivants. Il est complété par la description
+détaillée de l'ensemble des commandes et mots-clés dans la section
+:ref:`section_reference`, par des procédures avancées d'usage dans la section
+:ref:`section_advanced`, et par des exemples dans la section
+:ref:`section_tutorials_in_salome`.
+
+Procédure logique pour construire un cas ADAO
+---------------------------------------------
+
+La construction d'un cas ADAO suit une démarche simple pour définir l'ensemble
+des données d'entrée, et ensuite générer un diagramme complet d'exécution
+utilisé dans YACS [#]_. De nombreuses variations existent pour la définition
+des données d'entrée, mais la séquence logique reste inchangée.
+
+De manière générale, l'utilisateur doit connaître ses données d'entrées,
+requises pour mettre au point une étude d'assimilation de données, en suivant la
+:ref:`section_methodology`. Ces données peuvent déjà être disponibles dans
+SALOME ou non.
+
+Fondamentalement, la procédure d'utilisation de ADAO comprend les étapes
+suivantes:
+
+- :ref:`section_u_step1`
+- :ref:`section_u_step2`
+- :ref:`section_u_step3`
+- :ref:`section_u_step4`
+- :ref:`section_u_step5`
+
+Chaque étape est détaillée dans la section suivante.
+
+Procédure détaillée pour construire un cas ADAO
+-----------------------------------------------
+
+.. _section_u_step1:
+
+ÉTAPE 1 : Activer le module ADAO et utiliser l'interface graphique d'édition (GUI)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Comme toujours pour un module, il doit être préalablement activé en
+sélectionnant le bouton de module approprié (ou le menu) dans la barre d'outils
+de SALOME. S'il n'existe aucune étude SALOME chargée, un menu contextuel
+apparaît, permettant de choisir entre la création d'une nouvelle étude, ou
+l'ouverture d'une étude déjà existante:
+
+ .. _adao_activate1:
+ .. image:: images/adao_activate.png
+ :align: center
+ .. centered::
+ **Activation du module ADAO dans SALOME**
+
+En choisissant le bouton "*Nouveau*", un éditeur intégré de cas [#]_ sera
+ouvert, en même temps que le "*navigateur d'objets*" standard. On peut alors
+cliquer sur le bouton "*Nouveau*" (ou choisir l'entrée "*Nouveau*" dans le dans
+le menu principal "*ADAO*") pour créer un nouveau cas ADAO, et on obtient :
+
+ .. _adao_viewer:
+ .. image:: images/adao_viewer.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **L'éditeur intégré pour la définition des cas dans le module ADAO**
+
+.. _section_u_step2:
+
+ÉTAPE 2 : Créer et modifier le cas ADAO, et l'enregistrer
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Pour construire un cas en utilisant l'éditeur intégré, on doit passer par une
+série de sous-étapes, en choisissant, à chaque étape, un mot-clé puis en
+remplissant ses valeurs. On note que c'est dans cette étape qu'il faut, entre
+autres, définir l'**appel au code de simulation** utilisé dans les opérateurs
+d'observation ou d'évolution décrivant le problème [#]_.
+
+L'éditeur structuré indique des types hiérarchiques, des valeurs ou des
+mots-clés autorisés. Les mots-clés incomplets ou incorrects sont identifiés par
+un indicateur d'erreur visuel rouge. Les valeurs possibles sont indiquées pour
+les mots-clés par la définition d'une liste limitée de valeurs, et les entrées
+adaptées sont données pour les autres mots-clés. Des messages d'aide sont
+fournis de manière contextuelle aux places réservées de l'éditeur.
+
+Un nouveau cas est mis en place avec la liste minimale des commandes. Toutes les
+commandes ou les mots-clés obligatoires sont déjà présents, aucun d'eux ne peut
+être supprimé. Des mots-clés optionnels peuvent être ajoutés en les choisissant
+dans une liste de suggestions de ceux autorisés pour la commande principale, par
+exemple la commande "*ASSIMILATION_STUDY*". À titre d'exemple, on peut ajouter
+des paramètres dans le mot-clé "*AlgorithmParameters*", comme décrit dans la
+dernière partie de la section :ref:`section_tutorials_in_salome`.
+
+A la fin de ces actions, lorsque tous les champs ou les mots-clés ont été
+correctement définis, chaque ligne de l'arborescence des commandes doit
+présenter un drapeau vert. Cela signifie que l'ensemble du cas est valide et
+dûment rempli (et qu'il peut être sauvegardé).
+
+ .. _adao_jdcexample00:
+ .. image:: images/adao_jdcexample01.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **Exemple d'un cas ADAO valide**
+
+Au final, il faut enregistrer le cas ADAO en utilisant le bouton "*Enregistrer*"
+|eficas_save|, ou le bouton "*Enregistrer sous*" |eficas_saveas|, ou en
+choisissant l'entrée "*Enregistrer/ Enregistrer sous*" dans le menu "*ADAO*". Il
+est alors demandé un emplacement, à choisir dans l'arborescence des fichiers, et
+un nom, qui sera complété par l'extension "*.comm*" utilisée pour les fichiers
+de l'éditeur intégré de cas. Cette action va générer une paire de fichiers
+décrivant le cas ADAO, avec le même nom de base, le premier présentant une
+extension "*.comm*" et le second une extension "*.py*" [#]_.
+
+.. _section_u_step3:
+
+ÉTAPE 3 : Exporter le cas ADAO comme un schéma YACS
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Lorsque le cas ADAO est complété, il doit être converti ou exporté sous la forme
+d'un schéma YACS pour pouvoir exécuter le calcul d'assimilation de données. Cela
+peut être réalisé facilement en utilisant le bouton "*Exporter vers YACS*"
+|eficas_yacs|, ou de manière équivalente en choisissant l'entrée "*Exporter vers
+YACS*" dans le menu principal "*ADAO*", ou dans le menu contextuel du cas dans
+le navigateur d'objets SALOME.
+
+ .. _adao_exporttoyacs01:
+ .. image:: images/adao_exporttoyacs.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **Sous-menu "Exporter vers YACS" pour générer le schéma YACS à partir d'un cas ADAO**
+
+Cela conduit à générer automatiquement un schéma YACS, et à activer le module
+YACS sur ce schéma. Le fichier YACS, associé au schéma, est stocké dans le même
+répertoire et avec le même nom de base de fichier que le cas ADAO enregistré,
+changeant simplement son extension en "*.xml*". Attention, *si le nom de fichier
+XML existe déjà, le fichier est écrasé sans avertissement sur le remplacement du
+fichier XML*.
+
+.. _section_u_step4:
+
+ÉTAPE 4 : Compléter et modifier le schéma YACS, et l'enregistrer
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: Analysis
+
+Lorsque le schéma YACS est généré et ouvert dans SALOME à travers l'interface
+graphique du module YACS, on peut modifier ou compléter le schéma comme tout
+schéma YACS standard. Des noeuds ou des blocs peuvent être ajoutés, copiés ou
+modifiés pour élaborer une analyse complexe, ou pour insérer des capacités
+d'assimilation de données ou d'optimisation dans des schémas de calculs YACS
+plus complexes.
+
+Le principal complément nécessaire dans un schéma YACS est une étape de
+post-processing. L'évaluation du résultat doit être réalisée dans le contexte
+physique de simulation utilisé par la procédure d'assimilation de données. Le
+post-processing peut être fournit à travers le mot-clé "*UserPostAnalysis*"
+d'ADAO sous la forme d'un fichier de script ou d'une chaîne de caractères, par
+des patrons ("templates"), ou peut être construit comme des noeuds YACS. Ces
+deux manières de construire le post-processing peuvent utiliser toutes les
+capacités de SALOME. On se reportera à la partie traitant des
+:ref:`section_ref_output_variables`, ou à l'aide de chaque algorithme, pour la
+description complète de ces éléments.
+
+En pratique, le schéma YACS dispose d'un port de sortie "*algoResults*" dans le
+bloc de calcul, qui donne accès à un objet structuré nommé ci-après "*ADD*" par
+exemple, qui contient tous les résultats de calcul. Ces résultats peuvent être
+obtenus en récupérant les variables nommées stockées au cours des calculs.
+L'information principale est la variable "*Analysis*", qui peut être obtenue par
+une commande python (par exemple dans un noeud script intégré ("in-line script
+node") ou un script fourni à travers le mot-clé "*UserPostAnalysis*"::
+
+ Analysis = ADD.get("Analysis")[:]
+
+"*Analysis*" est un objet complexe, similaire à une liste de valeurs calculées à
+chaque étape du calcul d'assimilation. Pour obtenir et afficher l'évaluation
+optimale de l'état par assimilation de données, dans un script fournit par
+l'intermédiaire du mot-clé "*UserPostAnalysis*", on peut utiliser::
+
+ Xa = ADD.get("Analysis")[-1]
+ print("Optimal state:", Xa)
+ print()
+
+Cette variable ``Xa`` est un vecteur de valeurs, qui représente la solution du
+problème d'évaluation par assimilation de données ou par optimisation, notée
+:math:`\mathbf{x}^a` dans la section :ref:`section_theory`.
+
+Une telle méthode peut être utilisée pour imprimer les résultats, ou pour les
+convertir dans des structures qui peuvent être nécessaires à un post-processing
+natif ou externe à SALOME. Un exemple simple est disponible dans la section
+:ref:`section_tutorials_in_salome`.
+
+.. _section_u_step5:
+
+ÉTAPE 5 : Exécuter le schéma YACS et obtenir les résultats
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Le schéma YACS est maintenant complet et peut être exécuté. La paramétrisation
+et l'exécution de ce cas YACS est entièrement compatible avec la manière
+standard de traiter un schéma YACS, comme décrit dans le *Guide de l'utilisateur
+du module YACS*.
+
+Pour rappeler la manière la plus simple de procéder, le schéma YACS doit être
+compilé en utilisant le bouton |yacs_compile|, ou l'entrée équivalente du menu
+YACS, pour préparer le schéma à son exécution. Ensuite, le schéma compilé peut
+être démarré, exécuté pas à pas ou en utilisant des points d'arrêt, etc.
+
+La sortie standard est restituée dans la "*fenêtre de sortie de YACS*" (ou
+"*YACS Container Log*"), à laquelle on accède par un clic droit sur la fenêtre
+"*proc*" dans l'interface graphique YACS. Les erreurs sont présentées soit
+dans la "*fenêtre de sortie de YACS*", ou à la ligne de commande dans la fenêtre
+de commandes (si l'environnement SALOME a été lancé par une commande explicite,
+et non par un menu ou une icône de bureau). Par exemple, la sortie de l'exemple
+simple ci-dessus est de la forme suivante::
+
+ Entering in the assimilation study
+ Name is set to........: Test
+ Algorithm is set to...: Blue
+ Launching the analysis
+
+ Optimal state: [0.5, 0.5, 0.5]
+
+présentée dans la "*fenêtre de sortie de YACS*".
+
+L'exécution peut aussi être conduite en utilisant un script de commandes Shell,
+comme décrit dans la section :ref:`section_advanced`.
+
+.. [#] 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.
+
+.. [#] Pour de plus amples informations sur l'éditeur intégré de cas, voir le *module EFICAS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
+
+.. [#] L'utilisation du code de simulation physique dans les opérateurs de base de l'assimilation de données est illustrée ou décrite dans les parties principales qui suivent.
+
+.. [#] Ce fichier python intermédiaire peut aussi être utilisé comme décrit dans la section :ref:`section_advanced`.
================================================================================
Le but du module ADAO est **d'aider à l'usage de l'assimilation de données ou
-de l'optimisation en lien avec d'autres modules ou codes de simulation dans
-SALOME**. Le module ADAO fournit une interface à des algorithmes classiques
-d'assimilation de données ou d'optimisation, et permet d'intégrer leur usage
-dans une étude SALOME. Les modules de calcul ou de simulation doivent fournir
-une ou plusieurs méthodes d'appel spécifiques afin d'être appelable dans le
-cadre SALOME/ADAO, et tous les modules SALOME peuvent être utilisés grace à
-l'intégration dans YACS de ADAO.
-
-Son principal objectif est de **permettre l'usage de diverses méthodes standards
-d'assimilation de données ou d'optimisation, tout en restant facile à utiliser
-et en fournissant une démarche pour aider à la mise en oeuvre**. Pour
-l'utilisateur final, qui a préalablement recueilli les informations sur son
-problème physique, l'environnement lui permet d'avoir une démarche de type
-"souris\&click" pour construire un cas ADAO valide et pour l'évaluer.
+de l'optimisation en lien avec d'autres modules ou codes de simulation dans un
+contexte Python [Python]_ ou SALOME [Salome]_**. Le module ADAO fournit une
+interface simple à des algorithmes classiques d'assimilation de données ou
+d'optimisation, ainsi que de tests ou vérifications. Il permet d'intégrer leur
+usage dans une étude Python ou SALOME. Les modules utilisateurs de calcul ou de
+simulation doivent fournir une ou plusieurs méthodes d'appel spécifiques afin
+d'être appelable dans le cadre Python ou SALOME. En environnement SALOME, tous
+les modules natifs peuvent être utilisés grâce à l'intégration en Python ou en
+YACS.
+
+Son principal objectif est de **permettre l'usage de diverses méthodes
+standards d'assimilation de données ou d'optimisation, tout en restant facile à
+paramétrer, et en fournissant une démarche simplifiée pour aider à la mise en
+oeuvre**. Pour l'utilisateur final, qui a préalablement recueilli les
+informations sur son problème physique, l'environnement lui permet d'avoir une
+démarche centrée sur la simple déclaration de ces informations pour construire
+un cas ADAO valide, pour l'évaluer, et pour en tirer les résultats physiques
+dont il a besoin.
Le module couvre une grande variété d'applications pratiques, de façon robuste,
-permettant des applications réelles, mais aussi d'effectuer de l'expérimentation
-méthodologique rapide. Son évolutivité, des points de vue méthodologique et
-numérique, permettra l'extension de son domaine d'application.
+permettant des applications réelles, mais aussi d'effectuer de
+l'expérimentation méthodologique rapide. Son évolutivité, des points de vue
+méthodologique et numérique, permet aussi l'extension de son domaine
+d'application. Il est basé sur l'utilisation d'autres modules, à savoir YACS et
+EFICAS s'ils sont disponibles, et sur l'utilisation d'une bibliothèque et
+d'outils génériques sous-jacents d'assimilation de données.
Algorithme de vérification "*SamplingTest*"
-------------------------------------------
-Description
-+++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo01.rst
Cet algorithme permet d'établir les valeurs, liées à un état :math:`\mathbf{x}`,
d'une fonctionnelle d'erreur :math:`J` quelconque de type :math:`L^1`,
Pour effectuer un échantillonnage distribué ou plus complexe, voir le module
OPENTURNS disponible dans SALOME.
-Commandes requises et optionnelles
-++++++++++++++++++++++++++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo02.rst
-Les commandes requises générales, disponibles dans l'interface en édition, sont
-les suivantes:
+.. include:: snippets/CheckingPoint.rst
- .. include:: snippets/CheckingPoint.rst
+.. include:: snippets/BackgroundError.rst
- .. include:: snippets/BackgroundError.rst
+.. include:: snippets/Observation.rst
- .. include:: snippets/Observation.rst
+.. include:: snippets/ObservationError.rst
- .. include:: snippets/ObservationError.rst
+.. include:: snippets/ObservationOperator.rst
- .. include:: snippets/ObservationOperator.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo03Chck.rst
-Les commandes optionnelles générales, disponibles dans l'interface en édition,
-sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les
-paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les
-options particulières, décrites ci-après, de l'algorithme. On se reportera à la
-:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
-commande.
+.. include:: snippets/QualityCriterion.rst
-Les options de l'algorithme sont les suivantes:
-.. index:: single: SampleAsnUplet
-.. index:: single: SampleAsExplicitHyperCube
-.. index:: single: SampleAsMinMaxStepHyperCube
-.. index:: single: SampleAsIndependantRandomVariables
+.. include:: snippets/SampleAsExplicitHyperCube.rst
- SampleAsnUplet
- Cette clé décrit les points de calcul sous la forme d'une liste de n-uplets,
- chaque n-uplet étant un état.
+.. include:: snippets/SampleAsIndependantRandomVariables.rst
- Exemple :
- ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4
+.. include:: snippets/SampleAsMinMaxStepHyperCube.rst
- SampleAsExplicitHyperCube
- Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on
- donne la liste des échantillonnages explicites de chaque variable comme une
- liste. C'est donc une liste de listes, chacune étant de taille
- potentiellement différente.
+.. include:: snippets/SampleAsnUplet.rst
- Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2
+.. include:: snippets/SetDebug.rst
- SampleAsMinMaxStepHyperCube
- Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on
- donne la liste des échantillonnages implicites de chaque variable par un
- triplet *[min,max,step]*. C'est donc une liste de la même taille que celle
- de l'état. Les bornes sont incluses.
+.. include:: snippets/SetSeed.rst
- Exemple :
- ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2
+StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
- SampleAsIndependantRandomVariables
- Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont
- les points sur chaque axe proviennent de l'échantillonnage aléatoire
- indépendant de la variable d'axe, selon la spécification de la
- distribution, de ses paramètres et du nombre de points de l'échantillon,
- sous la forme d'une liste ``['distribution', [parametres], nombre]`` pour
- chaque axe. Les distributions possibles sont 'normal' de paramètres
- (mean,std), 'lognormal' de paramètres (mean,sigma), 'uniform' de paramètres
- (low,high), ou 'weibull' de paramètre (shape). C'est donc une liste de la
- même taille que celle de l'état.
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
+ aucune de ces variables n'étant calculée et stockée par défaut. Les noms
+ possibles sont dans la liste suivante : [
+ "CostFunctionJ",
+ "CostFunctionJb",
+ "CostFunctionJo",
+ "CurrentState",
+ "InnovationAtCurrentState",
+ "SimulatedObservationAtCurrentState",
+ ].
- Exemple :
- ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2
+ Exemple :
+ ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
- .. include:: snippets/QualityCriterion.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo04.rst
- .. include:: snippets/SetDebug.rst
+.. include:: snippets/CostFunctionJ.rst
- .. include:: snippets/SetSeed.rst
+.. include:: snippets/CostFunctionJb.rst
- StoreSupplementaryCalculations
- .. index:: single: StoreSupplementaryCalculations
+.. include:: snippets/CostFunctionJo.rst
- Cette liste indique les noms des variables supplémentaires qui peuvent être
- disponibles à la fin de l'algorithme. Cela implique potentiellement des
- calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
- aucune de ces variables n'étant calculée et stockée par défaut. Les noms
- possibles sont dans la liste suivante : ["CostFunctionJ", "CostFunctionJb",
- "CostFunctionJo", "CurrentState", "InnovationAtCurrentState",
- "SimulatedObservationAtCurrentState"].
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo05.rst
- Exemple :
- ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
+.. include:: snippets/CurrentState.rst
-Informations et variables disponibles à la fin de l'algorithme
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. include:: snippets/InnovationAtCurrentState.rst
-En sortie, après exécution de l'algorithme, on dispose d'informations et de
-variables issues du calcul. La description des
-:ref:`section_ref_output_variables` indique la manière de les obtenir par la
-méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables
-d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter
-l'écriture des procédures de post-processing, sont décrites dans
-l':ref:`subsection_r_o_v_Inventaire`.
+.. include:: snippets/SimulatedObservationAtCurrentState.rst
-Les sorties non conditionnelles de l'algorithme sont les suivantes:
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo06.rst
- .. include:: snippets/CostFunctionJ.rst
+- :ref:`section_ref_algorithm_FunctionTest`
+- :ref:`section_ref_algorithm_LocalSensitivityTest`
- .. include:: snippets/CostFunctionJb.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo08.rst
- .. include:: snippets/CostFunctionJo.rst
-
-Les sorties conditionnelles de l'algorithme sont les suivantes:
-
- .. include:: snippets/CurrentState.rst
-
- .. include:: snippets/InnovationAtCurrentState.rst
-
- .. include:: snippets/SimulatedObservationAtCurrentState.rst
-
-Voir aussi
-++++++++++
-
-Références vers d'autres sections :
- - :ref:`section_ref_algorithm_FunctionTest`
-
-Références vers d'autres modules SALOME :
- - OPENTURNS, voir le *Guide utilisateur du module OPENTURNS* dans le menu principal *Aide* de l'environnement SALOME
+- OPENTURNS, voir le *Guide utilisateur du module OPENTURNS* dans le menu principal *Aide* de l'environnement SALOME
--- /dev/null
+..
+ Copyright (C) 2008-2019 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
+
+.. index:: single: TabuSearch
+.. _section_ref_algorithm_TabuSearch:
+
+Algorithme de calcul "*TabuSearch*"
+-----------------------------------
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo01.rst
+
+Cet algorithme réalise une estimation d'état par minimisation d'une
+fonctionnelle d'écart :math:`J` sans gradient. C'est une méthode qui n'utilise
+pas les dérivées de la fonctionnelle d'écart. Elle entre, par exemple, dans la
+même catégorie que l':ref:`section_ref_algorithm_DerivativeFreeOptimization`,
+l':ref:`section_ref_algorithm_ParticleSwarmOptimization` ou
+l':ref:`section_ref_algorithm_DifferentialEvolution`.
+
+C'est une méthode d'optimisation permettant la recherche du minimum global d'une
+fonctionnelle d'erreur :math:`J` quelconque de type :math:`L^1`, :math:`L^2` ou
+:math:`L^{\infty}`, avec ou sans pondérations. La fonctionnelle d'erreur par
+défaut est celle de moindres carrés pondérés augmentés, classiquement utilisée
+en assimilation de données.
+
+Elle fonctionne par exploration aléatoire itérative du voisinage du point
+courant, pour en choisir l'état qui minimise la fonctionnelle d'écart. Pour
+éviter de revenir dans un point déjà exploré, le mécanisme de mémoire de
+l'algorithme permet d'interdire (d'où le nom de *tabou*) le retour dans les
+derniers états explorés. Les positions déjà explorées sont conservées dans une
+liste de longueur finie.
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo02.rst
+
+.. include:: snippets/Background.rst
+
+.. include:: snippets/BackgroundError.rst
+
+.. include:: snippets/Observation.rst
+
+.. include:: snippets/ObservationError.rst
+
+.. include:: snippets/ObservationOperator.rst
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo03AdOp.rst
+
+.. include:: snippets/LengthOfTabuList.rst
+
+.. include:: snippets/MaximumNumberOfSteps_50.rst
+
+.. include:: snippets/NoiseAddingProbability.rst
+
+.. include:: snippets/NoiseDistribution.rst
+
+.. include:: snippets/NoiseHalfRange.rst
+
+.. include:: snippets/NumberOfElementaryPerturbations.rst
+
+.. include:: snippets/QualityCriterion.rst
+
+.. include:: snippets/SetSeed.rst
+
+.. include:: snippets/StandardDeviation.rst
+
+StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
+
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
+ aucune de ces variables n'étant calculée et stockée par défaut. Les noms
+ possibles sont dans la liste suivante : [
+ "BMA",
+ "OMA",
+ "OMB",
+ "CurrentState",
+ "CostFunctionJ",
+ "CostFunctionJb",
+ "CostFunctionJo",
+ "Innovation",
+ "SimulatedObservationAtBackground",
+ "SimulatedObservationAtCurrentState",
+ "SimulatedObservationAtOptimum",
+ ].
+
+ Exemple :
+ ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo04.rst
+
+.. include:: snippets/Analysis.rst
+
+.. include:: snippets/CostFunctionJ.rst
+
+.. include:: snippets/CostFunctionJb.rst
+
+.. include:: snippets/CostFunctionJo.rst
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo05.rst
+
+.. include:: snippets/BMA.rst
+
+.. include:: snippets/OMA.rst
+
+.. include:: snippets/OMB.rst
+
+.. include:: snippets/CurrentState.rst
+
+.. include:: snippets/Innovation.rst
+
+.. include:: snippets/SimulatedObservationAtBackground.rst
+
+.. include:: snippets/SimulatedObservationAtCurrentState.rst
+
+.. include:: snippets/SimulatedObservationAtOptimum.rst
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo06.rst
+
+- :ref:`section_ref_algorithm_DerivativeFreeOptimization`
+- :ref:`section_ref_algorithm_DifferentialEvolution`
+- :ref:`section_ref_algorithm_ParticleSwarmOptimization`
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo07.rst
+
+- [Glover89]_
+- [Glover90]_
+- [WikipediaTS]_
Algorithme de vérification "*TangentTest*"
------------------------------------------
-Description
-+++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo01.rst
Cet algorithme permet de vérifier la qualité de l'opérateur tangent, en
calculant un résidu dont les propriétés théoriques sont connues.
On prend :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et
:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` est le code de calcul.
-Commandes requises et optionnelles
-++++++++++++++++++++++++++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo02.rst
-Les commandes requises générales, disponibles dans l'interface en édition, sont
-les suivantes:
+.. include:: snippets/CheckingPoint.rst
- .. include:: snippets/CheckingPoint.rst
+.. include:: snippets/ObservationOperator.rst
- .. include:: snippets/ObservationOperator.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo03Chck.rst
-Les commandes optionnelles générales, disponibles dans l'interface en édition,
-sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les
-paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les
-options particulières, décrites ci-après, de l'algorithme. On se reportera à la
-:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
-commande.
+.. include:: snippets/AmplitudeOfInitialDirection.rst
-Les options de l'algorithme sont les suivantes:
+.. include:: snippets/EpsilonMinimumExponent.rst
- .. include:: snippets/AmplitudeOfInitialDirection.rst
+.. include:: snippets/InitialDirection.rst
- .. include:: snippets/EpsilonMinimumExponent.rst
+.. include:: snippets/SetSeed.rst
- .. include:: snippets/InitialDirection.rst
+StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
- .. include:: snippets/SetSeed.rst
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
+ aucune de ces variables n'étant calculée et stockée par défaut. Les noms
+ possibles sont dans la liste suivante : [
+ "CurrentState",
+ "Residu",
+ "SimulatedObservationAtCurrentState",
+ ].
- StoreSupplementaryCalculations
- .. index:: single: StoreSupplementaryCalculations
+ Exemple :
+ ``{"StoreSupplementaryCalculations":["CurrentState"]}``
- Cette liste indique les noms des variables supplémentaires qui peuvent être
- disponibles à la fin de l'algorithme. Cela implique potentiellement des
- calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
- aucune de ces variables n'étant calculée et stockée par défaut. Les noms
- possibles sont dans la liste suivante : ["CurrentState", "Residu",
- "SimulatedObservationAtCurrentState"].
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo04.rst
- Exemple :
- ``{"StoreSupplementaryCalculations":["CurrentState"]}``
+.. include:: snippets/Residu.rst
-Informations et variables disponibles à la fin de l'algorithme
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo05.rst
-En sortie, après exécution de l'algorithme, on dispose d'informations et de
-variables issues du calcul. La description des
-:ref:`section_ref_output_variables` indique la manière de les obtenir par la
-méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables
-d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter
-l'écriture des procédures de post-processing, sont décrites dans
-l':ref:`subsection_r_o_v_Inventaire`.
+.. include:: snippets/CurrentState.rst
-Les sorties non conditionnelles de l'algorithme sont les suivantes:
+.. include:: snippets/SimulatedObservationAtCurrentState.rst
- .. include:: snippets/Residu.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo06.rst
-Les sorties conditionnelles de l'algorithme sont les suivantes:
-
- .. include:: snippets/CurrentState.rst
-
- .. include:: snippets/SimulatedObservationAtCurrentState.rst
-
-Voir aussi
-++++++++++
-
-Références vers d'autres sections :
- - :ref:`section_ref_algorithm_FunctionTest`
- - :ref:`section_ref_algorithm_LinearityTest`
- - :ref:`section_ref_algorithm_AdjointTest`
- - :ref:`section_ref_algorithm_GradientTest`
+- :ref:`section_ref_algorithm_FunctionTest`
+- :ref:`section_ref_algorithm_LinearityTest`
+- :ref:`section_ref_algorithm_AdjointTest`
+- :ref:`section_ref_algorithm_GradientTest`
+- :ref:`section_ref_algorithm_LocalSensitivityTest`
Algorithme de calcul "*UnscentedKalmanFilter*"
----------------------------------------------
-Description
-+++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo01.rst
Cet algorithme réalise une estimation de l'état d'un système dynamique par un
filtre de Kalman "unscented", permettant d'éviter de devoir calculer les
coûteux en évaluation sur de petits systèmes. On peut vérifier la linéarité des
opérateurs à l'aide de l':ref:`section_ref_algorithm_LinearityTest`.
-Commandes requises et optionnelles
-++++++++++++++++++++++++++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo02.rst
-Les commandes requises générales, disponibles dans l'interface en édition, sont
-les suivantes:
+.. include:: snippets/Background.rst
- .. include:: snippets/Background.rst
+.. include:: snippets/BackgroundError.rst
- .. include:: snippets/BackgroundError.rst
+.. include:: snippets/EvolutionError.rst
- .. include:: snippets/EvolutionError.rst
+.. include:: snippets/EvolutionModel.rst
- .. include:: snippets/EvolutionModel.rst
+.. include:: snippets/Observation.rst
- .. include:: snippets/Observation.rst
+.. include:: snippets/ObservationError.rst
- .. include:: snippets/ObservationError.rst
+.. include:: snippets/ObservationOperator.rst
- .. include:: snippets/ObservationOperator.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo03AdOp.rst
-Les commandes optionnelles générales, disponibles dans l'interface en édition,
-sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les
-paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les
-options particulières, décrites ci-après, de l'algorithme. On se reportera à la
-:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
-commande.
+.. include:: snippets/BoundsWithExtremes.rst
-Les options de l'algorithme sont les suivantes:
+.. include:: snippets/ConstrainedBy.rst
- .. include:: snippets/BoundsWithExtremes.rst
+.. include:: snippets/EstimationOf.rst
- .. include:: snippets/ConstrainedBy.rst
+.. include:: snippets/AlphaBeta.rst
- .. include:: snippets/EstimationOf.rst
+StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
- Alpha, Beta, Kappa, Reconditioner
- .. index:: single: Alpha
- .. index:: single: Beta
- .. index:: single: Kappa
- .. index:: single: Reconditioner
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
+ aucune de ces variables n'étant calculée et stockée par défaut. Les noms
+ possibles sont dans la liste suivante : [
+ "APosterioriCorrelations",
+ "APosterioriCovariance",
+ "APosterioriStandardDeviations",
+ "APosterioriVariances",
+ "BMA",
+ "CostFunctionJ",
+ "CostFunctionJb",
+ "CostFunctionJo",
+ "CurrentState",
+ "Innovation",
+ ].
- Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert
- une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour
- une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière,
- dont la bonne valeur par défaut est obtenue en la mettant à 0.
- "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut
- étant 1.
+ Exemple :
+ ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
- Exemple :
- ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}``
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo04.rst
- StoreSupplementaryCalculations
+.. include:: snippets/Analysis.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo05.rst
- Cette liste indique les noms des variables supplémentaires qui peuvent être
- disponibles à la fin de l'algorithme. Cela implique potentiellement des
- calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
- aucune de ces variables n'étant calculée et stockée par défaut. Les noms
- possibles sont dans la liste suivante : ["APosterioriCorrelations",
- "APosterioriCovariance", "APosterioriStandardDeviations",
- "APosterioriVariances", "BMA", "CostFunctionJ", "CostFunctionJb",
- "CostFunctionJo", "CurrentState", "Innovation"].
+.. include:: snippets/APosterioriCorrelations.rst
- Exemple :
- ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
+.. include:: snippets/APosterioriCovariance.rst
-Informations et variables disponibles à la fin de l'algorithme
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. include:: snippets/APosterioriStandardDeviations.rst
-En sortie, après exécution de l'algorithme, on dispose d'informations et de
-variables issues du calcul. La description des
-:ref:`section_ref_output_variables` indique la manière de les obtenir par la
-méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables
-d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter
-l'écriture des procédures de post-processing, sont décrites dans
-l':ref:`subsection_r_o_v_Inventaire`.
+.. include:: snippets/APosterioriVariances.rst
-Les sorties non conditionnelles de l'algorithme sont les suivantes:
+.. include:: snippets/BMA.rst
- .. include:: snippets/Analysis.rst
+.. include:: snippets/CostFunctionJ.rst
-Les sorties conditionnelles de l'algorithme sont les suivantes:
+.. include:: snippets/CostFunctionJb.rst
- .. include:: snippets/APosterioriCorrelations.rst
+.. include:: snippets/CostFunctionJo.rst
- .. include:: snippets/APosterioriCovariance.rst
+.. include:: snippets/CurrentState.rst
- .. include:: snippets/APosterioriStandardDeviations.rst
+.. include:: snippets/Innovation.rst
- .. include:: snippets/APosterioriVariances.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo06.rst
- .. include:: snippets/BMA.rst
+- :ref:`section_ref_algorithm_KalmanFilter`
+- :ref:`section_ref_algorithm_ExtendedKalmanFilter`
+- :ref:`section_ref_algorithm_EnsembleKalmanFilter`
- .. include:: snippets/CostFunctionJ.rst
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo07.rst
- .. include:: snippets/CostFunctionJb.rst
-
- .. include:: snippets/CostFunctionJo.rst
-
- .. include:: snippets/CurrentState.rst
-
- .. include:: snippets/Innovation.rst
-
-Voir aussi
-++++++++++
-
-Références vers d'autres sections :
- - :ref:`section_ref_algorithm_KalmanFilter`
- - :ref:`section_ref_algorithm_ExtendedKalmanFilter`
- - :ref:`section_ref_algorithm_EnsembleKalmanFilter`
-
-Références bibliographiques :
- - [WikipediaUKF]_
+- [WikipediaUKF]_
Liste des commandes et mots-clés pour un cas d'assimilation de données ou d'optimisation
----------------------------------------------------------------------------------------
-.. index:: single: Algorithm
-.. index:: single: AlgorithmParameters
-.. index:: single: ControlInput
-.. index:: single: Debug
-.. index:: single: InputVariables
-.. index:: single: Observer
-.. index:: single: Observers
-.. index:: single: Observer Template
-.. index:: single: OutputVariables
-.. index:: single: StudyName
-.. index:: single: StudyRepertory
-.. index:: single: UserDataInit
-.. index:: single: UserPostAnalysis
-.. index:: single: UserPostAnalysis Template
-
Ce jeu de commandes est lié à la description d'un cas de calcul, qui est une
procédure d'*Assimilation de Données* ou d'*Optimisation*. Les termes sont
classés par ordre alphabétique, sauf le premier, qui décrit le choix entre le
Les différentes commandes sont les suivantes:
- **ASSIMILATION_STUDY**
- *Commande obligatoire*. C'est la commande générale qui décrit le cas
- d'assimilation de données ou d'optimisation. Elle contient hiérarchiquement
- toutes les autres commandes.
-
- AlgorithmParameters
- *Commande obligatoire*. Elle définit l'algorithme d'assimilation de données
- ou d'optimisation choisi par le mot-clé "*Algorithm*", et ses éventuels
- paramètres optionnels. Les choix d'algorithmes sont disponibles à travers
- l'interface graphique. Il existe par exemple le "3DVAR", le "Blue"... Chaque
- algorithme est défini, plus loin, par une sous-section spécifique. De
- manière facultative, la commande permet aussi d'ajouter des paramètres pour
- contrôler l'algorithme. Leurs valeurs sont définies explicitement ou dans un
- objet de type "*Dict*". On se reportera à la
- :ref:`section_ref_options_Algorithm_Parameters` pour l'usage détaillé de
- cette partie de la commande.
-
- .. include:: snippets/Background.rst
-
- .. include:: snippets/BackgroundError.rst
-
- ControlInput
- *Commande optionnelle*. Elle indique le vecteur de contrôle utilisé pour
- forcer le modèle d'évolution à chaque pas, usuellement noté
- :math:`\mathbf{U}`. Sa valeur est définie comme un objet de type "*Vector*"
- ou de type "*VectorSerie*". Lorsqu'il n'y a pas de contrôle, sa valeur doit
- être une chaîne vide ''.
-
- Debug
- *Commande optionnelle*. Elle définit le niveau de sorties et d'informations
- intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et
- 1 (pour True).
-
- .. include:: snippets/EvolutionError.rst
-
- .. include:: snippets/EvolutionModel.rst
-
- InputVariables
- *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
- variables physiques qui sont rassemblées dans le vecteur d'état. Cette
- information est destinée à être utilisée dans le traitement algorithmique
- interne des données.
-
- .. include:: snippets/Observation.rst
-
- .. include:: snippets/ObservationError.rst
-
- .. include:: snippets/ObservationOperator.rst
-
- Observers
- *Commande optionnelle*. Elle permet de définir des observateurs internes,
- qui sont des fonctions liées à une variable particulière, qui sont exécutées
- chaque fois que cette variable est modifiée. C'est une manière pratique de
- suivre des variables d'intérêt durant le processus d'assimilation de données
- ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples
- courants (squelettes) sont fournis pour aider l'utilisateur ou pour
- faciliter l'élaboration d'un cas.
-
- OutputVariables
- *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
- variables physiques qui sont rassemblées dans le vecteur d'observation.
- Cette information est destinée à être utilisée dans le traitement
- algorithmique interne des données.
-
- StudyName
- *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
- décrire l'étude ADAO par un nom ou une déclaration.
-
- StudyRepertory
- *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
- pour les calculs, et il est utilisé pour trouver les fichiers de script,
- donnés par nom sans répertoire, qui peuvent être utilisés pour définir
- certaines variables.
-
- UserDataInit
- *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
- certaines données automatiquement avant le traitement de données d'entrée
- pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
- nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
- variables choisies.
-
- UserPostAnalysis
- *Commande optionnelle*. Elle permet de traiter des paramètres ou des
- résultats après le déroulement de l'algorithme d'assimilation de données ou
- d'optimisation. Sa valeur est définie comme un fichier script ou une chaîne
- de caractères, permettant de produire directement du code de post-processing
- dans un cas ADAO. Des exemples courants (squelettes) sont fournis pour aider
- l'utilisateur ou pour faciliter l'élaboration d'un cas.
+.. include:: snippets/ASSIMILATION_STUDY.rst
+
+.. include:: snippets/AlgorithmParameters.rst
+
+.. include:: snippets/Background.rst
+
+.. include:: snippets/BackgroundError.rst
+
+.. include:: snippets/ControlInput.rst
+
+.. include:: snippets/Debug.rst
+
+.. include:: snippets/EvolutionError.rst
+
+.. include:: snippets/EvolutionModel.rst
+
+.. include:: snippets/InputVariables.rst
+
+.. include:: snippets/Observation.rst
+
+.. include:: snippets/ObservationError.rst
+
+.. include:: snippets/ObservationOperator.rst
+
+.. include:: snippets/Observers.rst
+
+.. include:: snippets/OutputVariables.rst
+
+.. include:: snippets/StudyName.rst
+
+.. include:: snippets/StudyRepertory.rst
+
+.. include:: snippets/UserDataInit.rst
+
+.. include:: snippets/UserPostAnalysis.rst
Liste des commandes et mots-clés pour un cas de vérification
------------------------------------------------------------
-.. index:: single: Algorithm
-.. index:: single: AlgorithmParameters
-.. index:: single: Debug
-.. index:: single: Observer
-.. index:: single: Observers
-.. index:: single: Observer Template
-.. index:: single: StudyName
-.. index:: single: StudyRepertory
-.. index:: single: UserDataInit
-
Ce jeu de commandes est lié à la description d'un cas de vérification, qui est
une procédure pour vérifier les propriétés d'une information requise, utilisée
ailleurs par un cas de calcul. Les termes sont classés par ordre alphabétique,
Les différentes commandes sont les suivantes:
- **CHECKING_STUDY**
- *Commande obligatoire*. C'est la commande générale qui décrit le cas de
- vérification. Elle contient hiérarchiquement toutes les autres commandes.
-
- AlgorithmParameters
- *Commande obligatoire*. Elle définit l'algorithme de test choisi par le
- mot-clé "*Algorithm*", et ses éventuels paramètres optionnels. Les choix
- d'algorithmes sont disponibles à travers l'interface graphique. Il existe
- par exemple le "FunctionTest", le "GradientTest"... Chaque algorithme est
- défini, plus loin, par une sous-section spécifique. De manière facultative,
- la commande permet aussi d'ajouter des paramètres pour contrôler
- l'algorithme. Leurs valeurs sont définies explicitement ou dans un objet de
- type "*Dict*". On se reportera à la
- :ref:`section_ref_options_Algorithm_Parameters` pour l'usage détaillé de
- cette partie de la commande.
-
- .. include:: snippets/CheckingPoint.rst
-
- .. include:: snippets/BackgroundError.rst
-
- Debug
- *Commande optionnelle*. Elle définit le niveau de sorties et d'informations
- intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et
- 1 (pour True).
-
- .. include:: snippets/Observation.rst
-
- .. include:: snippets/ObservationError.rst
-
- .. include:: snippets/ObservationOperator.rst
-
- Observers
- *Commande optionnelle*. Elle permet de définir des observateurs internes,
- qui sont des fonctions liées à une variable particulière, qui sont exécutées
- chaque fois que cette variable est modifiée. C'est une manière pratique de
- suivre des variables d'intérêt durant le processus d'assimilation de données
- ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples
- courants (squelettes) sont fournis pour aider l'utilisateur ou pour
- faciliter l'élaboration d'un cas.
-
- StudyName
- *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
- décrire l'étude ADAO par un nom ou une déclaration.
-
- StudyRepertory
- *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
- pour les calculs, et il est utilisé pour trouver les fichiers de script,
- donnés par nom sans répertoire, qui peuvent être utilisés pour définir
- certaines variables.
-
- UserDataInit
- *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
- certaines données automatiquement avant le traitement de données d'entrée
- pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
- nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
- variables choisies.
+.. include:: snippets/CHECKING_STUDY.rst
+
+.. include:: snippets/AlgorithmParameters.rst
+
+.. include:: snippets/CheckingPoint.rst
+
+.. include:: snippets/BackgroundError.rst
+
+.. include:: snippets/Debug.rst
+
+.. include:: snippets/Observation.rst
+
+.. include:: snippets/ObservationError.rst
+
+.. include:: snippets/ObservationOperator.rst
+
+.. include:: snippets/Observers.rst
+
+.. include:: snippets/StudyName.rst
+
+.. include:: snippets/StudyRepertory.rst
+
+.. include:: snippets/UserDataInit.rst
Exigences pour décrire les matrices de covariance
-------------------------------------------------
+.. index:: single: setBackgroundError
+.. index:: single: setObservationError
+.. index:: single: setEvolutionError
.. index:: single: matrice de covariance
.. index:: single: covariances d'erreurs d'ébauche
.. index:: single: covariances d'erreurs d'observation
.. index:: single: covariances
-De manière générale, une matrice de covariance (ou une matrice de
-variance-covariance) doit être carrée, symétrique, semi-définie positive. Chacun
-de ses termes décrit la covariance des deux variables aléatoires correspondantes
-à sa position dans la matrice. La forme normalisée de la covariance est la
-corrélation linéaire. On peut écrire la relation suivante, entre une matrice de
-covariance :math:`\mathbf{M}` et ses matrices correspondantes de corrélation
-:math:`\mathbf{C}` (matrice pleine) et d'écart-type :math:`\mathbf{\Sigma}`
-(matrice diagonale):
+De manière générale, une matrice de variances-covariances, généralement appelée
+matrice de covariance, doit être carrée, symétrique et semi-définie positive.
+Chacun de ses termes décrit la covariance des deux variables aléatoires
+correspondantes à sa position dans la matrice. La forme normalisée de la
+covariance est la corrélation linéaire. On peut écrire la relation suivante,
+entre une matrice de covariance :math:`\mathbf{M}` et ses matrices
+correspondantes de corrélation :math:`\mathbf{C}` (matrice pleine) et
+d'écart-type :math:`\mathbf{\Sigma}` (matrice diagonale):
.. math:: \mathbf{M} = \mathbf{\Sigma} * \mathbf{C} * \mathbf{\Sigma}
matrice de covariance des erreurs d'ébauche, notée :math:`\mathbf{B}`, et la
matrice de covariance des erreurs d'observation, notée :math:`\mathbf{R}`.
-Il y a 3 méthodes pratiques pour l'utilisateur pour fournir une matrice de
-covariance. La méthode est choisie à l'aide du mot-clé "*INPUT_TYPE*" de chaque
-matrice de covariance, comme montré dans la figure qui suit :
+Dans l'interface graphique EFICAS d'ADAO, il y a 3 méthodes pratiques pour
+l'utilisateur pour fournir une matrice de covariance. La méthode est choisie à
+l'aide du mot-clé "*INPUT_TYPE*" de chaque matrice de covariance, comme montré
+dans la figure qui suit :
.. eficas_covariance_matrix:
.. image:: images/eficas_covariance_matrix.png
.. centered::
**Choisir la représentation d'une matrice de covariance**
+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 adéquate
+"*setBackgroundError*", "*setObservationError*" ou "*setEvolutionError*" selon
+la grandeur physique à définir. Les autres arguments "*Matrix*",
+"*ScalarSparseMatrix*" et "*DiagonalSparseMatrix*" de la commande permettent de
+la définir comme décrit dans les sous-parties qui suivent. Ces informations
+peuvent aussi être fournies dans un script contenu en fichier externe (argument
+"*Script*").
+
Première forme matricielle : utiliser la représentation "*Matrix*"
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
La première forme est le défaut, et c'est la plus générale. La matrice de
covariance :math:`\mathbf{M}` doit être entièrement spécifiée. Même si la
matrice est symétrique par nature, la totalité de la matrice :math:`\mathbf{M}`
-doit être donnée.
+doit être fournie.
.. math:: \mathbf{M} = \begin{pmatrix}
m_{11} & m_{12} & \cdots & m_{1n} \\
BackgroundError = 1.
-ou, mieux, par un "*String*" directement dans le cas ADAO.
+ou, mieux, par un argument "*String*" directement dans le cas graphique ou
+textuel ADAO.
Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*"
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ou::
BackgroundError = numpy.ones(...)
+
+De la même manière que précédemment, on peut aussi définir cette matrice par
+un "*String*" directement dans le cas graphique ou textuel ADAO.
Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
-.. _ref_observers_requirements:
+.. _section_ref_observers_requirements:
Exigences pour les fonctions décrivant un "*observer*"
------------------------------------------------------
.. index:: single: Observer
+.. index:: single: setObserver
.. index:: single: Observer Template
-Certaines variables spéciales, internes à l'optimisation, 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. 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. Ils sont activés à chaque
-modification de la variable.
+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.
-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 :
+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 :
.. eficas_observer_nodetype:
.. image:: images/eficas_observer_nodetype.png
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. 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, 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.
+défaut dans ADAO lors de l'usage de l'éditeur graphique EFICAS 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, 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*
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
On donne ci-après l'identifiant et le contenu de chaque modèle disponible.
+.. _section_ref_observers_templates:
+
Inventaire des modèles d'*observer* disponibles ("*Template*")
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Modèle **ValuePrinterAndSaver** :
..................................
-Imprime sur la sortie standard et, en même temps enregistre dans un fichier, la valeur courante de la variable.
+Imprime sur la sortie standard et, en même temps enregistre dans un fichier du répertoire '/tmp', la valeur courante de la variable.
::
Modèle **ValueIndexPrinterAndSaver** :
.......................................
-Imprime sur la sortie standard et, en même temps enregistre dans un fichier, la valeur courante de la variable, en ajoutant son index.
+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.
::
Modèle **ValueSeriePrinterAndSaver** :
.......................................
-Imprime sur la sortie standard et, en même temps, enregistre dans un fichier la série des valeurs de la variable.
+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.
::
Modèle **ValuePrinterSaverAndGnuPlotter** :
............................................
-Imprime sur la sortie standard et, en même temps, enregistre dans un fichier et affiche graphiquement la valeur courante de la variable .
+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 .
::
Modèle **ValueSeriePrinterSaverAndGnuPlotter** :
.................................................
-Imprime sur la sortie standard et, en même temps, enregistre dans un fichier et affiche graphiquement la série des valeurs de la variable.
+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.
::
Exigences pour les fonctions décrivant un opérateur
---------------------------------------------------
+.. index:: single: setObservationOperator
+.. index:: single: setEvolutionModel
+.. index:: single: setControlModel
+
Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en
oeuvre les procédures d'assimilation de données ou d'optimisation. Ils
comprennent la simulation physique par des calculs numériques, mais aussi le
représente la transition entre deux états successifs, et il est alors similaire
à l'opérateur d'observation.
-Schématiquement, un opérateur doit donner une solution étant donné les
-paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au
-cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un
-tel processus est une fonction. Il a été brièvement décrit dans la section
-:ref:`section_theory` et il est généralisée ici par la relation:
+Schématiquement, un opérateur :math:`O` a pour objet de restituer une solution
+pour des paramètres d'entrée spécifiés. Une partie des paramètres d'entrée peut
+être modifiée au cours de la procédure d'optimisation. Ainsi, la représentation
+mathématique d'un tel processus est une fonction. Il a été brièvement décrit
+dans la section :ref:`section_theory` et il est généralisé ici par la relation:
.. math:: \mathbf{y} = O( \mathbf{x} )
-entre les pseudo-observations :math:`\mathbf{y}` et les paramètres
-:math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution
-:math:`O`. La même représentation fonctionnelle peut être utilisée pour le
-modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint
-:math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes
+entre les pseudo-observations en sortie :math:`\mathbf{y}` et les paramètres
+d'entrée :math:`\mathbf{x}` en utilisant l'opérateur d'observation ou
+d'évolution :math:`O`. La même représentation fonctionnelle peut être utilisée
+pour le modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint
+:math:`\mathbf{O}^*` qui sont aussi requis par certains algorithmes
d'assimilation de données ou d'optimisation.
En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et
-:math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et
-ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur
-Numpy) ou orientés (de type matrice Numpy).
-
-Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à
-fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière
-complète**.
-
-Cette fonction est généralement donnée comme un script qui peut être exécuté
-dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes
-externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme
-nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme
-adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer.
-
-Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation
-fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*"
-de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le
-montre la figure suivante:
+:math:`\mathbf{y}`, ou leurs incréments, sont mathématiquement des vecteurs, et
+ils peuvent donc être donnés par l'utilisateur comme des vecteurs non-orientés
+(de type liste ou vecteur Numpy) ou orientés (de type matrice Numpy).
+
+Ainsi, **pour décrire de manière complète un opérateur, l'utilisateur n'a qu'à
+fournir une fonction qui réalise complètement et uniquement l'opération
+fonctionnelle**.
+
+Cette fonction est généralement donnée comme une fonction ou un script Python,
+qui peuvent en particulier être exécuté comme une fonction Python indépendante
+ou dans un noeud YACS. Cette fonction ou ce script peuvent, sans différences,
+lancer des codes externes ou utiliser des appels et des méthodes internes
+Python ou SALOME. Si l'algorithme nécessite les 3 aspects de l'opérateur (forme
+directe, forme tangente et forme adjointe), l'utilisateur doit donner les 3
+fonctions ou les approximer grâce à ADAO.
+
+Il existe pour l'utilisateur 3 méthodes effectives de fournir une représentation
+fonctionnelle de l'opérateur, qui diffèrent selon le type d'argument choisi:
+
+- :ref:`section_ref_operator_one`
+- :ref:`section_ref_operator_funcs`
+- :ref:`section_ref_operator_switch`
+
+Dans le cas de l'interface textuelle d'ADAO (TUI), seules les deux premières
+sont nécessaires car la troisième est incluse dans la seconde. Dans le cas de
+l'interface graphique EFICAS d'ADAO, ces méthodes sont choisies dans le champ
+"*FROM*" de chaque opérateur ayant une valeur "*Function*" comme
+"*INPUT_TYPE*", comme le montre la figure suivante:
.. eficas_operator_function:
.. image:: images/eficas_operator_function.png
:align: center
:width: 100%
.. centered::
- **Choisir une représentation fonctionnelle de l'opérateur**
+ **Choisir graphiquement une représentation fonctionnelle de l'opérateur**
-Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*"
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. _section_ref_operator_one:
+Première forme fonctionnelle : un seul opérateur direct
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: OneFunction
.. index:: single: ScriptWithOneFunction
.. index:: single: DirectOperator
.. index:: single: DifferentialIncrement
.. index:: single: CenteredFiniteDifference
-La première consiste à ne fournir qu'une seule fonction potentiellement non
-linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en
-utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de
-l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir
-la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par
-exemple, le script peut suivre le modèle suivant::
+La première consiste à ne fournir qu'une seule fonction, potentiellement non
+linéaire, et à approximer les opérateurs tangent et adjoint associés.
+
+Ceci est fait dans ADAO en utilisant dans l'interface graphique EFICAS le
+mot-clé "*ScriptWithOneFunction*" pour la description par un script. Dans
+l'interface textuelle, c'est le mot-clé "*OneFunction*", éventuellement combiné
+avec le mot-clé "*Script*" selon que c'est une fonction ou un script. Si c'est
+par script externe, l'utilisateur doit fournir un fichier contenant une
+fonction qui porte le nom obligatoire "*DirectOperator*". Par exemple, un
+script externe peut suivre le modèle générique suivant::
def DirectOperator( X ):
""" Opérateur direct de simulation non-linéaire """
Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément
différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface
-graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par
-défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies
-pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation
-différences finies peut aussi être choisi à travers l'interface, en utilisant le
-mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du
-premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du
-second ordre (qui coûte numériquement deux fois plus cher que le premier ordre).
-Si nécessaire et si possible, on peut :ref:`subsection_ref_parallel_df`. Dans
-tous les cas, un mécanisme de cache interne permet de limiter le nombre
-d'évaluations de l'opérateur au minimum possible du point de vue de l'exécution
-séquentielle ou parallèle des approximations numériques des opérateurs tangent
-et adjoint, pour éviter des calculs redondants.
+graphique (GUI) ou textuelle (TUI) le mot-clé "*DifferentialIncrement*" comme
+paramètre, qui a une valeur par défaut de 1%. Ce coefficient est utilisé dans
+l'approximation différences finies pour construire les opérateurs tangent et
+adjoint. L'ordre de l'approximation différences finies peut aussi être choisi à
+travers l'interface, en utilisant le mot-clé "*CenteredFiniteDifference*", avec
+0 pour un schéma non centré du premier ordre (qui est la valeur par défaut), et
+avec 1 pour un schéma centré du second ordre (et qui coûte numériquement deux
+fois plus cher que le premier ordre). Si nécessaire et si possible, on peut
+:ref:`subsection_ref_parallel_df`. Dans tous les cas, un mécanisme de cache
+interne permet de limiter le nombre d'évaluations de l'opérateur au minimum
+possible du point de vue de l'exécution séquentielle ou parallèle des
+approximations numériques des opérateurs tangent et adjoint, pour éviter des
+calculs redondants.
Cette première forme de définition de l'opérateur permet aisément de tester la
forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la
l':ref:`section_ref_algorithm_FunctionTest`) pour ce test.
**Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le
-type de l'argument ``X`` peut être une liste, un vecteur ou une matrice Numpy.
-La fonction utilisateur doit accepter et traiter tous ces cas.
+type de l'argument ``X`` peut être une liste de valeur réelles, un vecteur
+Numpy ou une matrice Numpy. La fonction utilisateur doit accepter et traiter
+tous ces cas.
+
+.. _section_ref_operator_funcs:
-Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*"
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Seconde forme fonctionnelle : trois opérateurs direct, tangent et adjoint
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. index:: single: ThreeFunctions
.. index:: single: ScriptWithFunctions
.. index:: single: DirectOperator
.. index:: single: TangentOperator
.. index:: single: AdjointOperator
-**En général, il est recommandé d'utiliser la première forme fonctionnelle
-plutôt que la seconde. Un petit accroissement de performances n'est pas une
-bonne raison pour utiliser l'implémentation détaillée de cette seconde forme
-fonctionnelle.**
+.. warning::
+
+ en général, il est recommandé d'utiliser la première forme fonctionnelle
+ plutôt que la seconde. Un petit accroissement de performances n'est pas une
+ bonne raison pour utiliser l'implémentation détaillée de cette seconde forme
+ fonctionnelle.
La seconde consiste à fournir directement les trois opérateurs liés :math:`O`,
:math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le
mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans
-l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions
-dans un script, avec trois noms obligatoires "*DirectOperator*",
-"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre
-le squelette suivant::
+l'interface graphique EFICAS d'ADAO. Dans l'interface textuelle, c'est le
+mot-clé "*ThreeFunctions*", éventuellement combiné avec le mot-clé "*Script*"
+selon que c'est une fonction ou un script. L'utilisateur doit fournir dans un
+script trois fonctions, avec les trois noms obligatoires "*DirectOperator*",
+"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script externe peut
+suivre le squelette suivant::
def DirectOperator( X ):
""" Opérateur direct de simulation non-linéaire """
...
return quelque chose comme Y
- def TangentOperator( (X, dX) ):
+ def TangentOperator( paire = (X, dX) ):
""" Opérateur linéaire tangent, autour de X, appliqué à dX """
+ X, dX = paire
...
...
...
return quelque chose comme Y
- def AdjointOperator( (X, Y) ):
+ def AdjointOperator( paire = (X, Y) ):
""" Opérateur adjoint, autour de X, appliqué à Y """
+ X, Y = paire
...
...
...
les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la
complexité de l'implémentation de l'opérateur.
-Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse
-renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque,
-respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur
-doit renvoyer la matrice associée.
+Pour certains algorithmes, il faut que les fonctions tangente et adjointe
+puisse renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas,
+lorsque, respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, le
+script de l'utilisateur doit renvoyer la matrice associée.
**Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*"
et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``,
-``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy.
-La fonction utilisateur doit accepter et traiter tous ces cas.
+``Y``, ``dX`` peut être une liste de valeur réelles, un vecteur Numpy ou une
+matrice Numpy. La fonction utilisateur doit accepter et traiter tous ces cas.
+
+.. _section_ref_operator_switch:
-Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*"
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Troisième forme fonctionnelle : trois opérateurs avec un branchement
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: ScriptWithSwitch
.. index:: single: DirectOperator
.. index:: single: TangentOperator
.. index:: single: AdjointOperator
-**Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans
-une solide raison numérique ou physique. Un accroissement de performances n'est
-pas une bonne raison pour utiliser la complexité de cette troisième forme
-fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes
-justifie l'usage de la troisième.**
-
-La troisième forme donne de plus grandes possibilités de contrôle de l'exécution
-des trois fonctions représentant l'opérateur, permettant un usage et un contrôle
-avancés sur chaque exécution du code de simulation. C'est réalisable en
-utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à
-travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script
-unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente
-et adjointe du code de simulation. L'utilisateur peut alors, par exemple,
-utiliser des approximations pour les codes tangent et adjoint, ou introduire une
-plus grande complexité du traitement des arguments des fonctions. Mais cette
-démarche sera plus difficile à implémenter et à déboguer.
-
-Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se
-baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier
-script ou un code externe nommé ici "*Physical_simulation_functions.py*",
-contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" et
-"*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage::
+.. warning::
+
+ il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans
+ une solide raison numérique ou physique. Un accroissement de performances
+ n'est pas une bonne raison pour utiliser la complexité de cette troisième
+ forme fonctionnelle. Seule une impossibilité à utiliser les première ou
+ seconde formes justifie l'usage de la troisième.
+
+La troisième forme donne de plus grandes possibilités de contrôle de
+l'exécution des trois fonctions représentant l'opérateur, permettant un usage
+et un contrôle avancés sur chaque exécution du code de simulation. C'est
+réalisable en utilisant le mot-clé "*ScriptWithSwitch*" pour la description de
+l'opérateur à travers l'interface graphique EFICAS d'ADAO. Dans l'interface
+textuelle, il suffit d'utiliser le mot-clé "*ThreeFunctions*" précédent pour
+définir aussi ce cas, en indiquant les fonctions adéquates. L'utilisateur doit
+fournir un script unique aiguillant, selon un contrôle, l'exécution des formes
+directe, tangente et adjointe du code de simulation. L'utilisateur peut alors,
+par exemple, utiliser des approximations pour les codes tangent et adjoint, ou
+introduire une plus grande complexité du traitement des arguments des
+fonctions. Mais cette démarche sera plus difficile à implémenter et à déboguer.
+
+Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de
+se baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un
+fichier script ou un code externe nommé ici
+"*Physical_simulation_functions.py*", contenant trois fonctions nommées
+"*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*" comme
+précédemment. Voici le squelette d'aiguillage::
import Physical_simulation_functions
import numpy, logging, codecs, pickle
Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé
par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la
-forme générique du modèle incrémental est légèrement modifié comme suit:
+forme générique du modèle incrémental :math:`O` est légèrement modifiée comme
+suit:
.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. En effet,
l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`.
-Schématiquement, l'opérateur doit être construit comme suit::
+Schématiquement, l'opérateur :math:`O` doit être construit comme une fonction
+applicable sur une paire:math:`\mathbf{(X, U)}` suit::
- def DirectOperator( (X, U) ):
+ def DirectOperator( paire = (X, U) ):
""" Opérateur direct de simulation non-linéaire """
+ X, U = paire
...
...
...
Les opérateurs tangent et adjoint ont la même signature que précédemment, en
notant que les dérivées doivent être faites seulement partiellement par rapport
à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième
-forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme
-fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées.
+forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième
+forme fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées.
+
+.. _section_ref_operator_dimensionless:
Remarques complémentaires sur l'adimensionnement des opérateurs
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Il est fréquent que les grandeurs physiques, en entrée ou en sortie des
opérateurs, présentent des différences notables d'ordre de grandeur ou de taux
-de variation. Une manière d'éviter des difficultés numériques est d'utiliser, ou
-d'établir, un adimensionnement des calculs menés dans les opérateurs
+de variation. Une manière d'éviter des difficultés numériques est d'utiliser,
+ou d'établir, un adimensionnement des calculs menés dans les opérateurs
[WikipediaND]_. Par principe, dans la mesure où la simulation de la physique
devrait être la plus adimensionnée possible, il est en premier lieu recommandé
d'utiliser les capacités existantes d'adimensionnement du code de calcul.
-Néanmoins, dans le cas courant où l'on ne peut en disposer, il est souvent utile
-d'environner le calcul pour l'adimensionner en entrée ou en sortie. Une manière
-simple de faire cela en entrée consiste à transformer les paramètres
+Néanmoins, dans le cas courant où l'on ne peut en disposer, il est souvent
+utile d'environner le calcul pour l'adimensionner en entrée ou en sortie. Une
+manière simple de faire cela en entrée consiste à transformer les paramètres
:math:`\mathbf{x}` en argument d'une fonction comme "*DirectOperator*". On
-utilise le plus souvent les valeurs par défaut :math:`\mathbf{x}^b` (ébauche, ou
-valeur nominale). Pourvu que chaque composante de :math:`\mathbf{x}^b` soit non
-nulle, on peut en effet poser:
+utilise le plus souvent comme référence les valeurs par défaut
+:math:`\mathbf{x}^b` (ébauche, ou valeur nominale). Pourvu que chaque
+composante de :math:`\mathbf{x}^b` soit non nulle, on peut ensuite procéder par
+correction multiplicative. Pour cela, on peut par exemple poser:
.. math:: \mathbf{x} = \mathbf{\alpha}\mathbf{x}^b
et optimiser ensuite le paramètre multiplicatif :math:`\mathbf{\alpha}`. Ce
-paramètre a pour valeur par défaut (ou pour ébauche) un vecteur de 1. Attention,
-l'application d'une démarche d'adimensionnement nécessite aussi la modification
-des covariances d'erreurs associées dans la formulation ADAO du problème
-d'optimisation.
+paramètre a pour valeur par défaut (ou pour ébauche) un vecteur de 1. De
+manière similaire, on peut procéder par correction additive si c'est plus
+judicieux pour la physique sous-jacente. Ainsi, dans ce cas, on peut poser:
+
+.. math:: \mathbf{x} =\mathbf{x}^b + \mathbf{\alpha}
+
+et optimiser ensuite le paramètre additif :math:`\mathbf{\alpha}`. Cette fois,
+ce paramètre a pour valeur d'ébauche un vecteur de 0.
+
+Attention, l'application d'une démarche d'adimensionnement nécessite aussi la
+modification des covariances d'erreurs associées dans la formulation globale du
+problème d'optimisation.
Une telle démarche suffit rarement à éviter tous les problèmes numériques, mais
permet souvent d'améliorer beaucoup le conditionnement numérique de
l'optimisation.
+
+Gestion explicite de fonctions "multiples"
+++++++++++++++++++++++++++++++++++++++++++
+
+.. warning::
+
+ il est fortement recommandé de ne pas utiliser cette gestion explicite de
+ fonctions "multiples" sans une très solide raison informatique pour le faire.
+ Cette gestion est déjà effectuée par défaut dans ADAO pour l'amélioration des
+ performances. Seul l'utilisateur très averti, cherchant à gérer des cas
+ particulièrement difficiles, peut s'intéresser à cette extension. En dépit de
+ sa simplicité, c'est au risque explicite de dégrader notablement les
+ performances.
+
+Il est possible, lorsque l'on fournit des fonctions d'opérateurs, de les
+définir comme des fonctions qui traitent non pas un seul argument, mais une
+série d'arguments, pour restituer en sortie la série des valeurs
+correspondantes. En pseudo-code, la fonction "multiple", ici nommée
+``MultiFunctionO``, représentant l'opérateur classique :math:`O` nommé
+"*DirectOperator*", effectue::
+
+ def MultiFunctionO( Inputs ):
+ """ Multiple ! """
+ Outputs = []
+ for X in Inputs:
+ Y = DirectOperator( X )
+ Outputs.append( Y )
+ return Outputs
+
+La longueur de la sortie (c'est-à-dire le nombre de valeurs calculées) est
+égale à la longueur de l'entrée (c'est-à-dire le nombre d'états dont on veut
+calculer la valeur par l'opérateur).
+
+Cette possibilité n'est disponible que dans l'interface textuelle d'ADAO. Pour
+cela, lors de la définition d'une fonction d'opérateur, en même temps que l'on
+définit de manière habituelle la fonction ou le script externe, il suffit
+d'indiquer en plus en argument par un booléen "*InputFunctionAsMulti*" que la
+définition est celle d'une fonction "multiple".
actions de calcul pilotés par YACS [#]_ ou un autre module, etc.
D'autres exemples d'utilisation sont aussi donnés en :ref:`section_u_step4` de
-la partie :ref:`section_using`, ou en partie :ref:`section_examples`.
+la partie :ref:`section_gui_in_salome`, ou en partie :ref:`section_tutorials_in_salome`.
Conditionnalité des informations disponibles en sortie
++++++++++++++++++++++++++++++++++++++++++++++++++++++
================================================================================
Les sections suivantes présentent la description de référence des commandes et
-mots-clés ADAO disponibles à travers l'interface graphique (GUI) ou à travers
-des scripts. Les deux premières sections communes présentent les
-:ref:`section_reference_entry` et les :ref:`section_reference_special_entry`.
-Ensuite, on décrit successivement les :ref:`section_reference_assimilation` et
-les :ref:`section_reference_checking`.
-
-Chaque commande ou mot-clé à définir par l'interface graphique (GUI) a des
-propriétés particulières. La première propriété est d'être *requise*,
-*optionnelle* ou simplement utile, décrivant un type d'entrée. La seconde
-propriété est d'être une variable "ouverte" avec un type fixé mais avec
-n'importe quelle valeur autorisée par le type, ou une variable "fermée", limitée
-à des valeurs spécifiées. L'éditeur graphique intégré disposant de capacités
-intrinsèques de validation, les propriétés des commandes ou mots-clés données à
-l'aide de l'interface graphique sont automatiquement correctes.
+mots-clés ADAO disponibles à travers l'interface textuelle (TUI), graphique
+(GUI) ou à travers des scripts. Les deux premières sections communes présentent
+les :ref:`section_reference_entry` et les
+:ref:`section_reference_special_entry`. Ensuite, on décrit successivement les
+:ref:`section_reference_assimilation` et les :ref:`section_reference_checking`.
+
+Chaque commande ou mot-clé à définir par la TUI ou la GUI a des propriétés
+particulières. La première propriété est d'être *requise*, *optionnelle* ou
+simplement utile, décrivant un type d'entrée. La seconde propriété est d'être
+une variable "ouverte" avec un type fixé mais avec n'importe quelle valeur
+autorisée par le type, ou une variable "fermée", limitée à des valeurs
+spécifiées. L'éditeur graphique GUI intégré disposant de capacités intrinsèques
+de validation, les propriétés des commandes ou mots-clés données à l'aide de
+l'interface graphique sont automatiquement correctes.
.. _section_reference_entry:
**[DocR]** Cas d'assimilation de données ou d'optimisation
============================================================================================
-Cette section décrit les algorithmes d'assimilation de données ou d'optimisation
-disponibles dans ADAO, détaillant leurs caractéristiques d'utilisation et leurs
-options.
+Cette section décrit les algorithmes d'assimilation de données ou
+d'optimisation disponibles dans ADAO, détaillant leurs caractéristiques
+d'utilisation et leurs options.
Des exemples sur l'usage de ces commandes sont disponibles dans la section
-:ref:`section_examples` et dans les fichiers d'exemple installés avec le module
-ADAO. Les notations mathématiques utilisées sont expliquées dans la section
-:ref:`section_theory`.
+:ref:`section_tutorials_in_salome`, dans la section
+:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés
+avec ADAO. Les notations mathématiques utilisées sont expliquées dans la
+section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
- ref_assimilation_keywords
ref_algorithm_3DVAR
ref_algorithm_4DVAR
ref_algorithm_Blue
ref_algorithm_NonLinearLeastSquares
ref_algorithm_ParticleSwarmOptimization
ref_algorithm_QuantileRegression
+ ref_algorithm_TabuSearch
ref_algorithm_UnscentedKalmanFilter
+ ref_assimilation_keywords
.. _section_reference_checking:
détaillant leurs caractéristiques d'utilisation et leurs options.
Des exemples sur l'usage de ces commandes sont disponibles dans la section
-:ref:`section_examples` et dans les fichiers d'exemple installés avec le module
-ADAO. Les notations mathématiques utilisées sont expliquées dans la section
-:ref:`section_theory`.
+:ref:`section_tutorials_in_salome`, dans la section
+:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés
+avec ADAO. Les notations mathématiques utilisées sont expliquées dans la
+section :ref:`section_theory`.
.. toctree::
:maxdepth: 1
- ref_checking_keywords
ref_algorithm_AdjointTest
ref_algorithm_FunctionTest
ref_algorithm_GradientTest
ref_algorithm_LinearityTest
+ ref_algorithm_LocalSensitivityTest
ref_algorithm_ObserverTest
ref_algorithm_SamplingTest
ref_algorithm_TangentTest
+ ref_checking_keywords
--- /dev/null
+.. index:: single: Alpha
+.. index:: single: Beta
+.. index:: single: Kappa
+.. index:: single: Reconditioner
+
+Alpha, Beta, Kappa, Reconditioner
+ Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert
+ une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour
+ une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière,
+ dont la bonne valeur par défaut est obtenue en la mettant à 0.
+ "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut
+ étant 1.
+
+ Exemple :
+ ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}``
CrossOverProbability_CR
Cette clé permet de définir la probabilité de recombinaison ou de croisement
lors de l'évolution différentielle. Cette variable est usuellement notée
- ``CR`` dans la littérature. La valeur par défaut est 0.7, et il est conseillé
- de la changer si nécessaire.
+ ``CR`` dans la littérature, et elle est obligatoirement comprise entre 0 et
+ 1. La valeur par défaut est 0.7, et il est conseillé de la changer si
+ nécessaire.
Exemple :
``{"CrossOverProbability_CR":0.7}``
--- /dev/null
+Les commandes optionnelles générales, disponibles en édition dans l'interface
+graphique ou textuelle, sont indiquées dans la
+:ref:`section_ref_assimilation_keywords`. De plus, les paramètres de la
+commande "*AlgorithmParameters*" permettent d'indiquer les options
+particulières, décrites ci-après, de l'algorithme. On se reportera à la
+:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
+commande.
+
+Les options de l'algorithme sont les suivantes :
--- /dev/null
+Les commandes optionnelles générales, disponibles en édition dans l'interface
+graphique ou textuelle, sont indiquées dans la
+:ref:`section_ref_checking_keywords`. De plus, les paramètres de la commande
+"*AlgorithmParameters*" permettent d'indiquer les options particulières,
+décrites ci-après, de l'algorithme. On se reportera à la
+:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
+commande.
+
+Les options de l'algorithme sont les suivantes :
--- /dev/null
+.. index:: single: JacobianMatrixAtBackground
+
+JacobianMatrixAtBackground
+ *Liste de matrices*. Chaque élément est une matrice jacobienne de dérivées
+ partielles de la sortie de l'opérateur d'observation par rapport aux
+ paramètres d'entrée, une colonne de dérivées par paramètre. Le calcul est
+ effectué à l'état initial.
+
+ Exemple:
+ ``GradH = ADD.get("JacobianMatrixAtBackground")[-1]``
--- /dev/null
+.. index:: single: JacobianMatrixAtCurrentState
+
+JacobianMatrixAtCurrentState
+ *Liste de matrices*. Chaque élément est une matrice jacobienne de dérivées
+ partielles de la sortie de l'opérateur d'observation par rapport aux
+ paramètres d'entrée, une colonne de dérivées par paramètre. Le calcul est
+ effectué à l'état courant.
+
+ Exemple:
+ ``GradH = ADD.get("JacobianMatrixAtCurrentState")[-1]``
--- /dev/null
+.. index:: single: JacobianMatrixAtOptimum
+
+JacobianMatrixAtOptimum
+ *Liste de matrices*. Chaque élément est une matrice jacobienne de dérivées
+ partielles de la sortie de l'opérateur d'observation par rapport aux
+ paramètres d'entrée, une colonne de dérivées par paramètre. Le calcul est
+ effectué à l'état optimal.
+
+ Exemple:
+ ``GradH = ADD.get("JacobianMatrixAtOptimum")[-1]``
--- /dev/null
+.. index:: single: KalmanGainAtOptimum
+
+KalmanGainAtOptimum
+ *Liste de matrices*. Chaque élément est une matrice de gain de Kalman
+ standard, évaluée à l'aide de l'opérateur d'observation linéarisé. Le calcul
+ est effectué à l'état optimal.
+
+ Exemple:
+ ``KG = ADD.get("KalmanGainAtOptimum")[-1]``
--- /dev/null
+.. index:: single: LengthOfTabuList
+
+LengthOfTabuList
+ Cette clé indique la longueur de la liste taboue, c'est-à-dire le nombre
+ maximal de perturbations antérieurement réalisées et conservées pour mémoire.
+ Le défaut est 50, et il est recommandé de l'adapter aux besoins pour des
+ problèmes réels.
+
+ Exemple :
+ ``{"LengthOfTabuList":50}``
--- /dev/null
+.. index:: single: NoiseAddingProbability
+
+NoiseAddingProbability
+ Cette clé indique la probabilité de perturbation d'une composante de l'état.
+ C'est une valeur obligatoirement comprise entre 0 et 1. La valeur par défaut
+ est 1, et il n'est pas recommandé de la changer.
+
+ Exemple :
+ ``{"NoiseAddingProbability":1.}``
--- /dev/null
+.. index:: single: NoiseDistribution
+
+NoiseDistribution
+ Cette clé indique le type de la distribution utilisée pour générer les
+ perturbations d'état. Cette distribution peut être de type "Uniform" ou
+ "Gaussian". Le défaut est une distribution de type "Uniform", et il est
+ recommandé de l'adapter aux besoins pour des problèmes réels.
+
+ Exemple :
+ ``{"NoiseDistribution":"Uniform"}``
--- /dev/null
+.. index:: single: NoiseHalfRange
+
+NoiseHalfRange
+ Cette clé indique, uniquement dans le cas d'une distribution de type
+ "Uniform" demandée par le mot-clé "*NoiseDistribution*", la demi-amplitude
+ des perturbations uniformes centrées d'état pour chaque composante de l'état.
+ Le défaut est une liste vide, cette clé doit donc obligatoirement être
+ renseignée dans le cas d'une distribution "Uniform". Une manière simple de le
+ faire est de donner une liste de la longueur de l'état recherché et de
+ demi-amplitudes identiques, comme dans l'exemple ci-dessous avec des
+ demi-amplitudes de 3%. Il est conseillé de prendre des demi-amplitudes de
+ quelques pourcents au maximum.
+
+ Exemple :
+ ``{"NoiseHalfRange":<longueur de l'état>*[0.03]}``
--- /dev/null
+.. index:: single: NumberOfElementaryPerturbations
+
+NumberOfElementaryPerturbations
+ Cette clé indique le nombre de perturbations élémentaires qui seront
+ réalisées pour choisir une perturbation complète d'état. Le défaut est de 1,
+ et il est recommandé de l'adapter avec prudence aux besoins pour des
+ problèmes réels, sans choisir un trop grand nombre de perturbations
+ élémentaires.
+
+ Exemple :
+ ``{"NumberOfElementaryPerturbations":1}``
--- /dev/null
+.. index:: single: OutputVariables
+
+OutputVariables
+ *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
+ variables physiques qui sont rassemblées dans le vecteur d'observation. Cette
+ information est destinée à être utilisée dans le traitement algorithmique
+ interne des données.
--- /dev/null
+.. index:: single: SampleAsExplicitHyperCube
+
+SampleAsExplicitHyperCube
+ Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on
+ donne la liste des échantillonnages explicites de chaque variable comme une
+ liste. C'est donc une liste de listes, chacune étant de taille
+ potentiellement différente.
+
+ Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2
--- /dev/null
+.. index:: single: SampleAsIndependantRandomVariables
+
+SampleAsIndependantRandomVariables
+ Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont les
+ points sur chaque axe proviennent de l'échantillonnage aléatoire indépendant
+ de la variable d'axe, selon la spécification de la distribution, de ses
+ paramètres et du nombre de points de l'échantillon, sous la forme d'une liste
+ ``['distribution', [parametres], nombre]`` pour chaque axe. Les distributions
+ possibles sont 'normal' de paramètres (mean,std), 'lognormal' de paramètres
+ (mean,sigma), 'uniform' de paramètres (low,high), ou 'weibull' de paramètre
+ (shape). C'est donc une liste de la même taille que celle de l'état.
+
+ Exemple :
+ ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2
--- /dev/null
+.. index:: single: SampleAsMinMaxStepHyperCube
+
+SampleAsMinMaxStepHyperCube
+ Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on
+ donne la liste des échantillonnages implicites de chaque variable par un
+ triplet *[min,max,step]*. C'est donc une liste de la même taille que celle
+ de l'état. Les bornes sont incluses.
+
+ Exemple :
+ ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2
--- /dev/null
+.. index:: single: SampleAsnUplet
+
+SampleAsnUplet
+ Cette clé décrit les points de calcul sous la forme d'une liste de n-uplets,
+ chaque n-uplet étant un état.
+
+ Exemple :
+ ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4
--- /dev/null
+.. index:: single: StandardDeviation
+
+StandardDeviation
+ Cette clé indique, uniquement dans le cas d'une distribution de type
+ "Gaussian" demandée par le mot-clé "*NoiseDistribution*", l'écart-type des
+ perturbations gaussiennes d'état pour chaque composante de l'état. Le défaut
+ est une liste vide, cette clé doit donc obligatoirement être renseignée dans
+ le cas d'une distribution "Gaussian". Une manière simple de le faire est de
+ donner une liste de la longueur de l'état recherché avec des écart-types
+ identiques, comme dans l'exemple ci-dessous avec des demi-amplitudes de 5%.
+ Il est conseillé de prendre des écart-types de quelques pourcents au maximum.
+
+ Exemple :
+ ``{"StandardDeviation":<longueur de l'état>*[0.05]}``
--- /dev/null
+..
+ Copyright (C) 2008-2019 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_tutorials_in_python:
+
+================================================================================
+**[DocU]** Tutoriaux sur l'utilisation du module ADAO dans Python
+================================================================================
+
+Cette section présente quelques exemples d'utilisation du module ADAO en Python
+SALOME. Le premier montre comment construire un cas simple d'assimilation de
+données définissant explicitement toutes les données d'entrée requises à
+travers l'interface utilisateur textuelle (TUI). Le second montre, sur le même
+cas, comment définir les données d'entrée à partir de sources externes à
+travers des scripts.
+
+Les notations mathématiques utilisées ci-dessous sont expliquées dans la
+section :ref:`section_theory`.
+
+Construire un cas d'estimation avec une définition explicite des données
+------------------------------------------------------------------------
--- /dev/null
+..
+ Copyright (C) 2008-2019 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_tutorials_in_salome:
+
+================================================================================
+**[DocU]** Tutoriaux sur l'utilisation du module ADAO dans SALOME
+================================================================================
+
+.. |eficas_new| image:: images/eficas_new.png
+ :align: middle
+ :scale: 50%
+.. |eficas_save| image:: images/eficas_save.png
+ :align: middle
+ :scale: 50%
+.. |eficas_saveas| image:: images/eficas_saveas.png
+ :align: middle
+ :scale: 50%
+.. |eficas_yacs| image:: images/eficas_yacs.png
+ :align: middle
+ :scale: 50%
+
+Cette section présente quelques exemples d'utilisation du module ADAO dans
+SALOME. Le premier montre comment construire un cas simple d'assimilation de
+données définissant explicitement toutes les données d'entrée requises à
+travers l'interface utilisateur graphique EFICAS (GUI). Le second montre, sur
+le même cas, comment définir les données d'entrée à partir de sources externes
+à travers des scripts. On présente ici toujours des scripts Python car ils sont
+directement insérables dans les noeuds de script de YACS, mais les fichiers
+externes peuvent utiliser d'autres langages.
+
+Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
+:ref:`section_theory`.
+
+Construire un cas d'estimation avec une définition explicite des données
+------------------------------------------------------------------------
+
+Cet exemple simple est un cas de démonstration, et il décrit comment mettre au
+point un environnement d'estimation par BLUE de manière à obtenir un *état
+estimé par méthode de moindres carrés pondérés* d'un système à partir d'une
+observation de l'état et d'une connaissance *a priori* (ou ébauche) de cet état.
+En d'autres termes, on cherche l'intermédiaire pondéré entre les vecteurs
+d'observation et d'ébauche. Toutes les valeurs numériques de cet exemple sont
+arbitraires.
+
+Conditions d'expérience
++++++++++++++++++++++++
+
+On choisit d'opérer dans un espace à 3 dimensions. La 3D est choisie de manière
+à restreindre la taille des objets numériques à entrer explicitement par
+l'utilisateur, mais le problème n'est pas dépendant de la dimension et peut être
+posé en dimension 10, 100, 1000... L'observation :math:`\mathbf{y}^o` vaut 1
+dans chaque direction, donc::
+
+ Yo = [1 1 1]
+
+L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
+priori* ou une régularisation mathématique, vaut 0 dans chaque direction, ce qui
+donne donc::
+
+ Xb = [0 0 0]
+
+La mise en oeuvre de l'assimilation de données requiert des informations sur les
+covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`, respectivement
+pour les variables d'observation et d'ébauche. On choisit ici des erreurs
+décorrélées (c'est-à-dire des matrices diagonales) et d'avoir la même variance
+de 1 pour toutes les variables (c'est-à-dire des matrices identité). On pose
+donc::
+
+ B = R = [1 0 0 ; 0 1 0 ; 0 0 1]
+
+Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
+convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
+dimensions d'espace sont les mêmes, on peut choisir l'identité comme opérateur
+d'observation::
+
+ H = [1 0 0 ; 0 1 0 ; 0 0 1]
+
+Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
+vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
+*analysis*, noté :math:`\mathbf{x}^a`, et valant::
+
+
+ Xa = [0.5 0.5 0.5]
+
+Pour étendre cet exemple, on peut modifier les variances représentées par
+:math:`\mathbf{B}` ou :math:`\mathbf{R}` indépendamment, et l'analyse
+:math:`\mathbf{x}^a` se déplacera vers :math:`\mathbf{y}^o` ou vers
+:math:`\mathbf{x}^b`, en proportion inverse des variances dans
+:math:`\mathbf{B}` et :math:`\mathbf{R}`. Comme autre extension, on peut aussi
+dire qu'il est équivalent de rechercher l'analyse à l'aide d'un algorithme de
+BLUE ou d'un algorithme de 3DVAR.
+
+Utiliser l'interface graphique (GUI) pour construire le cas ADAO
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+En premier lieu, il faut activer le module ADAO en choisissant le bouton ou le
+menu approprié de module de SALOME, et on voit :
+
+ .. _adao_activate2:
+ .. image:: images/adao_activate.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Activation du module ADAO dans SALOME**
+
+Choisir le bouton "*Nouveau*" dans cette fenêtre. On obtient directement
+l'interface de l'éditeur intégré de cas pour la définition de variables, en même
+temps que l'"*Arbre d'étude*" de SALOME. On peut alors choisir le bouton
+"*Nouveau*" |eficas_new| pour créer un nouveau cas ADAO, et on voit :
+
+ .. _adao_viewer:
+ .. image:: images/adao_viewer.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **L'éditeur intégré pour la définition de cas dans le module ADAO**
+
+Ensuite, il faut remplir les variables pour construire le cas ADAO en utilisant
+les conditions d'expérience décrites ci-dessus. L'ensemble des informations
+techniques données au-dessus sont à insérer directement dans la définition du
+cas ADAO, en utilisant le type *String* pour toutes les variables. Lorsque la
+définition du cas est prête, il faut l'enregistrer comme un fichier natif de ype
+"*JDC (\*.comm)*" à un endroit quelconque dans l'arborescence de l'utilisateur.
+Il faut bien se rappeler que d'autres fichiers seront aussi créés à côté de ce
+premier, donc il est judicieux de faire un répertoire spécifique pour ce cas, et
+d'enregistrer dedans le fichier. Le nom du fichier apparaît dans la fenêtre de
+l'"*Arbre d'étude*", sous le menu "*ADAO*". La définition finale du cas
+ressemble à :
+
+ .. _adao_jdcexample01:
+ .. image:: images/adao_jdcexample01.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Définition des conditions d'expérience choisies pour le cas ADAO**
+
+Pour poursuivre, on a besoin de générer le schéma YACS à partir de la définition
+du cas ADAO. Pour faire cela, on peut activer le menu contextuel par click droit
+sur le nom du cas dans la fenêtre de l'"*Arbre d'étude*", et choisir le
+sous-menu "*Exporter vers YACS*" (ou le bouton "*Exporter vers YACS*"
+|eficas_yacs|) comme ci-dessous :
+
+ .. _adao_exporttoyacs00:
+ .. image:: images/adao_exporttoyacs.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **Sous-menu contextuel "*Exporter vers YACS*" pour générer le schéma YACS à partir du cas ADAO**
+
+Cette commande conduit à la génération d'un schéma YACS, à l'activation du module
+YACS dans SALOME, et à ouvrir le nouveau schéma dans l'interface graphique du
+module YACS [#]_. Après avoir éventuellement réorganisé les noeuds en utilisant
+le sous-menu contextuel "*arranger les noeuds locaux*" de la vue graphique du
+schéma YACS, on obtient la représentation suivante du schéma ADAO généré :
+
+ .. _yacs_generatedscheme:
+ .. image:: images/yacs_generatedscheme.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Schéma YACS généré à partir du cas ADAO**
+
+Après ce point, toutes les modifications, exécutions et post-processing du
+schéma d'assimilation de données seront effectués dans le module YACS. De
+manière à vérifier les résultats d'une manière simple, on utilise le noeud
+"*UserPostAnalysis*" (ou on crée ici un nouveau noeud YACS par le sous-menu
+"*Noeud de script in-line*" dans la vue graphique de YACS).
+
+Ce noeud de script va récupérer l'analyse issue de l'assimilation de données
+depuis le port de sortie "*algoResults*" du bloc de calcul (qui donne accés à un
+objet Python SALOME), et va l'afficher à la sortie standard.
+
+Pour obtenir ceci, ce noeud de script doit comporter un port d'entrée de type
+"*pyobj*", nommé "*Study*" par exemple, qui doit être relié graphiquement au
+port de sortie "*algoResults*" du bloc de calcul. Ensuite, le code pour remplir
+le noeud de script est::
+
+ Xa = Study.getResults().get("Analysis")[-1]
+
+ print()
+ print("Analysis =",Xa)
+ print()
+
+Le schéma YACS (initial ou complété) peut être enregistré (en écrasant le schéma
+généré si la commande ou le bouton "*Enregistrer*" sont utilisés, ou sinon avec
+un nom nouveau par la commande "*Enregistrer sous*"). De manière pratique, la
+mise au point d'une telle procédure de post-processing peut être réalisée dans
+YACS pour la tester, et ensuite entièrement enregistrée dans un script Python
+qui peut être intégré au cas ADAO en utilisant le mot-clé "*UserPostAnalysis*".
+
+Ensuite, de manière classique dans YACS, le schéma doit être compilé, et ensuite
+être exécuté. Après la fin de l'exécution, les affichages sur la sortie standard
+sont disponibles dans la fenêtre "*fenêtre de sortie de YACS*" (ou "*YACS
+Container Log*"), obtenue par clic droit à l'aide du menu contextuel de la
+fenêtre "*proc*" du schéma YACS comme montré ci-dessous:
+
+ .. _yacs_containerlog:
+ .. image:: images/yacs_containerlog.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Menu YACS de la fenêtre de sortie, et boite de dialogue montrant la sortie**
+
+On vérifie que le résultat est correct en observant si la fenêtre de sortie
+contient la ligne suivante::
+
+ Analysis = [0.5, 0.5, 0.5]
+
+comme montré dans l'image précédente.
+
+Pour étendre cet exemple, on peut remarquer que le même problème résolu par un
+algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi lors
+de l'étape de construction du cas ADAO, avant d'entrer dans l'étape YACS. Le cas
+ADAO en 3DVAR est entièrement similaire au cas algorithmique du BLUE, comme
+montré dans la figure suivante:
+
+ .. _adao_jdcexample02:
+ .. image:: images/adao_jdcexample02.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Définir un cas ADAO en 3DVAR est entièrement similaire à un cas en BLUE**
+
+Il n'y a qu'une seule commande qui change, avec "*3DVAR*" dans le champ
+"*Algorithm*" à la place de "*Blue*".
+
+Construire un cas d'estimation avec une définition de données externes par scripts
+----------------------------------------------------------------------------------
+
+Il est utile d'acquérir une partie ou la totalité des données depuis une
+définition externe, en utilisant des scripts Python pour donner accès à ces
+données. À titre d'exemple, on construit ici un cas ADAO présentant le même
+dispositif expérimental que dans l'exemple ci-dessus `Construire un cas
+d'estimation avec une définition explicite des données`_, mais en utilisant des
+données issues d'un unique fichier script Python externe.
+
+En premier lieu, on écrit le fichier script suivant, utilisant des noms
+conventionnels pour les variables requises. Ici toutes les variables sont
+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 graphique ADAO et une définition implicite dans des fichiers
+externes. Le fichier script actuel ressemble à::
+
+ import numpy
+ #
+ # Definition of the Background as a vector
+ # ----------------------------------------
+ Background = [0, 0, 0]
+ #
+ # Definition of the Observation as a vector
+ # -----------------------------------------
+ Observation = "1 1 1"
+ #
+ # Definition of the Background Error covariance as a matrix
+ # ---------------------------------------------------------
+ BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
+ #
+ # Definition of the Observation Error covariance as a matrix
+ # ----------------------------------------------------------
+ ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
+ #
+ # Definition of the Observation Operator as a matrix
+ # --------------------------------------------------
+ ObservationOperator = numpy.identity(3)
+
+Les noms des variables Python sont obligatoires, de manière à définir les bonnes
+variables dans le cas, mais le script Python peut être plus conséquent et
+définir des classes, des fonctions, des accès à des fichiers ou des bases de
+données, etc. avec des noms différents. De plus, le fichier ci-dessus présente
+différentes manières de définir des vecteurs ou des matrices, utilisant des
+listes, des chaînes de caractères (comme dans Numpy ou Octave), des types
+vecteur ou matrice de Numpy, et des fonctions spéciales de Numpy. Toutes ces
+syntaxes sont valides.
+
+Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
+l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
+utilise l'interface graphique (GUI) pour construire le cas ADAO. La procédure
+pour compléter le cas est similaire à celle de l'exemple précédent à part le
+fait que, au lieu de choisir l'option "*String*" pour le mot-clé "*FROM*" de
+chaque variable, on choisit l'option "*Script*". Cela conduit à une entrée
+"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique, permettant de choisir un
+fichier de la manière suivante:
+
+ .. _adao_scriptentry01:
+ .. image:: images/adao_scriptentry01.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Définir une variable d'entrée en utilisant un fichier script externe**
+
+Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
+précédent `Construire un cas d'estimation avec une définition explicite des
+données`_.
+
+Dans la pratique, cette démarche par scripts est la manière la plus facile pour
+récupérer des information depuis des calculs en ligne ou préalables, depuis des
+fichiers statiques, depuis des bases de données ou des flux informatiques,
+chacun pouvant être dans ou hors SALOME. Cela permet aussi de modifier aisément
+des données d'entrée, par exemple à des fin de débogage ou pour des traitements
+répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
+d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
+"sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
+peuvent être directement introduites dans l'exécution du schéma YACS.
+L'utilisateur doit vérifier avec attention le contenu de ses scripts.**
+
+Ajout de paramètres pour contrôler l'algorithme d'assimilation de données
+-------------------------------------------------------------------------
+
+On peut ajouter des paramètres optionnels pour contrôler le calcul de
+l'algorithme d'assimilation de données. Ceci se fait en utilisant les paramètres
+optionnels dans la commande "*AlgorithmParameters*" de la définition du cas
+ADAO, qui est un mot-clé de la commande générale "*ASSIMILATION_STUDY*". Ce
+mot-clé nécessite une définition explicite des valeurs à partir de valeurs par
+défaut, ou à partir d'un dictionnaire Python, contenant des paires clé/valeur.
+La liste des paramètres optionnels possibles sont donnés dans la section
+:ref:`section_reference` et ses sous-sections. On recommande d'utiliser la
+définition explicite de valeurs à partir de la liste par défaut de paramètres
+optionnels, comme ici avec le "*MaximumNumberOfSteps*":
+
+ .. _adao_scriptentry02:
+ .. image:: images/adao_scriptentry02.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Ajouter des paramètres pour contrôler l'algorithme et les sorties**
+
+Le dictionnaire peut être défini, par exemple, dans un fichiers externe de
+script Python, en utilisant le nom obligatoire de variable
+"*AlgorithmParameters*" pour le dictionnaire. Toutes les clés dans le
+dictionnaire sont optionnelles, elles disposent toutes d'une valeur par défaut,
+et elles peuvent être présentes sans être utiles. Par exemple::
+
+ AlgorithmParameters = {
+ "Minimizer" : "LBFGSB", # Recommended
+ "MaximumNumberOfSteps" : 10,
+ }
+
+Si aucune borne n'est requise sur les variables de contrôle, alors on peut
+choisir les algorithmes de minimisation "*BFGS*" ou "*CG*" pour tous les
+algorithmes variationnels d'assimilation de données ou d'optimisation. Pour
+l'optimisation sous contraintes, l'algorithme "*LBFGSB*" est bien souvent plus
+robuste, mais le "*TNC*" est parfois plus performant. De manière générale, le
+choix de l'algorithme "*LBFGSB*" est recommandé. Ensuite le script peut être
+ajouté au cas ADAO, dans une entrée de type fichier associé au format "*Dict*"
+dans le mot-clé "*Parameters*".
+
+Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
+précédent `Construire un cas d'estimation avec une définition explicite des
+données`_. Le dictionnaire peut aussi être donné directement dans le champ
+d'entrée de type chaîne de caractères pour le mot-clé.
+
+Construire un cas complexe avec une définition de données externes par scripts
+------------------------------------------------------------------------------
+
+Cet exemple plus complexe et complet peut être considéré comme un cadre de base
+pour le traitement des entrées de l'utilisateur, qui doit ensuite être adapté à
+chaque application réelle. Néanmoins, les squelettes de fichiers sont
+suffisamment généraux pour avoir été utilisés pour des applications variées en
+neutronique, mécanique des fluides... Ici, on ne s'intéresse pas aux résultats,
+mais plus sur le contrôle de l'utilisateur des entrées et sorties dans un cas
+ADAO. Comme précédemment, toutes les valeurs numériques de cet exemple sont
+arbitraires.
+
+L'objectif est de configurer les entrées et les sortie d'un problème physique
+d'estimation par des scripts externes Python, en utilisant un opérateur
+non-linéaire général, en ajoutant un contrôle sur les paramètres et ainsi de
+suite... Les scripts complets peuvent être trouvés dans le répertoire des
+exemples de squelettes ADAO sous le nom de
+"*External_data_definition_by_scripts*".
+
+Conditions d'expérience
++++++++++++++++++++++++
+
+On continue à opérer dans un espace à 3 dimensions, afin de limiter la taille de
+l'objet numérique indiqué dans les scripts, mais le problème ne dépend pas de la
+dimension.
+
+On choisit un contexte d'expériences jumelles, en utilisant un état vrai
+:math:`\mathbf{x}^t` connu, mais de valeur arbitraire::
+
+ Xt = [1 2 3]
+
+L'état d'ébauche :math:`\mathbf{x}^b`, qui représentent une connaissance *a
+priori* de l'état vrai, est construit comme une perturbation aléatoire
+gaussienne de 20% de l'état vrai :math:`\mathbf{x}^t` pour chaque composante,
+qui est::
+
+ Xb = Xt + normal(0, 20%*Xt)
+
+Pour décrire la matrice des covariances d'erreur d'ébauche math:`\mathbf{B}`, on
+fait comme précédemment l'hypothèse d'erreurs décorrélées (c'est-à-dire, une
+matrice diagonale, de taille 3x3 parce-que :math:`\mathbf{x}^b` est de taille 3)
+et d'avoir la même variance de 0,1 pour toutes les variables. On obtient::
+
+ B = 0.1 * diagonal( length(Xb) )
+
+On suppose qu'il existe un opérateur d'observation :math:`\mathbf{H}`, qui peut
+être non linéaire. Dans une procédure réelle de recalage ou de problème inverse,
+les codes de simulation physique sont intégrés dans l'opérateur d'observation.
+On a également besoin de connaître son gradient par rapport à chaque variable
+estimée, ce qui est une information rarement connu avec les codes industriels.
+Mais on verra plus tard comment obtenir un gradient approché dans ce cas.
+
+Étant en expériences jumelles, les observations :math:`\mathbf{y}^o` et leur
+matrice de covariances d'erreurs :math:`\mathbf{R}` sont générées en utilisant
+l'état vrai :math:`\mathbf{x}^t` et l'opérateur d'observation
+:math:`\mathbf{H}`::
+
+ Yo = H( Xt )
+
+et, avec un écart-type arbitraire de 1% sur chaque composante de l'erreur::
+
+ R = 0.0001 * diagonal( length(Yo) )
+
+Toutes les informations requises pour l'estimation par assimilation de données
+sont maintenant définies.
+
+Squelettes des scripts décrivant les conditions d'expérience
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+On donne ici les éléments essentiels de chaque script utilisé par la suite pour
+construire le cas ADAO. On rappelle que l'utilisation de ces scripts dans de
+réels fichiers Python nécessite de définir correctement le chemin de modules ou
+des codes importés (même si le module est dans le même répertoire que le fichier
+Python qui l'importe. On indique le chemin à renseigner en utilisant la mention
+``"# INSERT PHYSICAL SCRIPT PATH"``), l'encodage si nécessaire, etc. Les noms de
+fichiers indiqués pour les scripts qui suivent sont arbitraires. Des exemples
+complets de fichiers scripts sont disponibles dans le répertoire standard des
+exemples ADAO.
+
+On définit en premier lieu l'état vrai :math:`\mathbf{x}^t` et une fonction
+utiles à la construction de matrices, dans un fichier script Python nommé
+``Physical_data_and_covariance_matrices.py``::
+
+ import numpy
+ #
+ def True_state():
+ """
+ Arbitrary values and names, as a tuple of two series of same length
+ """
+ return (numpy.array([1, 2, 3]), ['Para1', 'Para2', 'Para3'])
+ #
+ def Simple_Matrix( size, diagonal=None ):
+ """
+ Diagonal matrix, with either 1 or a given vector on the diagonal
+ """
+ if diagonal is not None:
+ S = numpy.diag( diagonal )
+ else:
+ S = numpy.matrix(numpy.identity(int(size)))
+ return S
+
+On définit ensuite l'état d'ébauche :math:`\mathbf{x}^b` comme une perturbation
+aléatoire de l'état vrai, en ajoutant une *variable ADAO requise* à la fin du
+script de définition, de manière à exporter la valeur définie. C'est réalisé
+dans un fichier de script Python nommé ``Script_Background_xb.py``::
+
+ from Physical_data_and_covariance_matrices import True_state
+ import numpy
+ #
+ xt, names = True_state()
+ #
+ Standard_deviation = 0.2*xt # 20% for each variable
+ #
+ xb = xt + abs(numpy.random.normal(0.,Standard_deviation,size=(len(xt),)))
+ #
+ # Creating the required ADAO variable
+ # ------------------------------------
+ Background = list(xb)
+
+De la même manière, on définit la matrice des covariances de l'erreur d'ébauche
+:math:`\mathbf{B}` comme une matrice diagonale, de la même longueur de diagonale
+que l'ébauche de la valeur vraie, en utilisant la fonction d'aide déjà définie.
+C'est réalisé dans un fichier script Python nommé
+``Script_BackgroundError_B.py``::
+
+ from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
+ #
+ xt, names = True_state()
+ #
+ B = 0.1 * Simple_Matrix( size = len(xt) )
+ #
+ # Creating the required ADAO variable
+ # -----------------------------------
+ BackgroundError = B
+
+Pour poursuivre, on a besoin de l'opérateur d'observation :math:`\mathbf{H}`
+comme une fonction de l'état. Il est ici défini dans un fichier externe nommé
+``"Physical_simulation_functions.py"``, qui doit contenir une fonction appelée
+``"DirectOperator"``. Cette fonction est une une fonction utilisateur,
+représentant de manière programmée l'opérateur :math:`\mathbf{H}`. On suppose
+que cette fonction est donnée par l'utilisateur. Un squelette simple est donné
+ici par facilité::
+
+ def DirectOperator( XX ):
+ """ Direct non-linear simulation operator """
+ #
+ # --------------------------------------> EXAMPLE TO BE REMOVED
+ if type(XX) is type(numpy.matrix([])): # EXAMPLE TO BE REMOVED
+ HX = XX.A1.tolist() # EXAMPLE TO BE REMOVED
+ elif type(XX) is type(numpy.array([])): # EXAMPLE TO BE REMOVED
+ HX = numpy.matrix(XX).A1.tolist() # EXAMPLE TO BE REMOVED
+ else: # EXAMPLE TO BE REMOVED
+ HX = XX # EXAMPLE TO BE REMOVED
+ # --------------------------------------> EXAMPLE TO BE REMOVED
+ #
+ return numpy.array( HX )
+
+On n'a pas besoin des opérateurs linéaires associés ``"TangentOperator"`` et
+``"AdjointOperator"`` car ils vont être approximés en utilisant les capacités
+d'ADAO.
+
+On insiste sur le fait que ces opérateurs non-linéaire ``"DirectOperator"``,
+linéaire tangent ``"TangentOperator"`` et linéaire adjoint ``"AdjointOperator"``
+proviennent de la connaissance de la physique, incluant le code de simulation de
+référence physique, et doivent être soigneusement mis au point par l'utilisateur
+de l'assimilation de données ou de l'optimisation. Les erreurs de simulation ou
+d'usage des opérateurs ne peuvent pas être détectés ou corrigés par
+l'environnement seul ADAO d'assimilation de données et d'optimisation.
+
+Dans cet environnement d'expériences jumelles, l'observation
+:math:`\mathbf{y}^o` et sa matrice des covariances d'erreur :math:`\mathbf{R}`
+peuvent être générées. C'est réalisé dans deux fichiers de script Python, le
+premier étant nommé ``Script_Observation_yo.py``::
+
+ from Physical_data_and_covariance_matrices import True_state
+ from Physical_simulation_functions import DirectOperator
+ #
+ xt, noms = True_state()
+ #
+ yo = DirectOperator( xt )
+ #
+ # Creating the required ADAO variable
+ # -----------------------------------
+ Observation = list(yo)
+
+et le second nommé ``Script_ObservationError_R.py``::
+
+ from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
+ from Physical_simulation_functions import DirectOperator
+ #
+ xt, names = True_state()
+ #
+ yo = DirectOperator( xt )
+ #
+ R = 0.0001 * Simple_Matrix( size = len(yo) )
+ #
+ # Creating the required ADAO variable
+ # -----------------------------------
+ ObservationError = R
+
+Comme dans les exemples précédents, il peut être utile de définir certains
+paramètres pour l'algorithme d'assimilation de données. Par exemple, si on
+utilise l'algorithme standard de "*3DVAR*", les paramètres suivants peuvent être
+définis dans un fichier de script Python nommé
+``Script_AlgorithmParameters.py``::
+
+ # Creating the required ADAO variable
+ # -----------------------------------
+ AlgorithmParameters = {
+ "Minimizer" : "LBFGSB", # Recommended
+ "MaximumNumberOfSteps" : 15, # Number of global iterative steps
+ "Bounds" : [
+ [ None, None ], # Bound on the first parameter
+ [ 0., 4. ], # Bound on the second parameter
+ [ 0., None ], # Bound on the third parameter
+ ],
+ }
+
+Enfin, il est courant de post-traiter les résultats, en les récupérant aprés la
+phase d'assimilation de données de manière à les analyser, les afficher ou les
+représenter. Cela nécessite d'utiliser un fichier script Python intermédiaire de
+manière à extraire ces résultats à la fin de la procédure d'assimilation de
+données ou d'optimisation. L'exemple suivant de fichier script Python, nommé
+``Script_UserPostAnalysis.py``, illustre le fait::
+
+ from Physical_data_and_covariance_matrices import True_state
+ import numpy
+ #
+ xt, names = True_state()
+ xa = ADD.get("Analysis")[-1]
+ x_series = ADD.get("CurrentState")[:]
+ J = ADD.get("CostFunctionJ")[:]
+ #
+ # Verifying the results by printing
+ # ---------------------------------
+ print()
+ print("xt = %s"%xt)
+ print("xa = %s"%numpy.array(xa))
+ print()
+ for i in range( len(x_series) ):
+ print("Etape %2i : J = %.5e et X = %s"%(i, J[i], x_series[i]))
+ print()
+
+Finalement, on obtient la description de l'ensemble des conditions
+d'expériences à travers la série de fichiers listée ici:
+
+#. ``Physical_data_and_covariance_matrices.py``
+#. ``Physical_simulation_functions.py``
+#. ``Script_AlgorithmParameters.py``
+#. ``Script_BackgroundError_B.py``
+#. ``Script_Background_xb.py``
+#. ``Script_ObservationError_R.py``
+#. ``Script_Observation_yo.py``
+#. ``Script_UserPostAnalysis.py``
+
+On insiste ici sur le fait que tous ces scripts sont écrits par l'utilisateur et
+ne peuvent être testés automatiquement par ADAO. Ainsi, l'utilisateur est tenu
+de vérifier les scripts (et en particulier leurs entrées/sorties) afin de
+limiter les difficultés de débogage. On rappelle que: **la méthodologie par
+scripts n'est pas une procédure "sûre", en ce sens que des données erronées ou
+des erreurs dans les calculs, peuvent être directement introduites dans
+l'exécution du schéma YACS.**
+
+Construire la cas avec une définition de données externes par scripts
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Tous ces scripts peuvent ensuite être utilisés pour définir le cas ADAO avec une
+définition de données externes par des fichiers de script Python. Cela se
+réalise de manière tout à fait similaire à la méthode décrite dans la partie
+précédente `Construire un cas d'estimation avec une définition de données
+externes par scripts`_. Pour chaque variable à définir, on sélectionne l'option
+"*Script*" du mot-clé "*FROM*", ce qui conduit à une entrée
+"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique. Pour le mot-clé
+"*ObservationOperator*", on choisit la forme "*ScriptWithOneFunction*" et on
+conserve la valeur par défaut de l'incrément différentiel.
+
+Les autres étapes pour construire le cas ADAO sont exactement les mêmes que dans
+la partie précédente `Construire un cas d'estimation avec une définition
+explicite des données`_.
+
+En utilisant l'opérateur linéaire simple :math:`\mathbf{H}` du fichier script
+Python ``Physical_simulation_functions.py`` disponible dans le répertoire
+standard des exemples, les résultats ressemblent à::
+
+ xt = [1 2 3]
+ xa = [ 1.000014 2.000458 3.000390]
+
+ Etape 0 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
+ Etape 1 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
+ Etape 2 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
+ Etape 3 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
+ Etape 4 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
+ Etape 5 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
+ Etape 6 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
+ Etape 7 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
+ Etape 8 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
+ Etape 9 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
+ Etape 10 : J = 1.81568e+00 et X = [1.000013, 2.000458, 3.000390]
+ ...
+
+L'état au premier pas est l'état d'ébauche :math:`\mathbf{x}^b` généré
+aléatoirement. Au cours du calcul, ces affichages sur la sortie standard sont
+disponibles dans la fenêtre "*fenêtre de sortie de YACS*", que l'on obtient par
+clic droit sur la fenêtre "*proc*" du schéma YACS exécuté.
+
+.. [#] 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.
+++ /dev/null
-..
- Copyright (C) 2008-2019 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_using:
-
-================================================================================
-**[DocU]** Utiliser le module ADAO
-================================================================================
-
-.. |eficas_new| image:: images/eficas_new.png
- :align: middle
- :scale: 50%
-.. |eficas_save| image:: images/eficas_save.png
- :align: middle
- :scale: 50%
-.. |eficas_saveas| image:: images/eficas_saveas.png
- :align: middle
- :scale: 50%
-.. |eficas_yacs| image:: images/eficas_yacs.png
- :align: middle
- :scale: 50%
-.. |yacs_compile| image:: images/yacs_compile.png
- :align: middle
- :scale: 50%
-
-Cette section présente l'usage du module ADAO dans la plateforme SALOME. On
-décrit ici le cheminement général pour établir un cas ADAO, les détails étant
-fournis dans les chapitres suivants. Il est complété par la description
-détaillée de l'ensemble des commandes et mots-clés dans la section
-:ref:`section_reference`, par des procédures avancées d'usage dans la section
-:ref:`section_advanced`, et par des exemples dans la section
-:ref:`section_examples`.
-
-Procédure logique pour construire un cas ADAO
----------------------------------------------
-
-La construction d'un cas ADAO suit une démarche simple pour définir l'ensemble
-des données d'entrée, et ensuite générer un diagramme complet d'exécution
-utilisé dans YACS [#]_. De nombreuses variations existent pour la définition
-des données d'entrée, mais la séquence logique reste inchangée.
-
-De manière générale, l'utilisateur doit connaître ses données d'entrées,
-requises pour mettre au point une étude d'assimilation de données, en suivant la
-:ref:`section_methodology`. Ces données peuvent déjà être disponibles dans
-SALOME ou non.
-
-Fondamentalement, la procédure d'utilisation de ADAO comprend les étapes
-suivantes:
-
- - :ref:`section_u_step1`
- - :ref:`section_u_step2`
- - :ref:`section_u_step3`
- - :ref:`section_u_step4`
- - :ref:`section_u_step5`
-
-Chaque étape est détaillée dans la section suivante.
-
-Procédure détaillée pour construire un cas ADAO
------------------------------------------------
-
-.. _section_u_step1:
-
-ÉTAPE 1 : Activer le module ADAO et utiliser l'interface graphique d'édition (GUI)
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Comme toujours pour un module, il doit être préalablement activé en
-sélectionnant le bouton de module approprié (ou le menu) dans la barre d'outils
-de SALOME. S'il n'existe aucune étude SALOME chargée, un menu contextuel
-apparaît, permettant de choisir entre la création d'une nouvelle étude, ou
-l'ouverture d'une étude déjà existante:
-
- .. _adao_activate1:
- .. image:: images/adao_activate.png
- :align: center
- .. centered::
- **Activation du module ADAO dans SALOME**
-
-En choisissant le bouton "*Nouveau*", un éditeur intégré de cas [#]_ sera
-ouvert, en même temps que le "*navigateur d'objets*" standard. On peut alors
-cliquer sur le bouton "*Nouveau*" (ou choisir l'entrée "*Nouveau*" dans le dans
-le menu principal "*ADAO*") pour créer un nouveau cas ADAO, et on obtient :
-
- .. _adao_viewer:
- .. image:: images/adao_viewer.png
- :align: center
- :width: 100%
- .. centered::
- **L'éditeur intégré pour la définition des cas dans le module ADAO**
-
-.. _section_u_step2:
-
-ÉTAPE 2 : Créer et modifier le cas ADAO, et l'enregistrer
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Pour construire un cas en utilisant l'éditeur intégré, on doit passer par une
-série de sous-étapes, en choisissant, à chaque étape, un mot-clé puis en
-remplissant ses valeurs. On note que c'est dans cette étape qu'il faut, entre
-autres, définir l'**appel au code de simulation** utilisé dans les opérateurs
-d'observation ou d'évolution décrivant le problème [#]_.
-
-L'éditeur structuré indique des types hiérarchiques, des valeurs ou des
-mots-clés autorisés. Les mots-clés incomplets ou incorrects sont identifiés par
-un indicateur d'erreur visuel rouge. Les valeurs possibles sont indiquées pour
-les mots-clés par la définition d'une liste limitée de valeurs, et les entrées
-adaptées sont données pour les autres mots-clés. Des messages d'aide sont
-fournis de manière contextuelle aux places réservées de l'éditeur.
-
-Un nouveau cas est mis en place avec la liste minimale des commandes. Toutes les
-commandes ou les mots-clés obligatoires sont déjà présents, aucun d'eux ne peut
-être supprimé. Des mots-clés optionnels peuvent être ajoutés en les choisissant
-dans une liste de suggestions de ceux autorisés pour la commande principale, par
-exemple la commande "*ASSIMILATION_STUDY*". À titre d'exemple, on peut ajouter
-des paramètres dans le mot-clé "*AlgorithmParameters*", comme décrit dans la
-dernière partie de la section :ref:`section_examples`.
-
-A la fin de ces actions, lorsque tous les champs ou les mots-clés ont été
-correctement définis, chaque ligne de l'arborescence des commandes doit
-présenter un drapeau vert. Cela signifie que l'ensemble du cas est valide et
-dûment rempli (et qu'il peut être sauvegardé).
-
- .. _adao_jdcexample00:
- .. image:: images/adao_jdcexample01.png
- :align: center
- :scale: 75%
- .. centered::
- **Exemple d'un cas ADAO valide**
-
-Au final, il faut enregistrer le cas ADAO en utilisant le bouton "*Enregistrer*"
-|eficas_save|, ou le bouton "*Enregistrer sous*" |eficas_saveas|, ou en
-choisissant l'entrée "*Enregistrer/ Enregistrer sous*" dans le menu "*ADAO*". Il
-est alors demandé un emplacement, à choisir dans l'arborescence des fichiers, et
-un nom, qui sera complété par l'extension "*.comm*" utilisée pour les fichiers
-de l'éditeur intégré de cas. Cette action va générer une paire de fichiers
-décrivant le cas ADAO, avec le même nom de base, le premier présentant une
-extension "*.comm*" et le second une extension "*.py*" [#]_.
-
-.. _section_u_step3:
-
-ÉTAPE 3 : Exporter le cas ADAO comme un schéma YACS
-+++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Lorsque le cas ADAO est complété, il doit être converti ou exporté sous la forme
-d'un schéma YACS pour pouvoir exécuter le calcul d'assimilation de données. Cela
-peut être réalisé facilement en utilisant le bouton "*Exporter vers YACS*"
-|eficas_yacs|, ou de manière équivalente en choisissant l'entrée "*Exporter vers
-YACS*" dans le menu principal "*ADAO*", ou dans le menu contextuel du cas dans
-le navigateur d'objets SALOME.
-
- .. _adao_exporttoyacs01:
- .. image:: images/adao_exporttoyacs.png
- :align: center
- :scale: 75%
- .. centered::
- **Sous-menu "Exporter vers YACS" pour générer le schéma YACS à partir d'un cas ADAO**
-
-Cela conduit à générer automatiquement un schéma YACS, et à activer le module
-YACS sur ce schéma. Le fichier YACS, associé au schéma, est stocké dans le même
-répertoire et avec le même nom de base de fichier que le cas ADAO enregistré,
-changeant simplement son extension en "*.xml*". Attention, *si le nom de fichier
-XML existe déjà, le fichier est écrasé sans avertissement sur le remplacement du
-fichier XML*.
-
-.. _section_u_step4:
-
-ÉTAPE 4 : Compléter et modifier le schéma YACS, et l'enregistrer
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. index:: single: Analysis
-
-Lorsque le schéma YACS est généré et ouvert dans SALOME à travers l'interface
-graphique du module YACS, on peut modifier ou compléter le schéma comme tout
-schéma YACS standard. Des noeuds ou des blocs peuvent être ajoutés, copiés ou
-modifiés pour élaborer une analyse complexe, ou pour insérer des capacités
-d'assimilation de données ou d'optimisation dans des schémas de calculs YACS
-plus complexes.
-
-Le principal complément nécessaire dans un schéma YACS est une étape de
-post-processing. L'évaluation du résultat doit être réalisée dans le contexte
-physique de simulation utilisé par la procédure d'assimilation de données. Le
-post-processing peut être fournit à travers le mot-clé "*UserPostAnalysis*"
-d'ADAO sous la forme d'un fichier de script ou d'une chaîne de caractères, par
-des patrons ("templates"), ou peut être construit comme des noeuds YACS. Ces
-deux manières de construire le post-processing peuvent utiliser toutes les
-capacités de SALOME. On se reportera à la partie traitant des
-:ref:`section_ref_output_variables`, ou à l'aide de chaque algorithme, pour la
-description complète de ces éléments.
-
-En pratique, le schéma YACS dispose d'un port de sortie "*algoResults*" dans le
-bloc de calcul, qui donne accès à un objet structuré nommé ci-après "*ADD*" par
-exemple, qui contient tous les résultats de calcul. Ces résultats peuvent être
-obtenus en récupérant les variables nommées stockées au cours des calculs.
-L'information principale est la variable "*Analysis*", qui peut être obtenue par
-une commande python (par exemple dans un noeud script intégré ("in-line script
-node") ou un script fourni à travers le mot-clé "*UserPostAnalysis*"::
-
- Analysis = ADD.get("Analysis")[:]
-
-"*Analysis*" est un objet complexe, similaire à une liste de valeurs calculées à
-chaque étape du calcul d'assimilation. Pour obtenir et afficher l'évaluation
-optimale de l'état par assimilation de données, dans un script fournit par
-l'intermédiaire du mot-clé "*UserPostAnalysis*", on peut utiliser::
-
- Xa = ADD.get("Analysis")[-1]
- print("Optimal state:", Xa)
- print()
-
-Cette variable ``Xa`` est un vecteur de valeurs, qui représente la solution du
-problème d'évaluation par assimilation de données ou par optimisation, notée
-:math:`\mathbf{x}^a` dans la section :ref:`section_theory`.
-
-Une telle méthode peut être utilisée pour imprimer les résultats, ou pour les
-convertir dans des structures qui peuvent être nécessaires à un post-processing
-natif ou externe à SALOME. Un exemple simple est disponible dans la section
-:ref:`section_examples`.
-
-.. _section_u_step5:
-
-ÉTAPE 5 : Exécuter le schéma YACS et obtenir les résultats
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Le schéma YACS est maintenant complet et peut être exécuté. La paramétrisation
-et l'exécution de ce cas YACS est entièrement compatible avec la manière
-standard de traiter un schéma YACS, comme décrit dans le *Guide de l'utilisateur
-du module YACS*.
-
-Pour rappeler la manière la plus simple de procéder, le schéma YACS doit être
-compilé en utilisant le bouton |yacs_compile|, ou l'entrée équivalente du menu
-YACS, pour préparer le schéma à son exécution. Ensuite, le schéma compilé peut
-être démarré, exécuté pas à pas ou en utilisant des points d'arrêt, etc.
-
-La sortie standard est restituée dans la "*fenêtre de sortie de YACS*" (ou
-"*YACS Container Log*"), à laquelle on accède par un clic droit sur la fenêtre
-"*proc*" dans l'interface graphique YACS. Les erreurs sont présentées soit
-dans la "*fenêtre de sortie de YACS*", ou à la ligne de commande dans la fenêtre
-de commandes (si l'environnement SALOME a été lancé par une commande explicite,
-et non par un menu ou une icône de bureau). Par exemple, la sortie de l'exemple
-simple ci-dessus est de la forme suivante::
-
- Entering in the assimilation study
- Name is set to........: Test
- Algorithm is set to...: Blue
- Launching the analysis
-
- Optimal state: [0.5, 0.5, 0.5]
-
-présentée dans la "*fenêtre de sortie de YACS*".
-
-L'exécution peut aussi être conduite en utilisant un script de commandes Shell,
-comme décrit dans la section :ref:`section_advanced`.
-
-.. [#] 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.
-
-.. [#] Pour de plus amples informations sur l'éditeur intégré de cas, voir le *module EFICAS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
-
-.. [#] L'utilisation du code de simulation physique dans les opérateurs de base de l'assimilation de données est illustrée ou décrite dans les parties principales qui suivent.
-
-.. [#] Ce fichier python intermédiaire peut aussi être utilisé comme décrit dans la section :ref:`section_advanced`.
default = [],
typecast = tuple,
message = "Liste de calculs supplémentaires à stocker et/ou effectuer",
- listval = ["BMA", "OMA", "OMB", "CurrentState", "CostFunctionJ", "CostFunctionJb", "CostFunctionJo", "Innovation", "SimulatedObservationAtBackground", "SimulatedObservationAtCurrentState", "SimulatedObservationAtOptimum"]
+ listval = [
+ "BMA",
+ "OMA",
+ "OMB",
+ "CurrentState",
+ "CostFunctionJ",
+ "CostFunctionJb",
+ "CostFunctionJo",
+ "Innovation",
+ "SimulatedObservationAtBackground",
+ "SimulatedObservationAtCurrentState",
+ "SimulatedObservationAtOptimum",
+ ]
)
self.defineRequiredParameter( # Pas de type
name = "Bounds",
self.__P.update( dict(__Dict) )
#
if __Algo is not None:
- self.__P.update( {"Algorithm":self.__A} )
+ self.__P.update( {"Algorithm":__Algo} )
def get(self, key = None):
"Vérifie l'existence d'une clé de variable ou de paramètres"
