3 ================================================================================
4 Examples on using the ADAO module
5 ================================================================================
7 .. |eficas_new| image:: images/eficas_new.png
9 .. |eficas_save| image:: images/eficas_save.png
11 .. |eficas_yacs| image:: images/eficas_yacs.png
14 This section presents some examples on using the ADAO module in SALOME. The
15 first one shows how to build a simple data assimilation case defining
16 explicitly all the required data through the GUI. The second one shows, on the
17 same case, how to define data using external sources through scripts.
19 Building a simple estimation case with explicit data definition
20 ---------------------------------------------------------------
22 This simple example is a demonstration one, and describes how to set a BLUE
23 estimation framework in order to get *weighted least square estimated state* of
24 a system from an observation of the state and from an *a priori* knowledge (or
25 background) of this state. In other words, we look for the weighted middle
26 between the observation and the background vectors. All the numerical values of
27 this example are arbitrary.
32 We choose to operate in a 3-dimensional space. 3D is chosen in order to restrict
33 the size of numerical object to explicitly enter by the user, but the problem is
34 not dependant of the dimension and can be set in dimension 1000... The observed
35 state is of value 1 in each direction, so:
39 The background state, which represent some *a priori* knowledge or a
40 regularization, is of value of 0 in each direction, which is:
44 Data assimilation requires information on errors covariances for observation and
45 background variables. We choose here to have uncorrelated errors (that is,
46 diagonal matrices) and to have the same variance of 1 for all variables (that
47 is, identity matrices. We get:
49 ``B = R = [1 0 0 ; 0 1 0 ; 0 0 1]``
51 Last, we need an observation operator to convert the background value in the
52 space of observation value. Here, because the space dimensions are the same, we
53 can choose the identity as the observation operator:
55 ``H = [1 0 0 ; 0 1 0 ; 0 0 1]``
57 With such choices, the Best Linear Unbiased Estimator (BLUE) will be the
58 average vector between ``Yo`` and ``Xb``, named the *analysis* and denoted by
61 ``Xa = [0.5 0.5 0.5]``
63 As en extension of this example, one can change the variances for ``B`` or ``R``
64 independently, and the analysis will move to ``Yo`` or ``Xb`` in inverse
65 proportion of the variances in ``B`` and ``R``. It is also equivalent to search
66 for the analysis thought a BLUE algorithm or a 3DVAR one.
68 Using the GUI to build the ADAO case
69 ++++++++++++++++++++++++++++++++++++
71 First, you have to activate the ADAO module by choosing the appropriate module
72 button or menu of SALOME, and you will see:
75 .. image:: images/adao_activate.png
79 **Activating the module ADAO in SALOME**
81 Choose the "*New*" button in this window. You will directly get the EFICAS
82 interface for variables definition, along with the "*Object browser*". You can
83 then click on the "*New*" button |eficas_new| to create a new ADAO case, and you
87 .. image:: images/adao_viewer.png
91 **The EFICAS viewer for cases definition in module ADAO**
93 Then fill in the variables to build the ADAO case by using the experimental set
94 up described above. All the technical information given above will be directly
95 inserted in the ADAO case definition, by using the *String* type for all the
96 variables. When the case definition is ready, save it to a "*JDC (\*.comm)*"
97 native file somewhere in your path. Remember that other files will be also
98 created near this first one, so it is better to make a specific directory for
99 your case, and to save the file inside. The name of the file will appear in the
100 "*Object browser*" window, under the "*ADAO*" menu. The final case definition
103 .. _adao_jdcexample01:
104 .. image:: images/adao_jdcexample01.png
108 **Definition of the experimental set up chosen for the ADAO case**
110 To go further, we need now to generate the YACS scheme from the ADAO case
111 definition. In order to do that, right click on the name of the file case in the
112 "*Object browser*" window, and choose the "*Export to YACS*" sub-menu (or the
113 "*Export to YACS*" button |eficas_yacs|) as below:
115 .. _adao_exporttoyacs:
116 .. image:: images/adao_exporttoyacs.png
120 **"Export to YACS" submenu to generate the YACS scheme from the ADAO case**
122 This command will generate the YACS scheme, activate YACS module in SALOME, and
123 open the new scheme in the GUI of the YACS module [#]. After reordering the
124 nodes by using the "*arrange local node*" sub-menu of the YACS graphical view of
125 the scheme, you get the following representation of the generated ADAO scheme:
127 .. _yacs_generatedscheme:
128 .. image:: images/yacs_generatedscheme.png
132 **YACS generated scheme from the ADAO case**
134 After that point, all the modifications, executions and post-processing of the
135 data assimilation scheme will be done in YACS. In order to check the result in a
136 simple way, we create here a new YACS node by using the "*in-line script node*"
137 sub-menu of the YACS graphical view, and we name it "*PostProcessing*".
139 This script will retrieve the data assimilation analysis from the
140 "*algoResults*" output port of the computation bloc (which gives access to a
141 SALOME Python Object), and will print it on the standard output.
143 To obtain this, the in-line script node need to have an input port of type
144 "*pyobj*" named "*results*" for example, that have to be linked graphically to
145 the "*algoResults*" output port of the computation bloc. Then the code to fill
146 in the script node is::
148 Xa = results.ADD.get("Analysis").valueserie(-1)
151 print "Analysis =",Xa
154 The augmented YACS scheme can be saved (overwriting the generated scheme if the
155 simple "*Save*" command or button are used, or with a new name). Then,
156 classically in YACS, it have to be prepared for run, and then executed. After
157 completion, the printing on standard output is available in the "*YACS Container
158 Log*", obtained through the right click menu of the "*proc*" window in the YACS
159 scheme as shown below:
161 .. _yacs_containerlog:
162 .. image:: images/yacs_containerlog.png
166 **YACS menu for Container Log, and dialog window showing the log**
168 We verify that the result is correct by checking that the log dialog window
169 contains the following line::
171 Analysis = [0.5, 0.5, 0.5]
173 as shown in the image above.
175 As a simple extension of this example, one can notice that the same problem
176 solved with a 3DVAR algorithm gives the same result. This algorithm can be
177 chosen at the ADAO case building step, before entering in YACS step. The
178 ADAO 3DVAR case will look completely similar to the BLUE algorithmic case, as
179 shown by the following figure:
181 .. _adao_jdcexample02:
182 .. image:: images/adao_jdcexample02.png
186 **Defining an ADAO 3DVAR case looks completely similar to a BLUE case**
188 There is only one command changing, with "*3DVAR*" value instead of "*Blue*".
190 Building a simple estimation case with external data definition by functions
191 ----------------------------------------------------------------------------
193 It is useful to get parts or all of the data from external definition, using
194 Python script files to provide access to the data. As an example, we build here
195 an ADAO case representing the same experimental set up as in the above example
196 `Building a simple estimation case with explicit data definition`_, but using
197 data form a single one external Python script file.
199 First, we write the following script file, using conventional names for the
200 desired variables. Here, all the input variables are defined in the script, but
201 the user can choose to split the file in several ones, or to mix explicit data
202 definition in the ADAO GUI and implicit data definition by external files. The
203 present script looks like::
205 #-*-coding:iso-8859-1-*-
208 # Definition of the Background as a vector
209 # ----------------------------------------
210 Background = [0, 0, 0]
212 # Definition of the Observation as a vector
213 # -----------------------------------------
214 Observation = "1 1 1"
216 # Definition of the Background Error covariance as a matrix
217 # ---------------------------------------------------------
218 BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
220 # Definition of the Observation Error covariance as a matrix
221 # ----------------------------------------------------------
222 ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
224 # Definition of the Observation Operator as a matrix
225 # --------------------------------------------------
226 ObservationOperator = numpy.identity(3)
228 The names of the Python variables above are mandatory, in order to define the
229 right variables, but the Python script can be bigger and define classes,
230 functions, etc. with other names. It shows different ways to define arrays and
231 matrices, using list, string (as in Numpy or Octave), Numpy array type or Numpy
232 matrix type, and Numpy special functions. All of these syntaxes are valid.
234 After saving this script somewhere in your path (named here "*script.py*" for
235 the example), we use the GUI to build the ADAO case. The procedure to fill in
236 the case is similar except that, instead of selecting the "*String*" option for
237 the "*FROM*" keyword, we select the "*Script*" one. This leads to a
238 "*SCRIPT_DATA/SCRIPT_FILE*" entry in the tree, allowing to choose a file as:
240 .. _adao_scriptentry01:
241 .. image:: images/adao_scriptentry01.png
245 **Defining an input value using an external script file**
247 Other steps and results are exactly the same as in the `Building a simple
248 estimation case with explicit data definition`_ previous example.
250 In fact, this script methodology allows to retrieve data from in-line or previous
251 calculations, from static files, from database or from stream, all of them
252 outside of SALOME. It allows also to modify easily some input data, for example
253 for debug purpose or for repetitive execution process, and it is the most
254 versatile method in order to parametrize the input data. **But be careful,
255 script methodology is not a "safe" procedure, in the sense that erroneous
256 data, or errors in calculations, can be directly injected into the YACS scheme
259 Adding parameters to control the data assimilation algorithm
260 ------------------------------------------------------------
262 One can add some optional parameters to control the data assimilation algorithm
263 calculation. This is done by using the "*AlgorithmParameters*" keyword in the
264 definition of the ADAO case, which is an keyword of the ASSIMILATION_STUDY. This
265 keyword requires a Python dictionary, containing some key/value pairs.
267 For example, with a 3DVAR algorithm, the possible keys are "*Minimizer*",
268 "*MaximumNumberOfSteps*", and "*Bounds*":
270 #. The "*Minimizer*" key allows to choose the optimisation minimizer, the
271 default choice being "LBFGSB", and the possible ones "LBFGSB" (nonlinear
272 constrained minimizer, see [Byrd95] and [Zhu97]), "TNC" (nonlinear
273 constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS"
274 (nonlinear unconstrained minimizer).
275 #. The "*MaximumNumberOfSteps*" key indicates the maximum number of iterations
276 allowed for iterative optimisation. The default is 15000, which very
277 similar of no limit on iterations. It is then recommended to adapt this
278 parameter to the needs on real problems.
279 #. The "*Bounds*" key allows to define upper and lower bounds for every
280 control variable being optimized. Bounds can be given by a list of list of
281 pairs of lower/upper bounds for each variable, with possibly ``None`` every
282 time there is no bound.
284 If no bounds at all are required on the control variables, then one can choose
285 the "BFGS" or "CG" minimisation algorithm for the 3DVAR algorithm.
287 This dictionary has to be defined, for example, in an external Python script
288 file, using the mandatory variable name "*AlgorithmParameters*" for the
289 dictionary. All the keys inside the dictionary are optional, they all have
290 default values, and can exist without being used. For example::
292 #-*-coding:iso-8859-1-*-
294 AlgorithmParameters = {
295 "Minimizer" : "CG", # Possible choice : "LBFGSB", "TNC", "CG", "BFGS"
296 "MaximumNumberOfSteps" : 10,
299 Then the script can be added to the ADAO case, in a file entry describing the
300 "*AlgorithmParameters*" keyword, as follows:
302 .. _adao_scriptentry02:
303 .. image:: images/adao_scriptentry02.png
307 **Adding parameters to control the algorithm**
309 Other steps and results are exactly the same as in the `Building a simple
310 estimation case with explicit data definition`_ previous example. The dictionary
311 can also be directly given in the input field associated with the keyword.
313 .. [#] For more information on YACS, see the the *YACS User Guide* available in the main "*Help*" menu of SALOME GUI.
