doc/fr/tui.rst

   1 ..
   2    Copyright (C) 2008-2015 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 .. index:: single: TUI
  25 .. index:: single: API/TUI
  26 .. index:: single: adaoBuilder
  27 .. _section_tui:
  28
  29 ================================================================================
  30 **[DocR]** Interface de programmation textuelle pour l'utilisateur (API/TUI)
  31 ================================================================================
  32
  33 .. warning::
  34
  35   dans sa présente version, cette interface de programmation textuelle (TUI) est
  36   expérimentale, et reste donc susceptible de changements dans les prochaines
  37   versions.
  38
  39 Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de
  40 son interface de programmation textuelle (API/TUI). Cette interface permet de
  41 créer un objet de calcul de manière similaire à la construction d'un cas par
  42 l'interface graphique (GUI). Dans le cas où l'on désire réaliser à la main le
  43 cas de calcul TUI, on recommande de bien s'appuyer sur l'ensemble de la
  44 documentation du module ADAO, et de se reporter si nécessaire à l'interface
  45 graphique (GUI), pour disposer de l'ensemble des éléments permettant de
  46 renseigner correctement les commandes. Les notions générales et termes utilisés
  47 ici sont définis dans :ref:`section_theory`.
  48
  49 .. _subsection_tui_creating:
  50
  51 Création de cas de calcul TUI ADAO et exemples
  52 ----------------------------------------------
  53
  54 .. _subsection_tui_example:
  55
  56 Un exemple simple de création d'un cas de calcul TUI ADAO
  57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  58
  59 Pour introduire l'interface TUI, on commence par un exemple simple mais complet
  60 de cas de calcul ADAO. Toutes les données sont explicitement définies dans le
  61 corps du script pour faciliter la lecture. L'ensemble des commandes est le
  62 suivant::
  63
  64     from numpy import array
  65     import adaoBuilder
  66     case = adaoBuilder.New()
  67     case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
  68     case.set( 'Background',          Vector=[0, 1, 2] )
  69     case.set( 'BackgroundError',     ScalarSparseMatrix=1.0 )
  70     case.set( 'Observation',         Vector=array([0.5, 1.5, 2.5]) )
  71     case.set( 'ObservationError',    DiagonalSparseMatrix='1 1 1' )
  72     case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
  73     case.set( 'Observer',            Variable="Analysis", Template="ValuePrinter" )
  74     case.execute()
  75
  76 Le résultat de l'exécution de ces commandes dans SALOME (que ce soit par la
  77 commande "*shell*" de SALOME, dans la console Python de l'interface, ou par le
  78 menu d'exécution d'un script) est le suivant::
  79
  80     Analysis [ 0.25000264  0.79999797  0.94999939]
  81
  82 Création détaillée d'un cas de calcul TUI ADAO
  83 ++++++++++++++++++++++++++++++++++++++++++++++
  84
  85 On décrit ici plus en détail les différentes étapes de création d'un cas de
  86 calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
  87 l':ref:`subsection_tui_commands`.
  88
  89 La création et l'initialisation d'une étude se font par les commandes suivantes,
  90 le nom ``case`` de l'objet du cas de calcul TUI ADAO étant quelconque, au choix
  91 de l'utilisateur::
  92
  93     from numpy import array
  94     import adaoBuilder
  95     case = adaoBuilder.New()
  96
  97 Il est recommandé d'importer par principe le module ``numpy`` ou ses
  98 constructeurs particuliers comme celui d'``array``, pour faciliter ensuite son
  99 usage dans les commandes elle-mêmes.
 100
 101 Ensuite, le cas doit être construit par une préparation et un enregistrement des
 102 données définissant l'étude. L'ordre de ces commande n'a pas d'importance, il
 103 suffit que les concepts requis par l'algorithme utilisé soient présentes. On se
 104 reportera à :ref:`section_reference` et à ses sous-parties pour avoir le détail
 105 des commandes par algorithme. Ici, on définit successivement l'algorithme
 106 d'assimilation de données ou d'optimisation choisi et ses paramètres, puis
 107 l'ébauche :math:`\mathbf{x}^b` (nommée ``Background``) et sa covariance
 108 d'erreurs :math:`\mathbf{B}` (nommée ``BackgroundError``), et enfin
 109 l'observation :math:`\mathbf{y}^o` (nommée ``Observation``) et sa covariance
 110 d'erreurs :math:`\mathbf{R}` (nommée ``ObservationError``)::
 111
 112     case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
 113     #
 114     case.set( 'Background',          Vector=[0, 1, 2] )
 115     case.set( 'BackgroundError',     ScalarSparseMatrix=1.0 )
 116     #
 117     case.set( 'Observation',         Vector=array([0.5, 1.5, 2.5]) )
 118     case.set( 'ObservationError',    DiagonalSparseMatrix='1 1 1' )
 119
 120 On remarque que l'on peut donner, en entrée des quantités vectorielles ou
 121 matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou de
 122 type ``array`` ou ``matrix`` de Numpy. Dans ces deux derniers cas, il faut
 123 simplement importer le module Numpy avant.
 124
 125 On doit ensuite définir les opérateurs :math:`H` d'observation et éventuellement
 126 :math:`M` d'évolution. Dans tous les cas, linéaire ou non-linéaire, on peut les
 127 définir comme des fonctions. Dans le cas simple d'un opérateur linéaire, on peut
 128 aussi le définir à l'aide de la matrice qui correspond à l'opérateur linéaire.
 129 Dans le cas présent le plus simple d'opérateur linéaire, on utilise la syntaxe
 130 suivante pour un opérateur de :math:`\mathbf{R}^3` sur lui-même::
 131
 132     case.ObservationOperator(Matrix = "1 0 0;0 2 0;0 0 3")
 133
 134 Dans le cas beaucoup plus courant d'un opérateur non-linéaire de
 135 :math:`\mathbf{R}^n` dans  :math:`\mathbf{R}^p`, il doit être préalablement
 136 disponible sous la forme d'une fonction Python, connue dans l'espace de nommage
 137 courant, qui prend en entrée un vecteur ``numpy`` (ou une liste ordonnée) de
 138 taille :math:`n` et qui restitue en sortie un vecteur ``numpy`` de taille
 139 :math:`p`. Lorsque seul l'opérateur non-linéaire est défini par l'argument
 140 "*OneFunction*", son adjoint est directement établi de manière numérique et il
 141 est paramétrable par l'argument "*Parameters*". L'exemple suivant montre une
 142 fonction ``simulation`` (qui réalise ici le même opérateur linéaire que
 143 ci-dessus) et l'enregistre dans le cas ADAO::
 144
 145     import numpy
 146     def simulation(x):
 147         "Fonction de simulation H pour effectuer Y=H(X)"
 148         __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
 149         __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
 150         return __H * __x
 151     #
 152     case.set( 'ObservationOperator',
 153         OneFunction = simulation,
 154         Parameters  = {"DifferentialIncrement":0.01},
 155         )
 156
 157 Pour connaître les résultats intermédiaire ou finaux du calcul du cas, on peut
 158 ajouter des "*observer*", qui permettent d'associer l'exécution d'un script à
 159 une variable intermédiaire ou finale du calcul. On se reportera à la description
 160 de la manière d':ref:`section_advanced_observer`, et à la :ref:`section_reference`
 161 pour savoir quelles sont les quantités observables. Cette association
 162 d'"*observer*" avec une quantité existante se fait de manière similaire à la
 163 définition des données du calcul::
 164
 165     case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
 166
 167 Enfin, lorsque toutes les informations requises sont disponibles dans le cas
 168 ``case`` de calcul ADAO, on peut en demander l'exécution de manière très
 169 simple dans l'environnement de l'interpréteur Python::
 170
 171     case.execute()
 172
 173 Au final, on obtient le script très compact proposé précédemment dans
 174 :ref:`subsection_tui_example`.
 175
 176 Fournir des données ou informations de calcul plus complexes
 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 178
 179 Une telle interface s'écrivant en Python, il est possible d'utiliser toute la
 180 puissance du langage pour entrer des données plus complexes qu'une déclaration
 181 explicite.
 182
 183 L'enregistrement des données d'entrées supporte différents types de variables,
 184 mais surtout, ces entrées peuvent recevoir des variables courantes disponibles
 185 dans l'espace de nommage du script. Il est donc aisé d'utiliser des variables
 186 calculées préalablement ou obtenues par l'import de scripts "utilisateur". Si
 187 par exemple les observations sont disponibles sous la forme d'une liste dans un
 188 fichier Python externe nommé ``observations.py`` sous le nom ``table``, il
 189 suffit de réaliser les opérations suivantes pour enregistrer les observations
 190 dans le cas de calcul TUI ADAO::
 191
 192     from observations import table
 193     case.set( 'Observation', Vector=table )
 194
 195 La première ligne importe la variable ``table`` depuis le fichier externe, et la
 196 seconde enregistre directement cette table comme la donnée "*Observation*".
 197
 198 La simplicité de cet enregistrement montre bien la facilité d'obtenir les
 199 données de calcul depuis des sources externes, fichiers ou flux informatiques
 200 atteignables en Python. Comme d'habitude, il est recommandé à l'utilisateur de
 201 vérifier ses données avant de les enregistrer dans le cas de calcul TUI ADAO
 202 pour éviter les erreurs compliquées à corriger.
 203
 204 Obtenir et utiliser les résultats de calcul de manière plus riche
 205 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 206
 207 De la même manière, il est possible d'obtenir et traiter les résultats de calcul
 208 de manière plus riche, pour enchaîner sur des post-traitements après le calcul
 209 en TUI.
 210
 211 Les variables de résultats de calcul, ou les variables internes issues de
 212 l'optimisation ou de l'assimilation de données, sont disponibles à travers la
 213 méthode ``get`` du cas de calcul TUI ADAO, qui renvoie un objet de type liste de
 214 la variable demandée. On se reportera aux :ref:`section_ref_output_variables`
 215 pour une description détaillée sur ce sujet.
 216
 217 A titre d'exemple, on donne quelques lignes de script qui permettent d'obtenir
 218 le nombre d'itérations de l'optimisation et la valeur optimale ainsi que sa
 219 taille::
 220
 221     print
 222     print "    Nombre d'iterations :", len(case.get("CostFunctionJ"))
 223     Xa = case.get("Analysis")
 224     print "    Analyse optimale    :", Xa[-1]
 225     print "    Taille de l'analyse :", len(Xa[-1])
 226     print
 227
 228 Ces lignes peuvent être très simplement additionnées à l'exemple initial de cas
 229 de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
 230
 231 De même que pour l'entrée des données, la simplicité de récupération des
 232 résultats permet d'envisager aisément des post-traitements enchaînés dans
 233 SALOME, pour utiliser par exemple de la visualisation avec MatPlotLib ou PARAVIS
 234 [PARAVIS]_, de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour d'autres
 235 calculs.
 236
 237 .. _subsection_tui_commands:
 238
 239 Ensemble des commandes disponibles en interface textuelle TUI
 240 -------------------------------------------------------------
 241
 242 Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
 243 courantes en Python pour la distinction entre ce qui est public, et ce qui est
 244 privé ou réservé car relevant des détails d'implémentation. De manière pratique,
 245 tout nom d'objet ou de fonction commençant par au moins un signe "_" est privé
 246 au sens courant de programmation ("*private*"). Néanmoins, l'absence d'un tel
 247 signe au début d'un nom ne le désigne pas comme public. De manière générale, en
 248 Python, et contrairement à d'autres langages, on peut accéder aux objets ou aux
 249 fonction privés. Cela peut parfois être utile, mais un tel usage dans vos codes
 250 conduira à des plantages sans avertissement lors de futures versions. Il est
 251 donc fortement recommandé de ne pas le faire.
 252
 253 Pour clarifier et faciliter l'utilisation du module pour du script, **cette
 254 section définit donc l'interface de programmation (API) textuelle publique pour
 255 l'utilisateur (TUI) de manière complète et limitative**. L'usage en script
 256 d'objets ou fonctions ADAO autres que ceux qui sont définis ici est fortement
 257 déconseillé, car cela conduira vraisemblablement à des plantages sans
 258 avertissement lors de futures versions.
 259
 260 Syntaxes d'appel équivalentes pour les commandes TUI
 261 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 262
 263 La définition des données lors de la création de cas de calcul TUI ADAO supporte
 264 **deux syntaxes entièrement équivalentes**. On peut :
 265
 266 - soit utiliser la commande ``set`` et comme premier argument le concept
 267   ``XXXXX`` sur lequel appliquer la commande dont les arguments suivent,
 268 - soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
 269   à appliquer.
 270
 271 Pour illustrer cette équivalence, on prend l'exemple des deux commandes
 272 suivantes qui conduisent au même résultat::
 273
 274     case.set( 'Background', Vector=[0, 1, 2] )
 275
 276 et::
 277
 278     case.setBackground( Vector=[0, 1, 2] )
 279
 280 Le choix de l'une ou l'autre des syntaxes est librement laissé à l'utilisateur,
 281 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
 282 commandes selon la seconde syntaxe.
 283
 284 Création d'un cas de calcul en interface textuelle TUI
 285 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 286
 287 La création et l'initialisation d'un cas de calcul en interface textuelle TUI se
 288 font en important le module d'interface "*adaoBuilder*" et en invoquant sa
 289 méthode "*New()*" comme illustré dans les quelques lignes suivantes (le nom
 290 ``case`` de l'objet étant quelconque, au choix de l'utilisateur)::
 291
 292     from numpy import array
 293     import adaoBuilder
 294     case = adaoBuilder.New()
 295
 296 Il est recommandé par principe de toujours importer le module ``numpy`` (ou ses
 297 constructeurs particuliers, comme celui d'``array``) pour faciliter ensuite son
 298 usage dans les commandes elle-mêmes.
 299
 300 Définir les données de calcul
 301 +++++++++++++++++++++++++++++
 302
 303 Les commandes qui suivent permettent de définir les données d'un cas de calcul
 304 TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux des
 305 entrées en interface GUI, décrits dans la section des
 306 :ref:`section_reference_entry` et en particulier par la
 307 :ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs se
 308 fait soit lors de leur définition, soit lors de l'exécution.
 309
 310 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
 311 veut éventuellement la stocker la grandeur définie, pour en disposer en cours de
 312 calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
 313 recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
 314 TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
 315 dans l'espace de nommage courant du cas.
 316
 317 Les commandes disponibles sont les suivantes :
 318
 319 .. index:: single: setBackground
 320
 321 **setBackground** (*Vector, VectorSerie, Script, Stored*)
 322     Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
 323     algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
 324     comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
 325     script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
 326     "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
 327
 328 .. index:: single: setBackgroundError
 329
 330 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 331     Cette commande permet de définir la matrice :math:`\mathbf{B}` de
 332     covariance des erreurs d'ébauche. La matrice peut être définie de manière
 333     complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
 334     matrice diagonale dont on donne la variance unique sur la diagonale par
 335     "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
 336     vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
 337     Si on la définit par un script dans "*Script*", la matrice est de type
 338     "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
 339     selon que l'une de ces variables est placée à "*True*".
 340
 341 .. index:: single: setCheckingPoint
 342
 343 **setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
 344     Cette commande permet de définir un point courant :math:`\mathbf{x}` utilisé
 345     pour un algorithme de vérification. Selon les algorithmes, on peut le
 346     définir comme un vecteur simple par "*Vector*", ou comme une liste de
 347     vecteurs par "*VectorSerie*". Si on le définit par un script dans
 348     "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
 349     "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
 350
 351 .. index:: single: setControlModel
 352
 353 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
 354     Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
 355     décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
 356     d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
 357     valeur est définie comme un objet de type fonction ou de type "*Matrix*".
 358     Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
 359     utilisées, comme décrit dans la section
 360     :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
 361     "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
 362     "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
 363     "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
 364     Les paramètres de contrôle de l'approximation numérique de l'opérateur
 365     adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
 366     dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
 367     de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
 368     "*CenteredFiniteDifference*" (similaires à celles de l'interface graphique).
 369
 370 .. index:: single: setControlInput
 371
 372 **setControlInput** (*Vector, VectorSerie, Script, Stored*)
 373     Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
 374     Selon les algorithmes, on peut le définir comme un vecteur simple par
 375     "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
 376     définit par un script dans "*Script*", le vecteur est de type "*Vector*"
 377     (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
 378     à "*True*".
 379
 380 .. index:: single: setEvolutionError
 381
 382 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 383     Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
 384     covariance des erreurs d'évolution. La matrice peut être définie de manière
 385     complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
 386     matrice diagonale dont on donne la variance unique sur la diagonale par
 387     "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
 388     vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
 389     Si on la définit par un script dans "*Script*", la matrice est de type
 390     "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
 391     selon que l'une de ces variables est placée à "*True*".
 392
 393 .. index:: single: setEvolutionModel
 394
 395 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
 396     Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
 397     décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
 398     de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
 399     différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
 400     la section :ref:`section_ref_operator_requirements`, et entrées par les
 401     mots-clés "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une
 402     définition par "*Script*", l'opérateur est de type "*Matrix*",
 403     "*OneFunction*" ou "*ThreeFunctions*" selon que l'une de ces variables est
 404     placée à "*True*". Les paramètres de contrôle de l'approximation numérique
 405     de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être renseignés
 406     par un dictionnaire dans "*Parameters*". Les entrées potentielles de ce
 407     dictionnaire de paramètres sont "*DifferentialIncrement*",
 408     "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
 409     "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
 410
 411 .. index:: single: setObservation
 412
 413 **setObservation** (*Vector, VectorSerie, Script, Stored*)
 414     Cette commande permet de définir le vecteur d'observation
 415     :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
 416     vecteur simple par "*Vector*", ou comme une liste de vecteurs par
 417     "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
 418     est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
 419     ces variables est placée à "*True*".
 420
 421 .. index:: single: setObservationError
 422
 423 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 424     Cette commande permet de définir la matrice :math:`\mathbf{R}` de
 425     covariance des erreurs d'observation. La matrice peut être définie de
 426     manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
 427     comme une matrice diagonale dont on donne la variance unique sur la
 428     diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on
 429     donne le vecteur des variances situé sur la diagonale par
 430     "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*", la
 431     matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
 432     "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
 433     "*True*".
 434
 435 .. index:: single: setObservationOperator
 436
 437 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
 438     Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
 439     transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
 440     :math:`\mathbf{y}` qui sont à comparer aux observations
 441     :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
 442     ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
 443     fonctionnelles peuvent être utilisées, comme décrit dans la section
 444     :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
 445     "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
 446     "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
 447     "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
 448     Les paramètres de contrôle de l'approximation numérique de l'opérateur
 449     adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
 450     dictionnaire dans "*Parameters*". Les entrées potentielles de ce
 451     dictionnaire de paramètres sont "*DifferentialIncrement*",
 452     "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
 453     "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
 454
 455 .. index:: single: set
 456
 457 **set** (*Concept,...*)
 458     Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
 459     commandes de ce paragraphe. Son premier argument est le nom du concept à
 460     définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
 461     s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
 462     les commandes individuelles précédentes. Lors de l'usage de cette commande,
 463     il est indispensable de nommer les arguments (par exemple "*Vector=...*").
 464
 465 Paramétrer le calcul, les sorties, etc.
 466 +++++++++++++++++++++++++++++++++++++++
 467
 468 .. index:: single: setAlgorithmParameters
 469
 470 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
 471     Cette commande permet de choisir l'algorithme de calcul ou de vérification
 472     par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
 473     reportera utilement aux listes des :ref:`section_reference_assimilation` et
 474     des :ref:`section_reference_checking`), et de définir les paramètres de
 475     calcul par l'argument "*Parameters*". Dans le cas d'une définition par
 476     "*Script*", le fichier indiqué doit contenir les deux variables
 477     "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
 478     équivalente).
 479
 480 .. index:: single: setDebug
 481
 482 **setDebug** ()
 483     Cette commande permet d'activer le mode d'information détaillé lors de
 484     l'exécution.
 485
 486 .. index:: single: setNoDebug
 487
 488 **setNoDebug** ()
 489     Cette commande permet de désactiver le mode d'information détaillé lors de
 490     l'exécution.
 491
 492 .. index:: single: setObserver
 493
 494 **setObserver** (*Variable, Template, String, Script, Info*)
 495     Cette commande permet de définir un *observer* sur une variable courante ou
 496     finale du calcul. On se reportera à la description de la manière
 497     d':ref:`section_advanced_observer`, et à la :ref:`section_reference` pour
 498     savoir quelles sont les quantités observables. On définit comme un
 499     "*String*" le corps de l'*observer*, en utilisant une chaine de caractères
 500     incluant si nécessaire des sauts de lignes. On recommande d'utiliser les
 501     patrons disponibles par l'argument "*Template*". On dispose des patrons
 502     simples suivants : "ValuePrinter", "ValueSeriePrinter", "ValueSaver",
 503     "ValueSerieSaver", "ValuePrinterAndSaver", "ValueSeriePrinterAndSaver",
 504     "ValueGnuPlotter", "ValueSerieGnuPlotter", "ValuePrinterAndGnuPlotter",
 505     "ValueSeriePrinterAndGnuPlotter", "ValuePrinterSaverAndGnuPlotter",
 506     "ValueSeriePrinterSaverAndGnuPlotter", "ValueMean", "ValueStandardError",
 507     "ValueVariance", "ValueRMS". Dans le cas d'une définition par "*Script*", le
 508     fichier indiqué doit contenir uniquement le corps de la fonction, comme
 509     décrit dans la manière d':ref:`section_advanced_observer`.
 510
 511 Effectuer le calcul
 512 +++++++++++++++++++
 513
 514 .. index:: single: executePythonScheme
 515
 516 **executePythonScheme** ()
 517     Cette commande lance le calcul complet dans l'environnement de
 518     l'interpréteur Python courant, sans interaction avec YACS [YACS]_. Les
 519     sorties standard et d'erreur sont celles de l'interpréteur Python. On
 520     dispose si nécessaire du parallélisme interne des algorithmes dans ADAO et
 521     du parallélisme interne du ou des codes de simulation utilisé.
 522
 523 .. .. index:: single: generateYACSscheme
 524 ..
 525 .. **executeYACSScheme** (*File*)
 526 ..     Cete commande génère le schéma YACS [YACS]_ du cas de calcul dans le fichier
 527 ..     requis "*File*", et en lance l'exécution dans l'interpréteur YACS, comme on
 528 ..     peut le réaliser en utilisant l'éditeur standard de cas ADAO. Les sorties
 529 ..     standard et d'erreur sont celles de l'interpréteur YACS. On dispose si
 530 ..     nécessaire du parallélisme de noeuds et blocs dans YACS, du parallélisme
 531 ..     interne des algorithmes dans ADAO et du parallélisme interne du ou des codes
 532 ..     de simulation utilisé.
 533
 534 .. index:: single: execute
 535
 536 **execute** ()
 537     Cette commande est un raccourci utilisateur pour "*executePythonScheme*".
 538
 539 Obtenir séparément les résultats de calcul
 540 ++++++++++++++++++++++++++++++++++++++++++
 541
 542 .. index:: single: get
 543
 544 **get** (*Concept*)
 545     Cette commande permet d'extraire explicitement les variables disponibles en
 546     sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
 547     scripting, par exemple en visualisation. Elle a pour argument le nom d'un
 548     variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
 549     d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
 550     base. Pour connaître la liste des variables et les utiliser, on se
 551     reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
 552     fois aux :ref:`section_ref_output_variables` et aux documentations
 553     individuelles des algorithmes.
 554
 555 Exemples plus avancés de cas de calcul TUI ADAO
 556 -----------------------------------------------
 557
 558 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
 559 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
 560 objectif.
 561
 562 Exploitation indépendante des résultats d'un cas de calcul
 563 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 564
 565 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
 566 son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
 567 exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
 568 ici, puisque dépendante de l'utilisateur).
 569
 570 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
 571
 572 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
 573 #. que l'on dispose d'observations nommées ``observations``,
 574 #. que l'utilisateur dispose en Python d'une fonction de simulation physique appellée ``simulation``, préalablement (bien) testée, qui transforme les 3 paramètres en résultats similaires aux observations,
 575 #. que l'exploitation indépendante, que l'utilisateur veut faire, est représentée ici par l'affichage simple de l'état initial, de l'état optimal, de la simulation en ce point, des états intermédiaires et du nombre d'itérations d'optimisation.
 576
 577 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
 578 exemple les entrées suivantes, parfaitement arbitraires, en construisant les
 579 observations par simulation pour se placer dans un cas d'expériences jumelles::
 580
 581     #
 582     # Construction artificielle d'un exemple de données utilisateur
 583     # -------------------------------------------------------------
 584     alpha = 5.
 585     beta = 7
 586     gamma = 9.0
 587     #
 588     alphamin, alphamax = 0., 10.
 589     betamin,  betamax  = 3, 13
 590     gammamin, gammamax = 1.5, 15.5
 591     #
 592     def simulation(x):
 593         "Fonction de simulation H pour effectuer Y=H(X)"
 594         import numpy
 595         __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
 596         __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
 597         return __H * __x
 598     #
 599     # Observations obtenues par simulation
 600     # ------------------------------------
 601     observations = simulation((2, 3, 4))
 602
 603 Le jeu de commandes que l'on peut utiliser est le suivant::
 604
 605     import numpy
 606     import adaoBuilder
 607     #
 608     # Mise en forme des entrées
 609     # -------------------------
 610     Xb = (alpha, beta, gamma)
 611     Bounds = (
 612         (alphamin, alphamax),
 613         (betamin,  betamax ),
 614         (gammamin, gammamax))
 615     #
 616     # TUI ADAO
 617     # --------
 618     case = adaoBuilder.New()
 619     case.set(
 620         'AlgorithmParameters',
 621         Algorithm = '3DVAR',
 622         Parameters = {
 623             "Bounds":Bounds,
 624             "MaximumNumberOfSteps":100,
 625             "StoreSupplementaryCalculations":[
 626                 "CostFunctionJ",
 627                 "CurrentState",
 628                 "SimulatedObservationAtOptimum",
 629                 ],
 630             }
 631         )
 632     case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
 633     case.set( 'Observation', Vector = numpy.array(observations) )
 634     case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
 635     case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
 636     case.set(
 637         'ObservationOperator',
 638         OneFunction = simulation,
 639         Parameters  = {"DifferentialIncrement":0.0001},
 640         )
 641     case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
 642     case.execute()
 643     #
 644     # Exploitation indépendante
 645     # -------------------------
 646     Xbackground   = case.get("Background")
 647     Xoptimum      = case.get("Analysis")[-1]
 648     FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
 649     J_values      = case.get("CostFunctionJ")[:]
 650     print
 651     print "Nombre d'itérations internes...: %i"%len(J_values)
 652     print "Etat initial...................:",numpy.ravel(Xbackground)
 653     print "Etat optimal...................:",numpy.ravel(Xoptimum)
 654     print "Simulation à l'état optimal....:",numpy.ravel(FX_at_optimum)
 655     print
 656
 657 L'exécution de jeu de commandes donne le résultat suivant::
 658
 659     CurrentState [ 5.  7.  9.]
 660     CurrentState [ 0.   3.   1.5]
 661     CurrentState [ 1.40006418  3.86705307  3.7061137 ]
 662     CurrentState [ 1.42580231  3.68474804  3.81008738]
 663     CurrentState [ 1.60220353  3.0677108   4.06146069]
 664     CurrentState [ 1.72517855  3.03296953  4.04915706]
 665     CurrentState [ 2.00010755  3.          4.00055409]
 666     CurrentState [ 1.99995528  3.          3.99996367]
 667     CurrentState [ 2.00000007  3.          4.00000011]
 668     CurrentState [ 2.  3.  4.]
 669
 670     Nombre d'itérations internes...: 10
 671     Etat initial...................: [ 5.  7.  9.]
 672     Etat optimal...................: [ 2.  3.  4.]
 673     Simulation à l'état optimal....: [  2.   6.  12.  20.]
 674
 675 Comme il se doit en expériences jumelles, on constate que l'on retouve bien les
 676 paramètres qui ont servi à construire artificiellement les observations.
 677
 678 .. Réconciliation de courbes à l'aide de MedCoupling
 679 .. +++++++++++++++++++++++++++++++++++++++++++++++++
 680
 681 .. Utilisation de fonctions de surveillance de type "observer"
 682 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 683
 684 .. Suivre d'un recalage à l'aide de MatPlotLib
 685 .. +++++++++++++++++++++++++++++++++++++++++++
 686
 687 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
 688 .. -----------------------------------------------------------------------------
 689
 690 .. [HOMARD] Pour de plus amples informations sur HOMARD, voir le *module HOMARD* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
 691
 692 .. [PARAVIS] Pour de plus amples informations sur PARAVIS, voir le *module PARAVIS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME.
 693
 694 .. [YACS] 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.