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
26 .. index:: single: adaoBuilder
29 ================================================================================
30 **[DocR]** Interface de programmation textuelle pour l'utilisateur (API/TUI)
31 ================================================================================
35 dans sa présente version, cette interface de programmation textuelle (TUI) est
36 expérimentale, et reste donc susceptible de changements dans les prochaines
39 Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de
40 son interface de programmation textuelle (API/TUI). Cette interface permet de
41 créer un objet de calcul de manière similaire à la construction d'un cas par
42 l'interface graphique (GUI). Dans le cas où l'on désire réaliser à la main le
43 cas de calcul TUI, on recommande de bien s'appuyer sur l'ensemble de la
44 documentation du module ADAO, et de se reporter si nécessaire à l'interface
45 graphique (GUI), pour disposer de l'ensemble des éléments permettant de
46 renseigner correctement les commandes. Les notions générales et termes utilisés
47 ici sont définis dans :ref:`section_theory`.
49 .. _subsection_tui_creating:
51 Création de cas de calcul TUI ADAO et exemples
52 ----------------------------------------------
54 .. _subsection_tui_example:
56 Un exemple simple de création d'un cas de calcul TUI ADAO
57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
59 Pour introduire l'interface TUI, on commence par un exemple simple mais complet
60 de cas de calcul ADAO. Toutes les données sont explicitement définies dans le
61 corps du script pour faciliter la lecture. L'ensemble des commandes est le
64 from numpy import array
66 case = adaoBuilder.New()
67 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
68 case.set( 'Background', Vector=[0, 1, 2] )
69 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
70 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
71 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
72 case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
73 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
76 Le résultat de l'exécution de ces commandes dans SALOME (que ce soit par la
77 commande "*shell*" de SALOME, dans la console Python de l'interface, ou par le
78 menu d'exécution d'un script) est le suivant::
80 Analysis [ 0.25000264 0.79999797 0.94999939]
82 Création détaillée d'un cas de calcul TUI ADAO
83 ++++++++++++++++++++++++++++++++++++++++++++++
85 On décrit ici plus en détail les différentes étapes de création d'un cas de
86 calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
87 l':ref:`subsection_tui_commands`.
89 La création et l'initialisation d'une étude se font par les commandes suivantes,
90 le nom ``case`` de l'objet du cas de calcul TUI ADAO étant quelconque, au choix
93 from numpy import array
95 case = adaoBuilder.New()
97 Il est recommandé d'importer par principe le module ``numpy`` ou ses
98 constructeurs particuliers comme celui d'``array``, pour faciliter ensuite son
99 usage dans les commandes elle-mêmes.
101 Ensuite, le cas doit être construit par une préparation et un enregistrement des
102 données définissant l'étude. L'ordre de ces commande n'a pas d'importance, il
103 suffit que les concepts requis par l'algorithme utilisé soient présentes. On se
104 reportera à :ref:`section_reference` et à ses sous-parties pour avoir le détail
105 des commandes par algorithme. Ici, on définit successivement l'algorithme
106 d'assimilation de données ou d'optimisation choisi et ses paramètres, puis
107 l'ébauche :math:`\mathbf{x}^b` (nommée ``Background``) et sa covariance
108 d'erreurs :math:`\mathbf{B}` (nommée ``BackgroundError``), et enfin
109 l'observation :math:`\mathbf{y}^o` (nommée ``Observation``) et sa covariance
110 d'erreurs :math:`\mathbf{R}` (nommée ``ObservationError``)::
112 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
114 case.set( 'Background', Vector=[0, 1, 2] )
115 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
117 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
118 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
120 On remarque que l'on peut donner, en entrée des quantités vectorielles ou
121 matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou de
122 type ``array`` ou ``matrix`` de Numpy. Dans ces deux derniers cas, il faut
123 simplement importer le module Numpy avant.
125 On doit ensuite définir les opérateurs :math:`H` d'observation et éventuellement
126 :math:`M` d'évolution. Dans tous les cas, linéaire ou non-linéaire, on peut les
127 définir comme des fonctions. Dans le cas simple d'un opérateur linéaire, on peut
128 aussi le définir à l'aide de la matrice qui correspond à l'opérateur linéaire.
129 Dans le cas présent le plus simple d'opérateur linéaire, on utilise la syntaxe
130 suivante pour un opérateur de :math:`\mathbf{R}^3` sur lui-même::
132 case.ObservationOperator(Matrix = "1 0 0;0 2 0;0 0 3")
134 Dans le cas beaucoup plus courant d'un opérateur non-linéaire de
135 :math:`\mathbf{R}^n` dans :math:`\mathbf{R}^p`, il doit être préalablement
136 disponible sous la forme d'une fonction Python, connue dans l'espace de nommage
137 courant, qui prend en entrée un vecteur ``numpy`` (ou une liste ordonnée) de
138 taille :math:`n` et qui restitue en sortie un vecteur ``numpy`` de taille
139 :math:`p`. Lorsque seul l'opérateur non-linéaire est défini par l'argument
140 "*OneFunction*", son adjoint est directement établi de manière numérique et il
141 est paramétrable par l'argument "*Parameters*". L'exemple suivant montre une
142 fonction ``simulation`` (qui réalise ici le même opérateur linéaire que
143 ci-dessus) et l'enregistre dans le cas ADAO::
147 "Fonction de simulation H pour effectuer Y=H(X)"
148 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
149 __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
152 case.set( 'ObservationOperator',
153 OneFunction = simulation,
154 Parameters = {"DifferentialIncrement":0.01},
157 Pour connaître les résultats intermédiaire ou finaux du calcul du cas, on peut
158 ajouter des "*observer*", qui permettent d'associer l'exécution d'un script à
159 une variable intermédiaire ou finale du calcul. On se reportera à la description
160 de la manière d':ref:`section_advanced_observer`, et à la :ref:`section_reference`
161 pour savoir quelles sont les quantités observables. Cette association
162 d'"*observer*" avec une quantité existante se fait de manière similaire à la
163 définition des données du calcul::
165 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
167 Enfin, lorsque toutes les informations requises sont disponibles dans le cas
168 ``case`` de calcul ADAO, on peut en demander l'exécution de manière très
169 simple dans l'environnement de l'interpréteur Python::
173 Au final, on obtient le script très compact proposé précédemment dans
174 :ref:`subsection_tui_example`.
176 Fournir des données ou informations de calcul plus complexes
177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
179 Une telle interface s'écrivant en Python, il est possible d'utiliser toute la
180 puissance du langage pour entrer des données plus complexes qu'une déclaration
183 L'enregistrement des données d'entrées supporte différents types de variables,
184 mais surtout, ces entrées peuvent recevoir des variables courantes disponibles
185 dans l'espace de nommage du script. Il est donc aisé d'utiliser des variables
186 calculées préalablement ou obtenues par l'import de scripts "utilisateur". Si
187 par exemple les observations sont disponibles sous la forme d'une liste dans un
188 fichier Python externe nommé ``observations.py`` sous le nom ``table``, il
189 suffit de réaliser les opérations suivantes pour enregistrer les observations
190 dans le cas de calcul TUI ADAO::
192 from observations import table
193 case.set( 'Observation', Vector=table )
195 La première ligne importe la variable ``table`` depuis le fichier externe, et la
196 seconde enregistre directement cette table comme la donnée "*Observation*".
198 La simplicité de cet enregistrement montre bien la facilité d'obtenir les
199 données de calcul depuis des sources externes, fichiers ou flux informatiques
200 atteignables en Python. Comme d'habitude, il est recommandé à l'utilisateur de
201 vérifier ses données avant de les enregistrer dans le cas de calcul TUI ADAO
202 pour éviter les erreurs compliquées à corriger.
204 Obtenir et utiliser les résultats de calcul de manière plus riche
205 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
207 De la même manière, il est possible d'obtenir et traiter les résultats de calcul
208 de manière plus riche, pour enchaîner sur des post-traitements après le calcul
211 Les variables de résultats de calcul, ou les variables internes issues de
212 l'optimisation ou de l'assimilation de données, sont disponibles à travers la
213 méthode ``get`` du cas de calcul TUI ADAO, qui renvoie un objet de type liste de
214 la variable demandée. On se reportera aux :ref:`section_ref_output_variables`
215 pour une description détaillée sur ce sujet.
217 A titre d'exemple, on donne quelques lignes de script qui permettent d'obtenir
218 le nombre d'itérations de l'optimisation et la valeur optimale ainsi que sa
222 print " Nombre d'iterations :", len(case.get("CostFunctionJ"))
223 Xa = case.get("Analysis")
224 print " Analyse optimale :", Xa[-1]
225 print " Taille de l'analyse :", len(Xa[-1])
228 Ces lignes peuvent être très simplement additionnées à l'exemple initial de cas
229 de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
231 De même que pour l'entrée des données, la simplicité de récupération des
232 résultats permet d'envisager aisément des post-traitements enchaînés dans
233 SALOME, pour utiliser par exemple de la visualisation avec MatPlotLib ou PARAVIS
234 [PARAVIS]_, de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour d'autres
237 .. _subsection_tui_commands:
239 Ensemble des commandes disponibles en interface textuelle TUI
240 -------------------------------------------------------------
242 Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
243 courantes en Python pour la distinction entre ce qui est public, et ce qui est
244 privé ou réservé car relevant des détails d'implémentation. De manière pratique,
245 tout nom d'objet ou de fonction commençant par au moins un signe "_" est privé
246 au sens courant de programmation ("*private*"). Néanmoins, l'absence d'un tel
247 signe au début d'un nom ne le désigne pas comme public. De manière générale, en
248 Python, et contrairement à d'autres langages, on peut accéder aux objets ou aux
249 fonction privés. Cela peut parfois être utile, mais un tel usage dans vos codes
250 conduira à des plantages sans avertissement lors de futures versions. Il est
251 donc fortement recommandé de ne pas le faire.
253 Pour clarifier et faciliter l'utilisation du module pour du script, **cette
254 section définit donc l'interface de programmation (API) textuelle publique pour
255 l'utilisateur (TUI) de manière complète et limitative**. L'usage en script
256 d'objets ou fonctions ADAO autres que ceux qui sont définis ici est fortement
257 déconseillé, car cela conduira vraisemblablement à des plantages sans
258 avertissement lors de futures versions.
260 Syntaxes d'appel équivalentes pour les commandes TUI
261 ++++++++++++++++++++++++++++++++++++++++++++++++++++
263 La définition des données lors de la création de cas de calcul TUI ADAO supporte
264 **deux syntaxes entièrement équivalentes**. On peut :
266 - soit utiliser la commande ``set`` et comme premier argument le concept
267 ``XXXXX`` sur lequel appliquer la commande dont les arguments suivent,
268 - soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
271 Pour illustrer cette équivalence, on prend l'exemple des deux commandes
272 suivantes qui conduisent au même résultat::
274 case.set( 'Background', Vector=[0, 1, 2] )
278 case.setBackground( Vector=[0, 1, 2] )
280 Le choix de l'une ou l'autre des syntaxes est librement laissé à l'utilisateur,
281 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
282 commandes selon la seconde syntaxe.
284 Création d'un cas de calcul en interface textuelle TUI
285 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
287 La création et l'initialisation d'un cas de calcul en interface textuelle TUI se
288 font en important le module d'interface "*adaoBuilder*" et en invoquant sa
289 méthode "*New()*" comme illustré dans les quelques lignes suivantes (le nom
290 ``case`` de l'objet étant quelconque, au choix de l'utilisateur)::
292 from numpy import array
294 case = adaoBuilder.New()
296 Il est recommandé par principe de toujours importer le module ``numpy`` (ou ses
297 constructeurs particuliers, comme celui d'``array``) pour faciliter ensuite son
298 usage dans les commandes elle-mêmes.
300 Définir les données de calcul
301 +++++++++++++++++++++++++++++
303 Les commandes qui suivent permettent de définir les données d'un cas de calcul
304 TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux des
305 entrées en interface GUI, décrits dans la section des
306 :ref:`section_reference_entry` et en particulier par la
307 :ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs se
308 fait soit lors de leur définition, soit lors de l'exécution.
310 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
311 veut éventuellement la stocker la grandeur définie, pour en disposer en cours de
312 calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
313 recommandé de conserver cette valeur par défaut. En effet, pour un cas de calcul
314 TUI, on dispose déjà souvent des grandeurs données en entrées qui sont présentes
315 dans l'espace de nommage courant du cas.
317 Les commandes disponibles sont les suivantes :
319 .. index:: single: setBackground
321 **setBackground** (*Vector, VectorSerie, Script, Stored*)
322 Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
323 algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
324 comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
325 script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
326 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
328 .. index:: single: setBackgroundError
330 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
331 Cette commande permet de définir la matrice :math:`\mathbf{B}` de
332 covariance des erreurs d'ébauche. La matrice peut être définie de manière
333 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
334 matrice diagonale dont on donne la variance unique sur la diagonale par
335 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
336 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
337 Si on la définit par un script dans "*Script*", la matrice est de type
338 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
339 selon que l'une de ces variables est placée à "*True*".
341 .. index:: single: setCheckingPoint
343 **setCheckingPoint** (*Vector, VectorSerie, Script, Stored*)
344 Cette commande permet de définir un point courant :math:`\mathbf{x}` utilisé
345 pour un algorithme de vérification. Selon les algorithmes, on peut le
346 définir comme un vecteur simple par "*Vector*", ou comme une liste de
347 vecteurs par "*VectorSerie*". Si on le définit par un script dans
348 "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
349 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*".
351 .. index:: single: setControlModel
353 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
354 Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
355 décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
356 d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
357 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
358 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
359 utilisées, comme décrit dans la section
360 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
361 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
362 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
363 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
364 Les paramètres de contrôle de l'approximation numérique de l'opérateur
365 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
366 dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
367 de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
368 "*CenteredFiniteDifference*" (similaires à celles de l'interface graphique).
370 .. index:: single: setControlInput
372 **setControlInput** (*Vector, VectorSerie, Script, Stored*)
373 Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
374 Selon les algorithmes, on peut le définir comme un vecteur simple par
375 "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
376 définit par un script dans "*Script*", le vecteur est de type "*Vector*"
377 (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
380 .. index:: single: setEvolutionError
382 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
383 Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
384 covariance des erreurs d'évolution. La matrice peut être définie de manière
385 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
386 matrice diagonale dont on donne la variance unique sur la diagonale par
387 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
388 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
389 Si on la définit par un script dans "*Script*", la matrice est de type
390 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
391 selon que l'une de ces variables est placée à "*True*".
393 .. index:: single: setEvolutionModel
395 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
396 Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
397 décrit un pas élémentaire d'évolution. Sa valeur est définie comme un objet
398 de type fonction ou de type "*Matrix*". Dans le cas d'une fonction,
399 différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
400 la section :ref:`section_ref_operator_requirements`, et entrées par les
401 mots-clés "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une
402 définition par "*Script*", l'opérateur est de type "*Matrix*",
403 "*OneFunction*" ou "*ThreeFunctions*" selon que l'une de ces variables est
404 placée à "*True*". Les paramètres de contrôle de l'approximation numérique
405 de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être renseignés
406 par un dictionnaire dans "*Parameters*". Les entrées potentielles de ce
407 dictionnaire de paramètres sont "*DifferentialIncrement*",
408 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
409 "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
411 .. index:: single: setObservation
413 **setObservation** (*Vector, VectorSerie, Script, Stored*)
414 Cette commande permet de définir le vecteur d'observation
415 :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
416 vecteur simple par "*Vector*", ou comme une liste de vecteurs par
417 "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
418 est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
419 ces variables est placée à "*True*".
421 .. index:: single: setObservationError
423 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
424 Cette commande permet de définir la matrice :math:`\mathbf{R}` de
425 covariance des erreurs d'observation. La matrice peut être définie de
426 manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
427 comme une matrice diagonale dont on donne la variance unique sur la
428 diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on
429 donne le vecteur des variances situé sur la diagonale par
430 "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*", la
431 matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
432 "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
435 .. index:: single: setObservationOperator
437 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, Stored*)
438 Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
439 transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
440 :math:`\mathbf{y}` qui sont à comparer aux observations
441 :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
442 ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
443 fonctionnelles peuvent être utilisées, comme décrit dans la section
444 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
445 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
446 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
447 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
448 Les paramètres de contrôle de l'approximation numérique de l'opérateur
449 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
450 dictionnaire dans "*Parameters*". Les entrées potentielles de ce
451 dictionnaire de paramètres sont "*DifferentialIncrement*",
452 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
453 "*NumberOfProcesses*" (similaires à celles de l'interface graphique).
455 .. index:: single: set
457 **set** (*Concept,...*)
458 Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
459 commandes de ce paragraphe. Son premier argument est le nom du concept à
460 définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
461 s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
462 les commandes individuelles précédentes. Lors de l'usage de cette commande,
463 il est indispensable de nommer les arguments (par exemple "*Vector=...*").
465 Paramétrer le calcul, les sorties, etc.
466 +++++++++++++++++++++++++++++++++++++++
468 .. index:: single: setAlgorithmParameters
470 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
471 Cette commande permet de choisir l'algorithme de calcul ou de vérification
472 par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
473 reportera utilement aux listes des :ref:`section_reference_assimilation` et
474 des :ref:`section_reference_checking`), et de définir les paramètres de
475 calcul par l'argument "*Parameters*". Dans le cas d'une définition par
476 "*Script*", le fichier indiqué doit contenir les deux variables
477 "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
480 .. index:: single: setDebug
483 Cette commande permet d'activer le mode d'information détaillé lors de
486 .. index:: single: setNoDebug
489 Cette commande permet de désactiver le mode d'information détaillé lors de
492 .. index:: single: setObserver
494 **setObserver** (*Variable, Template, String, Script, Info*)
495 Cette commande permet de définir un *observer* sur une variable courante ou
496 finale du calcul. On se reportera à la description de la manière
497 d':ref:`section_advanced_observer`, et à la :ref:`section_reference` pour
498 savoir quelles sont les quantités observables. On définit comme un
499 "*String*" le corps de l'*observer*, en utilisant une chaine de caractères
500 incluant si nécessaire des sauts de lignes. On recommande d'utiliser les
501 patrons disponibles par l'argument "*Template*". On dispose des patrons
502 simples suivants : "ValuePrinter", "ValueSeriePrinter", "ValueSaver",
503 "ValueSerieSaver", "ValuePrinterAndSaver", "ValueSeriePrinterAndSaver",
504 "ValueGnuPlotter", "ValueSerieGnuPlotter", "ValuePrinterAndGnuPlotter",
505 "ValueSeriePrinterAndGnuPlotter", "ValuePrinterSaverAndGnuPlotter",
506 "ValueSeriePrinterSaverAndGnuPlotter", "ValueMean", "ValueStandardError",
507 "ValueVariance", "ValueRMS". Dans le cas d'une définition par "*Script*", le
508 fichier indiqué doit contenir uniquement le corps de la fonction, comme
509 décrit dans la manière d':ref:`section_advanced_observer`.
514 .. index:: single: executePythonScheme
516 **executePythonScheme** ()
517 Cette commande lance le calcul complet dans l'environnement de
518 l'interpréteur Python courant, sans interaction avec YACS [YACS]_. Les
519 sorties standard et d'erreur sont celles de l'interpréteur Python. On
520 dispose si nécessaire du parallélisme interne des algorithmes dans ADAO et
521 du parallélisme interne du ou des codes de simulation utilisé.
523 .. .. index:: single: generateYACSscheme
525 .. **executeYACSScheme** (*File*)
526 .. Cete commande génère le schéma YACS [YACS]_ du cas de calcul dans le fichier
527 .. requis "*File*", et en lance l'exécution dans l'interpréteur YACS, comme on
528 .. peut le réaliser en utilisant l'éditeur standard de cas ADAO. Les sorties
529 .. standard et d'erreur sont celles de l'interpréteur YACS. On dispose si
530 .. nécessaire du parallélisme de noeuds et blocs dans YACS, du parallélisme
531 .. interne des algorithmes dans ADAO et du parallélisme interne du ou des codes
532 .. de simulation utilisé.
534 .. index:: single: execute
537 Cette commande est un raccourci utilisateur pour "*executePythonScheme*".
539 Obtenir séparément les résultats de calcul
540 ++++++++++++++++++++++++++++++++++++++++++
542 .. index:: single: get
545 Cette commande permet d'extraire explicitement les variables disponibles en
546 sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
547 scripting, par exemple en visualisation. Elle a pour argument le nom d'un
548 variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
549 d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
550 base. Pour connaître la liste des variables et les utiliser, on se
551 reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
552 fois aux :ref:`section_ref_output_variables` et aux documentations
553 individuelles des algorithmes.
555 Exemples plus avancés de cas de calcul TUI ADAO
556 -----------------------------------------------
558 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
559 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
562 Exploitation indépendante des résultats d'un cas de calcul
563 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
565 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
566 son exécution, puis la récupération des résultats pour ensuite enchaîner sur une
567 exploitation indépendante de ces résultats (cette dernière n'étant pas décrite
568 ici, puisque dépendante de l'utilisateur).
570 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
572 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
573 #. que l'on dispose d'observations nommées ``observations``,
574 #. 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,
575 #. 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.
577 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne par
578 exemple les entrées suivantes, parfaitement arbitraires, en construisant les
579 observations par simulation pour se placer dans un cas d'expériences jumelles::
582 # Construction artificielle d'un exemple de données utilisateur
583 # -------------------------------------------------------------
588 alphamin, alphamax = 0., 10.
589 betamin, betamax = 3, 13
590 gammamin, gammamax = 1.5, 15.5
593 "Fonction de simulation H pour effectuer Y=H(X)"
595 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
596 __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
599 # Observations obtenues par simulation
600 # ------------------------------------
601 observations = simulation((2, 3, 4))
603 Le jeu de commandes que l'on peut utiliser est le suivant::
608 # Mise en forme des entrées
609 # -------------------------
610 Xb = (alpha, beta, gamma)
612 (alphamin, alphamax),
614 (gammamin, gammamax))
618 case = adaoBuilder.New()
620 'AlgorithmParameters',
624 "MaximumNumberOfSteps":100,
625 "StoreSupplementaryCalculations":[
628 "SimulatedObservationAtOptimum",
632 case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
633 case.set( 'Observation', Vector = numpy.array(observations) )
634 case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
635 case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
637 'ObservationOperator',
638 OneFunction = simulation,
639 Parameters = {"DifferentialIncrement":0.0001},
641 case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
644 # Exploitation indépendante
645 # -------------------------
646 Xbackground = case.get("Background")
647 Xoptimum = case.get("Analysis")[-1]
648 FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
649 J_values = case.get("CostFunctionJ")[:]
651 print "Nombre d'itérations internes...: %i"%len(J_values)
652 print "Etat initial...................:",numpy.ravel(Xbackground)
653 print "Etat optimal...................:",numpy.ravel(Xoptimum)
654 print "Simulation à l'état optimal....:",numpy.ravel(FX_at_optimum)
657 L'exécution de jeu de commandes donne le résultat suivant::
659 CurrentState [ 5. 7. 9.]
660 CurrentState [ 0. 3. 1.5]
661 CurrentState [ 1.40006418 3.86705307 3.7061137 ]
662 CurrentState [ 1.42580231 3.68474804 3.81008738]
663 CurrentState [ 1.60220353 3.0677108 4.06146069]
664 CurrentState [ 1.72517855 3.03296953 4.04915706]
665 CurrentState [ 2.00010755 3. 4.00055409]
666 CurrentState [ 1.99995528 3. 3.99996367]
667 CurrentState [ 2.00000007 3. 4.00000011]
668 CurrentState [ 2. 3. 4.]
670 Nombre d'itérations internes...: 10
671 Etat initial...................: [ 5. 7. 9.]
672 Etat optimal...................: [ 2. 3. 4.]
673 Simulation à l'état optimal....: [ 2. 6. 12. 20.]
675 Comme il se doit en expériences jumelles, on constate que l'on retouve bien les
676 paramètres qui ont servi à construire artificiellement les observations.
678 .. Réconciliation de courbes à l'aide de MedCoupling
679 .. +++++++++++++++++++++++++++++++++++++++++++++++++
681 .. Utilisation de fonctions de surveillance de type "observer"
682 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
684 .. Suivre d'un recalage à l'aide de MatPlotLib
685 .. +++++++++++++++++++++++++++++++++++++++++++
687 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
688 .. -----------------------------------------------------------------------------
690 .. [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.
692 .. [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.
694 .. [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.