doc/using.rst

   1 .. _section_using:
   2
   3 ================================================================================
   4 Using the ADAO module
   5 ================================================================================
   6
   7 .. |eficas_new| image:: images/eficas_new.png
   8    :align: middle
   9 .. |eficas_save| image:: images/eficas_save.png
  10    :align: middle
  11 .. |eficas_yacs| image:: images/eficas_yacs.png
  12    :align: middle
  13
  14 This section presents the usage of the ADAO module in SALOME. It is complemented
  15 by advanced usage procedures the section :ref:`section_advanced`, and by
  16 examples in the section :ref:`section_examples`.
  17
  18 Logical procedure to build an ADAO test case
  19 --------------------------------------------
  20
  21 The construction of an ADAO case follows a simple approach to define the set of
  22 input data, either static or dynamic data, and then generates a complete block
  23 diagram used in YACS. Many variations exist for the definition of input data,
  24 but the logical sequence remains unchanged.
  25
  26 First of all, the user is considered to know the input data needed to set up the
  27 data assimilation study. These data can be in SALOME or not.
  28
  29 **Basically, the procedure of using ADAO involves the following steps:**
  30
  31 #.  **Activate the ADAO module and use the editor GUI,**
  32 #.  **Build and modify the ADAO case and save it,**
  33 #.  **Export the ADAO case as a YACS scheme,**
  34 #.  **Modify and supplement the YACS scheme and save it,**
  35 #.  **Execute the YACS case and obtain the results.**
  36
  37 Each step will be detailed in the next section.
  38
  39 Detailed procedure to build an ADAO test case
  40 ---------------------------------------------
  41
  42 Activate the ADAO module and use the editor GUI
  43 +++++++++++++++++++++++++++++++++++++++++++++++
  44
  45 As always for a module, it has to be activated by choosing the appropriate
  46 module button (or menu) in the toolbar of SALOME. A popup appears, allowing to
  47 choose between creating a new study, or opening an already existing one:
  48
  49   .. _adao_activate1:
  50   .. image:: images/adao_activate.png
  51     :align: center
  52     :width: 100%
  53   .. centered::
  54     **Activating the module ADAO in SALOME**
  55
  56 Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened,
  57 along with the standard "*Object browser*". You can then click on the "*New*"
  58 button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to
  59 create a new ADAO case, and you will see:
  60
  61   .. _adao_viewer:
  62   .. image:: images/adao_viewer.png
  63     :align: center
  64     :width: 100%
  65   .. centered::
  66     **The EFICAS editor for cases definition in module ADAO**
  67
  68 It is a good habit to save the ADAO case now, by pushing the "*Save*" button
  69 |eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
  70 You will be prompted for a location in your file tree and a name, that will be
  71 completed by a "*.comm*" extension used for JDC EFICAS files.
  72
  73 Build and modify the ADAO case and save it
  74 ++++++++++++++++++++++++++++++++++++++++++
  75
  76 To build a case using EFICAS, you have to go through a series of steps, by
  77 selecting a keyword and then filling in its value.
  78
  79 The structured editor indicates hierarchical types, values or keywords allowed.
  80 Incomplete or incorrect keywords are identified by a visual error red flag.
  81 Possible values are indicated for keywords defined with a limited list of
  82 values, and adapted entries are given for the other keywords. All the mandatory
  83 command or keyword are already present, and optionnal commands can be added.
  84
  85 A new case is set up with the minimal list of commands. No mandatory command can
  86 be suppressed, but others can be added as allowed keywords for an
  87 "*ASSIMILATION_STUDY*" command. As an example, one can add an
  88 "*AlgorithmParameters*" keyword, as described in the last part of the section
  89 :ref:`section_examples`.
  90
  91 At the end, when all fields or keywords have been correctly defined, each line
  92 of the commands tree must have a green flag. This indicates that the whole case
  93 is valid and completed.
  94
  95   .. _adao_jdcexample00:
  96   .. image:: images/adao_jdcexample01.png
  97     :align: center
  98     :width: 50%
  99   .. centered::
 100     **Example of a valid ADAO case**
 101
 102 Finally, you have to save your ADAO case by pushing the "*Save*" button
 103 |eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
 104
 105 Export the ADAO case as a YACS scheme
 106 +++++++++++++++++++++++++++++++++++++
 107
 108 When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
 109 order to execute the data assimilation calculation. This can be easily done by
 110 using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
 111 "*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
 112 menu in the object browser.
 113
 114   .. _adao_exporttoyacs:
 115   .. image:: images/adao_exporttoyacs.png
 116     :align: center
 117     :scale: 75%
 118   .. centered::
 119     **"Export to YACS" submenu to generate the YACS scheme from the ADAO case**
 120
 121 This will lead to automatically generate an XML file for the YACS scheme, and
 122 open YACS module on this file. The YACS file will be stored in the same
 123 directory and with the same name as the ADAO saved case, only changing its
 124 extension from "*.comm*" to "*.xml*". *Be careful, if the name already exist, it
 125 will overwrite it without prompting for replacing the file*. In the same time,
 126 an intermediary python file is also stored in the same place, with a "*.py*"
 127 extension replacing the "*.comm*" one [#]_.
 128
 129 Modify and supplement the YACS scheme and save it
 130 +++++++++++++++++++++++++++++++++++++++++++++++++
 131
 132 When the YACS scheme is generated and opened in SALOME through the YACS module
 133 GUI, you can modify or supplement the scheme like any YACS scheme. It is
 134 recommended to save the modified scheme with a new name, in order to preserve in
 135 the case you re-export to YACS the ADAO case.
 136
 137 The main supplement needed in the YACS scheme is a postprocessing step. The
 138 evaluation of the results has to be done in the physical context of the
 139 simulation used by the data assimilation procedure.
 140
 141 The YACS scheme has an "*algoResults*" output port of the computation bloc,
 142 which gives access to a "*pyobj*" containing all the results. These results can
 143 be obtained by retrieving the named variables stored along the calculation. The
 144 main is the "*Analysis*" one, that can be obtained by the python command (for
 145 example in an in-line script node)::
 146
 147     Analysis = results.ADD.get("Analysis").valueserie(-1)
 148
 149 This is a complex object, similar to a list of values calculated at each step of
 150 data assimilation calculation. In order to get the last data assimilation
 151 analysis, one can use::
 152
 153     Xa = results.ADD.get("Analysis").valueserie(-1)
 154
 155 This ``Xa`` is a vector of values, that represents the solution of the data
 156 assimilation evaluation problem, noted as :math:`\mathbf{x}^a` in the section
 157 :ref:`section_theory`.
 158
 159 Such command can be used to print results, or to convert these ones to
 160 structures that can be used in the native or external SALOME postprocessing. A
 161 simple example is given in the section :ref:`section_examples`.
 162
 163 Execute the YACS case and obtain the results
 164 ++++++++++++++++++++++++++++++++++++++++++++
 165
 166 The YACS scheme is now complete and can be executed. Parametrisation and
 167 execution of a YACS case is fully compliant with the standard way to deal with a
 168 YACS scheme, and is described in the *YACS module User's Guide*.
 169
 170 Results can be obtained, through the "*algoResults*" output port, using YACS
 171 nodes to retrieve all the informations in the "*pyobj*" object, to transform
 172 them, to convert them, to save part of them, etc.
 173
 174 The data assimilation results and complementary calculations can be retrieved
 175 using the "*get*" method af the "*algoResults.ADD*" object. This method pick the
 176 different output variables identified by their name. Indicating in parenthesis
 177 their availability as automatic (for every algorithm) or optional (depending on
 178 the algorithm), and their notation coming from section :ref:`section_theory`,
 179 the main available output variables are the following:
 180
 181 #.  "Analysis" (automatic): the control state evaluated by the data assimilation
 182     procedure, noted as :math:`\mathbf{x}^a`.
 183 #.  "Innovation" (automatic): the difference between the observations and the
 184     control state transformed by the observation operator, noted as
 185     :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^b`.
 186 #.  "OMB" (optional): the difference between the observations and the
 187     background, similar to the innovation.
 188 #.  "BMA" (optional): the difference between the background and the analysis,
 189     noted as :math:`\mathbf{x}^b - \mathbf{x}^a`.
 190 #.  "OMA" (optional): the difference between the observations and the analysis,
 191     noted as :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^a`.
 192
 193 Input variables are also available as output in order to gather all the
 194 information at the end of the procedure.
 195
 196 All the variables are list of typed values, each item of the list
 197 corresponding to the value of the variable at a time step or an iteration step
 198 in the data assimilation optimization procedure. The variable value at a given
 199 "*i*" step can be obtained by the method "*valueserie(i)*". The last one
 200 (consisting in the solution of the evaluation problem) can be obtained using the
 201 step "*-1*" as in a standard list.
 202
 203 Reference description of the commands and keywords available through the GUI
 204 -----------------------------------------------------------------------------
 205
 206 Each command or keyword to be defined through the ADAO GUI has some properties.
 207 The first property is to be a required command, an optional command or a keyword
 208 describing a type of input. The second property is to be an "open" variable with
 209 a fixed type but with any value allowed by the type, or a "restricted" variable,
 210 limited to some specified values. The mathematical notations used afterwards are
 211 explained in the section :ref:`section_theory`.
 212
 213 List of possible input types
 214 ++++++++++++++++++++++++++++
 215
 216 The different type-style commands are:
 217
 218 :Dict:
 219     *Type of an input*. This indicates a variable that has to be filled by a
 220     dictionary, usually given as a script.
 221
 222 :Function:
 223     *Type of an input*. This indicates a variable that has to be filled by a
 224     function, usually given as a script.
 225
 226 :Matrix:
 227     *Type of an input*. This indicates a variable that has to be filled by a
 228     matrix, usually given either as a string or as a script.
 229
 230 :String:
 231     *Type of an input*. This indicates a string, such as a name or a literal
 232     representation of a matrix or vector, such as "1 2 ; 3 4".
 233
 234 :Script:
 235     *Type of an input*. This indicates a script given as an external file.
 236
 237 :Vector:
 238     *Type of an input*. This indicates a variable that has to be filled by a
 239     vector, usually given either as a string or as a script.
 240
 241 List of commands
 242 ++++++++++++++++
 243
 244 The different commands are the following:
 245
 246 :ASSIM_STUDY:
 247     *Required command*. This is the general command describing an ADAO case. It
 248     hierarchicaly contains all the other commands.
 249
 250 :Algorithm:
 251     *Required command*. This is a string to indicates the data assimilation
 252     algorithm chosen. The choices are limited and available through the GUI.
 253     There exists for example: "3DVAR", "Blue"... See below the list of
 254     algorithms and associated parameters.
 255
 256 :AlgorithmParameters:
 257     *Optional command*. This command allows to add some optional parameters to
 258     control the data assimilation algorithm calculation. It is defined as a
 259     "*Dict*" type object.  See below the list of algorithms and associated
 260     parameters.
 261
 262 :Background:
 263     *Required command*. This indicates the backgroud vector used for data
 264     assimilation, previously noted as :math:`\mathbf{x}^b`. It is defined as a
 265     "*Vector*" type object, that is, given either as a string or as a script.
 266
 267 :BackgroundError:
 268     *Required command*. This indicates the backgroud error covariance matrix,
 269     previously noted as :math:`\mathbf{B}`.It is defined as a "*Matrix*" type
 270     object, that is, given either as a string or as a script.
 271
 272 :Debug:
 273     *Required command*. This let choose the level of trace and intermediary
 274     debug informations.The choices are limited between 0 (for False) and 1 (for
 275     True) and available through the GUI.
 276
 277 :InputVariables:
 278     *Optional command*. This command allows to indicates the name and size of
 279     physical variables that are bundled together in the control vector. This
 280     information is dedicated to data processed inside of data assimilation
 281     algorithm.
 282
 283 :Observation:
 284     *Required command*. This indicates the observation vector used for data
 285     assimilation, previously noted as :math:`\mathbf{y}^o`. It is defined as a
 286     "*Vector*" type object, that is, given either as a string or as a script.
 287
 288 :ObservationError:
 289     *Required command*. This indicates the observation error covariance matrix,
 290     previously noted as :math:`\mathbf{R}`.It is defined as a "*Matrix*" type
 291     object, that is, given either as a string or as a script.
 292
 293 :ObservationOperator:
 294     *Required command*. This indicates the observation operator, previously
 295     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}`
 296     to results :math:`\mathbf{y}` to be compared to observations
 297     :math:`\mathbf{y}^o`.
 298
 299 :OutputVariables:
 300     *Optional command*. This command allows to indicates the name and size of
 301     physical variables that are bundled together in the output observation
 302     vector. This information is dedicated to data processed inside of data
 303     assimilation algorithm.
 304
 305 :Study_name:
 306     *Required command*. This is an open string to describe the study by a name
 307     or a sentence.
 308
 309 :Study_repertory:
 310     *Optional command*. If available, this repertory is used to find all the
 311     script files that can be used to define some other commands by scripts.
 312
 313 :UserDataInit:
 314     *Optional command*. This commands allows to initialise some parameters or
 315     data automatically before data assimilation algorithm processing.
 316
 317 :UserPostAnalysis:
 318     *Optional command*. This commands allows to process some parameters or data
 319     automatically after data assimilation algorithm processing. It is defined as
 320     a script or a string, allowing to put simple code directly inside the ADAO
 321     case.
 322
 323 .. _subsection_algo_options:
 324
 325 List of possible options for the algorithms
 326 +++++++++++++++++++++++++++++++++++++++++++
 327
 328 Each algorithm can be controled using some generic or specific options given
 329 throught the "*AlgorithmParameters*" optional command, as follows::
 330
 331     AlgorithmParameters = {
 332         "Minimizer" : "CG",
 333         "MaximumNumberOfSteps" : 10,
 334         }
 335
 336 This section describes the available options by algorithm. If an option is
 337 specified for an algorithm that doesn't support it, the option is simply left
 338 unused.
 339
 340 :"Blue":
 341     no option
 342
 343 :"LinearLeastSquares":
 344     no option
 345
 346 :"3DVAR":
 347
 348     :Minimizer:
 349       This key allows to choose the optimization minimizer. The default choice
 350       is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
 351       minimizer, see [Byrd95] and [Zhu97]), "TNC" (nonlinear constrained
 352       minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
 353       unconstrained minimizer), "NCG" (Newton CG minimizer).
 354
 355     :Bounds:
 356       This key allows to define upper and lower bounds for every control
 357       variable being optimized. Bounds can be given by a list of list of pairs
 358       of lower/upper bounds for each variable, with possibly ``None`` every time
 359       there is no bound. The bounds can always be specified, but they are taken
 360       into account only by the constrained minimizers.
 361
 362     :MaximumNumberOfSteps:
 363       This key indicates the maximum number of iterations allowed for iterative
 364       optimization. The default is 15000, which very similar to no limit on
 365       iterations. It is then recommended to adapt this parameter to the needs on
 366       real problems. For some algorithms, the effective stopping step can be
 367       slightly different due to algorihtm internal control requirements.
 368
 369     :ProjectedGradientTolerance:
 370       This key indicates a limit value, leading to stop successfully the
 371       iterative optimization process when all the components of the projected
 372       gradient are under this limit. It is only used for constrained algorithms.
 373
 374     :GradientNormTolerance:
 375       This key indicates a limit value, leading to stop successfully the
 376       iterative optimization process when the norm of the gradient is under this
 377       limit. It is only used for non-constrained algorithms.
 378
 379 :"NonLinearLeastSquares":
 380
 381     :Minimizer:
 382       This key allows to choose the optimization minimizer. The default choice
 383       is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
 384       minimizer, see [Byrd95] and [Zhu97]), "TNC" (nonlinear constrained
 385       minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
 386       unconstrained minimizer), "NCG" (Newton CG minimizer).
 387
 388     :Bounds:
 389       This key allows to define upper and lower bounds for every control
 390       variable being optimized. Bounds can be given by a list of list of pairs
 391       of lower/upper bounds for each variable, with possibly ``None`` every time
 392       there is no bound. The bounds can always be specified, but they are taken
 393       into account only by the constrained minimizers.
 394
 395     :MaximumNumberOfSteps:
 396       This key indicates the maximum number of iterations allowed for iterative
 397       optimization. The default is 15000, which very similar to no limit on
 398       iterations. It is then recommended to adapt this parameter to the needs on
 399       real problems. For some algorithms, the effective stopping step can be
 400       slightly different due to algorihtm internal control requirements.
 401
 402     :ProjectedGradientTolerance:
 403       This key indicates a limit value, leading to stop successfully the
 404       iterative optimization process when all the components of the projected
 405       gradient are under this limit. It is only used for constrained algorithms.
 406
 407     :GradientNormTolerance:
 408       This key indicates a limit value, leading to stop successfully the
 409       iterative optimization process when the norm of the gradient is under this
 410       limit. It is only used for non-constrained algorithms.
 411
 412 :"EnsembleBlue":
 413     no option
 414
 415 :"KalmanFilter":
 416     no option
 417
 418 Examples of using these commands are available in the section
 419 :ref:`section_examples` and in example files installed with ADAO module.
 420
 421 .. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME GUI.
 422
 423 .. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME GUI.
 424
 425 .. [#] This intermediary python file can be safely removed after YACS export, but can also be used as described in the section :ref:`section_advanced`.