]> SALOME platform Git repositories - modules/adao.git/blob - doc/fr/examples.rst
Salome HOME
Illustrations corrections and improvements
[modules/adao.git] / doc / fr / examples.rst
1 ..
2    Copyright (C) 2008-2017 EDF R&D
3
4    This file is part of SALOME ADAO module.
5
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.
10
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.
15
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
19
20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
21
22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
23
24 .. _section_examples:
25
26 ================================================================================
27 **[DocU]** Tutoriaux sur l'utilisation du module ADAO
28 ================================================================================
29
30 .. |eficas_new| image:: images/eficas_new.png
31    :align: middle
32    :scale: 50%
33 .. |eficas_save| image:: images/eficas_save.png
34    :align: middle
35    :scale: 50%
36 .. |eficas_saveas| image:: images/eficas_saveas.png
37    :align: middle
38    :scale: 50%
39 .. |eficas_yacs| image:: images/eficas_yacs.png
40    :align: middle
41    :scale: 50%
42
43 Cette section présente quelques exemples d'utilisation du module ADAO dans
44 SALOME. Le premier montre comment construire un cas simple d'assimilation de
45 données définissant explicitement toutes les données d'entrée requises à travers
46 l'interface graphique d'édition (GUI). Le second montre, sur le même cas,
47 comment définir les données d'entrée à partir de sources externes à travers des
48 scripts. On présente ici toujours des scripts Python car ils sont directement
49 insérables dans les noeuds de script de YACS, mais les fichiers externes peuvent
50 utiliser d'autres langages.
51
52 Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
53 :ref:`section_theory`.
54
55 Construire un cas d'estimation avec une définition explicite des données
56 ------------------------------------------------------------------------
57
58 Cet exemple simple est un cas de démonstration, et il décrit comment mettre au
59 point un environnement d'estimation par BLUE de manière à obtenir un *état
60 estimé par méthode de moindres carrés pondérés* d'un système à partir d'une
61 observation de l'état et d'une connaissance *a priori* (ou ébauche) de cet état.
62 En d'autres termes, on cherche l'intermédiaire pondéré entre les vecteurs
63 d'observation et d'ébauche. Toutes les valeurs numériques de cet exemple sont
64 arbitraires.
65
66 Conditions d'expérience
67 +++++++++++++++++++++++
68
69 On choisit d'opérer dans un espace à 3 dimensions. La 3D est choisie de manière
70 à restreindre la taille des objets numériques à entrer explicitement par
71 l'utilisateur, mais le problème n'est pas dépendant de la dimension et peut être
72 posé en dimension 10, 100, 1000... L'observation :math:`\mathbf{y}^o` vaut 1
73 dans chaque direction, donc::
74
75     Yo = [1 1 1]
76
77 L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
78 priori* ou une régularisation mathématique, vaut 0 dans chaque direction, ce qui
79 donne donc::
80
81     Xb = [0 0 0]
82
83 La mise en oeuvre de l'assimilation de données requiert des informations sur les
84 covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`, respectivement
85 pour les variables d'observation et d'ébauche. On choisit ici des erreurs
86 décorrélées (c'est-à-dire des matrices diagonales) et d'avoir la même variance
87 de 1 pour toutes les variables (c'est-à-dire des matrices identité). On pose
88 donc::
89
90     B = R = [1 0 0 ; 0 1 0 ; 0 0 1]
91
92 Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
93 convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
94 dimensions d'espace sont les mêmes, on peut choisir l'identité comme opérateur
95 d'observation::
96
97     H = [1 0 0 ; 0 1 0 ; 0 0 1]
98
99 Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
100 vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
101 *analysis*, noté :math:`\mathbf{x}^a`, et valant::
102
103
104     Xa = [0.5 0.5 0.5]
105
106 Pour étendre cet exemple, on peut modifier les variances représentées par
107 :math:`\mathbf{B}` ou :math:`\mathbf{R}` indépendamment, et l'analyse
108 :math:`\mathbf{x}^a` se déplacera vers :math:`\mathbf{y}^o` ou vers
109 :math:`\mathbf{x}^b`, en proportion inverse des variances dans
110 :math:`\mathbf{B}` et :math:`\mathbf{R}`. Comme autre extension, on peut aussi
111 dire qu'il est équivalent de rechercher l'analyse à l'aide d'un algorithme de
112 BLUE ou d'un algorithme de 3DVAR.
113
114 Utiliser l'interface graphique (GUI) pour construire le cas ADAO
115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
116
117 En premier lieu, il faut activer le module ADAO en choisissant le bouton ou le
118 menu approprié de module de SALOME, et on voit :
119
120   .. _adao_activate2:
121   .. image:: images/adao_activate.png
122     :align: center
123     :width: 100%
124   .. centered::
125     **Activation du module ADAO dans SALOME**
126
127 Choisir le bouton "*Nouveau*" dans cette fenêtre. On obtient directement
128 l'interface de l'éditeur intégré de cas pour la définition de variables, en même
129 temps que l'"*Arbre d'étude*" de SALOME. On peut alors choisir le bouton
130 "*Nouveau*" |eficas_new| pour créer un nouveau cas ADAO, et on voit :
131
132   .. _adao_viewer:
133   .. image:: images/adao_viewer.png
134     :align: center
135     :width: 100%
136   .. centered::
137     **L'éditeur intégré pour la définition de cas dans le module ADAO**
138
139 Ensuite, il faut remplir les variables pour construire le cas ADAO en utilisant
140 les conditions d'expérience décrites ci-dessus. L'ensemble des informations
141 techniques données au-dessus sont à insérer directement dans la définition du
142 cas ADAO, en utilisant le type *String* pour toutes les variables. Lorsque la
143 définition du cas est prête, il faut l'enregistrer comme un fichier natif de ype
144 "*JDC (\*.comm)*" à un endroit quelconque dans l'arborescence de l'utilisateur.
145 Il faut bien se rappeler que d'autres fichiers seront aussi créés à côté de ce
146 premier, donc il est judicieux de faire un répertoire spécifique pour ce cas, et
147 d'enregistrer dedans le fichier. Le nom du fichier apparaît dans la fenêtre de
148 l'"*Arbre d'étude*", sous le menu "*ADAO*". La définition finale du cas
149 ressemble à :
150
151   .. _adao_jdcexample01:
152   .. image:: images/adao_jdcexample01.png
153     :align: center
154     :width: 100%
155   .. centered::
156     **Définition des conditions d'expérience choisies pour le cas ADAO**
157
158 Pour poursuivre, on a besoin de générer le schéma YACS à partir de la définition
159 du cas ADAO. Pour faire cela, on peut activer le menu contextuel par click droit
160 sur le nom du cas dans la fenêtre de l'"*Arbre d'étude*", et choisir le
161 sous-menu "*Exporter vers YACS*" (ou le bouton "*Exporter vers YACS*"
162 |eficas_yacs|) comme ci-dessous :
163
164   .. _adao_exporttoyacs00:
165   .. image:: images/adao_exporttoyacs.png
166     :align: center
167     :scale: 75%
168   .. centered::
169     **Sous-menu contextuel "*Exporter vers YACS*" pour générer le schéma YACS à partir du cas ADAO**
170
171 Cette commande conduit à la génération d'un schéma YACS, à l'activation du module
172 YACS dans SALOME, et à ouvrir le nouveau schéma dans l'interface graphique du
173 module YACS [#]_. Après avoir éventuellement réorganisé les noeuds en utilisant
174 le sous-menu contextuel "*arranger les noeuds locaux*" de la vue graphique du
175 schéma YACS, on obtient la représentation suivante du schéma ADAO généré :
176
177   .. _yacs_generatedscheme:
178   .. image:: images/yacs_generatedscheme.png
179     :align: center
180     :width: 100%
181   .. centered::
182     **Schéma YACS généré à partir du cas ADAO**
183
184 Après ce point, toutes les modifications, exécutions et post-processing du
185 schéma d'assimilation de données seront effectués dans le module YACS. De
186 manière à vérifier les résultats d'une manière simple, on utilise le noeud
187 "*UserPostAnalysis*" (ou on crée ici un nouveau noeud YACS par le sous-menu
188 "*Noeud de script in-line*" dans la vue graphique de YACS).
189
190 Ce noeud de script va récupérer l'analyse issue de l'assimilation de données
191 depuis le port de sortie "*algoResults*" du bloc de calcul (qui donne accés à un
192 objet Python SALOME), et va l'afficher à la sortie standard.
193
194 Pour obtenir ceci, ce noeud de script doit comporter un port d'entrée de type
195 "*pyobj*", nommé "*Study*" par exemple, qui doit être relié graphiquement au
196 port de sortie "*algoResults*" du bloc de calcul. Ensuite, le code pour remplir
197 le noeud de script est::
198
199     Xa = Study.getResults().get("Analysis")[-1]
200
201     print
202     print "Analysis =",Xa
203     print
204
205 Le schéma YACS (initial ou complété) peut être enregistré (en écrasant le schéma
206 généré si la commande ou le bouton "*Enregistrer*" sont utilisés, ou sinon avec
207 un nom nouveau par la commande "*Enregistrer sous*"). De manière pratique, la
208 mise au point d'une telle procédure de post-processing peut être réalisée dans
209 YACS pour la tester, et ensuite entièrement enregistrée dans un script Python
210 qui peut être intégré au cas ADAO en utilisant le mot-clé "*UserPostAnalysis*".
211
212 Ensuite, de manière classique dans YACS, le schéma doit être compilé, et ensuite
213 être exécuté. Après la fin de l'exécution, les affichages sur la sortie standard
214 sont disponibles dans la fenêtre "*fenêtre de sortie de YACS*" (ou "*YACS
215 Container Log*"), obtenue par clic droit à l'aide du menu contextuel de la
216 fenêtre "*proc*" du schéma YACS comme montré ci-dessous:
217
218   .. _yacs_containerlog:
219   .. image:: images/yacs_containerlog.png
220     :align: center
221     :width: 100%
222   .. centered::
223     **Menu YACS de la fenêtre de sortie, et boite de dialogue montrant la sortie**
224
225 On vérifie que le résultat est correct en observant si la fenêtre de sortie
226 contient la ligne suivante::
227
228     Analysis = [0.5, 0.5, 0.5]
229
230 comme montré dans l'image précédente.
231
232 Pour étendre cet exemple, on peut remarquer que le même problème résolu par un
233 algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi lors
234 de l'étape de construction du cas ADAO, avant d'entrer dans l'étape YACS. Le cas
235 ADAO en 3DVAR est entièrement similaire au cas algorithmique du BLUE, comme
236 montré dans la figure suivante:
237
238   .. _adao_jdcexample02:
239   .. image:: images/adao_jdcexample02.png
240     :align: center
241     :width: 100%
242   .. centered::
243     **Définir un cas ADAO en 3DVAR est entièrement similaire à un cas en BLUE**
244
245 Il n'y a qu'une seule commande qui change, avec "*3DVAR*" dans le champ
246 "*Algorithm*" à la place de "*Blue*".
247
248 Construire un cas d'estimation avec une définition de données externes par scripts
249 ----------------------------------------------------------------------------------
250
251 Il est utile d'acquérir une partie ou la totalité des données depuis une
252 définition externe, en utilisant des scripts Python pour donner accès à ces
253 données. À titre d'exemple, on construit ici un cas ADAO présentant le même
254 dispositif expérimental que dans l'exemple ci-dessus `Construire un cas
255 d'estimation avec une définition explicite des données`_, mais en utilisant des
256 données issues d'un unique fichier script Python externe.
257
258 En premier lieu, on écrit le fichier script suivant, utilisant des noms
259 conventionnels pour les variables requises. Ici toutes les variables sont
260 définies dans le même script, mais l'utilisateur peut choisir de séparer le
261 fichier en plusieurs autres, ou de mélanger une définition explicite des données
262 dans l'interface graphique ADAO et une définition implicite dans des fichiers
263 externes. Le fichier script actuel ressemble à::
264
265     import numpy
266     #
267     # Definition of the Background as a vector
268     # ----------------------------------------
269     Background = [0, 0, 0]
270     #
271     # Definition of the Observation as a vector
272     # -----------------------------------------
273     Observation = "1 1 1"
274     #
275     # Definition of the Background Error covariance as a matrix
276     # ---------------------------------------------------------
277     BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
278     #
279     # Definition of the Observation Error covariance as a matrix
280     # ----------------------------------------------------------
281     ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
282     #
283     # Definition of the Observation Operator as a matrix
284     # --------------------------------------------------
285     ObservationOperator = numpy.identity(3)
286
287 Les noms des variables Python sont obligatoires, de manière à définir les bonnes
288 variables dans le cas, mais le script Python peut être plus conséquent et
289 définir des classes, des fonctions, des accès à des fichiers ou des bases de
290 données, etc. avec des noms différents. De plus, le fichier ci-dessus présente
291 différentes manières de définir des vecteurs ou des matrices, utilisant des
292 listes, des chaînes de caractères (comme dans Numpy ou Octave), des types
293 vecteur ou matrice de Numpy, et des fonctions spéciales de Numpy. Toutes ces
294 syntaxes sont valides.
295
296 Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
297 l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
298 utilise l'interface graphique (GUI) pour construire le cas ADAO. La procédure
299 pour compléter le cas est similaire à celle de l'exemple précédent à part le
300 fait que, au lieu de choisir l'option "*String*" pour le mot-clé "*FROM*" de
301 chaque variable, on choisit l'option "*Script*". Cela conduit à une entrée
302 "*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique, permettant de choisir un
303 fichier de la manière suivante:
304
305   .. _adao_scriptentry01:
306   .. image:: images/adao_scriptentry01.png
307     :align: center
308     :width: 100%
309   .. centered::
310     **Définir une variable d'entrée en utilisant un fichier script externe**
311
312 Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
313 précédent `Construire un cas d'estimation avec une définition explicite des
314 données`_.
315
316 Dans la pratique, cette démarche par scripts est la manière la plus facile pour
317 récupérer des information depuis des calculs en ligne ou préalables, depuis des
318 fichiers statiques, depuis des bases de données ou des flux informatiques,
319 chacun pouvant être dans ou hors SALOME. Cela permet aussi de modifier aisément
320 des données d'entrée, par exemple à des fin de débogage ou pour des traitements
321 répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
322 d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
323 "sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
324 peuvent être directement introduites dans l'exécution du schéma YACS.
325 L'utilisateur doit vérifier avec attention le contenu de ses scripts.**
326
327 Ajout de paramètres pour contrôler l'algorithme d'assimilation de données
328 -------------------------------------------------------------------------
329
330 On peut ajouter des paramètres optionnels pour contrôler le calcul de
331 l'algorithme d'assimilation de données. Ceci se fait en utilisant les paramètres
332 optionnels dans la commande "*AlgorithmParameters*" de la définition du cas
333 ADAO, qui est un mot-clé de la commande générale "*ASSIMILATION_STUDY*". Ce
334 mot-clé nécessite une définition explicite des valeurs à partir de valeurs par
335 défaut, ou à partir d'un dictionnaire Python, contenant des paires clé/valeur.
336 La liste des paramètres optionnels possibles sont donnés dans la section
337 :ref:`section_reference` et ses sous-sections. On recommande d'utiliser la
338 définition explicite de valeurs à partir de la liste par défaut de paramètres
339 optionnels, comme ici avec le "*MaximumNumberOfSteps*":
340
341   .. _adao_scriptentry02:
342   .. image:: images/adao_scriptentry02.png
343     :align: center
344     :width: 100%
345   .. centered::
346     **Ajouter des paramètres pour contrôler l'algorithme et les sorties**
347
348 Le dictionnaire peut être défini, par exemple, dans un fichiers externe de
349 script Python, en utilisant le nom obligatoire de variable
350 "*AlgorithmParameters*" pour le dictionnaire. Toutes les clés dans le
351 dictionnaire sont optionnelles, elles disposent toutes d'une valeur par défaut,
352 et elles peuvent être présentes sans être utiles. Par exemple::
353
354     AlgorithmParameters = {
355         "Minimizer" : "LBFGSB", # Recommended
356         "MaximumNumberOfSteps" : 10,
357         }
358
359 Si aucune borne n'est requise sur les variables de contrôle, alors on peut
360 choisir les algorithmes de minimisation "*BFGS*" ou "*CG*" pour tous les
361 algorithmes variationnels d'assimilation de données ou d'optimisation. Pour
362 l'optimisation sous contraintes, l'algorithme "*LBFGSB*" est bien souvent plus
363 robuste, mais le "*TNC*" est parfois plus performant. De manière générale, le
364 choix de l'algorithme "*LBFGSB*" est recommandé. Ensuite le script peut être
365 ajouté au cas ADAO, dans une entrée de type fichier associé au format "*Dict*"
366 dans le mot-clé "*Parameters*".
367
368 Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
369 précédent `Construire un cas d'estimation avec une définition explicite des
370 données`_. Le dictionnaire peut aussi être donné directement dans le champ
371 d'entrée de type chaîne de caractères pour le mot-clé.
372
373 Construire un cas complexe avec une définition de données externes par scripts
374 ------------------------------------------------------------------------------
375
376 Cet exemple plus complexe et complet peut être considéré comme un cadre de base
377 pour le traitement des entrées de l'utilisateur, qui doit ensuite être adapté à
378 chaque application réelle. Néanmoins, les squelettes de fichiers sont
379 suffisamment généraux pour avoir été utilisés pour des applications variées en
380 neutronique, mécanique des fluides... Ici, on ne s'intéresse pas aux résultats,
381 mais plus sur le contrôle de l'utilisateur des entrées et sorties dans un cas
382 ADAO. Comme précédemment, toutes les valeurs numériques de cet exemple sont
383 arbitraires.
384
385 L'objectif est de configurer les entrées et les sortie d'un problème physique
386 d'estimation par des scripts externes Python, en utilisant un opérateur
387 non-linéaire général, en ajoutant un contrôle sur les paramètres et ainsi de
388 suite... Les scripts complets peuvent être trouvés dans le répertoire des
389 exemples de squelettes ADAO sous le nom de
390 "*External_data_definition_by_scripts*".
391
392 Conditions d'expérience
393 +++++++++++++++++++++++
394
395 On continue à opérer dans un espace à 3 dimensions, afin de limiter la taille de
396 l'objet numérique indiqué dans les scripts, mais le problème ne dépend pas de la
397 dimension.
398
399 On choisit un contexte d'expériences jumelles, en utilisant un état vrai
400 :math:`\mathbf{x}^t` connu, mais de valeur arbitraire::
401
402     Xt = [1 2 3]
403
404 L'état d'ébauche :math:`\mathbf{x}^b`, qui représentent une connaissance *a
405 priori* de l'état vrai, est construit comme une perturbation aléatoire
406 gaussienne de 20% de l'état vrai :math:`\mathbf{x}^t` pour chaque composante,
407 qui est::
408
409     Xb = Xt + normal(0, 20%*Xt)
410
411 Pour décrire la matrice des covariances d'erreur d'ébauche math:`\mathbf{B}`, on
412 fait comme précédemment l'hypothèse d'erreurs décorrélées (c'est-à-dire, une
413 matrice diagonale, de taille 3x3 parce-que :math:`\mathbf{x}^b` est de taille 3)
414 et d'avoir la même variance de 0,1 pour toutes les variables. On obtient::
415
416     B = 0.1 * diagonal( length(Xb) )
417
418 On suppose qu'il existe un opérateur d'observation :math:`\mathbf{H}`, qui peut
419 être non linéaire. Dans une procédure réelle de recalage ou de problème inverse,
420 les codes de simulation physique sont intégrés dans l'opérateur d'observation.
421 On a également besoin de connaître son gradient par rapport à chaque variable
422 estimée, ce qui est une information rarement connu avec les codes industriels.
423 Mais on verra plus tard comment obtenir un gradient approché dans ce cas.
424
425 Étant en expériences jumelles, les observations :math:`\mathbf{y}^o` et leur
426 matrice de covariances d'erreurs :math:`\mathbf{R}` sont générées en utilisant
427 l'état vrai :math:`\mathbf{x}^t` et l'opérateur d'observation
428 :math:`\mathbf{H}`::
429
430     Yo = H( Xt )
431
432 et, avec un écart-type arbitraire de 1% sur chaque composante de l'erreur::
433
434     R = 0.0001 * diagonal( length(Yo) )
435
436 Toutes les informations requises pour l'estimation par assimilation de données
437 sont maintenant définies.
438
439 Squelettes des scripts décrivant les conditions d'expérience
440 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
441
442 On donne ici les éléments essentiels de chaque script utilisé par la suite pour
443 construire le cas ADAO. On rappelle que l'utilisation de ces scripts dans de
444 réels fichiers Python nécessite de définir correctement le chemin de modules ou
445 des codes importés (même si le module est dans le même répertoire que le fichier
446 Python qui l'importe. On indique le chemin à renseigner en utilisant la mention
447 ``"# INSERT PHYSICAL SCRIPT PATH"``), l'encodage si nécessaire, etc. Les noms de
448 fichiers indiqués pour les scripts qui suivent sont arbitraires. Des exemples
449 complets de fichiers scripts sont disponibles dans le répertoire standard des
450 exemples ADAO.
451
452 On définit en premier lieu l'état vrai :math:`\mathbf{x}^t` et une fonction
453 utiles à la construction de matrices, dans un fichier script Python nommé
454 ``Physical_data_and_covariance_matrices.py``::
455
456     import numpy
457     #
458     def True_state():
459         """
460         Arbitrary values and names, as a tuple of two series of same length
461         """
462         return (numpy.array([1, 2, 3]), ['Para1', 'Para2', 'Para3'])
463     #
464     def Simple_Matrix( size, diagonal=None ):
465         """
466         Diagonal matrix, with either 1 or a given vector on the diagonal
467         """
468         if diagonal is not None:
469             S = numpy.diag( diagonal )
470         else:
471             S = numpy.matrix(numpy.identity(int(size)))
472         return S
473
474 On définit ensuite l'état d'ébauche :math:`\mathbf{x}^b` comme une perturbation
475 aléatoire de l'état vrai, en ajoutant une *variable ADAO requise* à la fin du
476 script de définition, de manière à exporter la valeur définie. C'est réalisé
477 dans un fichier de script Python nommé ``Script_Background_xb.py``::
478
479     from Physical_data_and_covariance_matrices import True_state
480     import numpy
481     #
482     xt, names = True_state()
483     #
484     Standard_deviation = 0.2*xt # 20% for each variable
485     #
486     xb = xt + abs(numpy.random.normal(0.,Standard_deviation,size=(len(xt),)))
487     #
488     # Creating the required ADAO variable
489     # ------------------------------------
490     Background = list(xb)
491
492 De la même manière, on définit la matrice des covariances de l'erreur d'ébauche
493 :math:`\mathbf{B}` comme une matrice diagonale, de la même longueur de diagonale
494 que l'ébauche de la valeur vraie, en utilisant la fonction d'aide déjà définie.
495 C'est réalisé dans un fichier script Python nommé
496 ``Script_BackgroundError_B.py``::
497
498     from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
499     #
500     xt, names = True_state()
501     #
502     B = 0.1 * Simple_Matrix( size = len(xt) )
503     #
504     # Creating the required ADAO variable
505     # -----------------------------------
506     BackgroundError = B
507
508 Pour poursuivre, on a besoin de l'opérateur d'observation :math:`\mathbf{H}`
509 comme une fonction de l'état. Il est ici défini dans un fichier externe nommé 
510 ``"Physical_simulation_functions.py"``, qui doit contenir une fonction appelée
511 ``"DirectOperator"``. Cette fonction est une une fonction utilisateur,
512 représentant de manière programmée l'opérateur :math:`\mathbf{H}`. On suppose
513 que cette fonction est donnée par l'utilisateur. Un squelette simple est donné
514 ici par facilité::
515
516     def DirectOperator( XX ):
517         """ Direct non-linear simulation operator """
518         #
519         # --------------------------------------> EXAMPLE TO BE REMOVED
520         if type(XX) is type(numpy.matrix([])):  # EXAMPLE TO BE REMOVED
521             HX = XX.A1.tolist()                 # EXAMPLE TO BE REMOVED
522         elif type(XX) is type(numpy.array([])): # EXAMPLE TO BE REMOVED
523             HX = numpy.matrix(XX).A1.tolist()   # EXAMPLE TO BE REMOVED
524         else:                                   # EXAMPLE TO BE REMOVED
525             HX = XX                             # EXAMPLE TO BE REMOVED
526         # --------------------------------------> EXAMPLE TO BE REMOVED
527         #
528         return numpy.array( HX )
529
530 On n'a pas besoin des opérateurs linéaires associés ``"TangentOperator"`` et
531 ``"AdjointOperator"`` car ils vont être approximés en utilisant les capacités
532 d'ADAO.
533
534 On insiste sur le fait que ces opérateurs non-linéaire ``"DirectOperator"``,
535 linéaire tangent ``"TangentOperator"`` et linéaire adjoint ``"AdjointOperator"``
536 proviennent de la connaissance de la physique, incluant le code de simulation de
537 référence physique, et doivent être soigneusement mis au point par l'utilisateur
538 de l'assimilation de données ou de l'optimisation. Les erreurs de simulation ou
539 d'usage des opérateurs ne peuvent pas être détectés ou corrigés par
540 l'environnement seul ADAO d'assimilation de données et d'optimisation.
541
542 Dans cet environnement d'expériences jumelles, l'observation
543 :math:`\mathbf{y}^o` et sa matrice des covariances d'erreur :math:`\mathbf{R}`
544 peuvent être générées. C'est réalisé dans deux fichiers de script Python, le
545 premier étant nommé ``Script_Observation_yo.py``::
546
547     from Physical_data_and_covariance_matrices import True_state
548     from Physical_simulation_functions import DirectOperator
549     #
550     xt, noms = True_state()
551     #
552     yo = DirectOperator( xt )
553     #
554     # Creating the required ADAO variable
555     # -----------------------------------
556     Observation = list(yo)
557
558 et le second nommé ``Script_ObservationError_R.py``::
559
560     from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
561     from Physical_simulation_functions import DirectOperator
562     #
563     xt, names = True_state()
564     #
565     yo = DirectOperator( xt )
566     #
567     R  = 0.0001 * Simple_Matrix( size = len(yo) )
568     #
569     # Creating the required ADAO variable
570     # -----------------------------------
571     ObservationError = R
572
573 Comme dans les exemples précédents, il peut être utile de définir certains
574 paramètres pour l'algorithme d'assimilation de données. Par exemple, si on
575 utilise l'algorithme standard de "*3DVAR*", les paramètres suivants peuvent être
576 définis dans un fichier de script Python nommé
577 ``Script_AlgorithmParameters.py``::
578
579     # Creating the required ADAO variable
580     # -----------------------------------
581     AlgorithmParameters = {
582         "Minimizer" : "LBFGSB",      # Recommended
583         "MaximumNumberOfSteps" : 15, # Number of global iterative steps
584         "Bounds" : [
585             [ None, None ],          # Bound on the first parameter
586             [ 0., 4. ],              # Bound on the second parameter
587             [ 0., None ],            # Bound on the third parameter
588             ],
589     }
590
591 Enfin, il est courant de post-traiter les résultats, en les récupérant aprés la
592 phase d'assimilation de données de manière à les analyser, les afficher ou les
593 représenter. Cela nécessite d'utiliser un fichier script Python intermédiaire de
594 manière à extraire ces résultats à la fin de la procédure d'assimilation de
595 données ou d'optimisation. L'exemple suivant de fichier script Python, nommé
596 ``Script_UserPostAnalysis.py``, illustre le fait::
597
598     from Physical_data_and_covariance_matrices import True_state
599     import numpy
600     #
601     xt, names   = True_state()
602     xa          = ADD.get("Analysis")[-1]
603     x_series    = ADD.get("CurrentState")[:]
604     J           = ADD.get("CostFunctionJ")[:]
605     #
606     # Verifying the results by printing
607     # ---------------------------------
608     print
609     print "xt = %s"%xt
610     print "xa = %s"%numpy.array(xa)
611     print
612     for i in range( len(x_series) ):
613         print "Etape %2i : J = %.5e  et  X = %s"%(i, J[i], x_series[i])
614     print
615
616 Finalement, on obtient la description de l'ensemble des conditions
617 d'expériences à travers la série de fichiers listée ici:
618
619 #.      ``Physical_data_and_covariance_matrices.py``
620 #.      ``Physical_simulation_functions.py``
621 #.      ``Script_AlgorithmParameters.py``
622 #.      ``Script_BackgroundError_B.py``
623 #.      ``Script_Background_xb.py``
624 #.      ``Script_ObservationError_R.py``
625 #.      ``Script_Observation_yo.py``
626 #.      ``Script_UserPostAnalysis.py``
627
628 On insiste ici sur le fait que tous ces scripts sont écrits par l'utilisateur et
629 ne peuvent être testés automatiquement par ADAO. Ainsi, l'utilisateur est tenu
630 de vérifier les scripts (et en particulier leurs entrées/sorties) afin de
631 limiter les difficultés de débogage. On rappelle que: **la méthodologie par
632 scripts n'est pas une procédure "sûre", en ce sens que des données erronées ou
633 des erreurs dans les calculs, peuvent être directement introduites dans
634 l'exécution du schéma YACS.**
635
636 Construire la cas avec une définition de données externes par scripts
637 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
638
639 Tous ces scripts peuvent ensuite être utilisés pour définir le cas ADAO avec une
640 définition de données externes par des fichiers de script Python. Cela se
641 réalise de manière tout à fait similaire à la méthode décrite dans la partie
642 précédente `Construire un cas d'estimation avec une définition de données
643 externes par scripts`_. Pour chaque variable à définir, on sélectionne l'option
644 "*Script*"  du mot-clé "*FROM*", ce qui conduit à une entrée
645 "*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique. Pour le mot-clé
646 "*ObservationOperator*", on choisit la forme "*ScriptWithOneFunction*" et on
647 conserve la valeur par défaut de l'incrément différentiel.
648
649 Les autres étapes pour construire le cas ADAO sont exactement les mêmes que dans
650 la partie précédente `Construire un cas d'estimation avec une définition
651 explicite des données`_.
652
653 En utilisant l'opérateur linéaire simple :math:`\mathbf{H}` du fichier script
654 Python ``Physical_simulation_functions.py`` disponible dans le répertoire
655 standard des exemples, les résultats ressemblent à::
656
657     xt = [1 2 3]
658     xa = [ 1.000014    2.000458  3.000390]
659
660     Etape  0 : J = 1.81750e+03  et  X = [1.014011, 2.459175, 3.390462]
661     Etape  1 : J = 1.81750e+03  et  X = [1.014011, 2.459175, 3.390462]
662     Etape  2 : J = 1.79734e+01  et  X = [1.010771, 2.040342, 2.961378]
663     Etape  3 : J = 1.79734e+01  et  X = [1.010771, 2.040342, 2.961378]
664     Etape  4 : J = 1.81909e+00  et  X = [1.000826, 2.000352, 3.000487]
665     Etape  5 : J = 1.81909e+00  et  X = [1.000826, 2.000352, 3.000487]
666     Etape  6 : J = 1.81641e+00  et  X = [1.000247, 2.000651, 3.000156]
667     Etape  7 : J = 1.81641e+00  et  X = [1.000247, 2.000651, 3.000156]
668     Etape  8 : J = 1.81569e+00  et  X = [1.000015, 2.000432, 3.000364]
669     Etape  9 : J = 1.81569e+00  et  X = [1.000015, 2.000432, 3.000364]
670     Etape 10 : J = 1.81568e+00  et  X = [1.000013, 2.000458, 3.000390]
671     ...
672
673 L'état au premier pas est l'état d'ébauche :math:`\mathbf{x}^b` généré
674 aléatoirement. Au cours du calcul, ces affichages sur la sortie standard sont
675 disponibles dans la fenêtre "*fenêtre de sortie de YACS*", que l'on obtient par
676 clic droit sur la fenêtre "*proc*" du schéma YACS exécuté.
677
678 .. [#] 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.