2 Copyright (C) 2008-2021 EDF R&D
4 This file is part of SALOME ADAO module.
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
24 .. index:: single: TUI
25 .. index:: single: API/TUI
26 .. index:: single: adaoBuilder
29 ================================================================================
30 **[DocR]** Interface textuelle pour l'utilisateur (TUI/API)
31 ================================================================================
33 Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de
34 son interface de programmation textuelle (API/TUI). Cette interface permet de
35 créer un objet de calcul de manière similaire à la construction d'un cas par
36 l'interface graphique (GUI). Dans le cas où l'on désire réaliser à la main le
37 cas de calcul TUI, on recommande de bien s'appuyer sur l'ensemble de la
38 documentation du module ADAO, et de se reporter si nécessaire à l'interface
39 graphique (GUI), pour disposer de l'ensemble des éléments permettant de
40 renseigner correctement les commandes. Les notions générales et termes utilisés
41 ici sont définis dans :ref:`section_theory`.
43 .. _subsection_tui_creating:
45 Création de cas de calcul TUI ADAO et exemples
46 ----------------------------------------------
48 .. _subsection_tui_example:
50 Un exemple simple de création d'un cas de calcul TUI ADAO
51 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
53 Pour introduire l'interface TUI, on commence par un exemple simple mais complet
54 de cas de calcul ADAO. Toutes les données sont explicitement définies dans le
55 corps du script pour faciliter la lecture. L'ensemble des commandes est le
58 from numpy import array, matrix
59 from adao import adaoBuilder
60 case = adaoBuilder.New()
61 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
62 case.set( 'Background', Vector=[0, 1, 2] )
63 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
64 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
65 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
66 case.set( 'ObservationOperator', Matrix='1 0 0;0 2 0;0 0 3' )
67 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
70 Le résultat de l'exécution de ces commandes dans SALOME (que ce soit par la
71 commande "*shell*" de SALOME, dans la console Python de l'interface, ou par le
72 menu d'exécution d'un script) est le suivant::
74 Analysis [ 0.25000264 0.79999797 0.94999939]
76 Création détaillée d'un cas de calcul TUI ADAO
77 ++++++++++++++++++++++++++++++++++++++++++++++
79 On décrit ici plus en détail les différentes étapes de création d'un cas de
80 calcul TUI ADAO. Les commandes elles-mêmes sont détaillées juste après dans
81 l':ref:`subsection_tui_commands`.
83 La création et l'initialisation d'une étude se font par les commandes
84 suivantes, le nom ``case`` de l'objet du cas de calcul TUI ADAO étant
85 quelconque, au choix de l'utilisateur::
87 from numpy import array, matrix
88 from adao import adaoBuilder
89 case = adaoBuilder.New()
91 Il est recommandé d'importer par principe le module ``numpy`` ou ses
92 constructeurs particuliers comme celui d'``array``, pour faciliter ensuite son
93 usage dans les commandes elle-mêmes.
95 Ensuite, le cas doit être construit par une préparation et un enregistrement
96 des données définissant l'étude. L'ordre de ces commandes n'a pas d'importance,
97 il suffit que les concepts requis par l'algorithme utilisé soient présents. On
98 se reportera à :ref:`section_reference` et à ses sous-parties pour avoir le
99 détail des commandes par algorithme. Ici, on définit successivement
100 l'algorithme d'assimilation de données ou d'optimisation choisi et ses
101 paramètres, puis l'ébauche :math:`\mathbf{x}^b` (nommée ``Background``) et sa
102 covariance d'erreurs :math:`\mathbf{B}` (nommée ``BackgroundError``), et enfin
103 l'observation :math:`\mathbf{y}^o` (nommée ``Observation``) et sa covariance
104 d'erreurs :math:`\mathbf{R}` (nommée ``ObservationError``)::
106 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
108 case.set( 'Background', Vector=[0, 1, 2] )
109 case.set( 'BackgroundError', ScalarSparseMatrix=1.0 )
111 case.set( 'Observation', Vector=array([0.5, 1.5, 2.5]) )
112 case.set( 'ObservationError', DiagonalSparseMatrix='1 1 1' )
114 On remarque que l'on peut donner, en entrée des quantités vectorielles ou
115 matricielles, des objets de type ``str``, ``list`` ou ``tuple`` de Python, ou
116 de type ``array`` ou ``matrix`` de Numpy. Dans ces deux derniers cas, il faut
117 simplement importer le module Numpy avant.
119 On doit ensuite définir les opérateurs :math:`H` d'observation et
120 éventuellement :math:`M` d'évolution. Dans tous les cas, linéaire ou
121 non-linéaire, on peut les définir comme des fonctions. Dans le cas simple d'un
122 opérateur linéaire, on peut aussi le définir à l'aide de la matrice qui
123 correspond à l'opérateur linéaire. Dans le cas présent le plus simple
124 d'opérateur linéaire, on utilise la syntaxe suivante pour un opérateur de
125 :math:`\mathbf{R}^3` sur lui-même::
127 case.set( 'ObservationOperator', Matrix = "1 0 0;0 2 0;0 0 3")
129 Dans le cas beaucoup plus courant d'un opérateur non-linéaire de
130 :math:`\mathbf{R}^n` dans :math:`\mathbf{R}^p`, il doit être préalablement
131 disponible sous la forme d'une fonction Python, connue dans l'espace de nommage
132 courant, qui prend en entrée un vecteur ``numpy`` (ou une liste ordonnée) de
133 taille :math:`n` et qui restitue en sortie un vecteur ``numpy`` de taille
134 :math:`p`. Lorsque seul l'opérateur non-linéaire est défini par l'argument
135 "*OneFunction*", son adjoint est directement établi de manière numérique et il
136 est paramétrable par l'argument "*Parameters*". L'exemple suivant montre une
137 fonction ``simulation`` (qui réalise ici le même opérateur linéaire que
138 ci-dessus) et l'enregistre dans le cas ADAO::
142 "Fonction de simulation H pour effectuer Y=H(X)"
143 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
144 __H = numpy.matrix("1 0 0;0 2 0;0 0 3")
147 case.set( 'ObservationOperator',
148 OneFunction = simulation,
149 Parameters = {"DifferentialIncrement":0.01},
152 Pour connaître les résultats intermédiaire ou finaux du calcul du cas, on peut
153 ajouter des "*observer*", qui permettent d'associer l'exécution d'un script à
154 une variable intermédiaire ou finale du calcul. On se reportera à la
155 description de la manière d':ref:`section_advanced_observer`, et à la
156 :ref:`section_reference` pour savoir quelles sont les quantités observables.
157 Cette association d'"*observer*" avec une quantité existante se fait de manière
158 similaire à la définition des données du calcul::
160 case.set( 'Observer', Variable="Analysis", Template="ValuePrinter" )
162 Enfin, lorsque toutes les informations requises sont disponibles dans le cas
163 ``case`` de calcul ADAO, on peut en demander l'exécution de manière très
164 simple dans l'environnement de l'interpréteur Python::
168 Au final, on obtient le script très compact proposé précédemment dans
169 :ref:`subsection_tui_example`.
171 Fournir des données ou informations de calcul plus complexes
172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
174 Une telle interface s'écrivant en Python, il est possible d'utiliser toute la
175 puissance du langage pour entrer des données plus complexes qu'une déclaration
178 L'enregistrement des données d'entrées supporte différents types de variables,
179 mais surtout, ces entrées peuvent recevoir des variables courantes disponibles
180 dans l'espace de nommage du script. Il est donc aisé d'utiliser des variables
181 calculées préalablement ou obtenues par l'import de scripts "utilisateur". Si
182 par exemple les observations sont disponibles sous la forme d'une liste dans un
183 fichier Python externe nommé ``observations.py`` sous le nom ``table``, il
184 suffit de réaliser les opérations suivantes pour enregistrer les observations
185 dans le cas de calcul TUI ADAO::
187 from observations import table
188 case.set( 'Observation', Vector=table )
190 La première ligne importe la variable ``table`` depuis le fichier externe, et
191 la seconde enregistre directement cette table comme la donnée "*Observation*".
193 La simplicité de cet enregistrement montre bien la facilité d'obtenir les
194 données de calcul depuis des sources externes, fichiers ou flux informatiques
195 atteignables en Python. Comme d'habitude, il est recommandé à l'utilisateur de
196 vérifier ses données avant de les enregistrer dans le cas de calcul TUI ADAO
197 pour éviter les erreurs compliquées à corriger.
199 Obtenir et utiliser les résultats de calcul de manière plus riche
200 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
202 De la même manière, il est possible d'obtenir et traiter les résultats de
203 calcul de manière plus riche, pour enchaîner sur des post-traitements après le
206 Les variables de résultats de calcul, ou les variables internes issues de
207 l'optimisation ou de l'assimilation de données, sont disponibles à travers la
208 méthode ``get`` du cas de calcul TUI ADAO, qui renvoie un objet de type liste
209 de la variable demandée. On se reportera aux
210 :ref:`section_ref_output_variables` pour une description détaillée sur ce
213 A titre d'exemple, on donne quelques lignes de script qui permettent d'obtenir
214 le nombre d'itérations de l'optimisation et la valeur optimale ainsi que sa
218 print(" Nombre d'iterations : %i"%len(case.get("CostFunctionJ")))
219 Xa = case.get("Analysis")
220 print(" Analyse optimale : %s"%(Xa[-1],))
221 print(" Taille de l'analyse : %i"%len(Xa[-1]))
224 Ces lignes peuvent être très simplement additionnées à l'exemple initial de cas
225 de calcul TUI ADAO proposé dans :ref:`subsection_tui_example`.
227 De même que pour l'entrée des données, la simplicité de récupération des
228 résultats permet d'envisager aisément des post-traitements enchaînés dans
229 SALOME, pour utiliser par exemple de la visualisation avec MatPlotLib ou
230 PARAVIS [PARAVIS]_, de l'adaptation de maillage avec HOMARD [HOMARD]_, ou pour
233 .. _subsection_tui_commands:
235 Ensemble des commandes disponibles en interface textuelle TUI
236 -------------------------------------------------------------
238 Dans l'interface TUI du module ADAO, on suit les conventions et recommandations
239 courantes en Python pour la distinction entre ce qui est public, et ce qui est
240 privé ou réservé car relevant des détails d'implémentation. De manière
241 pratique, tout nom d'objet ou de fonction commençant par au moins un signe "_"
242 est privé au sens courant de programmation ("*private*"). Néanmoins, l'absence
243 d'un tel signe au début d'un nom ne le désigne pas comme public. De manière
244 générale, en Python, et contrairement à d'autres langages, on peut accéder aux
245 objets ou aux fonctions privés. Cela peut parfois être utile, mais un tel usage
246 dans vos codes conduira à des plantages sans avertissement lors de futures
247 versions. Il est donc fortement recommandé de ne pas le faire.
249 Pour clarifier et faciliter l'utilisation du module pour du script, **cette
250 section définit donc l'interface de programmation (API) textuelle publique pour
251 l'utilisateur (TUI) de manière complète et limitative**. L'usage en script
252 d'objets ou fonctions ADAO autres que ceux qui sont définis ici est fortement
253 déconseillé, car cela conduira vraisemblablement à des plantages sans
254 avertissement lors de futures versions.
256 Syntaxes d'appel équivalentes pour les commandes TUI
257 ++++++++++++++++++++++++++++++++++++++++++++++++++++
259 La définition des données lors de la création de cas de calcul TUI ADAO
260 supporte **deux syntaxes entièrement équivalentes**. On peut :
262 - soit utiliser la commande ``set`` et comme premier argument le concept
263 ``XXXXX`` sur lequel appliquer la commande dont les arguments suivent,
264 - soit utiliser la commande ``setXXXXX`` contenant les arguments de la commande
267 Pour illustrer cette équivalence, on prend l'exemple des deux commandes
268 suivantes qui conduisent au même résultat::
270 case.set( 'Background', Vector=[0, 1, 2] )
274 case.setBackground( Vector=[0, 1, 2] )
276 Le choix de l'une ou l'autre des syntaxes est librement laissé à l'utilisateur,
277 selon son contexte d'usage. Dans la suite, par souci de clarté, on définit les
278 commandes selon la seconde syntaxe.
280 Création d'un cas de calcul en interface textuelle TUI
281 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
283 La création et l'initialisation d'un cas de calcul en interface textuelle TUI
284 se font en important le module d'interface "*adaoBuilder*" et en invoquant sa
285 méthode "*New()*" comme illustré dans les quelques lignes suivantes (le nom
286 ``case`` de l'objet étant quelconque, au choix de l'utilisateur)::
288 from numpy import array, matrix
289 from adao import adaoBuilder
290 case = adaoBuilder.New()
292 Il est recommandé par principe de toujours importer le module ``numpy`` (ou ses
293 constructeurs particuliers, comme celui d'``array``) pour faciliter ensuite son
294 usage dans les commandes elles-mêmes.
296 Définir les données de calcul
297 +++++++++++++++++++++++++++++
299 Les commandes qui suivent permettent de définir les données d'un cas de calcul
300 TUI ADAO. Le pseudo-type des arguments est similaire et compatible avec ceux
301 des entrées en interface GUI, décrits dans la section des
302 :ref:`section_reference_entry` et en particulier par la
303 :ref:`section_ref_entry_types`. La vérification de l'adéquation des grandeurs
304 se fait soit lors de leur définition, soit lors de l'exécution.
306 .. index:: single: Stored
308 Dans chaque commande, le mot-clé booléen "*Stored*" permet d'indiquer si l'on
309 veut éventuellement stocker la grandeur définie, pour en disposer en cours de
310 calcul ou en sortie. Le choix par défaut est de ne pas stocker, et il est
311 recommandé de conserver cette valeur par défaut. En effet, pour un cas de
312 calcul TUI, on dispose déjà souvent des grandeurs données en entrées qui sont
313 présentes dans l'espace de nommage courant du cas.
315 Les commandes disponibles sont les suivantes :
317 .. index:: single: Background
318 .. index:: single: setBackground
320 **setBackground** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
321 Cette commande permet de définir l'ébauche :math:`\mathbf{x}^b`. Selon les
322 algorithmes, on peut la définir comme un vecteur simple par "*Vector*", ou
323 comme une liste de vecteurs par "*VectorSerie*". Si on la définit par un
324 script dans "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
325 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*". Si
326 on utilise un fichier de données par "*DataFile*" (en sélectionnant, en
327 colonne par défaut ou en ligne selon "*ColMajor*", toutes les variables par
328 défaut ou celles de la liste "*ColNames*"), le vecteur est de type
331 .. index:: single: BackgroundError
332 .. index:: single: setBackgroundError
334 **setBackgroundError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
335 Cette commande permet de définir la matrice :math:`\mathbf{B}` de
336 covariance des erreurs d'ébauche. La matrice peut être définie de manière
337 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
338 matrice diagonale dont on donne la variance unique sur la diagonale par
339 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
340 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
341 Si on la définit par un script dans "*Script*", la matrice est de type
342 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
343 selon que l'une de ces variables est placée à "*True*".
345 .. index:: single: CheckingPoint
346 .. index:: single: setCheckingPoint
348 **setCheckingPoint** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
349 Cette commande permet de définir un point courant :math:`\mathbf{x}`
350 utilisé pour un algorithme de vérification. Selon les algorithmes, on peut
351 le définir comme un vecteur simple par "*Vector*", ou comme une liste de
352 vecteurs par "*VectorSerie*". Si on le définit par un script dans
353 "*Script*", le vecteur est de type "*Vector*" (par défaut) ou
354 "*VectorSerie*" selon que l'une de ces variables est placée à "*True*". Si
355 on utilise un fichier de données par "*DataFile*" (en sélectionnant, en
356 colonne par défaut ou en ligne selon "*ColMajor*", toutes les variables par
357 défaut ou celles de la liste "*ColNames*"), le vecteur est de type
360 .. index:: single: ControlModel
361 .. index:: single: setControlModel
362 .. index:: single: ExtraArguments
364 **setControlModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
365 Cette commande permet de définir l'opérateur de contrôle :math:`O`, qui
366 décrit un contrôle d'entrée linéaire externe de l'opérateur d'évolution ou
367 d'observation. On se reportera :ref:`section_ref_operator_control`. Sa
368 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
369 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
370 utilisées, comme décrit dans la section
371 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
372 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
373 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
374 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
375 Les paramètres de contrôle de l'approximation numérique de l'opérateur
376 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
377 dictionnaire à travers le mot-clé "*Parameters*". Les entrées potentielles
378 de ce dictionnaire de paramètres sont "*DifferentialIncrement*",
379 "*CenteredFiniteDifference*" (similaires à celles de l'interface
380 graphique). Si l'opérateur nécessite des arguments fixes complémentaires,
381 ils peuvent être fournis par la variable "*ExtraArguments*" sous la forme
382 d'un dictionnaire de paramètres nommés.
384 .. index:: single: ControlInput
385 .. index:: single: setControlInput
387 **setControlInput** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
388 Cette commande permet de définir le vecteur de contrôle :math:`\mathbf{u}`.
389 Selon les algorithmes, on peut le définir comme un vecteur simple par
390 "*Vector*", ou comme une liste de vecteurs par "*VectorSerie*". Si on le
391 définit par un script dans "*Script*", le vecteur est de type "*Vector*"
392 (par défaut) ou "*VectorSerie*" selon que l'une de ces variables est placée
393 à "*True*". Si on utilise un fichier de données par "*DataFile*" (en
394 sélectionnant, en colonne par défaut ou en ligne selon "*ColMajor*", toutes
395 les variables par défaut ou celles de la liste "*ColNames*"), le vecteur
396 est de type "*Vector*".
398 .. index:: single: EvolutionError
399 .. index:: single: setEvolutionError
401 **setEvolutionError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
402 Cette commande permet de définir la matrice :math:`\mathbf{Q}` de
403 covariance des erreurs d'évolution. La matrice peut être définie de manière
404 complète par le mot-clé "*Matrix*", ou de manière parcimonieuse, comme une
405 matrice diagonale dont on donne la variance unique sur la diagonale par
406 "*ScalarSparseMatrix*", ou comme une matrice diagonale dont on donne le
407 vecteur des variances situé sur la diagonale par "*DiagonalSparseMatrix*".
408 Si on la définit par un script dans "*Script*", la matrice est de type
409 "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou "*DiagonalSparseMatrix*"
410 selon que l'une de ces variables est placée à "*True*".
412 .. index:: single: EvolutionModel
413 .. index:: single: setEvolutionModel
414 .. index:: single: ExtraArguments
416 **setEvolutionModel** (*Matrix, OneFunction, ThreeFunctions, Parameters, Script, ExtraArguments, Stored*)
417 Cette commande permet de définir l'opérateur d'evolution :math:`M`, qui
418 décrit un pas élémentaire d'évolution de l'état :math:`\mathbf{x}`. Sa
419 valeur est définie comme un objet de type fonction ou de type "*Matrix*".
420 Dans le cas d'une fonction, différentes formes fonctionnelles peuvent être
421 utilisées, comme décrit dans la section
422 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
423 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
424 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
425 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
426 Les paramètres de contrôle de l'approximation numérique de l'opérateur
427 adjoint, dans le cas "*OneFunction*", peuvent être renseignés par un
428 dictionnaire dans "*Parameters*". Les entrées potentielles de ce
429 dictionnaire de paramètres sont "*DifferentialIncrement*",
430 "*CenteredFiniteDifference*", "*EnableMultiProcessing*",
431 "*NumberOfProcesses*" (similaires à celles de l'interface graphique). Si
432 l'opérateur nécessite des paramètres fixes complémentaires en plus de
433 l'état :math:`\mathbf{x}`, ils peuvent être fournis par la variable
434 "*ExtraArguments*" sous la forme d'un dictionnaire de paramètres nommés.
436 .. index:: single: Observation
437 .. index:: single: setObservation
439 **setObservation** (*Vector, VectorSerie, Script, DataFile, ColNames, ColMajor, Stored*)
440 Cette commande permet de définir le vecteur d'observation
441 :math:`\mathbf{y}^o`. Selon les algorithmes, on peut le définir comme un
442 vecteur simple par "*Vector*", ou comme une liste de vecteurs par
443 "*VectorSerie*". Si on le définit par un script dans "*Script*", le vecteur
444 est de type "*Vector*" (par défaut) ou "*VectorSerie*" selon que l'une de
445 ces variables est placée à "*True*". Si on utilise un fichier de données
446 par "*DataFile*" (en sélectionnant, en colonne par défaut ou en ligne selon
447 "*ColMajor*", toutes les variables par défaut ou celles de la liste
448 "*ColNames*"), le vecteur est de type "*Vector*".
450 .. index:: single: ObservationError
451 .. index:: single: setObservationError
453 **setObservationError** (*Matrix, ScalarSparseMatrix, DiagonalSparseMatrix, Script, Stored*)
454 Cette commande permet de définir la matrice :math:`\mathbf{R}` de
455 covariance des erreurs d'observation. La matrice peut être définie de
456 manière complète par le mot-clé "*Matrix*", ou de manière parcimonieuse,
457 comme une matrice diagonale dont on donne la variance unique sur la
458 diagonale par "*ScalarSparseMatrix*", ou comme une matrice diagonale dont
459 on donne le vecteur des variances situé sur la diagonale par
460 "*DiagonalSparseMatrix*". Si on la définit par un script dans "*Script*",
461 la matrice est de type "*Matrix*" (par défaut), "*ScalarSparseMatrix*" ou
462 "*DiagonalSparseMatrix*" selon que l'une de ces variables est placée à
465 .. index:: single: ObservationOperator
466 .. index:: single: setObservationOperator
467 .. index:: single: ExtraArguments
469 **setObservationOperator** (*Matrix, OneFunction, ThreeFunctions, AppliedInXb, Parameters, Script, ExtraArguments, Stored*)
470 Cette commande permet de définir l'opérateur d'observation :math:`H`, qui
471 transforme les paramètres d'entrée :math:`\mathbf{x}` en résultats
472 :math:`\mathbf{y}` qui sont à comparer aux observations
473 :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type fonction
474 ou de type "*Matrix*". Dans le cas d'une fonction, différentes formes
475 fonctionnelles peuvent être utilisées, comme décrit dans la section
476 :ref:`section_ref_operator_requirements`, et entrées par les mots-clés
477 "*OneFunction*" ou "*ThreeFunctions*". Dans le cas d'une définition par
478 "*Script*", l'opérateur est de type "*Matrix*", "*OneFunction*" ou
479 "*ThreeFunctions*" selon que l'une de ces variables est placée à "*True*".
480 Dans le cas où l'opérateur :math:`H` évalué en :math:`\mathbf{x}^b` est
481 disponible, il peut être donné en utilisant "*AppliedInXb*" et sera
482 considéré comme un vecteur. Les paramètres de contrôle de l'approximation
483 numérique de l'opérateur adjoint, dans le cas "*OneFunction*", peuvent être
484 renseignés par un dictionnaire dans "*Parameters*". Les entrées
485 potentielles de ce dictionnaire de paramètres sont
486 "*DifferentialIncrement*", "*CenteredFiniteDifference*",
487 "*EnableMultiProcessing*", "*NumberOfProcesses*" (similaires à celles de
488 l'interface graphique). Si l'opérateur nécessite des paramètres fixes
489 complémentaires en plus de l'état :math:`\mathbf{x}`, ils peuvent être
490 fournis par la variable "*ExtraArguments*" sous la forme d'un dictionnaire
491 de paramètres nommés.
493 .. index:: single: set
495 **set** (*Concept,...*)
496 Cette commande permet de disposer d'une syntaxe équivalente pour toutes les
497 commandes de ce paragraphe. Son premier argument est le nom du concept à
498 définir (par exemple "*Background*" ou "*ObservationOperator*"), sur lequel
499 s'applique ensuite les arguments qui suivent, qui sont les mêmes que dans
500 les commandes individuelles précédentes. Lors de l'usage de cette commande,
501 il est indispensable de nommer les arguments (par exemple "*Vector=...*").
503 Paramétrer le calcul, les sorties, etc.
504 +++++++++++++++++++++++++++++++++++++++
506 .. index:: single: AlgorithmParameters
507 .. index:: single: setAlgorithmParameters
509 **setAlgorithmParameters** (*Algorithm, Parameters, Script*)
510 Cette commande permet de choisir l'algorithme de calcul ou de vérification
511 par l'argument "*Algorithm*" sous la forme d'un nom d'algorithme (on se
512 reportera utilement aux listes des :ref:`section_reference_assimilation` et
513 des :ref:`section_reference_checking`), et de définir les paramètres de
514 calcul par l'argument "*Parameters*". Dans le cas d'une définition par
515 "*Script*", le fichier indiqué doit contenir les deux variables
516 "*Algorithm*" et "*Parameters*" (ou "*AlgorithmParameters*" de manière
519 .. index:: single: setName
521 **setName** (*String*)
522 Cette commande permet de donner un titre court au cas de calcul.
524 .. index:: single: setDirectory
526 **setDirectory** (*String*)
527 Cette commande permet d'indiquer le répertoire courant d'exécution.
529 .. index:: single: setDebug
532 Cette commande permet d'activer le mode d'information détaillé lors de
535 .. index:: single: setNoDebug
538 Cette commande permet de désactiver le mode d'information détaillé lors de
541 .. index:: single: Observer
542 .. index:: single: setObserver
544 **setObserver** (*Variable, Template, String, Script, Info*)
545 Cette commande permet de définir un *observer* sur une variable courante ou
546 finale du calcul. On se reportera à la description des
547 :ref:`section_ref_observers_requirements` pour avoir leur liste et leur
548 format, et à la :ref:`section_reference` pour savoir quelles sont les
549 quantités observables. On définit comme un "*String*" le corps de
550 l'*observer*, en utilisant une chaîne de caractères incluant si nécessaire
551 des sauts de lignes. On recommande d'utiliser les patrons disponibles par
552 l'argument "*Template*". Dans le cas d'une définition par "*Script*", le
553 fichier indiqué doit contenir uniquement le corps de la fonction, comme
554 décrit dans les :ref:`section_ref_observers_requirements`. La variable
555 "*Info*" contient une chaîne de caractère d'information ou une chaine vide.
557 .. index:: single: UserPostAnalysis
558 .. index:: single: setUserPostAnalysis
559 .. index:: single: setUserPostAnalysis Template
561 **setUserPostAnalysis** (*Template, String, Script*)
562 Cette commande permet de définir le traitement des paramètres ou des
563 résultats après le déroulement de l'algorithme de calcul. Sa valeur est
564 définie comme nom de patron prédéfini, un fichier script ou une chaîne de
565 caractères. Cela permet de produire directement du code de post-processing
566 dans un cas ADAO. On peut d'utiliser les patrons disponibles par l'argument
567 "*Template*" (qui peut valoir "*AnalysisPrinter*", "*AnalysisSaver*" et
568 "*AnalysisPrinterAndSaver*"). Dans le cas d'une définition par "*Script*",
569 le fichier indiqué doit contenir uniquement les commandes que l'on aurait
570 pu mettre à la suite de l'exécution du calcul.
575 .. index:: single: execute
576 .. index:: single: Executor
577 .. index:: single: SaveCaseInFile
578 .. index:: single: nextStep
580 **execute** (*Executor, SaveCaseInFile, nextStep*)
581 Cette commande lance le calcul complet dans l'environnement d'exécution
582 choisi par le mot-clé *Executor*, qui est défini par défaut selon
583 l'environnement de lancement. Cet environnement peut être celui de
584 l'interpréteur Python, sans interaction avec YACS (demandé par la valeur
585 "*Python*"), ou celui de YACS (demandé par la valeur "*YACS*" [YACS]_). Si
586 un fichier est indiqué dans le mot-clé *SaveCaseInFile*, il sera utilisé
587 pour enregistrer la version associée du fichier de commande pour
588 l'environnement d'exécution requis. Le mot-clé booléen "*nextStep*" indique
589 que l'exécution repart du résultat de la précédente exécution sans la
590 stocker (valeur "*True*") ou non (valeur "*False*", par défaut). Lors de
591 l'exécution, les sorties courantes (standard et d'erreur) sont celles de
592 l'environnement choisi. On dispose si nécessaire (ou si possible) du
593 parallélisme interne des algorithmes dans ADAO, du parallélisme de YACS, et
594 du parallélisme interne du ou des codes de simulation utilisés.
596 Obtenir séparément les résultats de calcul
597 ++++++++++++++++++++++++++++++++++++++++++
599 .. index:: single: get
602 Cette commande permet d'extraire explicitement les variables disponibles en
603 sortie du cas de calcul TUI ADAO pour les utiliser dans la suite du
604 scripting, par exemple en visualisation. Elle a pour argument le nom d'un
605 variable dans "*Concept*", et renvoie en retour la grandeur sous la forme
606 d'une liste (même s'il n'y en a qu'un exemplaire) de cette variable de
607 base. Pour connaître la liste des variables et les utiliser, on se
608 reportera à l':ref:`subsection_r_o_v_Inventaire`, et plus généralement à la
609 fois aux :ref:`section_ref_output_variables` et aux documentations
610 individuelles des algorithmes.
612 Enregistrer, charger ou convertir les commandes de cas de calcul
613 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
615 L'enregistrement ou le chargement d'un cas de calcul concernent les quantités
616 et les actions qui lui sont liées par les commandes précédentes, à l'exclusion
617 d'opérations externes au cas (comme par exemple le post-processing qui peut
618 être développé après le cas de calcul). Les commandes enregistrées ou chargées
619 restent néanmoins parfaitement compatibles avec ces opérations en Python
622 .. index:: single: load
623 .. index:: single: FileName
624 .. index:: single: Content
625 .. index:: single: Object
626 .. index:: single: Formater
628 **load** (*FileName, Content, Object, Formater*)
629 Cette commande permet de lire ou charger un cas d'étude, à partir d'un
630 fichier "*FileName*" ou d'un contenu en mémoire par "*Content*" ou
631 "*Object*". Le mot-clé "*Formater*" peut désigner le format "*TUI*" pour
632 les commandes du type interface de programmation textuelle (défaut), et le
633 format "*COM*" pour les commandes du type COMM provenant de l'interface
636 .. index:: single: dump
638 **dump** (*FileName, Formater*)
639 Cette commande permet d'enregistrer, dans un fichier "*FileName*", les
640 commandes du cas d'étude en cours. Le mot-clé "*Formater*" peut désigner
641 les formats "*TUI*" pour les commandes du type interface de programmation
642 textuelle (défaut), et "*YACS*" pour les commandes du type YACS.
644 .. index:: single: convert
645 .. index:: single: FileNameFrom
646 .. index:: single: ContentFrom
647 .. index:: single: ObjectFrom
648 .. index:: single: FormaterFrom
649 .. index:: single: FileNameTo
650 .. index:: single: FormaterTo
652 **convert** (*FileNameFrom, ContentFrom, ObjectFrom, FormaterFrom, FileNameTo, FormaterTo*)
653 Cette commande permet de convertir directement d'un format reconnu à un
654 autre les commandes établissant le cas de calcul en cours. Certains
655 formats ne sont disponibles qu'en entrée ou qu'en sortie.
657 De plus, on peut obtenir une information simple sur le cas d'étude tel que
658 défini par l'utilisateur en utilisant directement la commande "*print*" de Python
659 sur le cas, à toute étape lors de sa construction. Par exemple::
661 from numpy import array, matrix
662 from adao import adaoBuilder
663 case = adaoBuilder.New()
664 case.set( 'AlgorithmParameters', Algorithm='3DVAR' )
665 case.set( 'Background', Vector=[0, 1, 2] )
668 dont le résultat est ici::
670 ================================================================================
672 ================================================================================
674 - AlgorithmParameters command has been set with values:
677 - Background command has been set with values:
680 .. _subsection_tui_advanced:
682 Exemples plus avancés de cas de calcul TUI ADAO
683 -----------------------------------------------
685 On propose ici des exemples plus complets de cas de calcul TUI ADAO, en donnant
686 l'objectif de l'exemple et un jeu de commandes qui permet de parvenir à cet
689 Exploitation indépendante des résultats d'un cas de calcul
690 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
692 L'objectif est d'effectuer en TUI la mise en données d'un cas de calcul ADAO,
693 son exécution, puis la récupération des résultats pour ensuite enchaîner sur
694 une exploitation indépendante de ces résultats (cette dernière n'étant pas
695 décrite ici, puisque dépendante de l'utilisateur).
697 Les hypothèses du cas utilisateur sont les suivantes. On suppose :
699 #. que l'on veut recaler 3 paramètres ``alpha``, ``beta`` et ``gamma`` dans un domaine borné,
700 #. que l'on dispose d'observations nommées ``observations``,
701 #. que l'utilisateur dispose en Python d'une fonction de simulation physique appelée ``simulation``, préalablement (bien) testée, qui transforme les 3 paramètres en résultats similaires aux observations,
702 #. 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.
704 Pour effectuer de manière simple cet essai de cas de calcul TUI, on se donne
705 par exemple les entrées suivantes, parfaitement arbitraires, en construisant
706 les observations par simulation pour se placer dans un cas d'expériences
707 jumelles (pour mémoire, voir la démarche :ref:`section_methodology_twin`)::
710 # Construction artificielle d'un exemple de données utilisateur
711 # -------------------------------------------------------------
716 alphamin, alphamax = 0., 10.
717 betamin, betamax = 3, 13
718 gammamin, gammamax = 1.5, 15.5
721 "Fonction de simulation H pour effectuer Y=H(X)"
723 __x = numpy.matrix(numpy.ravel(numpy.matrix(x))).T
724 __H = numpy.matrix("1 0 0;0 2 0;0 0 3; 1 2 3")
727 # Observations obtenues par simulation
728 # ------------------------------------
729 observations = simulation((2, 3, 4))
731 Le jeu de commandes que l'on peut utiliser est le suivant::
734 from adao import adaoBuilder
736 # Mise en forme des entrées
737 # -------------------------
738 Xb = (alpha, beta, gamma)
740 (alphamin, alphamax),
742 (gammamin, gammamax))
746 case = adaoBuilder.New()
748 'AlgorithmParameters',
752 "MaximumNumberOfSteps":100,
753 "StoreSupplementaryCalculations":[
756 "SimulatedObservationAtOptimum",
760 case.set( 'Background', Vector = numpy.array(Xb), Stored = True )
761 case.set( 'Observation', Vector = numpy.array(observations) )
762 case.set( 'BackgroundError', ScalarSparseMatrix = 1.0e10 )
763 case.set( 'ObservationError', ScalarSparseMatrix = 1.0 )
765 'ObservationOperator',
766 OneFunction = simulation,
767 Parameters = {"DifferentialIncrement":0.0001},
769 case.set( 'Observer', Variable="CurrentState", Template="ValuePrinter" )
772 # Exploitation indépendante
773 # -------------------------
774 Xbackground = case.get("Background")
775 Xoptimum = case.get("Analysis")[-1]
776 FX_at_optimum = case.get("SimulatedObservationAtOptimum")[-1]
777 J_values = case.get("CostFunctionJ")[:]
779 print("Nombre d'itérations internes...: %i"%len(J_values))
780 print("Etat initial...................: %s"%(numpy.ravel(Xbackground),))
781 print("Etat optimal...................: %s"%(numpy.ravel(Xoptimum),))
782 print("Simulation à l'état optimal....: %s"%(numpy.ravel(FX_at_optimum),))
785 L'exécution de jeu de commandes donne le résultat suivant::
787 CurrentState [ 5. 7. 9.]
788 CurrentState [ 0. 3. 1.5]
789 CurrentState [ 1.40006418 3.86705307 3.7061137 ]
790 CurrentState [ 1.42580231 3.68474804 3.81008738]
791 CurrentState [ 1.60220353 3.0677108 4.06146069]
792 CurrentState [ 1.72517855 3.03296953 4.04915706]
793 CurrentState [ 2.00010755 3. 4.00055409]
794 CurrentState [ 1.99995528 3. 3.99996367]
795 CurrentState [ 2.00000007 3. 4.00000011]
796 CurrentState [ 2. 3. 4.]
798 Nombre d'itérations internes...: 10
799 Etat initial...................: [ 5. 7. 9.]
800 Etat optimal...................: [ 2. 3. 4.]
801 Simulation à l'état optimal....: [ 2. 6. 12. 20.]
803 Comme il se doit en expériences jumelles, avec une confiance majoritairement
804 placée dans les observations, on constate que l'on retrouve bien les paramètres
805 qui ont servi à construire artificiellement les observations.
807 .. Réconciliation de courbes à l'aide de MedCoupling
808 .. +++++++++++++++++++++++++++++++++++++++++++++++++
810 .. Utilisation de fonctions de surveillance de type "observer"
811 .. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
813 .. Equivalences entre l'interface graphique (GUI) et l'interface textuelle (TUI)
814 .. -----------------------------------------------------------------------------
816 .. [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.
818 .. [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.
820 .. [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.