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