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