doc/en/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    :scale: 50%
  10 .. |eficas_save| image:: images/eficas_save.png
  11    :align: middle
  12    :scale: 50%
  13 .. |eficas_saveas| image:: images/eficas_saveas.png
  14    :align: middle
  15    :scale: 50%
  16 .. |eficas_yacs| image:: images/eficas_yacs.png
  17    :align: middle
  18    :scale: 50%
  19 .. |yacs_compile| image:: images/yacs_compile.png
  20    :align: middle
  21    :scale: 50%
  22
  23 This section presents the usage of the ADAO module in SALOME platform. It is
  24 complemented by the detailed description of all the commands and keywords in the
  25 section :ref:`section_reference`, by advanced usage procedures in the section
  26 :ref:`section_advanced`, and by examples in the section :ref:`section_examples`.
  27
  28 Logical procedure to build an ADAO case
  29 ---------------------------------------
  30
  31 The construction of an ADAO case follows a simple approach to define the set of
  32 input data, and then generates a complete executable block diagram used in YACS.
  33 Many variations exist for the definition of input data, but the logical sequence
  34 remains unchanged.
  35
  36 First of all, the user is considered to know its personal input data needed to
  37 set up the data assimilation study. These data can already be available in
  38 SALOME or not.
  39
  40 **Basically, the procedure of using ADAO involves the following steps:**
  41
  42 #.  **Activate the ADAO module and use the editor GUI,**
  43 #.  **Build and/or modify the ADAO case, and save it,**
  44 #.  **Export the ADAO case as a YACS scheme,**
  45 #.  **Supplement and modify the YACS scheme, and save it,**
  46 #.  **Execute the YACS case and obtain the results.**
  47
  48 Each step will be detailed in the next section.
  49
  50 STEP 1: Activate the ADAO module and use the editor GUI
  51 -------------------------------------------------------
  52
  53 As always for a module, it has to be activated by choosing the appropriate
  54 module button (or the menu) in the toolbar of SALOME. If there is no SALOME
  55 study loaded, a popup appears, allowing to choose between creating a new study,
  56 or opening an already existing one:
  57
  58   .. _adao_activate1:
  59   .. image:: images/adao_activate.png
  60     :align: center
  61   .. centered::
  62     **Activating the module ADAO in SALOME**
  63
  64 Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened,
  65 along with the standard "*Object browser*". You can then click on the "*New*"
  66 button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to
  67 create a new ADAO case, and you will see:
  68
  69   .. _adao_viewer:
  70   .. image:: images/adao_viewer.png
  71     :align: center
  72     :width: 100%
  73   .. centered::
  74     **The EFICAS editor for cases definition in module ADAO**
  75
  76 STEP 2: Build and modify the ADAO case, and save it
  77 ---------------------------------------------------
  78
  79 To build a case using EFICAS, you have to go through a series of sub-steps, by
  80 selecting, at each sub-step, a keyword and then filling in its value. It is
  81 noted that it is in this step that is needed, among other things, to define the
  82 call to the simulation code used in observation or evolution operators
  83 describing the problem [#]_.
  84
  85 The structured editor indicates hierarchical types, values or keywords allowed.
  86 Incomplete or incorrect keywords are identified by a visual error red flag.
  87 Possible values are indicated for keywords defined with a limited list of
  88 values, and adapted entries are given for the other keywords. Some help messages
  89 are contextually provided in the editor reserved places.
  90
  91 A new case is set up with the minimal list of commands. All the mandatory
  92 commands or keywords are already present, none of them can be suppressed.
  93 Optional keywords can be added by choosing them in a list of suggestions of
  94 allowed ones for the main command, for example the "*ASSIMILATION_STUDY*"
  95 command. As an example, one can add an "*AlgorithmParameters*" keyword, as
  96 described in the last part of the section :ref:`section_examples`.
  97
  98 At the end, when all fields or keywords have been correctly defined, each line
  99 of the commands tree must have a green flag. This indicates that the whole case
 100 is valid and completed (and can be saved).
 101
 102   .. _adao_jdcexample00:
 103   .. image:: images/adao_jdcexample01.png
 104     :align: center
 105     :scale: 75%
 106   .. centered::
 107     **Example of a valid ADAO case**
 108
 109 Finally, you have to save your ADAO case by pushing the "*Save*" button
 110 |eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the
 111 "*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location
 112 in your file tree and a name, that will be completed by a "*.comm*" extension
 113 used for JDC EFICAS files. This will generate a pair of files describing the
 114 ADAO case, with the same base name, the first one being completed by a "*.comm*"
 115 extension and the second one by a "*.py*" extension [#]_.
 116
 117 STEP 3: Export the ADAO case as a YACS scheme
 118 ---------------------------------------------
 119
 120 When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
 121 order to execute the data assimilation calculation. This can be easily done by
 122 using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
 123 "*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
 124 menu in the SALOME object browser.
 125
 126   .. _adao_exporttoyacs01:
 127   .. image:: images/adao_exporttoyacs.png
 128     :align: center
 129     :scale: 75%
 130   .. centered::
 131     **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
 132
 133 This will lead to automatically generate a YACS scheme, and open the YACS module
 134 on this scheme. The YACS file, associated with the scheme, will be stored in the
 135 same directory and with the same base name as the ADAO saved case, only changing
 136 its extension to "*.xml*". Be careful, *if the XML file name already exist, the
 137 file will be overwritten without prompting for replacing the XML file*.
 138
 139 STEP 4: Supplement and modify the YACS scheme, and save it
 140 ----------------------------------------------------------
 141
 142 .. index:: single: Analysis
 143
 144 When the YACS scheme is generated and opened in SALOME through the YACS module
 145 GUI, you can modify or supplement the scheme like any standard YACS scheme.
 146 Nodes or blocs can be added, copied or modified to elaborate complex analysis,
 147 or to insert data assimilation or optimization capabilities into more complex
 148 YACS calculation schemes. It is recommended to save the modified scheme with a
 149 new name, in order to preserve the XML file in the case you re-export the ADAO
 150 case to YACS.
 151
 152 The main supplement needed in the YACS scheme is a post-processing step. The
 153 evaluation of the results has to be done in the physical context of the
 154 simulation used by the data assimilation procedure. The post-processing can be
 155 provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string,
 156 by templates, or can be build as YACS nodes. These two ways of building the
 157 post-processing can use all the SALOME possibilities.
 158
 159 In details, the YACS scheme has an "*algoResults*" output port of the
 160 computation bloc, which gives access to an object of type "*pyobj*" named
 161 hereafter "*ADD*", containing all the calculation results. These results can be
 162 obtained by retrieving the named variables stored along the calculation. The
 163 main information is the "*Analysis*" one, that can be obtained by the python
 164 command (for example in an in-line script node or a script provided through the
 165 "*UserPostAnalysis*" keyword)::
 166
 167     Analysis = ADD.get("Analysis")[:]
 168
 169 "*Analysis*" is a complex object, similar to a list of values calculated at each
 170 step of data assimilation calculation. In order to get and print the optimal
 171 data assimilation state evaluation, in a script provided through the
 172 "*UserPostAnalysis*" keyword, one can use::
 173
 174     Xa = ADD.get("Analysis")[-1]
 175     print "Optimal state:", Xa
 176     print
 177
 178 This ``Xa`` variable is a vector of values, that represents the solution of the
 179 data assimilation or optimization evaluation problem, noted as
 180 :math:`\mathbf{x}^a` in the section :ref:`section_theory`.
 181
 182 Such method can be used to print results, or to convert these ones to
 183 structures that can be used in the native or external SALOME post-processing. A
 184 simple example is given in the section :ref:`section_examples`.
 185
 186 STEP 5: Execute the YACS case and obtain the results
 187 ----------------------------------------------------
 188
 189 The YACS scheme is now complete and can be executed. Parametrization and
 190 execution of this YACS case is fully compliant with the standard way to deal
 191 with a YACS scheme, as described in the *YACS module User's Guide*.
 192
 193 To recall the simplest way to proceed, the YACS scheme has to be compiled using
 194 the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the
 195 scheme to run. Then the compiled scheme can be started, executed step by step or
 196 using breakpoints, etc.
 197
 198 The standard output will be pushed into the "*YACS Container Log*", obtained
 199 through the right click menu of the "*proc*" window in the YACS GUI. The errors
 200 are shown either in the "*YACS Container Log*", or at the command line in the
 201 shell window (if SALOME has been launched by its explicit command, and not by a
 202 menu or a desktop icon). As an example, the output of the above simple case is
 203 of the following form::
 204
 205    Entering in the assimilation study
 206    Name is set to........: Test
 207    Algorithm is set to...: Blue
 208    Launching the analyse
 209
 210    Optimal state: [0.5, 0.5, 0.5]
 211
 212 shown in the "*YACS Container Log*".
 213
 214 The execution can also be done using a shell script, as described in the section
 215 :ref:`section_advanced`.
 216
 217 .. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME platform.
 218
 219 .. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts.
 220
 221 .. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME platform.
 222
 223 .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`.