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