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