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 in 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, and then generates a complete executable block diagram used in YACS.
  23 Many variations exist for the definition of input data, but the logical sequence
  24 remains unchanged.
  25
  26 First of all, the user is considered to know its personnal input data needed to
  27 set up the data assimilation study. These data can already be available in
  28 SALOME or not.
  29
  30 **Basically, the procedure of using ADAO involves the following steps:**
  31
  32 #.  **Activate the ADAO module and use the editor GUI,**
  33 #.  **Build and/or modify the ADAO case and save it,**
  34 #.  **Export the ADAO case as a YACS scheme,**
  35 #.  **Modify and supplement the YACS scheme and save it,**
  36 #.  **Execute the YACS case and obtain the results.**
  37
  38 Each step will be detailed in the next section.
  39
  40 Detailed procedure to build an ADAO test case
  41 ---------------------------------------------
  42
  43 Activate the ADAO module and use the editor GUI
  44 +++++++++++++++++++++++++++++++++++++++++++++++
  45
  46 As always for a module, it has to be activated by choosing the appropriate
  47 module button (or menu) in the toolbar of SALOME. If there is no SALOME study
  48 loaded, a popup appears, allowing to choose between creating a new study, or
  49 opening an already existing one:
  50
  51   .. _adao_activate1:
  52   .. image:: images/adao_activate.png
  53     :align: center
  54   .. centered::
  55     **Activating the module ADAO in SALOME**
  56
  57 Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened,
  58 along with the standard "*Object browser*". You can then click on the "*New*"
  59 button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to
  60 create a new ADAO case, and you will see:
  61
  62   .. _adao_viewer:
  63   .. image:: images/adao_viewer.png
  64     :align: center
  65     :width: 100%
  66   .. centered::
  67     **The EFICAS editor for cases definition in module ADAO**
  68
  69 It is a good habit to save the ADAO case now, by pushing the "*Save*" button
  70 |eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
  71 You will be prompted for a location in your file tree and a name, that will be
  72 completed by a "*.comm*" extension used for JDC EFICAS files.
  73
  74 Build and modify the ADAO case and save it
  75 ++++++++++++++++++++++++++++++++++++++++++
  76
  77 To build a case using EFICAS, you have to go through a series of steps, by
  78 selecting a keyword and then filling in its value.
  79
  80 The structured editor indicates hierarchical types, values or keywords allowed.
  81 Incomplete or incorrect keywords are identified by a visual error red flag.
  82 Possible values are indicated for keywords defined with a limited list of
  83 values, and adapted entries are given for the other keywords. All the mandatory
  84 command or keyword are already present, and optionnal commands can be added.
  85
  86 A new case is set up with the minimal list of commands. No mandatory command can
  87 be suppressed, but others can be added as allowed keywords for an
  88 "*ASSIMILATION_STUDY*" command. As an example, one can add an
  89 "*AlgorithmParameters*" keyword, as described in the last part of the section
  90 :ref:`section_examples`.
  91
  92 At the end, when all fields or keywords have been correctly defined, each line
  93 of the commands tree must have a green flag. This indicates that the whole case
  94 is valid and completed.
  95
  96   .. _adao_jdcexample00:
  97   .. image:: images/adao_jdcexample01.png
  98     :align: center
  99     :width: 50%
 100   .. centered::
 101     **Example of a valid ADAO case**
 102
 103 Finally, you have to save your ADAO case by pushing the "*Save*" button
 104 |eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
 105
 106 Export the ADAO case as a YACS scheme
 107 +++++++++++++++++++++++++++++++++++++
 108
 109 When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
 110 order to execute the data assimilation calculation. This can be easily done by
 111 using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
 112 "*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
 113 menu in the object browser.
 114
 115   .. _adao_exporttoyacs01:
 116   .. image:: images/adao_exporttoyacs.png
 117     :align: center
 118     :scale: 75%
 119   .. centered::
 120     **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
 121
 122 This will lead to automatically generate an XML file for the YACS scheme, and
 123 open YACS module on this file. The YACS file will be stored in the same
 124 directory and with the same name as the ADAO saved case, only changing its
 125 extension from "*.comm*" to "*.xml*". *Be careful, if the name already exist, it
 126 will overwrite it without prompting for replacing the file*. In the same time,
 127 an intermediary python file is also stored in the same place, with a "*.py*"
 128 extension replacing the "*.comm*" one [#]_.
 129
 130 Modify and supplement the YACS scheme and save it
 131 +++++++++++++++++++++++++++++++++++++++++++++++++
 132
 133 .. index:: single: Analysis
 134
 135 When the YACS scheme is generated and opened in SALOME through the YACS module
 136 GUI, you can modify or supplement the scheme like any YACS scheme. It is
 137 recommended to save the modified scheme with a new name, in order to preserve in
 138 the case you re-export to YACS the ADAO case.
 139
 140 The main supplement needed in the YACS scheme is a postprocessing step. The
 141 evaluation of the results has to be done in the physical context of the
 142 simulation used by the data assimilation procedure.
 143
 144 The YACS scheme has an "*algoResults*" output port of the computation bloc,
 145 which gives access to a "*pyobj*" containing all the results. These results can
 146 be obtained by retrieving the named variables stored along the calculation. The
 147 main is the "*Analysis*" one, that can be obtained by the python command (for
 148 example in an in-line script node)::
 149
 150     Analysis = results.ADD.get("Analysis").valueserie(-1)
 151
 152 This is a complex object, similar to a list of values calculated at each step of
 153 data assimilation calculation. In order to get the last data assimilation
 154 analysis, one can use::
 155
 156     Xa = results.ADD.get("Analysis").valueserie(-1)
 157
 158 This ``Xa`` is a vector of values, that represents the solution of the data
 159 assimilation evaluation problem, noted as :math:`\mathbf{x}^a` in the section
 160 :ref:`section_theory`.
 161
 162 Such command can be used to print results, or to convert these ones to
 163 structures that can be used in the native or external SALOME postprocessing. A
 164 simple example is given in the section :ref:`section_examples`.
 165
 166 Execute the YACS case and obtain the results
 167 ++++++++++++++++++++++++++++++++++++++++++++
 168
 169 .. index:: single: Analysis
 170 .. index:: single: Innovation
 171 .. index:: single: APosterioriCovariance
 172 .. index:: single: OMB (Observation minus Background)
 173 .. index:: single: BMA (Background minus Analysis)
 174 .. index:: single: OMA (Observation minus Analysis)
 175 .. index:: single: CostFunctionJ
 176 .. index:: single: CostFunctionJo
 177 .. index:: single: CostFunctionJb
 178
 179 The YACS scheme is now complete and can be executed. Parametrisation and
 180 execution of a YACS case is fully compliant with the standard way to deal with a
 181 YACS scheme, and is described in the *YACS module User's Guide*.
 182
 183 Results can be obtained, through the "*algoResults*" output port, using YACS
 184 nodes to retrieve all the informations in the "*pyobj*" object, to transform
 185 them, to convert them, to save part of them, etc.
 186
 187 The data assimilation results and complementary calculations can be retrieved
 188 using the "*get*" method af the "*algoResults.ADD*" object. This method pick the
 189 different output variables identified by their name. Indicating in parenthesis
 190 their availability as automatic (for every algorithm) or optional (depending on
 191 the algorithm), and their notation coming from section :ref:`section_theory`,
 192 the main available output variables are the following:
 193
 194 #.  "Analysis" (automatic): the control state evaluated by the data assimilation
 195     procedure, noted as :math:`\mathbf{x}^a`.
 196 #.  "Innovation" (automatic): the difference between the observations and the
 197     control state transformed by the observation operator, noted as
 198     :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^b`.
 199 #.  "APosterioriCovariance" (optional): the covariance matrix of the *a
 200     posteriori* analysis errors, noted as :math:`\mathbf{A}`.
 201 #.  "OMB" (optional): the difference between the observations and the
 202     background, similar to the innovation.
 203 #.  "BMA" (optional): the difference between the background and the analysis,
 204     noted as :math:`\mathbf{x}^b - \mathbf{x}^a`.
 205 #.  "OMA" (optional): the difference between the observations and the analysis,
 206     noted as :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^a`.
 207 #.  "CostFunctionJ" (optional): the minimisation function, noted as :math:`J`.
 208 #.  "CostFunctionJo" (optional): the observation part of the minimisation
 209     function, noted as :math:`J^o`.
 210 #.  "CostFunctionJb" (optional): the background part of the minimisation
 211     function, noted as :math:`J^b`.
 212
 213 Input variables are also available as output in order to gather all the
 214 information at the end of the procedure.
 215
 216 All the variables are list of typed values, each item of the list
 217 corresponding to the value of the variable at a time step or an iteration step
 218 in the data assimilation optimization procedure. The variable value at a given
 219 "*i*" step can be obtained by the method "*valueserie(i)*". The last one
 220 (consisting in the solution of the evaluation problem) can be obtained using the
 221 step "*-1*" as in a standard list.
 222
 223 .. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME GUI.
 224
 225 .. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME GUI.
 226
 227 .. [#] This intermediary python file can be safely removed after YACS export, but can also be used as described in the section :ref:`section_advanced`.