doc/fr/tui.rst

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