2 Copyright (C) 2008-2014 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 .. _section_ref_operator_requirements:
26 Exigences pour les fonctions décrivant un opérateur
27 ---------------------------------------------------
29 Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en
30 oeuvre les procédures d'assimilation de données ou d'optimisation. Ils
31 comprennent la simulation physique par des calculs numériques, mais aussi le
32 filtrage et de restriction pour comparer la simulation à l'observation.
33 L'opérateur d'évolution est ici considéré dans sa forme incrémentale, qui
34 représente la transition entre deux états successifs, et il est alors similaire
35 à l'opérateur d'observation.
37 Schématiquement, un opérateur doit donner une solution étant donné les
38 paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au
39 cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un
40 tel processus est une fonction. Il a été brièvement décrit dans la section
41 :ref:`section_theory` et il est généralisée ici par la relation:
43 .. math:: \mathbf{y} = O( \mathbf{x} )
45 entre les pseudo-observations :math:`\mathbf{y}` et les paramètres
46 :math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution
47 :math:`O`. La même représentation fonctionnelle peut être utilisée pour le
48 modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint
49 :math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes
50 d'assimilation de données ou d'optimisation.
52 En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et
53 :math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et
54 ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur
55 Numpy) ou orientés (de type matrice Numpy).
57 Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à
58 fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière
61 Cette fonction est généralement donnée comme un script qui peut être exécuté
62 dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes
63 externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme
64 nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme
65 adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer.
67 Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation
68 fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*"
69 de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le
70 montre la figure suivante:
72 .. eficas_operator_function:
73 .. image:: images/eficas_operator_function.png
77 **Choisir une représentation fonctionnelle de l'opérateur**
79 Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*"
80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
82 .. index:: single: ScriptWithOneFunction
83 .. index:: single: DirectOperator
84 .. index:: single: DifferentialIncrement
85 .. index:: single: CenteredFiniteDifference
87 La première consiste à ne fournir qu'une seule fonction potentiellement non
88 linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en
89 utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de
90 l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir
91 la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par
92 exemple, le script peut suivre le modèle suivant::
94 def DirectOperator( X ):
95 """ Opérateur direct de simulation non-linéaire """
101 Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément
102 différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface
103 graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par
104 défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies
105 pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation
106 différences finies peut aussi être choisi à travers l'interface, en utilisant le
107 mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du
108 premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du
109 second ordre (qui coûte numériquement deux fois plus cher que le premier ordre).
111 Cette première forme de définition de l'opérateur permet aisément de tester la
112 forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la
113 complexité de l'implémentation de l'opérateur.
115 **Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le
116 type de l'argument X peut être une liste, un vecteur ou une matrice Numpy.
117 L'utilisateur doit traiter ces cas dans sa fonction.
119 Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*"
120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
122 .. index:: single: ScriptWithFunctions
123 .. index:: single: DirectOperator
124 .. index:: single: TangentOperator
125 .. index:: single: AdjointOperator
127 **En général, il est recommandé d'utiliser la première forme fonctionnelle
128 plutôt que la seconde. Un petit accroissement de performances n'est pas une
129 bonne raison pour utiliser l'implémentation détaillée de cette seconde forme
132 La seconde consiste à fournir directement les trois opérateurs liés :math:`O`,
133 :math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le
134 mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans
135 l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions
136 dans un script, avec trois noms obligatoires "*DirectOperator*",
137 "*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre
138 le squelette suivant::
140 def DirectOperator( X ):
141 """ Opérateur direct de simulation non-linéaire """
145 return quelque chose comme Y
147 def TangentOperator( (X, dX) ):
148 """ Opérateur linéaire tangent, autour de X, appliqué à dX """
152 return quelque chose comme Y
154 def AdjointOperator( (X, Y) ):
155 """ Opérateur adjoint, autour de X, appliqué à Y """
159 return quelque chose comme X
161 Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tester
162 les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la
163 complexité de l'implémentation de l'opérateur.
165 Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse
166 renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque,
167 respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur
168 doit renvoyer la matrice associée.
170 **Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*"
171 et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``,
172 ``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy.
173 L'utilisateur doit traiter ces cas dans ses fonctions.
175 Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*"
176 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
178 .. index:: single: ScriptWithSwitch
179 .. index:: single: DirectOperator
180 .. index:: single: TangentOperator
181 .. index:: single: AdjointOperator
183 **Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans
184 une solide raison numérique ou physique. Un accroissement de performances n'est
185 pas une bonne raison pour utiliser la complexité de cette troisième forme
186 fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes
187 justifie l'usage de la troisième.**
189 La troisième forme donne de plus grandes possibilités de contrôle de l'exécution
190 des trois fonctions représentant l'opérateur, permettant un usage et un contrôle
191 avancés sur chaque exécution du code de simulation. C'est réalisable en
192 utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à
193 travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script
194 unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente
195 et adjointe du code de simulation. L'utilisateur peut alors, par exemple,
196 utiliser des approximations pour les codes tangent et adjoint, ou introduire une
197 plus grande complexité du traitement des arguments des fonctions. Mais cette
198 démarche sera plus difficile à implémenter et à déboguer.
200 Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se
201 baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier
202 script ou un code externe nommé ici "*Physical_simulation_functions.py*",
203 contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" et
204 "*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage::
206 import Physical_simulation_functions
207 import numpy, logging
210 for param in computation["specificParameters"]:
211 if param["name"] == "method":
212 method = param["value"]
213 if method not in ["Direct", "Tangent", "Adjoint"]:
214 raise ValueError("No valid computation method is given")
215 logging.info("Found method is \'%s\'"%method)
217 logging.info("Loading operator functions")
218 Function = Physical_simulation_functions.DirectOperator
219 Tangent = Physical_simulation_functions.TangentOperator
220 Adjoint = Physical_simulation_functions.AdjointOperator
222 logging.info("Executing the possible computations")
224 if method == "Direct":
225 logging.info("Direct computation")
226 Xcurrent = computation["inputValues"][0][0][0]
227 data = Function(numpy.matrix( Xcurrent ).T)
228 if method == "Tangent":
229 logging.info("Tangent computation")
230 Xcurrent = computation["inputValues"][0][0][0]
231 dXcurrent = computation["inputValues"][0][0][1]
232 data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
233 if method == "Adjoint":
234 logging.info("Adjoint computation")
235 Xcurrent = computation["inputValues"][0][0][0]
236 Ycurrent = computation["inputValues"][0][0][1]
237 data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
239 logging.info("Formatting the output")
240 it = numpy.ravel(data)
241 outputValues = [[[[]]]]
243 outputValues[0][0][0].append(val)
246 result["outputValues"] = outputValues
247 result["specificOutputInfos"] = []
248 result["returnCode"] = 0
249 result["errorMessage"] = ""
251 Toutes les modifications envisageables peuvent être faites à partir de cette
252 hypothèse de squelette.
254 Cas spécial d'un opérateur d'évolution avec contrôle
255 ++++++++++++++++++++++++++++++++++++++++++++++++++++
257 Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé
258 par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la
259 forme générique du modèle incrémental est légèrement modifié comme suit:
261 .. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
263 où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. Dans ce cas,
264 l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`.
265 Schématiquement, l'opérateur doit être constuit comme suit::
267 def DirectOperator( (X, U) ):
268 """ Opérateur direct de simulation non-linéaire """
272 return quelque chose comme X(n+1) (évolution) ou Y(n+1) (observation)
274 Les opérateurs tangent et adjoint ont la même signature que précédemment, en
275 notant que les dérivées doivent être faites seulement partiellement par rapport
276 à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième
277 forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme
278 fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées.
