doc/fr/tutorials_in_python.rst

   1 ..
   2    Copyright (C) 2008-2021 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. _section_tutorials_in_python:
  25
  26 ================================================================================
  27 **[DocU]** Tutoriaux sur l'utilisation du module ADAO dans Python
  28 ================================================================================
  29
  30 Cette section présente quelques exemples d'utilisation du module ADAO en
  31 Python. Le premier montre comment construire un cas simple d'assimilation de
  32 données définissant explicitement toutes les données d'entrée requises à
  33 travers l'interface utilisateur textuelle (TUI) décrite en partie
  34 :ref:`section_tui`. Le second montre, sur le même cas, comment définir les
  35 données d'entrée à partir de sources externes à travers des scripts. On
  36 présente ici toujours des scripts Python car ils sont directement insérables
  37 dans les définitions de script de l'interface Python, mais les fichiers
  38 externes peuvent utiliser d'autres langages.
  39
  40 Ces exemples sont intentionnellement décrits de manière semblables aux
  41 :ref:`section_tutorials_in_salome` car ils sont similaires à ceux que l'on peut
  42 traiter dans l'interface graphique SALOME. Les notations mathématiques
  43 utilisées ci-dessous sont expliquées dans la section :ref:`section_theory`.
  44
  45 .. _section_tutorials_in_python_explicit:
  46
  47 Construire un cas d'estimation avec une définition explicite des données
  48 ------------------------------------------------------------------------
  49
  50 Cet exemple très simple est un cas de démonstration, et il décrit comment
  51 mettre au point un environnement d'estimation par BLUE de manière à obtenir un
  52 *état estimé par méthode de moindres carrés pondérés* d'un système à partir
  53 d'une observation de l'état et d'une connaissance *a priori* (ou ébauche) de
  54 cet état. En d'autres termes, on cherche l'intermédiaire pondéré entre les
  55 vecteurs d'observation et d'ébauche. Toutes les valeurs numériques de cet
  56 exemple sont arbitraires.
  57
  58 Conditions d'expérience
  59 +++++++++++++++++++++++
  60
  61 On choisit d'opérer dans un espace d'observation à 3 dimensions. La 3D est
  62 choisie de manière à restreindre la taille des objets numériques à entrer
  63 explicitement par l'utilisateur, mais le problème n'est pas dépendant de la
  64 dimension et peut être posé en dimension 10, 100, 1000... L'observation
  65 :math:`\mathbf{y}^o` vaut 1 dans chaque direction, donc :
  66 ::
  67
  68     Yo = [1 1 1]
  69
  70 L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
  71 priori* ou une régularisation mathématique, est choisie comme valant 0 dans
  72 chaque cas, ce qui donne donc :
  73 ::
  74
  75     Xb = [0 0 0]
  76
  77 La mise en oeuvre de l'assimilation de données requiert des informations sur
  78 les covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`,
  79 respectivement pour les variables d'erreur d'observation et d'ébauche. On
  80 choisit ici des erreurs décorrélées (c'est-à-dire des matrices diagonales) et
  81 d'avoir la même variance de 1 pour toutes les variables (c'est-à-dire des
  82 matrices identité). On pose donc :
  83 ::
  84
  85     B = R = Id = [1 0 0 ; 0 1 0 ; 0 0 1]
  86
  87 Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
  88 convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
  89 dimensions d'espace sont les mêmes et que l'on postule un opérateur linéaire de
  90 sélection, on peut choisir l'identité comme opérateur d'observation :
  91 ::
  92
  93     H = Id = [1 0 0 ; 0 1 0 ; 0 0 1]
  94
  95 Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
  96 vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
  97 *analysis*, noté :math:`\mathbf{x}^a`, et valant :
  98 ::
  99
 100     Xa = [0.5 0.5 0.5]
 101
 102 Pour étendre cet exemple, on peut modifier les variances représentées par
 103 :math:`\mathbf{B}` ou :math:`\mathbf{R}` indépendamment, et l'analyse
 104 :math:`\mathbf{x}^a` se déplacera vers :math:`\mathbf{y}^o` ou vers
 105 :math:`\mathbf{x}^b`, en proportion inverse des variances dans
 106 :math:`\mathbf{B}` et :math:`\mathbf{R}`. Comme autre extension, on peut aussi
 107 dire qu'il est équivalent de rechercher l'analyse à l'aide d'un algorithme de
 108 BLUE ou d'un algorithme de 3DVAR.
 109
 110 Utiliser l'interface textuelle (TUI) pour construire le cas ADAO
 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 112
 113 On va renseigner les variables pour construire le cas ADAO en utilisant les
 114 conditions d'expérience décrites ci-dessus. L'ensemble des informations
 115 techniques données au-dessus sont à insérer directement dans la définition du
 116 cas ADAO, en utilisant au choix une liste, un vecteur ou une chaîne de
 117 caractères pour chaque variable. On s'appuie sur la documentation de référence
 118 :ref:`section_tui`. On constitue ainsi un cas ADAO, qui peut être enregistré en
 119 fichier Python standard.
 120
 121 L'entête du fichier doit comporter les déclarations habituelles du cas :
 122 ::
 123
 124     from adao import adaoBuilder
 125     case = adaoBuilder.New()
 126     case.set( 'AlgorithmParameters', Algorithm='Blue' )
 127
 128 La définition des observations et des covariances d'erreurs sont les suivantes :
 129 ::
 130
 131     case.set( 'Observation',         Vector=[1, 1, 1] )
 132     case.set( 'ObservationError',    Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
 133
 134 De la même manière, l'information *a priori* est définie avec ses covariances
 135 d'erreur par :
 136 ::
 137
 138     case.set( 'Background',          Vector=[0, 0, 0] )
 139     case.set( 'BackgroundError',     Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
 140
 141 L'opérateur d'observation, très simple et ici linéaire, peut être défini par:
 142 ::
 143
 144     case.set( 'ObservationOperator', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
 145
 146 Pour obtenir un affichage automatique de l'état optimal analysé, on peut
 147 ajouter une commande d'"*observer*", ou ajouter après l'exécution des commandes de
 148 traitement des résultats de l'assimilation de données. On peut se contenter
 149 dans ce cas très simple d'ajouter :
 150 ::
 151
 152     case.set( 'Observer',            Variable="Analysis", Template="ValuePrinter" )
 153
 154 La démarche d'exécution est extrêmement simple et consiste à effectuer à la
 155 ligne de commande, ou dans le fichier enregistrant le cas, la commande
 156 suivante :
 157 ::
 158
 159     case.execute()
 160
 161 Le résultat de l'exécution de ces commandes (que ce soit en console Python, par
 162 la commande "*shell*" de SALOME, dans la console Python de l'interface, ou par
 163 le menu d'exécution d'un script) est le suivant :
 164 ::
 165
 166     Analysis [0.5 0.5 0.5]
 167
 168 comme montré ci-après :
 169 ::
 170
 171     adao@python$ python
 172     Python 3.6.5 (default, Feb 01 2019, 12:12:12)
 173     [GCC] on linux
 174     Type "help", "copyright", "credits" or "license" for more information.
 175     >>>
 176     >>> from adao import adaoBuilder
 177     >>> case = adaoBuilder.New()
 178     >>> case.set( 'AlgorithmParameters', Algorithm='Blue' )
 179     >>> case.set( 'Observation',         Vector=[1, 1, 1] )
 180     >>> case.set( 'ObservationError',    Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
 181     >>> case.set( 'Background',          Vector=[0, 0, 0] )
 182     >>> case.set( 'BackgroundError',     Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
 183     >>> case.set( 'ObservationOperator', Matrix="1 0 0 ; 0 1 0 ; 0 0 1" )
 184     >>> case.set( 'Observer',            Variable="Analysis", Template="ValuePrinter" )
 185     >>> case.execute()
 186     Analysis [0.5 0.5 0.5]
 187     0
 188     >>>
 189
 190 Pour étendre cet exemple, on peut remarquer que le même problème résolu par un
 191 algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi
 192 lors de l'étape de construction du cas ADAO en changeant simplement l'argument
 193 "*Algorithm*" en entête. Le reste du cas ADAO en 3DVAR est alors entièrement
 194 similaire au cas algorithmique du BLUE.
 195
 196 .. _section_tutorials_in_python_script:
 197
 198 Construire un cas d'estimation avec une définition de données externes par scripts
 199 ----------------------------------------------------------------------------------
 200
 201 Il est utile d'acquérir une partie ou la totalité des données du cas ADAO
 202 depuis une définition externe, en utilisant des scripts Python pour donner
 203 accès à ces données. À titre d'exemple, on construit ici un cas ADAO présentant
 204 le même dispositif expérimental que dans l'exemple ci-dessus
 205 :ref:`section_tutorials_in_python_explicit`, mais en utilisant des données
 206 issues d'un unique fichier script Python externe.
 207
 208 En premier lieu, on écrit le fichier script suivant, utilisant des noms
 209 conventionnels pour les variables requises. Ici toutes les variables sont
 210 définies dans le même script, mais l'utilisateur peut choisir de séparer le
 211 fichier en plusieurs autres, ou de mélanger une définition explicite des
 212 données dans l'interface textuelle ADAO et une définition implicite dans des
 213 fichiers externes. Le fichier script actuel ressemble à:
 214 ::
 215
 216     import numpy
 217     #
 218     # Definition of the Background as a vector
 219     # ----------------------------------------
 220     Background = [0, 0, 0]
 221     #
 222     # Definition of the Observation as a vector
 223     # -----------------------------------------
 224     Observation = "1 1 1"
 225     #
 226     # Definition of the Background Error covariance as a matrix
 227     # ---------------------------------------------------------
 228     BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
 229     #
 230     # Definition of the Observation Error covariance as a matrix
 231     # ----------------------------------------------------------
 232     ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
 233     #
 234     # Definition of the Observation Operator as a matrix
 235     # --------------------------------------------------
 236     ObservationOperator = numpy.identity(3)
 237
 238 Les noms des variables Python sont obligatoires, de manière à définir les
 239 bonnes variables dans le cas ADAO, mais le script Python peut être plus
 240 conséquent et définir des classes, des fonctions, des accès à des fichiers ou
 241 des bases de données, etc. avec des noms différents. De plus, le fichier
 242 ci-dessus présente différentes manières de définir des vecteurs ou des
 243 matrices, utilisant des listes, des chaînes de caractères (comme dans Numpy ou
 244 Octave), des types vecteur ou matrice de Numpy, et des fonctions spéciales de
 245 Numpy. Toutes ces syntaxes sont valides.
 246
 247 Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
 248 l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
 249 utilise l'interface textuelle pour construire le cas ADAO. La procédure pour
 250 compléter le cas est similaire à celle de l'exemple précédent à part le fait
 251 que, au lieu de choisir l'option "*Vector*" ou "*Matrix*" pour construire
 252 chaque variable, on choisit l'option "*Script*" en indiquant simultanément le
 253 type "*Vector*" ou "*Matrix*" de la variable. Cela permet d'obtenir les
 254 commandes suivantes (que ce soit en console Python, par la commande "*shell*"
 255 de SALOME, dans la console Python de l'interface, ou par le menu d'exécution
 256 d'un script) :
 257 ::
 258
 259     adao@python$ python
 260     Python 3.6.5 (default, Feb 01 2019, 12:12:12)
 261     [GCC] on linux
 262     Type "help", "copyright", "credits" or "license" for more information.
 263     >>>
 264     >>> from adao import adaoBuilder
 265     >>> case = adaoBuilder.New()
 266     >>> case.set( 'AlgorithmParameters', Algorithm='Blue' )
 267     >>> case.set( 'Observation',         Vector=True, Script="script.py" )
 268     >>> case.set( 'ObservationError',    Matrix=True, Script="script.py" )
 269     >>> case.set( 'Background',          Vector=True, Script="script.py" )
 270     >>> case.set( 'BackgroundError',     Matrix=True, Script="script.py" )
 271     >>> case.set( 'ObservationOperator', Matrix=True, Script="script.py" )
 272     >>> case.set( 'Observer',            Variable="Analysis", Template="ValuePrinter" )
 273     >>> case.execute()
 274     Analysis [0.5 0.5 0.5]
 275     0
 276     >>>
 277
 278 Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
 279 précédent :ref:`section_tutorials_in_python_explicit`.
 280
 281 Dans la pratique, cette démarche par scripts est la manière la plus facile pour
 282 récupérer des informations depuis des calculs en ligne ou préalables, depuis des
 283 fichiers statiques, depuis des bases de données ou des flux informatiques,
 284 chacun pouvant être dans ou hors SALOME. Cela permet aussi de modifier aisément
 285 des données d'entrée, par exemple à des fin de débogage ou pour des traitements
 286 répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
 287 d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
 288 "sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
 289 peuvent être directement introduites dans l'exécution du cas ADAO.
 290 L'utilisateur doit vérifier avec attention le contenu de ses scripts.**