2 Copyright (C) 2008-2015 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
28 ================================================================================
29 **[DocR]** Interface de programmation textuelle pour l'utilisateur (API/TUI)
30 ================================================================================
34 dans sa présente version, cette interface de programmation textuelle (TUI) est
35 expérimentale, et reste donc susceptible de changements dans les prochaines
38 Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de
39 son interface de programmation textuelle (API/TUI). Cette interface permet de
40 créer un objet de calcul de manière similaire à la construction d'un cas par
41 l'interface graphique (GUI). Dans le cas où l'on désire réaliser à la main le
42 cas de calcul TUI, on recommande de bien s'appuyer sur l'ensemble de la
43 documentation du module ADAO, et de se reporter si nécessaire à l'interface
44 graphique (GUI), pour disposer de l'ensemble des éléments permettant de
45 renseigner correctement les commandes. Les notions générales et termes utilisés
46 ici sont définis dans :ref:`section_theory`.
48 .. _subsection_tui_creating:
50 Création de cas de calcul TUI ADAO et exemples
51 ----------------------------------------------
53 .. _subsection_tui_example:
55 Un exemple simple de création d'un cas de calcul TUI ADAO
56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
58 Pour introduire l'interface TUI, on commence par un exemple simple mais complet
59 de cas de calcul ADAO. Toutes les données sont explicitement définies dans le
60 corps du script pour faciliter la lecture. L'ensemble des commandes est le
63 from numpy import array
65 case = adaoBuilder.New()
66 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
67 case.set( 'Background', Vector=[0, 1, 2] )
68 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
69 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
70 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
71 case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
72 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
75 Le résultat de l'exécution de ces commandes dans SALOME (que ce soit par la
76 commande "*shell*" de SALOME, dans la console Python de l'interface, ou par le
77 menu d'exécution d'un script) est le suivant::
79 Analysis [ 0.25000264 0.79999797 0.94999939]
81 Création détaillée d'un cas de calcul TUI ADAO
82 ++++++++++++++++++++++++++++++++++++++++++++++
84 On décrit ici plus en détail les différentes étapes de création d'un cas de
85 calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
86 l':ref:`subsection_tui_commands`.
88 L'initialisation et la création d'une étude se fait par les commandes suivantes,
89 le nom ``case`` de l'objet du cas de calcul TUI ADAO étant quelconque, au choix
92 from numpy import array
94 case = adaoBuilder.New()
96 Il est recommandé d'importer par principe le module ``numpy`` ou ses
97 constructeurs particuliers comme celui d'``array``, pour faciliter ensuite son
98 usage dans les commandes elle-mêmes.
100 Ensuite, le cas doit être construit par une préparation et un enregistrement des
101 données définissant l'étude. L'ordre de ces commande n'a pas d'importance, il
102 suffit que les concepts requis par l'algorithme utilisé soient présentes. On se
103 reportera à :ref:`section_reference` et à ses sous-parties pour avoir le détail
104 des commandes par algorithme. Ici, on définit successivement l'algorithme
105 d'assimilation de données ou d'optimisation choisi et ses paramètres, puis
106 l'ébauche :math:`\mathbf{x}^b` (nommée ``Background``) et sa covariance
107 d'erreurs :math:`\mathbf{B}` (nommée ``BackgroundError``), et enfin
108 l'observation :math:`\mathbf{y}^o` (nommée ``Observation``) et sa covariance
109 d'erreurs :math:`\mathbf{R}` (nommée ``ObservationError``)::
111 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
113 case.set( 'Background', Vector=[0, 1, 2] )
114 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
116 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
117 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
119 On remarque que l'on peut donner, en entrée des quantités vectorielles ou
120 matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou de
121 type ``array`` ou ``matrix`` de Numpy. Dans ces deux derniers cas, il faut
122 simplement importer le module Numpy avant.
124 On doit ensuite définir les opérateurs :math:`H` d'observation et éventuellement
125 :math:`M` d'évolution. Dans tous les cas, linéaire ou non-linéaire, on peut les
126 définir comme des fonctions. Dans le cas simple d'un opérateur linéaire, on peut
127 aussi le définir à l'aide de la matrice qui correspond à l'opérateur linéaire.
128 Dans le cas présent le plus simple d'opérateur linéaire, on utilise la syntaxe
129 suivante pour un opérateur de :math:`\mathbf{R}^3` sur lui-même::
131 case.ObservationOperator(Matrix = "1 0 0;0 2 0;0 0 3")
133 Dans le cas beaucoup plus courant d'un opérateur non-linéaire de
134 :math:`\mathbf{R}^n` dans :math:`\mathbf{R}^p`, il doit être préalablement
135 disponible sous la forme d'une fonction Python, connue dans l'espace de nommage
136 courant, qui prend en entrée un vecteur ``numpy`` (ou une liste ordonnée) de
137 taille :math:`n` et qui restitue en sortie un vecteur ``numpy`` de taille
138 :math:`p`. Lorsque seul l'opérateur non-linéaire est défini par l'argument
139 "*OneFunction*", son adjoint est directement établi de manière numérique et il
140 est paramétrable par l'argument "*Parameters*". L'exemple suivant montre une
141 fonction ``simulation`` (qui réalise ici le même opérateur linéaire que
142 ci-dessus) et l'enregistre dans le cas ADAO::
146 "Fonction de simulation H pour effectuer Y=H(X)"
147 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
148 __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
151 case.set( 'ObservationOperator',
152 OneFunction = simulation,
153 Parameters = {"DifferentialIncrement":0.01},
156 Pour connaître les résultats intermédiaire ou finaux du calcul du cas, on peut
157 ajouter des "*observer*", qui permettent d'associer l'exécution d'un script à
158 une variable intermédiaire ou finale du calcul. On se reportera à la description
159 de la manière d':ref:`section_advanced_observer`, et à la :ref:`section_reference`
160 pour savoir quelles sont les quantités observables. Cette association
161 d'"*observer*" avec une quantité existante se fait de manière similaire à la
162 définition des données du calcul::
164 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
166 Enfin, lorsque toutes les informations requises sont disponibles dans le cas
167 ``case`` de calcul ADAO, on peut en demander l'exécution de manière très
168 simple dans l'environnement de l'interpréteur Python::
172 Au final, on obtient le script très compact proposé précédemment dans
173 :ref:`subsection_tui_example`.
175 Fournir des données ou informations de calcul plus complexes
176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
178 Une telle interface s'écrivant en Python, il est possible d'utiliser toute la
179 puissance du langage pour entrer des données plus complexes qu'une déclaration
182 L'enregistrement des données d'entrées supporte différents types de variables,
183 mais surtout, ces entrées peuvent recevoir des variables courantes disponibles
184 dans l'espace de nommage du script. Il est donc aisé d'utiliser des variables
185 calculées préalablement ou obtenues par l'import de scripts "utilisateur". Si
186 par exemple les observations sont disponibles sous la forme d'une liste dans un
187 fichier Python externe nommé ``observations.py`` sous le nom ``table``, il
188 suffit de réaliser les opérations suivantes pour enregistrer les observations
189 dans le cas de calcul TUI ADAO::
191 from observations import table
192 case.set( 'Observation', Vector=table )
194 La première ligne importe la variable ``table`` depuis le fichier externe, et la
195 seconde enregistre directement cette table comme la donnée "*Observation*".
197 La simplicité de cet enregistrement montre bien la facilité d'obtenir les
198 données de calcul depuis des sources externes, fichiers ou flux informatiques
199 atteignables en Python. Comme d'habitude, il est recommandé à l'utilisateur de
200 vérifier ses données avant de les enregistrer dans le cas de calcul TUI ADAO
201 pour éviter les erreurs compliquées à corriger.
203 Obtenir et utiliser les résultats de calcul de manière plus riche
204 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
206 De la même manière, il est possible d'obtenir et traiter les résultats de calcul
207 de manière plus riche, pour enchaîner sur des post-traitements après le calcul
210 Les variables de résultats de calcul, ou les variables internes issues de
211 l'optimisation ou de l'assimilation de données, sont disponibles à travers la
212 méthode ``get`` du cas de calcul TUI ADAO, qui renvoie un objet de type liste de
213 la variable demandée. On se reportera aux :ref:`section_ref_output_variables`
214 pour une description détaillée sur ce sujet.
216 A titre d'exemple, on donne quelques lignes de script qui permettent d'obtenir
217 le nombre d'itérations de l'optimisation et la valeur optimale ainsi que sa
221 print " Nombre d'iterations :", len(case.get("CostFunctionJ"))
222 Xa = case.get("Analysis")
223 print " Analyse optimale :", Xa[-1]
224 print " Taille de l'analyse :", len(Xa[-1])
227 Ces lignes peuvent être très simplement additionnées à l'exemple initial de cas
228 de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
230 De même que pour l'entrée des données, la simplicité de récupération des
231 résultats permet d'envisager aisément des post-traitements enchaînés dans
232 SALOME, pour utiliser par exemple de la visualisation avec MatPlotLib ou PARAVIS
233 [PARAVIS]_, de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour d'autres
236 .. _subsection_tui_commands:
238 Ensemble des commandes disponibles en interface textuelle TUI
239 -------------------------------------------------------------
241 Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
242 courantes en Python pour la distinction entre ce qui est public, et ce qui est
243 privé ou réservé car relevant des détails d'implémentation. De manière pratique,
244 tout nom d'objet ou de fonction commençant par au moins un signe "_" est privé
245 au sens courant de programmation ("*private*"). Néanmoins, l'absence d'un tel
246 signe au début d'un nom ne le désigne pas comme public. De manière générale, en
247 Python, et contrairement à d'autres langages, on peut accéder aux objets ou aux
248 fonction privés. Cela peut parfois être utile, mais un tel usage dans vos codes
249 conduira à des plantages sans avertissement lors de futures versions. Il est
250 donc fortement recommandé de ne pas le faire.
252 Pour clarifier et faciliter l'utilisation du module pour du script, **cette
253 section définit donc l'interface de programmation (API) textuelle publique pour
254 l'utilisateur (TUI) de manière complète et limitative**. L'usage en script
255 d'objets ou fonctions ADAO autres que ceux qui sont définis ici est fortement
256 déconseillé, car cela conduira vraisemblablement à des plantages sans
257 avertissement lors de futures versions.
259 Syntaxes d'appel équivalentes pour les commandes TUI
260 ++++++++++++++++++++++++++++++++++++++++++++++++++++
262 La définition des données lors de la création de cas de calcul TUI ADAO supporte
263 **deux syntaxes entièrement équivalentes**. On peut :
265 - soit utiliser la commande ``set`` et comme premier argument le concept
266 ``XXXXX`` sur lequel appliquer la commande dont les arguments suivent,
267 - soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
270 Pour illustrer cette équivalence, on prend l'exemple des deux commandes
271 suivantes qui conduisent au même résultat::
273 case.set( 'Background', Vector=[0, 1, 2] )
277 case.setBackground( Vector=[0, 1, 2] )
279 Le choix de l'une ou l'autre des syntaxes est librement laissé à l'utilisateur,
280 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
281 commandes selon la seconde syntaxe.
283 Définir les données de calcul
284 +++++++++++++++++++++++++++++
286 Les commandes qui suivent permettent de définir les données d'un cas de calcul
287 TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux des
288 entrées en interface GUI, décrits dans la section des
289 :ref:`section_reference_entry` et en particulier par la
290 :ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs se
291 fait soit lors de leur définition, soit lors de l'exécution.
293 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
294 veut éventuellement la stocker la grandeur définie, pour en disposer en cours de
295 calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
296 recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
297 TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
298 dans l'espace de nommage courant du cas.
300 Les commandes disponibles sont les suivantes :
302 .. index:: single: setBackground
304 **setBackground** (*Vector, VectorSerie, Script, Stored*)
305 Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
306 algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
307 comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
308 script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
309 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
311 .. index:: single: setBackgroundError
313 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
314 Cette commande permet de définir la matrice :math:`\mathbf{B}` de
315 covariance des erreurs d'ébauche. La matrice peut être définie de manière
316 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
317 matrice diagonale dont on donne la variance unique sur la diagonale par
318 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
319 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
320 Si on la définit par un script dans "*Script*", la matrice est de type
321 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
322 selon que l'une de ces variables est placée à "*True*".
324 .. index:: single: setCheckingPoint
326 **setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
327 Cette commande permet de définir un point courant :math:`\mathbf{x}` utilisé
328 pour un algorithme de vérification. Selon les algorithmes, on peut le
329 définir comme un vecteur simple par "*Vector*", ou comme une liste de
330 vecteurs par "*VectorSerie*". Si on le définit par un script dans
331 "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
332 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
334 .. index:: single: setControlModel
336 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
337 Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
338 décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
339 d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
340 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
341 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
342 utilisées, comme décrit dans la section
343 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
344 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
345 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
346 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
347 Les paramètres de contrôle de l'approximation numérique de l'opérateur
348 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
349 dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
350 de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
351 "*CenteredFiniteDifference*" (similaires à celles de l'interface graphique).
353 .. index:: single: setControlInput
355 **setControlInput** (*Vector, VectorSerie, Script, Stored*)
356 Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
357 Selon les algorithmes, on peut le définir comme un vecteur simple par
358 "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
359 définit par un script dans "*Script*", le vecteur est de type "*Vector*"
360 (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
363 .. index:: single: setEvolutionError
365 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
366 Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
367 covariance des erreurs d'évolution. La matrice peut être définie de manière
368 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
369 matrice diagonale dont on donne la variance unique sur la diagonale par
370 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
371 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
372 Si on la définit par un script dans "*Script*", la matrice est de type
373 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
374 selon que l'une de ces variables est placée à "*True*".
376 .. index:: single: setEvolutionModel
378 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
379 Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
380 décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
381 de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
382 différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
383 la section :ref:`section_ref_operator_requirements`, et entrées par les
384 mots-clés "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une
385 définition par "*Script*", l'opérateur est de type "*Matrix*",
386 "*OneFunction*" ou "*ThreeFunctions*" selon que l'une de ces variables est
387 placée à "*True*". Les paramètres de contrôle de l'approximation numérique
388 de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être renseignés
389 par un dictionnaire dans "*Parameters*". Les entrées potentielles de ce
390 dictionnaire de paramètres sont "*DifferentialIncrement*",
391 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
392 "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
394 .. index:: single: setObservation
396 **setObservation** (*Vector, VectorSerie, Script, Stored*)
397 Cette commande permet de définir le vecteur d'observation
398 :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
399 vecteur simple par "*Vector*", ou comme une liste de vecteurs par
400 "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
401 est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
402 ces variables est placée à "*True*".
404 .. index:: single: setObservationError
406 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
407 Cette commande permet de définir la matrice :math:`\mathbf{R}` de
408 covariance des erreurs d'observation. La matrice peut être définie de
409 manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
410 comme une matrice diagonale dont on donne la variance unique sur la
411 diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on
412 donne le vecteur des variances situé sur la diagonale par
413 "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*", la
414 matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
415 "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
418 .. index:: single: setObservationOperator
420 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
421 Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
422 transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
423 :math:`\mathbf{y}` qui sont à comparer aux observations
424 :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
425 ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
426 fonctionnelles peuvent être utilisées, comme décrit dans la section
427 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
428 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
429 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
430 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
431 Les paramètres de contrôle de l'approximation numérique de l'opérateur
432 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
433 dictionnaire dans "*Parameters*". Les entrées potentielles de ce
434 dictionnaire de paramètres sont "*DifferentialIncrement*",
435 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
436 "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
438 .. index:: single: set
440 **set** (*Concept,...*)
441 Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
442 commandes de ce paragraphe. Son premier argument est le nom du concept à
443 définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
444 s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
445 les commandes individuelles précédentes. Lors de l'usage de cette commande,
446 il est indispensable de nommer les arguments (par exemple "*Vector=...*").
448 Paramétrer le calcul, les sorties, etc.
449 +++++++++++++++++++++++++++++++++++++++
451 .. index:: single: setAlgorithmParameters
453 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
454 Cette commande permet de choisir l'algorithme de calcul ou de vérification
455 par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
456 reportera utilement aux listes des :ref:`section_reference_assimilation` et
457 des :ref:`section_reference_checking`), et de définir les paramètres de
458 calcul par l'argument "*Parameters*". Dans le cas d'une définition par
459 "*Script*", le fichier indiqué doit contenir les deux variables
460 "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
463 .. index:: single: setDebug
466 Cette commande permet d'activer le mode d'information détaillé lors de
469 .. index:: single: setNoDebug
472 Cette commande permet de désactiver le mode d'information détaillé lors de
475 .. index:: single: setObserver
477 **setObserver** (*Variable, Template, String, Script, Info*)
478 Cette commande permet de définir un *observer* sur une variable courante ou
479 finale du calcul. On se reportera à la description de la manière
480 d':ref:`section_advanced_observer`, et à la :ref:`section_reference` pour
481 savoir quelles sont les quantités observables. On définit comme un
482 "*String*" le corps de l'*observer*, en utilisant une chaine de caractères
483 incluant si nécessaire des sauts de lignes. On recommande d'utiliser les
484 patrons disponibles par l'argument "*Template*". On dispose des patrons
485 simples suivants : "ValuePrinter", "ValueSeriePrinter", "ValueSaver",
486 "ValueSerieSaver", "ValuePrinterAndSaver", "ValueSeriePrinterAndSaver",
487 "ValueGnuPlotter", "ValueSerieGnuPlotter", "ValuePrinterAndGnuPlotter",
488 "ValueSeriePrinterAndGnuPlotter", "ValuePrinterSaverAndGnuPlotter",
489 "ValueSeriePrinterSaverAndGnuPlotter", "ValueMean", "ValueStandardError",
490 "ValueVariance", "ValueRMS". Dans le cas d'une définition par "*Script*", le
491 fichier indiqué doit contenir uniquement le corps de la fonction, comme
492 décrit dans la manière d':ref:`section_advanced_observer`.
497 .. index:: single: executePythonScheme
499 **executePythonScheme** ()
500 Cette commande lance le calcul complet dans l'environnement de
501 l'interpréteur Python courant, sans interaction avec YACS [YACS]_. Les
502 sorties standard et d'erreur sont celles de l'interpréteur Python. On
503 dispose si nécessaire du parallélisme interne des algorithmes dans ADAO et
504 du parallélisme interne du ou des codes de simulation utilisé.
506 .. .. index:: single: generateYACSscheme
508 .. **executeYACSScheme** (*File*)
509 .. Cete commande génère le schéma YACS [YACS]_ du cas de calcul dans le fichier
510 .. requis "*File*", et en lance l'exécution dans l'interpréteur YACS, comme on
511 .. peut le réaliser en utilisant l'éditeur standard de cas ADAO. Les sorties
512 .. standard et d'erreur sont celles de l'interpréteur YACS. On dispose si
513 .. nécessaire du parallélisme de noeuds et blocs dans YACS, du parallélisme
514 .. interne des algorithmes dans ADAO et du parallélisme interne du ou des codes
515 .. de simulation utilisé.
517 .. index:: single: execute
520 Cette commande est un raccourci utilisateur pour "*executePythonScheme*".
522 Obtenir séparément les résultats de calcul
523 ++++++++++++++++++++++++++++++++++++++++++
525 .. index:: single: get
528 Cette commande permet d'extraire explicitement les variables disponibles en
529 sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
530 scripting, par exemple en visualisation. Elle a pour argument le nom d'un
531 variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
532 d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
533 base. Pour connaître la liste des variables et les utiliser, on se
534 reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
535 fois aux :ref:`section_ref_output_variables` et aux documentations
536 individuelles des algorithmes.
538 Exemples plus avancés de cas de calcul TUI ADAO
539 -----------------------------------------------
541 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
542 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
545 Exploitation indépendante des résultats d'un cas de calcul
546 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
548 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
549 son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
550 exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
551 ici, puisque dépendante de l'utilisateur).
553 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
555 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
556 #. que l'on dispose d'observations nommées ``observations``,
557 #. que l'utilisateur dispose en Python d'une fonction de simulation physique appellée ``simulation``, préalablement (bien) testée, qui transforme les 3 paramètres en résultats similaires aux observations,
558 #. 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.
560 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
561 exemple les entrées suivantes, parfaitement arbitraires, en construisant les
562 observations par simulation pour se placer dans un cas d'expériences jumelles::
565 # Construction artificielle d'un exemple de données utilisateur
566 # -------------------------------------------------------------
571 alphamin, alphamax = 0., 10.
572 betamin, betamax = 3, 13
573 gammamin, gammamax = 1.5, 15.5
576 "Fonction de simulation H pour effectuer Y=H(X)"
578 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
579 __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
582 # Observations obtenues par simulation
583 # ------------------------------------
584 observations = simulation((2, 3, 4))
586 Le jeu de commandes que l'on peut utiliser est le suivant::
591 # Mise en forme des entrées
592 # -------------------------
593 Xb = (alpha, beta, gamma)
595 (alphamin, alphamax),
597 (gammamin, gammamax))
601 case = adaoBuilder.New()
603 'AlgorithmParameters',
607 "MaximumNumberOfSteps":100,
608 "StoreSupplementaryCalculations":[
611 "SimulatedObservationAtOptimum",
615 case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
616 case.set( 'Observation', Vector = numpy.array(observations) )
617 case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
618 case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
620 'ObservationOperator',
621 OneFunction = simulation,
622 Parameters = {"DifferentialIncrement":0.0001},
624 case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
627 # Exploitation indépendante
628 # -------------------------
629 Xbackground = case.get("Background")
630 Xoptimum = case.get("Analysis")[-1]
631 FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
632 J_values = case.get("CostFunctionJ")[:]
634 print "Nombre d'itérations internes...: %i"%len(J_values)
635 print "Etat initial...................:",numpy.ravel(Xbackground)
636 print "Etat optimal...................:",numpy.ravel(Xoptimum)
637 print "Simulation à l'état optimal....:",numpy.ravel(FX_at_optimum)
640 L'exécution de jeu de commandes donne le résultat suivant::
642 CurrentState [ 5. 7. 9.]
643 CurrentState [ 0. 3. 1.5]
644 CurrentState [ 1.40006418 3.86705307 3.7061137 ]
645 CurrentState [ 1.42580231 3.68474804 3.81008738]
646 CurrentState [ 1.60220353 3.0677108 4.06146069]
647 CurrentState [ 1.72517855 3.03296953 4.04915706]
648 CurrentState [ 2.00010755 3. 4.00055409]
649 CurrentState [ 1.99995528 3. 3.99996367]
650 CurrentState [ 2.00000007 3. 4.00000011]
651 CurrentState [ 2. 3. 4.]
653 Nombre d'itérations internes...: 10
654 Etat initial...................: [ 5. 7. 9.]
655 Etat optimal...................: [ 2. 3. 4.]
656 Simulation à l'état optimal....: [ 2. 6. 12. 20.]
658 Comme il se doit en expériences jumelles, on constate que l'on retouve bien les
659 paramètres qui ont servi à construire artificiellement les observations.
661 .. Réconciliation de courbes à l'aide de MedCoupling
662 .. +++++++++++++++++++++++++++++++++++++++++++++++++
664 .. Utilisation de fonctions de surveillance de type "observer"
665 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
667 .. Suivre d'un recalage à l'aide de MatPlotLib
668 .. +++++++++++++++++++++++++++++++++++++++++++
670 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
671 .. -----------------------------------------------------------------------------
673 .. [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.
675 .. [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.
677 .. [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.