3 ================================================================================
4 Examples on using the ADAO module
5 ================================================================================
7 This section presents some examples on using the ADAO module in SALOME.
9 Building a simple estimation case with explicit data definition
10 --------------------------------------------------------------------------------
12 This simple example is a demonstration one, and describes how to set a BLUE
13 estimation framework in order to get *weighted least square estimated state* of
14 a system from an observation of the state and from an *a priori* knowledge (or
15 background) of this state. In other words, we look for the weighted middle
16 between the observation and the background vectors. All the numerical values of
17 this example are arbitrary.
22 We choose to operate in a 3-dimensional space. 3D is chosen in order to restrict
23 the size of numerical object to explicitly enter by the user, but the problem is
24 not dependant of the dimension and can be set in dimension 1000... The observed
25 state is of value 1 in each direction, so:
29 The background state, wich represent some *a priori* knowledge or a
30 regularization, is of value of 0 in each direction, which is:
34 Data assimilation requires information on errors covariances for observation and
35 background variables. We choose here to have uncorrelated errors (that is,
36 diagonal matrices) and to have the same variance of 1 for all variables (that
37 is, identity matrices. We get:
39 ``B = R = [1 0 0 ; 0 1 0 ; 0 0 1]``
41 Last, we need an observation operator to convert the background value in the
42 space of observation value. Here, because the space dimensions are the same, we
43 can choose the identity as the observation operator:
45 ``H = [1 0 0 ; 0 1 0 ; 0 0 1]``
47 With such choices, the Best Linear Unbiased Estimator (BLUE) will be the
48 average vector between ``Yo`` and ``Xb``, named the *analysis* and denoted by
51 ``Xa = [0.5 0.5 0.5]``
53 As en extension of this example, one can change the variances for ``B`` or ``R``
54 independantly, and the analysis will move to ``Yo`` or ``Xb`` in inverse
55 proportion of the variances in ``B`` and ``R``. It is also equivalent to serach
56 for the analysis thought a BLUE algorithm or a 3DVAR one.
58 Using the GUI to build the ADAO case
59 ++++++++++++++++++++++++++++++++++++
61 First, you have to activate the ADAO module by choosing the appropriate module
62 button or menu of SALOME, and you will see:
65 .. image:: images/adao_activate.png
68 **Activating the module ADAO in SALOME**
70 .. |eficas_new| image:: images/eficas_new.png
73 Choose the "*New*" button in this window. You will directly get the EFICAS
74 interface for variables definition, along with the "*Object browser*". You can
75 then click on the "*New*" button |eficas_new| to create a new ADAO case, and you
79 .. image:: images/adao_viewer.png
83 **The EFICAS viewer for cases definition in module ADAO**
85 Then fill in the variables to build the ADAO case by using the experimental set
86 up described above. All the technical information given above will be directly
87 inserted in the ADAO case definition, by using the *String* type for all the
88 variables. When the case definition is ready, save it to a "*JDC (\*.comm)*"
89 native file somewhere in your path. Remember that other files will be also
90 created near this first one, so it is better to make a specific directory for
91 your case, and to save the file inside. The name of the file will appear in the
92 "*Object browser*" window, under the "*ADAO*" menu. The final case definition
95 .. _adao_jdcexample01:
96 .. image:: images/adao_jdcexample01.png
100 **Definition of the experimental set up chosen for the ADAO case**
102 To go further, we need now to generate the YACS scheme from the ADAO case
103 definition. In order to do that, right click on the name of the file case in the
104 "*Object browser*" window, and choose the "*Export to YACS*" submenu as below:
106 .. _adao_exporttoyacs:
107 .. image:: images/adao_exporttoyacs.png
111 **"*Export to YACS*" submenu to generate the YACS scheme from the ADAO case**
113 This command will generate the YACS scheme, activate YACS module in SALOME, and
114 open the new scheme in the YACS module GUI [#]. After reordering the nodes by
115 using the "*arrange local node*" submenu of the YACS graphical view of the
116 scheme, you get the following representation of the generated ADAO scheme:
118 .. _yacs_generatedscheme:
119 .. image:: images/yacs_generatedscheme.png
123 **YACS generated scheme from the ADAO case**
125 After that point, all the modifications, executions and post-processing of the
126 data assimilation scheme will be done in YACS. In order to check the result in a
127 simple way, we create here a new YACS node by using the "*inline script node*"
128 submenu of the YACS graphical view, and we name it "*PostProcessing*".
130 This script will retrieve the data assimilation analysis from the
131 "*algoResults*" output port of the computation bloc (which gives access to a
132 SALOME Python Object), and will print it on the standard output.
134 To obtain this, the inline script node need to have an input port of type
135 "*pyobj*" named "*results*", that have to be linked graphically to the
136 "*algoResults*" output port of the computation bloc. Then the code to fill in
139 Xa = results.ADD.get("Analysis").valueserie(-1)
142 print "Analysis =",Xa
145 The augmented YACS scheme can be saved (overwriting the generated scheme if the
146 simple "*Save*" command or button is used, or with a new name). Then,
147 classically in YACS, it have to be prepared for run, and then executed. After
148 completion, the printing on standard output is available in the "*YACS Container
149 Log*", obtained throught the right click menu of the "*proc*" window in the YACS
150 scheme as shown below:
152 .. _yacs_containerlog:
153 .. image:: images/yacs_containerlog.png
157 **YACS menu for Container Log, and dialog window showing the log**
159 We verify that the result is correct by checking that the log contains the
162 Analysis = [0.5, 0.5, 0.5]
164 as shown in the image above.
166 As a simple extension of this example, one can notice that the same problem
167 solved with a 3DVAR algorithm gives the same result. This algorithm can be
168 chosen at the ADAO case building step, before entering in YACS step. The
169 ADAO 3DVAR case will look completly similar to the BLUE algoritmic case, as
170 shown by the following figure:
172 .. _adao_jdcexample01:
173 .. image:: images/adao_jdcexample02.png
177 **Defining an ADAO 3DVAR case looks completly similar to a BLUE case**
179 There is only one keyword changing, with "*ThreeDVAR*" instead of "*Blue*".
181 Building a simple estimation case with external data definition by functions
182 --------------------------------------------------------------------------------
184 It is useful to get parts or all of the data from external definition, using
185 Python script files to provide access to the data. As an example, we build here
186 an ADAO case representing the same experimental set up as in the above example
187 `Building a simple estimation case with explicit data definition`_, but using
188 data form a single one external Python script file.
190 First, we write the following script file, using conventional names for the
191 desired variables. Here, all the input variables are defined in the script, but
192 the user can choose to split the file in several ones, or to mix explicit data
193 definition in the ADAO GUI and implicit data definition by external files. This
196 #-*-coding:iso-8859-1-*-
199 # Definition of the Background as a vector
200 # ----------------------------------------
201 Background = [0, 0, 0]
203 # Definition of the Observation as a vector
204 # -----------------------------------------
205 Observation = "1 1 1"
207 # Definition of the Background Error covariance as a matrix
208 # ---------------------------------------------------------
209 BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
211 # Definition of the Observation Error covariance as a matrix
212 # ----------------------------------------------------------
213 ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
215 # Definition of the Observation Operator as a matrix
216 # --------------------------------------------------
217 ObservationOperator = numpy.identity(3)
219 The names of the Python variables above are mandatory, in order to define the
220 right variables, but the Python script can be bigger and define classes,
221 functions, etc. with other names. It shows different ways to define arrays and
222 matrices, using list, string (as in Numpy or Octave), Numpy array type or Numpy
223 matrix type, and Numpy special functions. All of these syntaxes are valid.
225 After saving this script somewhere in your path (named here
226 "*test003_ADAO_example_scripts.py*" for the example), we use the GUI to build
227 the ADAO case. The procedure to fill in the case is similar except that, instead
228 of selecting the "*String*" option for the "*FROM*" keyword, we select the
229 "*Script*" one. This leads to a "*SCRIPT_DATA/SCRIPT_FILE*" entry in the tree,
230 allowing to choose a file as:
232 .. _adao_scriptentry01:
233 .. image:: images/adao_scriptentry01.png
237 **Defining an input value using an external script file**
239 Other steps and results are exactly the same as in the `Building a simple
240 estimation case with explicit data definition`_ previous example.
242 In fact, this script methodology allows to retrieve data from inline or previous
243 calculations, from static files, from database or from stream, all of them
244 outside of SALOME. It allows also to modify easily some input data, for example
245 debug purpose or for repetitive process. **But be careful, it is not a "safe"
246 process, in the sense that erroneous data, or errors in calculations, can be
247 directly injected into the YACS scheme execution.**
249 Adding parameters to control the data assimilation algorithm
250 --------------------------------------------------------------------------------
252 One can add some optional parameters to control the data assimilation algorithm
253 calculation. This is done by using the "*AlgorithmParameters*" keyword in the
254 definition of the ADAO case, which is an option of the algorithm. This keyword
255 requires a Python dictionary containing some key/value pairs.
257 For example, with a 3DVAR algorithm, the possible keys are "*Minimizer*",
258 "*MaximumNumberOfSteps*", "*Bounds*". Bounds can be given by a list of list of
259 pairs of lower/upper bounds for each variable, with possibly ``None`` every time
260 there is no bound. If no bounds at all are required on the control variables,
261 then one can choose the "BFGS" or "CG" minimisation algorithm for the 3DVAR
264 This dictionary has to be defined in an external Python script file, using the
265 mandatory variable name "*AlgorithmParameters*" for the dictionary. All the keys
266 inside the dictionary are optional, they all have default values, and can exist
267 without being used. For example::
269 #-*-coding:iso-8859-1-*-
271 AlgorithmParameters = {
272 "Minimizer" : "CG", # Possible choice : "LBFGSB", "TNC", "CG", "BFGS"
273 "MaximumNumberOfSteps" : 10,
276 Then the script can be added to the ADAO case, in a file entry describing the
277 "*AlgorithmParameters*" keyword, as follows:
279 .. _adao_scriptentry02:
280 .. image:: images/adao_scriptentry02.png
284 **Adding parameters to control the algorithm**
286 Other steps and results are exactly the same as in the `Building a simple
287 estimation case with explicit data definition`_ previous example.
289 .. [#] For more information on YACS, see the the *YACS User Guide* available in the main "*Help*" menu of SALOME GUI.
