doc/fr/tui.rst

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