2 Copyright (C) 2008-2024 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 elles-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 taille
149 :math:`n` et qui restitue en sortie un vecteur Numpy de taille :math:`p`.
150 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: set
361 **set** (*Concept,...*)
362 Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
363 commandes de ce paragraphe. Son premier argument est le nom du concept à
364 définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
365 s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
366 les commandes individuelles précédentes. Lors de l'usage de cette commande,
367 il est indispensable de nommer les arguments (par exemple "*Vector=...*").
369 .. index:: single: Background
370 .. index:: single: setBackground
372 **setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
373 Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
374 algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
375 comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
376 script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
377 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*". Si
378 on utilise un fichier de données par "*DataFile*" (en sélectionnant, en
379 colonne par défaut ou en ligne selon "*ColMajor*", toutes les variables par
380 défaut ou celles de la liste "*ColNames*"), le vecteur est de type
383 .. index:: single: BackgroundError
384 .. index:: single: setBackgroundError
386 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
387 Cette commande permet de définir la matrice :math:`\mathbf{B}` de
388 covariance des erreurs d'ébauche. La matrice peut être définie de manière
389 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
390 matrice diagonale dont on donne la variance unique sur la diagonale par
391 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
392 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
393 Si on la définit par un script dans "*Script*", la matrice est de type
394 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
395 selon que l'une de ces variables est placée à "*True*".
397 .. index:: single: CheckingPoint
398 .. index:: single: setCheckingPoint
400 **setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
401 Cette commande permet de définir un point courant :math:`\mathbf{x}`
402 utilisé pour un algorithme de vérification. Selon les algorithmes, on peut
403 le définir comme un vecteur simple par "*Vector*", ou comme une liste de
404 vecteurs par "*VectorSerie*". Si on le définit par un script dans
405 "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
406 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*". Si
407 on utilise un fichier de données par "*DataFile*" (en sélectionnant, en
408 colonne par défaut ou en ligne selon "*ColMajor*", toutes les variables par
409 défaut ou celles de la liste "*ColNames*"), le vecteur est de type
412 .. index:: single: ControlModel
413 .. index:: single: setControlModel
414 .. index:: single: ExtraArguments
416 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
417 Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
418 décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
419 d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
420 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
421 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
422 utilisées, comme décrit dans la section
423 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
424 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
425 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
426 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
427 Les paramètres de contrôle de l'approximation numérique de l'opérateur
428 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
429 dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
430 de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
431 "*CenteredFiniteDifference*" (similaires à celles de l'interface
432 graphique). Si l'opérateur nécessite des arguments fixes complémentaires,
433 ils peuvent être fournis par la variable "*ExtraArguments*" sous la forme
434 d'un dictionnaire de paramètres nommés.
436 .. index:: single: ControlInput
437 .. index:: single: setControlInput
439 **setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
440 Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
441 Selon les algorithmes, on peut le définir comme un vecteur simple par
442 "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
443 définit par un script dans "*Script*", le vecteur est de type "*Vector*"
444 (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
445 à "*True*". Si on utilise un fichier de données par "*DataFile*" (en
446 sélectionnant, en colonne par défaut ou en ligne selon "*ColMajor*", toutes
447 les variables par défaut ou celles de la liste "*ColNames*"), le vecteur
448 est de type "*Vector*".
450 .. index:: single: EvolutionError
451 .. index:: single: setEvolutionError
453 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
454 Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
455 covariance des erreurs d'évolution. La matrice peut être définie de manière
456 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
457 matrice diagonale dont on donne la variance unique sur la diagonale par
458 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
459 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
460 Si on la définit par un script dans "*Script*", la matrice est de type
461 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
462 selon que l'une de ces variables est placée à "*True*".
464 .. index:: single: EvolutionModel
465 .. index:: single: setEvolutionModel
466 .. index:: single: ExtraArguments
468 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
469 Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
470 décrit un pas élémentaire d'évolution de l'état :math:`\mathbf{x}`. Sa
471 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
472 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
473 utilisées, comme décrit dans la section
474 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
475 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
476 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
477 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
478 Les paramètres de contrôle de l'approximation numérique de l'opérateur
479 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
480 dictionnaire dans "*Parameters*". Les entrées potentielles de ce
481 dictionnaire de paramètres sont "*DifferentialIncrement*",
482 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
483 "*NumberOfProcesses*" (similaires à celles de l'interface graphique). Si
484 l'opérateur nécessite des paramètres fixes complémentaires en plus de
485 l'état :math:`\mathbf{x}`, ils peuvent être fournis par la variable
486 "*ExtraArguments*" sous la forme d'un dictionnaire de paramètres nommés.
488 .. index:: single: Observation
489 .. index:: single: setObservation
491 **setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
492 Cette commande permet de définir le vecteur d'observation
493 :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
494 vecteur simple par "*Vector*", ou comme une liste de vecteurs par
495 "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
496 est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
497 ces variables est placée à "*True*". Si on utilise un fichier de données
498 par "*DataFile*" (en sélectionnant, en colonne par défaut ou en ligne selon
499 "*ColMajor*", toutes les variables par défaut ou celles de la liste
500 "*ColNames*"), le vecteur est de type "*Vector*".
502 .. index:: single: ObservationError
503 .. index:: single: setObservationError
505 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
506 Cette commande permet de définir la matrice :math:`\mathbf{R}` de
507 covariance des erreurs d'observation. La matrice peut être définie de
508 manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
509 comme une matrice diagonale dont on donne la variance unique sur la
510 diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont
511 on donne le vecteur des variances situé sur la diagonale par
512 "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*",
513 la matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
514 "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
517 .. index:: single: ObservationOperator
518 .. index:: single: setObservationOperator
519 .. index:: single: ExtraArguments
521 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArguments, Stored*)
522 Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
523 transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
524 :math:`\mathbf{y}` qui sont à comparer aux observations
525 :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
526 ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
527 fonctionnelles peuvent être utilisées, comme décrit dans la section
528 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
529 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
530 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
531 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
532 Dans le cas où l'opérateur :math:`H` évalué en :math:`\mathbf{x}^b` est
533 disponible, il peut être donné en utilisant "*AppliedInXb*" et sera
534 considéré comme un vecteur. Les paramètres de contrôle de l'approximation
535 numérique de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être
536 renseignés par un dictionnaire dans "*Parameters*". Les entrées
537 potentielles de ce dictionnaire de paramètres sont
538 "*DifferentialIncrement*", "*CenteredFiniteDifference*",
539 "*EnableMultiProcessing*", "*NumberOfProcesses*" (similaires à celles de
540 l'interface graphique). Si l'opérateur nécessite des paramètres fixes
541 complémentaires en plus de l'état :math:`\mathbf{x}`, ils peuvent être
542 fournis par la variable "*ExtraArguments*" sous la forme d'un dictionnaire
543 de paramètres nommés.
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 Obtenir des informations sur le cas, le calcul ou le système
708 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
710 On peut obtenir de manière simple une **information agrégée sur le cas
711 d'étude** tel que défini par l'utilisateur, en utilisant directement la
712 commande "*print*" de Python sur le cas, à n'importe quelle étape lors de sa
713 construction. Par exemple :
715 .. literalinclude:: scripts/tui_example_07.py
718 dont le résultat est ici :
720 .. literalinclude:: scripts/tui_example_07.res
722 .. index:: single: callinfo
724 Une **information synthétique sur le nombre d'appels aux calculs d'opérateurs**
725 peut être dynamiquement obtenue par la commande "**callinfo()**". Ces calculs
726 d'opérateurs sont ceux définis par l'utilisateur dans un cas ADAO, pour les
727 opérateurs d'observation et d'évolution. Elle s'utilise après l'exécution du
728 calcul dans le cas ADAO, sachant que le résultat de cette commande est
729 simplement vide lorsqu'aucun calcul n'a été effectué :
732 from adao import adaoBuilder
733 case = adaoBuilder.New()
736 print(case.callinfo())
738 .. index:: single: sysinfo
740 Une **information synthétique sur le système** peut être obtenue par la
741 commande "**sysinfo()**", présente dans chaque cas de calcul ADAO. Elle
742 retourne dynamiquement des informations système et des détails sur les modules
743 Python utiles pour ADAO. Elle s'utilise de la manière suivante :
746 from adao import adaoBuilder
747 case = adaoBuilder.New()
748 print(case.sysinfo())
750 .. _subsection_tui_advanced:
752 Exemples plus avancés de cas de calcul TUI ADAO
753 -----------------------------------------------
755 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
756 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
759 Exploitation indépendante des résultats d'un cas de calcul
760 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
762 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
763 son exécution, puis la récupération des résultats pour ensuite enchaîner sur
764 une exploitation indépendante de ces résultats (cette dernière n'étant pas
765 décrite ici, puisque dépendante de l'utilisateur).
767 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
769 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
770 #. que l'on dispose d'observations nommées ``observations``,
771 #. 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,
772 #. 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.
774 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se place
775 dans un cas d'expériences jumelles (pour mémoire, voir la démarche
776 :ref:`section_methodology_twin`). Pour cela, on se donne par exemple les
777 entrées suivantes, parfaitement arbitraires, en construisant les observations
778 par simulation. Puis on résout le problème de recalage par le jeu de commandes
779 qui vient ensuite. Au final, l'ensemble du problème est posé et résolu par le
782 .. literalinclude:: scripts/tui_example_11.py
785 L'exécution de jeu de commandes donne les résultats suivants :
787 .. literalinclude:: scripts/tui_example_11.res
789 Comme il se doit en expériences jumelles, avec une confiance majoritairement
790 placée dans les observations, on constate que l'on retrouve bien les paramètres
791 qui ont servi à construire artificiellement les observations.
793 .. Réconciliation de courbes à l'aide de MedCoupling
794 .. +++++++++++++++++++++++++++++++++++++++++++++++++
796 .. Utilisation de fonctions de surveillance de type "observer"
797 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
799 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
800 .. -----------------------------------------------------------------------------
802 .. [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.
804 .. [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.
806 .. [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.
