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 des objets
120 de type ``list``, ``tuple``, ``array`` ou ``matrix`` de Numpy. Dans ces deux
121 derniers cas, il faut simplement importer Numpy avant.
123 On doit ensuite définir les opérateurs :math:`H` d'observation et éventuellement
124 :math:`M` d'évolution. Dans tous les cas, linéaire ou non-linéaire, on peut les
125 définir comme des fonctions. Dans le cas simple d'un opérateur linéaire, on peut
126 aussi le définir à l'aide de la matrice qui correspond à l'opérateur linéaire.
127 Dans le cas présent le plus simple d'opérateur linéaire, on utilise la syntaxe
128 suivante pour un opérateur de :math:`\mathbf{R}^3` sur lui-même::
130 case.ObservationOperator(Matrix = "1 0 0;0 2 0;0 0 3")
132 Dans le cas beaucoup plus courant d'un opérateur non-linéaire de
133 :math:`\mathbf{R}^n` dans :math:`\mathbf{R}^p`, il doit être préalablement
134 disponible sous la forme d'une fonction Python, connue dans l'espace de nommage
135 courant, qui prend en entrée un vecteur ``numpy`` (ou une liste ordonnée) de
136 taille :math:`n` et qui restitue en sortie un vecteur ``numpy`` de taille
137 :math:`p`. Lorsque seul l'opérateur non-linéaire est défini par l'argument
138 "*OneFunction*", son adjoint est directement établi de manière numérique et il
139 est paramétrable par l'argument "*Parameters*". L'exemple suivant montre une
140 fonction ``simulation`` (qui réalise ici le même opérateur linéaire que
141 ci-dessus) et l'enregistre dans le cas ADAO::
145 "Fonction de simulation H pour effectuer Y=H(X)"
146 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
147 __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
150 case.set( 'ObservationOperator',
151 OneFunction = simulation,
152 Parameters = {"DifferentialIncrement":0.01},
155 Pour connaître les résultats intermédiaire ou finaux du calcul du cas, on peut
156 ajouter des "*observer*", qui permettent d'associer l'exécution d'un script à
157 une variable interne ou finale du calcul. On se reportera à la description de la
158 manière d':ref:`section_advanced_observer`, et à la :ref:`section_reference`
159 pour savoir quelles sont les quantités observables. Cette association
160 d'"*observer*" avec une quantité existante se fait de manière similaire à la
161 définition des données du calcul::
163 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
165 Enfin, lorsque toutes les informations requises sont disponibles dans le cas
166 ``case`` de calcul ADAO, on peut en demander l'exécution de manière très
167 simple dans l'environnement de l'interpréteur Python::
171 Au final, on obtient le script très compact proposé précédemment dans
172 :ref:`subsection_tui_example`.
174 Fournir des données de calcul plus complexes
175 ++++++++++++++++++++++++++++++++++++++++++++
177 Une telle interface s'écrivant en Python, il est possible d'utiliser toute la
178 puissance du langage pour entrer des données plus complexes qu'une déclaration
181 L'enregistrement des données d'entrées supporte différents types de variables,
182 mais surtout, ces entrées peuvent recevoir des variables courantes disponibles
183 dans l'espace de nommage du script. Il est donc aisé d'utiliser des variables
184 calculées préalablement ou obtenues par l'import de scripts "utilisateur". Si
185 par exemple les observations sont disponibles sous la forme d'une liste dans un
186 fichier Python externe nommé ``observations.py`` sous le nom ``table``, il
187 suffit de réaliser les opérations suivantes pour enregistrer les observations
188 dans le cas de calcul TUI ADAO::
190 from observations import table
191 case.set( 'Observation', Vector=table )
193 La première ligne importe la variable ``table`` depuis le fichier externe, et la
194 seconde enregistre directement cette table comme la donnée "*Observation*".
196 La simplicité de cet enregistrement montre bien la facilité d'obtenir les
197 données de calcul depuis des sources externes, fichiers ou flux informatiques
198 atteignables en Python. Comme d'habitude, il est recommandé à l'utilisateur de
199 vérifier ses données avant de les enregistrer dans le cas de calcul TUI ADAO
200 pour éviter les erreurs compliquées à corriger.
202 Obtenir et utiliser les résultats de calcul de manière plus riche
203 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
205 De la même manière, il est possible d'obtenir et traiter les résultats de calcul
206 de manière plus riche, pour enchaîner sur des post-traitements après le calcul
209 Les variables de résultats de calcul, ou les variables internes issues de
210 l'optimisation sont disponibles à travers la méthode ``get`` du cas de calcul TUI
211 ADAO, qui renvoie un objet de type liste de la variable demandée. On se
212 reportera aux :ref:`section_ref_output_variables` pour une description détaillée
215 A titre d'exemple, on donne quelques lignes de script qui permettent d'obtenir
216 le nombre d'itérations de l'optimisation et la valeur optimale ainsi que sa
220 print " Nombre d'iterations :", len(case.get("CostFunctionJ"))
221 Xa = case.get("Analysis")
222 print " Analyse optimale :", Xa[-1]
223 print " Taille de l'analyse :", len(Xa[-1])
226 Ces lignes peuvent être très simplement additionnées à l'exemple initial de cas
227 de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
229 De même que pour l'entrée des données, la simplicité de récupération des
230 résultats permet d'envisager aisément des post-traitements enchaînés, pour
231 utiliser par exemple de la visualisation avec MatPlotLib ou PARAVIS [PARAVIS]_,
232 de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour d'autres calculs.
234 .. _subsection_tui_commands:
236 Ensemble des commandes disponibles en interface textuelle TUI
237 -------------------------------------------------------------
239 Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
240 courantes en Python pour la distinction entre ce qui est public, et ce qui est
241 privé ou réservé car relevant des détails d'implémentation. De manière pratique,
242 tout nom d'objet ou de fonction commençant par au moins un signe "_" est privé
243 au sens courant de programmation ("*private*"). Néanmoins, l'absence d'un tel
244 signe au début d'un nom ne le désigne pas comme public. De manière générale, en
245 Python, et contrairement à d'autres langages, on peut accéder aux objets ou aux
246 fonction privés. Cela peut parfois être utile, mais un tel usage dans vos codes
247 conduira à des plantages sans avertissement lors de futures versions. Il est
248 donc fortement recommandé de ne pas le faire.
250 Pour clarifier et faciliter l'utilisation du module pour du script, **cette
251 section définit donc l'interface de programmation (API) textuelle publique pour
252 l'utilisateur (TUI) de manière complète et limitative**. L'usage en script
253 d'objets ou fonctions ADAO autres que ceux qui sont définis ici est fortement
254 déconseillé, car cela conduira vraisemblablement à des plantages sans
255 avertissement lors de futures versions.
257 Syntaxes d'appel équivalentes pour les commandes TUI
258 ++++++++++++++++++++++++++++++++++++++++++++++++++++
260 La définition des données lors de la création de cas de calcul TUI ADAO supporte
261 **deux syntaxes entièrement équivalentes**. On peut :
263 - soit utiliser la commande ``set`` et comme premier argument le concept
264 ``XXXXX`` sur laquelle appliquer la commande dont les arguments suivent,
265 - soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
268 Pour illustrer cette équivalence, on prend l'exemple des deux commandes
269 suivantes qui conduisent au même résultat::
271 case.set( 'Background', Vector=[0, 1, 2] )
275 case.setBackground( Vector=[0, 1, 2] )
277 Le choix de l'une ou l'autre des syntaxes est librement laissé à l'utilisateur,
278 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
279 commandes selon la seconde syntaxe.
281 Définir les données de calcul
282 +++++++++++++++++++++++++++++
284 Les commandes qui suivent permettent de définir les données d'un cas de calcul
285 TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux des
286 entrées en interface GUI, décrits dans la section des
287 :ref:`section_reference_entry` et en particulier par la
288 :ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs se
289 fait soit lors de leur définition, soit lors de l'exécution.
291 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
292 veut éventuellement la stocker la grandeur définie pour en disposer en en cours
293 de calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
294 recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
295 TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
296 dans l'espace de nommage courant du cas.
298 Les commandes disponibles sont les suivantes :
300 .. index:: single: setBackground
302 **setBackground** (*Vector, VectorSerie, Script, Stored*)
303 Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
304 algorithmes, on peut le définir comme un vecteur simple par "*Vector*", ou
305 comme une liste de vecteurs par "*VectorSerie*". Si on le définit par un
306 script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
307 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
309 .. index:: single: setBackgroundError
311 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
312 Cette commande permet de définir la matrice :math:`\mathbf{B}` des
313 covariance des erreurs d'ébauche. La matrice peut être définie de manière
314 complète par "*Matrix*", ou de manière parcimonieuse comme une matrice
315 diagonale dont on donne la variance unique sur la diagonale par
316 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
317 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
318 Si on la définit par un script dans "*Script*", la matrice est de type
319 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
320 selon que l'une de ces variables est placée à "*True*".
322 .. index:: single: setCheckingPoint
324 **setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
325 Cette commande permet de définir un point courant :math:`\mathbf{x}` utilisé
326 pour un algorithme de vérification. Selon les algorithmes, on peut le
327 définir comme un vecteur simple par "*Vector*", ou comme une liste de
328 vecteurs par "*VectorSerie*". Si on le définit par un script dans
329 "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
330 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
332 .. index:: single: setControlModel
334 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
335 Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
336 décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
337 d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
338 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
339 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
340 utilisées, comme décrit dans la section
341 :ref:`section_ref_operator_requirements`, et entrées par "*OneFunction*" ou
342 "*ThreeFunctions*". Dans le cas d'une définition par "*Script*", l'opérateur
343 est de type "*Matrix*", "*OneFunction*" ou "*ThreeFunctions*" selon que
344 l'une de ces variables est placée à "*True*". Les paramètres de contrôle de
345 l'approximation numérique de l'opérateur adjoint, dans le cas
346 "*OneFunction*", peuvent être renseignés par un dictionnaire dans
347 "*Parameters*". Les entrées potentielles de ce dictionnaire de paramètres
348 sont "*DifferentialIncrement*", "*CenteredFiniteDifference*" (similaires à
349 celles de l'interface graphique).
351 .. index:: single: setControlInput
353 **setControlInput** (*Vector, VectorSerie, Script, Stored*)
354 Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
355 Selon les algorithmes, on peut le définir comme un vecteur simple par
356 "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
357 définit par un script dans "*Script*", le vecteur est de type "*Vector*"
358 (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
361 .. index:: single: setEvolutionError
363 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
364 Cette commande permet de définir la matrice :math:`\mathbf{Q}` des
365 covariance des erreurs d'évolution. La matrice peut être définie de manière
366 complète par "*Matrix*", ou de manière parcimonieuse comme une matrice
367 diagonale dont on donne la variance unique sur la diagonale par
368 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
369 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
370 Si on la définit par un script dans "*Script*", la matrice est de type
371 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
372 selon que l'une de ces variables est placée à "*True*".
374 .. index:: single: setEvolutionModel
376 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
377 Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
378 décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
379 de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
380 différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
381 la section :ref:`section_ref_operator_requirements`, et entrées par
382 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
383 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
384 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
385 Les paramètres de contrôle de l'approximation numérique de l'opérateur
386 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
387 dictionnaire dans "*Parameters*". Les entrées potentielles de ce
388 dictionnaire de paramètres sont "*DifferentialIncrement*",
389 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
390 "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
392 .. index:: single: setObservation
394 **setObservation** (*Vector, VectorSerie, Script, Stored*)
395 Cette commande permet de définir le vecteur d'observation
396 :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
397 vecteur simple par "*Vector*", ou comme une liste de vecteurs par
398 "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
399 est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
400 ces variables est placée à "*True*".
402 .. index:: single: setObservationError
404 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
405 Cette commande permet de définir la matrice :math:`\mathbf{R}` des
406 covariance des erreurs d'observation. La matrice peut être définie de
407 manière complète par "*Matrix*", ou de manière parcimonieuse comme une
408 matrice diagonale dont on donne la variance unique sur la diagonale par
409 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
410 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
411 Si on la définit par un script dans "*Script*", la matrice est de type
412 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
413 selon que l'une de ces variables est placée à "*True*".
415 .. index:: single: setObservationOperator
417 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
418 Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
419 transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
420 :math:`\mathbf{y}` qui sont à comparer aux observations
421 :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
422 ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
423 fonctionnelles peuvent être utilisées, comme décrit dans la section
424 :ref:`section_ref_operator_requirements`, et entrées par "*OneFunction*" ou
425 "*ThreeFunctions*". Dans le cas d'une définition par "*Script*", l'opérateur
426 est de type "*Matrix*", "*OneFunction*" ou "*ThreeFunctions*" selon que
427 l'une de ces variables est placée à "*True*". Les paramètres de contrôle de
428 l'approximation numérique de l'opérateur adjoint, dans le cas
429 "*OneFunction*", peuvent être renseignés par un dictionnaire dans
430 "*Parameters*". Les entrées potentielles de ce dictionnaire de paramètres
431 sont "*DifferentialIncrement*", "*CenteredFiniteDifference*",
432 "*EnableMultiProcessing*", "*NumberOfProcesses*" (similaires à celles de
433 l'interface graphique).
435 .. index:: single: set
437 **set** (*Concept,...*)
438 Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
439 commandes de ce paragraphe. Son premier argument est le nom du concept à
440 définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
441 s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
442 les commandes individuelles précédentes. Lors de l'usage de cette commande,
443 il est indispensable de nommer les arguments (par exemple "*Vector=...*").
445 Paramétrer le calcul, les sorties, etc.
446 +++++++++++++++++++++++++++++++++++++++
448 .. index:: single: setAlgorithmParameters
450 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
451 Cette commande permet de choisir l'algorithme de calcul ou de vérification
452 par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
453 reportera utilement aux listes des :ref:`section_reference_assimilation` et
454 des :ref:`section_reference_checking`), et de définir les paramètres de
455 calcul par l'argument "*Parameters*". Dans le cas d'une définition par
456 "*Script*", le fichier indiqué doit contenir les deux variables
457 "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
460 .. index:: single: setDebug
463 Cette commande permet d'activer le mode d'information détaillé lors de
466 .. index:: single: setNoDebug
469 Cette commande permet de désactiver le mode d'information détaillé lors de
472 .. index:: single: setObserver
474 **setObserver** (*Variable, Template, String, Script, Info*)
475 Cette commande permet de définir un observer sur une variable courante ou
476 finale du calcul. On se reportera à la description de la manière
477 d':ref:`section_advanced_observer`, et à la :ref:`section_reference` pour
478 savoir quelles sont les quantités observables. On définit par "*String*" le
479 corps de l'observer par une chaine de caractères incluant si nécessaire des
480 sauts de lignes. On recommande d'utiliser les patrons disponibles par
481 l'argument "*Template*". On dispose des patrons simples suivants :
482 "*ValuePrinter*", "*ValueSeriePrinter*", "*ValueSaver*",
483 "*ValueSerieSaver*", "*ValuePrinterAndSaver*",
484 "*ValueSeriePrinterAndSaver*", "*ValueGnuPlotter*",
485 "*ValueSerieGnuPlotter*". Dans le cas d'une définition par "*Script*", le
486 fichier indiqué doit contenir uniquement le corps de la fonction, comme
487 décrit dans la manière d':ref:`section_advanced_observer`.
492 .. index:: single: executePythonScheme
494 **executePythonScheme** ()
495 Cette commande lance le calcul complet dans l'environnement de
496 l'interpréteur Python courant, sans interaction avec YACS. Les sorties
497 standard et d'erreur sont celles de l'interpréteur Python. On dispose si
498 nécessaire du parallélisme interne des algorithmes dans ADAO et du
499 parallélisme interne du ou des codes de simulation utilisé.
501 .. index:: single: generateYACSscheme
503 **executeYACSScheme** (*File*)
504 Cete commande génère le schéma YACS [YACS]_ du cas de calcul dans le fichier
505 requis "*File*", et en lance l'exécution dans l'interpréteur YACS, comme on
506 peut le réaliser en utilisant l'éditeur standard de cas ADAO. Les sorties
507 standard et d'erreur sont celles de l'interpréteur YACS. On dispose si
508 nécessaire du parallélisme de noeuds et blocs dans YACS, du parallélisme
509 interne des algorithmes dans ADAO et du parallélisme interne du ou des codes
510 de simulation utilisé.
512 .. index:: single: execute
515 Cette commande est un raccourci utilisateur pour "*executePythonScheme*".
517 Obtenir séparément les résultats de calcul
518 ++++++++++++++++++++++++++++++++++++++++++
520 .. index:: single: get
523 Cette commande permet d'extraire explicitement les variables disponibles en
524 sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
525 scripting, par exemple en visualisation. Elle a pour argument le nom d'un
526 variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
527 d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
528 base. Pour connaître la liste des variables et les utiliser, on se
529 reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
530 fois aux :ref:`section_ref_output_variables` et aux documentations
531 individuelles des algorithmes.
533 Exemples plus avancés de cas de calcul TUI ADAO
534 -----------------------------------------------
536 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
537 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
540 Exploitation indépendante des résultats d'un cas de calcul
541 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
543 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
544 son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
545 exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
546 ici, puisque dépendante de l'utilisateur).
548 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
550 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
551 #. que l'on dispose d'observations nommées ``observations``,
552 #. 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,
553 #. 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.
555 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
556 exemple les entrées suivantes, parfaitement arbitraires, en construisant les
557 observations par simulation pour se placer dans un cas d'expériences jumelles::
560 # Construction artificielle d'un exemple de données utilisateur
561 # -------------------------------------------------------------
566 alphamin, alphamax = 0., 10.
567 betamin, betamax = 3, 13
568 gammamin, gammamax = 1.5, 15.5
571 "Fonction de simulation H pour effectuer Y=H(X)"
573 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
574 __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
577 # Observations obtenues par simulation
578 # ------------------------------------
579 observations = simulation((2, 3, 4))
581 Le jeu de commandes que l'on peut utiliser est le suivant::
586 # Mise en forme des entrées
587 # -------------------------
588 Xb = (alpha, beta, gamma)
590 (alphamin, alphamax),
592 (gammamin, gammamax))
596 case = adaoBuilder.New()
598 'AlgorithmParameters',
602 "MaximumNumberOfSteps":100,
603 "StoreSupplementaryCalculations":[
606 "SimulatedObservationAtOptimum",
610 case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
611 case.set( 'Observation', Vector = numpy.array(observations) )
612 case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
613 case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
615 'ObservationOperator',
616 OneFunction = simulation,
617 Parameters = {"DifferentialIncrement":0.0001},
619 case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
622 # Exploitation indépendante
623 # -------------------------
624 Xbackground = case.get("Background")
625 Xoptimum = case.get("Analysis")[-1]
626 FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
627 J_values = case.get("CostFunctionJ")[:]
629 print "Nombre d'itérations internes...: %i"%len(J_values)
630 print "Etat initial...................:",numpy.ravel(Xbackground)
631 print "Etat optimal...................:",numpy.ravel(Xoptimum)
632 print "Simulation à l'état optimal....:",numpy.ravel(FX_at_optimum)
635 L'exécution de jeu de commandes donne le résultat suivant::
637 CurrentState [ 5. 7. 9.]
638 CurrentState [ 0. 3. 1.5]
639 CurrentState [ 1.40006418 3.86705307 3.7061137 ]
640 CurrentState [ 1.42580231 3.68474804 3.81008738]
641 CurrentState [ 1.60220353 3.0677108 4.06146069]
642 CurrentState [ 1.72517855 3.03296953 4.04915706]
643 CurrentState [ 2.00010755 3. 4.00055409]
644 CurrentState [ 1.99995528 3. 3.99996367]
645 CurrentState [ 2.00000007 3. 4.00000011]
646 CurrentState [ 2. 3. 4.]
648 Nombre d'itérations internes...: 10
649 Etat initial...................: [ 5. 7. 9.]
650 Etat optimal...................: [ 2. 3. 4.]
651 Simulation à l'état optimal....: [ 2. 6. 12. 20.]
653 Comme il se doit en expériences jumelles, on constate que l'on retouve bien les
654 paramètres qui ont servi à construire artificiellement les observations.
656 .. Réconciliation de courbes à l'aide de MedCoupling
657 .. +++++++++++++++++++++++++++++++++++++++++++++++++
659 .. Utilisation de fonctions de surveillance de type "observer"
660 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
662 .. Suivre d'un recalage à l'aide de MatPlotLib
663 .. +++++++++++++++++++++++++++++++++++++++++++
665 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
666 .. -----------------------------------------------------------------------------
668 .. [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.
670 .. [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.
672 .. [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.