doc/fr/tui.rst

   1 ..
   2    Copyright (C) 2008-2021 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 textuelle pour l'utilisateur (TUI/API)
  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     from adao 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     from adao 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     from adao 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 .. index:: single: Stored
 305
 306 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
 307 veut éventuellement stocker la grandeur définie, pour en disposer en cours de
 308 calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
 309 recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
 310 TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
 311 dans l'espace de nommage courant du cas.
 312
 313 Les commandes disponibles sont les suivantes :
 314
 315 .. index:: single: setBackground
 316
 317 **setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 318     Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
 319     algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
 320     comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
 321     script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
 322     "*VectorSerie*" selon que l'une de ces variables est placée à "*True*". Si
 323     on utilise un fichier de données par "*DataFile*" (en sélectionnant, en
 324     colonne par défaut ou en ligne selon "*ColMajor*", toutes les variables par
 325     défaut ou celles de la liste "*ColNames*"), le vecteur est de type
 326     "*Vector*".
 327
 328 .. index:: single: setBackgroundError
 329
 330 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 331     Cette commande permet de définir la matrice :math:`\mathbf{B}` de
 332     covariance des erreurs d'ébauche. La matrice peut être définie de manière
 333     complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
 334     matrice diagonale dont on donne la variance unique sur la diagonale par
 335     "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
 336     vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
 337     Si on la définit par un script dans "*Script*", la matrice est de type
 338     "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
 339     selon que l'une de ces variables est placée à "*True*".
 340
 341 .. index:: single: setCheckingPoint
 342
 343 **setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 344     Cette commande permet de définir un point courant :math:`\mathbf{x}`
 345     utilisé pour un algorithme de vérification. Selon les algorithmes, on peut
 346     le définir comme un vecteur simple par "*Vector*", ou comme une liste de
 347     vecteurs par "*VectorSerie*". Si on le définit par un script dans
 348     "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
 349     "*VectorSerie*" selon que l'une de ces variables est placée à "*True*". Si
 350     on utilise un fichier de données par "*DataFile*" (en sélectionnant, en
 351     colonne par défaut ou en ligne selon "*ColMajor*", toutes les variables par
 352     défaut ou celles de la liste "*ColNames*"), le vecteur est de type
 353     "*Vector*".
 354
 355 .. index:: single: setControlModel
 356
 357 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArgs, Stored*)
 358     Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
 359     décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
 360     d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
 361     valeur est définie comme un objet de type fonction ou de type "*Matrix*".
 362     Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
 363     utilisées, comme décrit dans la section
 364     :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
 365     "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
 366     "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
 367     "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
 368     Les paramètres de contrôle de l'approximation numérique de l'opérateur
 369     adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
 370     dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
 371     de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
 372     "*CenteredFiniteDifference*" (similaires à celles de l'interface graphique).
 373
 374 .. index:: single: setControlInput
 375
 376 **setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 377     Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
 378     Selon les algorithmes, on peut le définir comme un vecteur simple par
 379     "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
 380     définit par un script dans "*Script*", le vecteur est de type "*Vector*"
 381     (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
 382     à "*True*". Si on utilise un fichier de données par "*DataFile*" (en
 383     sélectionnant, en colonne par défaut ou en ligne selon "*ColMajor*", toutes
 384     les variables par défaut ou celles de la liste "*ColNames*"), le vecteur
 385     est de type "*Vector*".
 386
 387 .. index:: single: setEvolutionError
 388
 389 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 390     Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
 391     covariance des erreurs d'évolution. La matrice peut être définie de manière
 392     complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
 393     matrice diagonale dont on donne la variance unique sur la diagonale par
 394     "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
 395     vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
 396     Si on la définit par un script dans "*Script*", la matrice est de type
 397     "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
 398     selon que l'une de ces variables est placée à "*True*".
 399
 400 .. index:: single: setEvolutionModel
 401
 402 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArgs, Stored*)
 403     Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
 404     décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
 405     de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
 406     différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
 407     la section :ref:`section_ref_operator_requirements`, et entrées par les
 408     mots-clés "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une
 409     définition par "*Script*", l'opérateur est de type "*Matrix*",
 410     "*OneFunction*" ou "*ThreeFunctions*" selon que l'une de ces variables est
 411     placée à "*True*". Les paramètres de contrôle de l'approximation numérique
 412     de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être renseignés
 413     par un dictionnaire dans "*Parameters*". Les entrées potentielles de ce
 414     dictionnaire de paramètres sont "*DifferentialIncrement*",
 415     "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
 416     "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
 417
 418 .. index:: single: setObservation
 419
 420 **setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
 421     Cette commande permet de définir le vecteur d'observation
 422     :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
 423     vecteur simple par "*Vector*", ou comme une liste de vecteurs par
 424     "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
 425     est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
 426     ces variables est placée à "*True*". Si on utilise un fichier de données
 427     par "*DataFile*" (en sélectionnant, en colonne par défaut ou en ligne selon
 428     "*ColMajor*", toutes les variables par défaut ou celles de la liste
 429     "*ColNames*"), le vecteur est de type "*Vector*".
 430
 431 .. index:: single: setObservationError
 432
 433 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
 434     Cette commande permet de définir la matrice :math:`\mathbf{R}` de
 435     covariance des erreurs d'observation. La matrice peut être définie de
 436     manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
 437     comme une matrice diagonale dont on donne la variance unique sur la
 438     diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on
 439     donne le vecteur des variances situé sur la diagonale par
 440     "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*", la
 441     matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
 442     "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
 443     "*True*".
 444
 445 .. index:: single: setObservationOperator
 446
 447 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArgs, Stored*)
 448     Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
 449     transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
 450     :math:`\mathbf{y}` qui sont à comparer aux observations
 451     :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
 452     ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
 453     fonctionnelles peuvent être utilisées, comme décrit dans la section
 454     :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
 455     "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
 456     "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
 457     "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
 458     Dans le cas où l'opérateur :math:`H` évalué en :math:`\mathbf{x}^b` est
 459     disponible, il peut être donné en utilisant "*AppliedInXb*" et sera
 460     considéré comme un vecteur. Les paramètres de contrôle de l'approximation
 461     numérique de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être
 462     renseignés par un dictionnaire dans "*Parameters*". Les entrées potentielles
 463     de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
 464     "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
 465     "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
 466
 467 .. index:: single: set
 468
 469 **set** (*Concept,...*)
 470     Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
 471     commandes de ce paragraphe. Son premier argument est le nom du concept à
 472     définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
 473     s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
 474     les commandes individuelles précédentes. Lors de l'usage de cette commande,
 475     il est indispensable de nommer les arguments (par exemple "*Vector=...*").
 476
 477 Paramétrer le calcul, les sorties, etc.
 478 +++++++++++++++++++++++++++++++++++++++
 479
 480 .. index:: single: setAlgorithmParameters
 481
 482 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
 483     Cette commande permet de choisir l'algorithme de calcul ou de vérification
 484     par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
 485     reportera utilement aux listes des :ref:`section_reference_assimilation` et
 486     des :ref:`section_reference_checking`), et de définir les paramètres de
 487     calcul par l'argument "*Parameters*". Dans le cas d'une définition par
 488     "*Script*", le fichier indiqué doit contenir les deux variables
 489     "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
 490     équivalente).
 491
 492 .. index:: single: setName
 493
 494 **setName** (*String*)
 495     Cette commande permet de donner un titre court au cas de calcul.
 496
 497 .. index:: single: setDirectory
 498
 499 **setDirectory** (*String*)
 500     Cette commande permet d'indiquer le répertoire courant d'exécution.
 501
 502 .. index:: single: setDebug
 503
 504 **setDebug** ()
 505     Cette commande permet d'activer le mode d'information détaillé lors de
 506     l'exécution.
 507
 508 .. index:: single: setNoDebug
 509
 510 **setNoDebug** ()
 511     Cette commande permet de désactiver le mode d'information détaillé lors de
 512     l'exécution.
 513
 514 .. index:: single: setObserver
 515
 516 **setObserver** (*Variable, Template, String, Script, Info*)
 517     Cette commande permet de définir un *observer* sur une variable courante ou
 518     finale du calcul. On se reportera à la description des
 519     :ref:`section_ref_observers_requirements` pour avoir leur liste et leur
 520     format, et à la :ref:`section_reference` pour savoir quelles sont les
 521     quantités observables. On définit comme un "*String*" le corps de
 522     l'*observer*, en utilisant une chaîne de caractères incluant si nécessaire
 523     des sauts de lignes. On recommande d'utiliser les patrons disponibles par
 524     l'argument "*Template*". Dans le cas d'une définition par "*Script*", le
 525     fichier indiqué doit contenir uniquement le corps de la fonction, comme
 526     décrit dans les :ref:`section_ref_observers_requirements`. La variable
 527     "*Info*" contient une chaîne de caractère d'information ou une chaine vide.
 528
 529 Effectuer le calcul
 530 +++++++++++++++++++
 531
 532 .. index:: single: execute
 533 .. index:: single: Executor
 534 .. index:: single: SaveCaseInFile
 535 .. index:: single: nextStep
 536
 537 **execute** (*Executor, SaveCaseInFile, nextStep*)
 538     Cette commande lance le calcul complet dans l'environnement d'exécution
 539     choisi par le mot-clé *Executor*, qui est défini par défaut selon
 540     l'environnement de lancement. Cet environnement peut être celui de
 541     l'interpréteur Python, sans interaction avec YACS (demandé par la valeur
 542     "*Python*"), ou celui de YACS (demandé par la valeur "*YACS*" [YACS]_). Si
 543     un fichier est indiqué dans le mot-clé *SaveCaseInFile*, il sera utilisé
 544     pour enregistrer la version associée du fichier de commande pour
 545     l'environnement d'exécution requis. Le mot-clé booléen "*nextStep*" indique
 546     que l'exécution repart du résultat de la précédente exécution sans la
 547     stocker (valeur "*True*") ou non (valeur "*False*", par défaut). Lors de
 548     l'exécution, les sorties courantes (standard et d'erreur) sont celles de
 549     l'environnement choisi. On dispose si nécessaire (ou si possible) du
 550     parallélisme interne des algorithmes dans ADAO, du parallélisme de YACS, et
 551     du parallélisme interne du ou des codes de simulation utilisés.
 552
 553 Obtenir séparément les résultats de calcul
 554 ++++++++++++++++++++++++++++++++++++++++++
 555
 556 .. index:: single: get
 557
 558 **get** (*Concept*)
 559     Cette commande permet d'extraire explicitement les variables disponibles en
 560     sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
 561     scripting, par exemple en visualisation. Elle a pour argument le nom d'un
 562     variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
 563     d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
 564     base. Pour connaître la liste des variables et les utiliser, on se
 565     reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
 566     fois aux :ref:`section_ref_output_variables` et aux documentations
 567     individuelles des algorithmes.
 568
 569 Enregistrer, charger ou convertir les commandes de cas de calcul
 570 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 571
 572 L'enregistrement ou le chargement d'un cas de calcul concernent les quantités
 573 et les actions qui lui sont liées par les commandes précédentes, à l'exclusion
 574 d'opérations externes au cas (comme par exemple le post-processing qui peut
 575 être développé après le cas de calcul). Les commandes enregistrées ou chargées
 576 restent néanmoins parfaitement compatibles avec ces opérations en Python
 577 externes au cas.
 578
 579 .. index:: single: load
 580 .. index:: single: FileName
 581 .. index:: single: Content
 582 .. index:: single: Object
 583 .. index:: single: Formater
 584
 585 **load** (*FileName, Content, Object, Formater*)
 586     Cette commande permet de lire ou charger un cas d'étude, à partir d'un
 587     fichier "*FileName*" ou d'un contenu en mémoire par "*Content*" ou
 588     "*Object*". Le mot-clé "*Formater*" peut désigner le format "*TUI*" pour
 589     les commandes du type interface de programmation textuelle (défaut), et le
 590     format "*COM*" pour les commandes du type COMM provenant de l'interface
 591     ADAO de type EFICAS.
 592
 593 .. index:: single: dump
 594
 595 **dump** (*FileName, Formater*)
 596     Cette commande permet d'enregistrer, dans un fichier "*FileName*", les
 597     commandes du cas d'étude en cours. Le mot-clé "*Formater*" peut désigner
 598     les formats "*TUI*" pour les commandes du type interface de programmation
 599     textuelle (défaut), et "*YACS*" pour les commandes du type YACS.
 600
 601 .. index:: single: convert
 602 .. index:: single: FileNameFrom
 603 .. index:: single: ContentFrom
 604 .. index:: single: ObjectFrom
 605 .. index:: single: FormaterFrom
 606 .. index:: single: FileNameTo
 607 .. index:: single: FormaterTo
 608
 609 **convert** (*FileNameFrom, ContentFrom, ObjectFrom, FormaterFrom, FileNameTo, FormaterTo*)
 610     Cette commande permet de convertir directement d'un format reconnu à un
 611     autre les commandes établissant le cas de calcul en cours. Certains
 612     formats ne sont disponibles qu'en entrée ou qu'en sortie.
 613
 614 .. _subsection_tui_advanced:
 615
 616 Exemples plus avancés de cas de calcul TUI ADAO
 617 -----------------------------------------------
 618
 619 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
 620 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
 621 objectif.
 622
 623 Exploitation indépendante des résultats d'un cas de calcul
 624 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 625
 626 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
 627 son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
 628 exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
 629 ici, puisque dépendante de l'utilisateur).
 630
 631 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
 632
 633 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
 634 #. que l'on dispose d'observations nommées ``observations``,
 635 #. 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,
 636 #. 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.
 637
 638 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
 639 exemple les entrées suivantes, parfaitement arbitraires, en construisant les
 640 observations par simulation pour se placer dans un cas d'expériences jumelles::
 641
 642     #
 643     # Construction artificielle d'un exemple de données utilisateur
 644     # -------------------------------------------------------------
 645     alpha = 5.
 646     beta = 7
 647     gamma = 9.0
 648     #
 649     alphamin, alphamax = 0., 10.
 650     betamin,  betamax  = 3, 13
 651     gammamin, gammamax = 1.5, 15.5
 652     #
 653     def simulation(x):
 654         "Fonction de simulation H pour effectuer Y=H(X)"
 655         import numpy
 656         __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
 657         __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
 658         return __H * __x
 659     #
 660     # Observations obtenues par simulation
 661     # ------------------------------------
 662     observations = simulation((2, 3, 4))
 663
 664 Le jeu de commandes que l'on peut utiliser est le suivant::
 665
 666     import numpy
 667     from adao import adaoBuilder
 668     #
 669     # Mise en forme des entrées
 670     # -------------------------
 671     Xb = (alpha, beta, gamma)
 672     Bounds = (
 673         (alphamin, alphamax),
 674         (betamin,  betamax ),
 675         (gammamin, gammamax))
 676     #
 677     # TUI ADAO
 678     # --------
 679     case = adaoBuilder.New()
 680     case.set(
 681         'AlgorithmParameters',
 682         Algorithm = '3DVAR',
 683         Parameters = {
 684             "Bounds":Bounds,
 685             "MaximumNumberOfSteps":100,
 686             "StoreSupplementaryCalculations":[
 687                 "CostFunctionJ",
 688                 "CurrentState",
 689                 "SimulatedObservationAtOptimum",
 690                 ],
 691             }
 692         )
 693     case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
 694     case.set( 'Observation', Vector = numpy.array(observations) )
 695     case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
 696     case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
 697     case.set(
 698         'ObservationOperator',
 699         OneFunction = simulation,
 700         Parameters  = {"DifferentialIncrement":0.0001},
 701         )
 702     case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
 703     case.execute()
 704     #
 705     # Exploitation indépendante
 706     # -------------------------
 707     Xbackground   = case.get("Background")
 708     Xoptimum      = case.get("Analysis")[-1]
 709     FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
 710     J_values      = case.get("CostFunctionJ")[:]
 711     print("")
 712     print("Nombre d'itérations internes...: %i"%len(J_values))
 713     print("Etat initial...................: %s"%(numpy.ravel(Xbackground),))
 714     print("Etat optimal...................: %s"%(numpy.ravel(Xoptimum),))
 715     print("Simulation à l'état optimal....: %s"%(numpy.ravel(FX_at_optimum),))
 716     print("")
 717
 718 L'exécution de jeu de commandes donne le résultat suivant::
 719
 720     CurrentState [ 5.  7.  9.]
 721     CurrentState [ 0.   3.   1.5]
 722     CurrentState [ 1.40006418  3.86705307  3.7061137 ]
 723     CurrentState [ 1.42580231  3.68474804  3.81008738]
 724     CurrentState [ 1.60220353  3.0677108   4.06146069]
 725     CurrentState [ 1.72517855  3.03296953  4.04915706]
 726     CurrentState [ 2.00010755  3.          4.00055409]
 727     CurrentState [ 1.99995528  3.          3.99996367]
 728     CurrentState [ 2.00000007  3.          4.00000011]
 729     CurrentState [ 2.  3.  4.]
 730
 731     Nombre d'itérations internes...: 10
 732     Etat initial...................: [ 5.  7.  9.]
 733     Etat optimal...................: [ 2.  3.  4.]
 734     Simulation à l'état optimal....: [  2.   6.  12.  20.]
 735
 736 Comme il se doit en expériences jumelles, avec une confiance majoritairement
 737 placée dans les observations, on constate que l'on retrouve bien les paramètres
 738 qui ont servi à construire artificiellement les observations.
 739
 740 .. Réconciliation de courbes à l'aide de MedCoupling
 741 .. +++++++++++++++++++++++++++++++++++++++++++++++++
 742
 743 .. Utilisation de fonctions de surveillance de type "observer"
 744 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 745
 746 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
 747 .. -----------------------------------------------------------------------------
 748
 749 .. [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.
 750
 751 .. [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.
 752
 753 .. [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.