doc/fr/tutorials_in_python.rst

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