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