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 sont disponibles à travers la méthode ``get`` du cas de calcul TUI
212 ADAO, qui renvoie un objet de type liste de la variable demandée. On se
213 reportera aux :ref:`section_ref_output_variables` pour une description détaillée
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, pour
232 utiliser par exemple de la visualisation avec MatPlotLib ou PARAVIS [PARAVIS]_,
233 de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour d'autres calculs.
235 .. _subsection_tui_commands:
237 Ensemble des commandes disponibles en interface textuelle TUI
238 -------------------------------------------------------------
240 Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
241 courantes en Python pour la distinction entre ce qui est public, et ce qui est
242 privé ou réservé car relevant des détails d'implémentation. De manière pratique,
243 tout nom d'objet ou de fonction commençant par au moins un signe "_" est privé
244 au sens courant de programmation ("*private*"). Néanmoins, l'absence d'un tel
245 signe au début d'un nom ne le désigne pas comme public. De manière générale, en
246 Python, et contrairement à d'autres langages, on peut accéder aux objets ou aux
247 fonction privés. Cela peut parfois être utile, mais un tel usage dans vos codes
248 conduira à des plantages sans avertissement lors de futures versions. Il est
249 donc fortement recommandé de ne pas le faire.
251 Pour clarifier et faciliter l'utilisation du module pour du script, **cette
252 section définit donc l'interface de programmation (API) textuelle publique pour
253 l'utilisateur (TUI) de manière complète et limitative**. L'usage en script
254 d'objets ou fonctions ADAO autres que ceux qui sont définis ici est fortement
255 déconseillé, car cela conduira vraisemblablement à des plantages sans
256 avertissement lors de futures versions.
258 Syntaxes d'appel équivalentes pour les commandes TUI
259 ++++++++++++++++++++++++++++++++++++++++++++++++++++
261 La définition des données lors de la création de cas de calcul TUI ADAO supporte
262 **deux syntaxes entièrement équivalentes**. On peut :
264 - soit utiliser la commande ``set`` et comme premier argument le concept
265 ``XXXXX`` sur laquelle appliquer la commande dont les arguments suivent,
266 - soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
269 Pour illustrer cette équivalence, on prend l'exemple des deux commandes
270 suivantes qui conduisent au même résultat::
272 case.set( 'Background', Vector=[0, 1, 2] )
276 case.setBackground( Vector=[0, 1, 2] )
278 Le choix de l'une ou l'autre des syntaxes est librement laissé à l'utilisateur,
279 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
280 commandes selon la seconde syntaxe.
282 Définir les données de calcul
283 +++++++++++++++++++++++++++++
285 Les commandes qui suivent permettent de définir les données d'un cas de calcul
286 TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux des
287 entrées en interface GUI, décrits dans la section des
288 :ref:`section_reference_entry` et en particulier par la
289 :ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs se
290 fait soit lors de leur définition, soit lors de l'exécution.
292 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
293 veut éventuellement la stocker la grandeur définie pour en disposer en en cours
294 de calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
295 recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
296 TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
297 dans l'espace de nommage courant du cas.
299 Les commandes disponibles sont les suivantes :
301 .. index:: single: setBackground
303 **setBackground** (*Vector, VectorSerie, Script, Stored*)
304 Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
305 algorithmes, on peut le définir comme un vecteur simple par "*Vector*", ou
306 comme une liste de vecteurs par "*VectorSerie*". Si on le définit par un
307 script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
308 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
310 .. index:: single: setBackgroundError
312 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
313 Cette commande permet de définir la matrice :math:`\mathbf{B}` des
314 covariance des erreurs d'ébauche. La matrice peut être définie de manière
315 complète par "*Matrix*", ou de manière parcimonieuse comme une matrice
316 diagonale dont on donne la variance unique sur la diagonale par
317 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
318 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
319 Si on la définit par un script dans "*Script*", la matrice est de type
320 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
321 selon que l'une de ces variables est placée à "*True*".
323 .. index:: single: setCheckingPoint
325 **setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
326 Cette commande permet de définir un point courant :math:`\mathbf{x}` utilisé
327 pour un algorithme de vérification. Selon les algorithmes, on peut le
328 définir comme un vecteur simple par "*Vector*", ou comme une liste de
329 vecteurs par "*VectorSerie*". Si on le définit par un script dans
330 "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
331 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
333 .. index:: single: setControlModel
335 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
336 Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
337 décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
338 d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
339 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
340 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
341 utilisées, comme décrit dans la section
342 :ref:`section_ref_operator_requirements`, et entrées par "*OneFunction*" ou
343 "*ThreeFunctions*". Dans le cas d'une définition par "*Script*", l'opérateur
344 est de type "*Matrix*", "*OneFunction*" ou "*ThreeFunctions*" selon que
345 l'une de ces variables est placée à "*True*". Les paramètres de contrôle de
346 l'approximation numérique de l'opérateur adjoint, dans le cas
347 "*OneFunction*", peuvent être renseignés par un dictionnaire dans
348 "*Parameters*". Les entrées potentielles de ce dictionnaire de paramètres
349 sont "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similaires à
350 celles de l'interface graphique).
352 .. index:: single: setControlInput
354 **setControlInput** (*Vector, VectorSerie, Script, Stored*)
355 Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
356 Selon les algorithmes, on peut le définir comme un vecteur simple par
357 "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
358 définit par un script dans "*Script*", le vecteur est de type "*Vector*"
359 (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
362 .. index:: single: setEvolutionError
364 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
365 Cette commande permet de définir la matrice :math:`\mathbf{Q}` des
366 covariance des erreurs d'évolution. La matrice peut être définie de manière
367 complète par "*Matrix*", ou de manière parcimonieuse comme une matrice
368 diagonale dont on donne la variance unique sur la diagonale par
369 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
370 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
371 Si on la définit par un script dans "*Script*", la matrice est de type
372 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
373 selon que l'une de ces variables est placée à "*True*".
375 .. index:: single: setEvolutionModel
377 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
378 Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
379 décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
380 de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
381 différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
382 la section :ref:`section_ref_operator_requirements`, et entrées par
383 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
384 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
385 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
386 Les paramètres de contrôle de l'approximation numérique de l'opérateur
387 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
388 dictionnaire dans "*Parameters*". Les entrées potentielles de ce
389 dictionnaire de paramètres sont "*DifferentialIncrement*",
390 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
391 "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
393 .. index:: single: setObservation
395 **setObservation** (*Vector, VectorSerie, Script, Stored*)
396 Cette commande permet de définir le vecteur d'observation
397 :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
398 vecteur simple par "*Vector*", ou comme une liste de vecteurs par
399 "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
400 est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
401 ces variables est placée à "*True*".
403 .. index:: single: setObservationError
405 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
406 Cette commande permet de définir la matrice :math:`\mathbf{R}` des
407 covariance des erreurs d'observation. La matrice peut être définie de
408 manière complète par "*Matrix*", ou de manière parcimonieuse comme une
409 matrice diagonale dont on donne la variance unique sur la diagonale par
410 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
411 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
412 Si on la définit par un script dans "*Script*", la matrice est de type
413 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
414 selon que l'une de ces variables est placée à "*True*".
416 .. index:: single: setObservationOperator
418 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
419 Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
420 transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
421 :math:`\mathbf{y}` qui sont à comparer aux observations
422 :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
423 ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
424 fonctionnelles peuvent être utilisées, comme décrit dans la section
425 :ref:`section_ref_operator_requirements`, et entrées par "*OneFunction*" ou
426 "*ThreeFunctions*". Dans le cas d'une définition par "*Script*", l'opérateur
427 est de type "*Matrix*", "*OneFunction*" ou "*ThreeFunctions*" selon que
428 l'une de ces variables est placée à "*True*". Les paramètres de contrôle de
429 l'approximation numérique de l'opérateur adjoint, dans le cas
430 "*OneFunction*", peuvent être renseignés par un dictionnaire dans
431 "*Parameters*". Les entrées potentielles de ce dictionnaire de paramètres
432 sont "*DifferentialIncrement*", "*CenteredFiniteDifference*",
433 "*EnableMultiProcessing*", "*NumberOfProcesses*" (similaires à celles de
434 l'interface graphique).
436 .. index:: single: set
438 **set** (*Concept,...*)
439 Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
440 commandes de ce paragraphe. Son premier argument est le nom du concept à
441 définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
442 s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
443 les commandes individuelles précédentes. Lors de l'usage de cette commande,
444 il est indispensable de nommer les arguments (par exemple "*Vector=...*").
446 Paramétrer le calcul, les sorties, etc.
447 +++++++++++++++++++++++++++++++++++++++
449 .. index:: single: setAlgorithmParameters
451 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
452 Cette commande permet de choisir l'algorithme de calcul ou de vérification
453 par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
454 reportera utilement aux listes des :ref:`section_reference_assimilation` et
455 des :ref:`section_reference_checking`), et de définir les paramètres de
456 calcul par l'argument "*Parameters*". Dans le cas d'une définition par
457 "*Script*", le fichier indiqué doit contenir les deux variables
458 "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
461 .. index:: single: setDebug
464 Cette commande permet d'activer le mode d'information détaillé lors de
467 .. index:: single: setNoDebug
470 Cette commande permet de désactiver le mode d'information détaillé lors de
473 .. index:: single: setObserver
475 **setObserver** (*Variable, Template, String, Script, Info*)
476 Cette commande permet de définir un observer sur une variable courante ou
477 finale du calcul. On se reportera à la description de la manière
478 d':ref:`section_advanced_observer`, et à la :ref:`section_reference` pour
479 savoir quelles sont les quantités observables. On définit par "*String*" le
480 corps de l'observer par une chaine de caractères incluant si nécessaire des
481 sauts de lignes. On recommande d'utiliser les patrons disponibles par
482 l'argument "*Template*". On dispose des patrons simples suivants :
483 "*ValuePrinter*", "*ValueSeriePrinter*", "*ValueSaver*",
484 "*ValueSerieSaver*", "*ValuePrinterAndSaver*",
485 "*ValueSeriePrinterAndSaver*", "*ValueGnuPlotter*",
486 "*ValueSerieGnuPlotter*". Dans le cas d'une définition par "*Script*", le
487 fichier indiqué doit contenir uniquement le corps de la fonction, comme
488 décrit dans la manière d':ref:`section_advanced_observer`.
493 .. index:: single: executePythonScheme
495 **executePythonScheme** ()
496 Cette commande lance le calcul complet dans l'environnement de
497 l'interpréteur Python courant, sans interaction avec YACS. Les sorties
498 standard et d'erreur sont celles de l'interpréteur Python. On dispose si
499 nécessaire du parallélisme interne des algorithmes dans ADAO et du
500 parallélisme interne du ou des codes de simulation utilisé.
502 .. .. index:: single: generateYACSscheme
504 .. **executeYACSScheme** (*File*)
505 .. Cete commande génère le schéma YACS [YACS]_ du cas de calcul dans le fichier
506 .. requis "*File*", et en lance l'exécution dans l'interpréteur YACS, comme on
507 .. peut le réaliser en utilisant l'éditeur standard de cas ADAO. Les sorties
508 .. standard et d'erreur sont celles de l'interpréteur YACS. On dispose si
509 .. nécessaire du parallélisme de noeuds et blocs dans YACS, du parallélisme
510 .. interne des algorithmes dans ADAO et du parallélisme interne du ou des codes
511 .. de simulation utilisé.
513 .. index:: single: execute
516 Cette commande est un raccourci utilisateur pour "*executePythonScheme*".
518 Obtenir séparément les résultats de calcul
519 ++++++++++++++++++++++++++++++++++++++++++
521 .. index:: single: get
524 Cette commande permet d'extraire explicitement les variables disponibles en
525 sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
526 scripting, par exemple en visualisation. Elle a pour argument le nom d'un
527 variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
528 d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
529 base. Pour connaître la liste des variables et les utiliser, on se
530 reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
531 fois aux :ref:`section_ref_output_variables` et aux documentations
532 individuelles des algorithmes.
534 Exemples plus avancés de cas de calcul TUI ADAO
535 -----------------------------------------------
537 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
538 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
541 Exploitation indépendante des résultats d'un cas de calcul
542 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
544 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
545 son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
546 exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
547 ici, puisque dépendante de l'utilisateur).
549 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
551 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
552 #. que l'on dispose d'observations nommées ``observations``,
553 #. que l'utilisateur dispose en Python d'une fonction de simulation physique appellée ``simulation`` préalablement testée, qui transforme les 3 paramètres en résultats similaires aux observations,
554 #. 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.
556 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
557 exemple les entrées suivantes, parfaitement arbitraires, en construisant les
558 observations par simulation pour se placer dans un cas d'expériences jumelles::
561 # Construction artificielle d'un exemple de données utilisateur
562 # -------------------------------------------------------------
567 alphamin, alphamax = 0., 10.
568 betamin, betamax = 3, 13
569 gammamin, gammamax = 1.5, 15.5
572 "Fonction de simulation H pour effectuer Y=H(X)"
574 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
575 __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
578 # Observations obtenues par simulation
579 # ------------------------------------
580 observations = simulation((2, 3, 4))
582 Le jeu de commandes que l'on peut utiliser est le suivant::
587 # Mise en forme des entrées
588 # -------------------------
589 Xb = (alpha, beta, gamma)
591 (alphamin, alphamax),
593 (gammamin, gammamax))
597 case = adaoBuilder.New()
599 'AlgorithmParameters',
603 "MaximumNumberOfSteps":100,
604 "StoreSupplementaryCalculations":[
607 "SimulatedObservationAtOptimum",
611 case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
612 case.set( 'Observation', Vector = numpy.array(observations) )
613 case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
614 case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
616 'ObservationOperator',
617 OneFunction = simulation,
618 Parameters = {"DifferentialIncrement":0.0001},
620 case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
623 # Exploitation indépendante
624 # -------------------------
625 Xbackground = case.get("Background")
626 Xoptimum = case.get("Analysis")[-1]
627 FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
628 J_values = case.get("CostFunctionJ")[:]
630 print "Nombre d'itérations internes...: %i"%len(J_values)
631 print "Etat initial...................:",numpy.ravel(Xbackground)
632 print "Etat optimal...................:",numpy.ravel(Xoptimum)
633 print "Simulation à l'état optimal....:",numpy.ravel(FX_at_optimum)
636 L'exécution de jeu de commandes donne le résultat suivant::
638 CurrentState [ 5. 7. 9.]
639 CurrentState [ 0. 3. 1.5]
640 CurrentState [ 1.40006418 3.86705307 3.7061137 ]
641 CurrentState [ 1.42580231 3.68474804 3.81008738]
642 CurrentState [ 1.60220353 3.0677108 4.06146069]
643 CurrentState [ 1.72517855 3.03296953 4.04915706]
644 CurrentState [ 2.00010755 3. 4.00055409]
645 CurrentState [ 1.99995528 3. 3.99996367]
646 CurrentState [ 2.00000007 3. 4.00000011]
647 CurrentState [ 2. 3. 4.]
649 Nombre d'itérations internes...: 10
650 Etat initial...................: [ 5. 7. 9.]
651 Etat optimal...................: [ 2. 3. 4.]
652 Simulation à l'état optimal....: [ 2. 6. 12. 20.]
654 Comme il se doit en expériences jumelles, on constate que l'on retouve bien les
655 paramètres qui ont servi à construire artificiellement les observations.
657 .. Réconciliation de courbes à l'aide de MedCoupling
658 .. +++++++++++++++++++++++++++++++++++++++++++++++++
660 .. Utilisation de fonctions de surveillance de type "observer"
661 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
663 .. Suivre d'un recalage à l'aide de MatPlotLib
664 .. +++++++++++++++++++++++++++++++++++++++++++
666 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
667 .. -----------------------------------------------------------------------------
669 .. [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.
671 .. [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.
673 .. [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.