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