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    :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. It is complemented
  24 by the detailed description of all the commands and keywords in the section
  25 :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 test 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 menu) in the toolbar of SALOME. If there is no SALOME study
  55 loaded, a popup appears, allowing to choose between creating a new study, or
  56 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.
  81
  82 The structured editor indicates hierarchical types, values or keywords allowed.
  83 Incomplete or incorrect keywords are identified by a visual error red flag.
  84 Possible values are indicated for keywords defined with a limited list of
  85 values, and adapted entries are given for the other keywords. Some help messages
  86 are contextually provided in the editor reserved places.
  87
  88 A new case is set up with the minimal list of commands. All the mandatory
  89 commands or keywords are already present, none of them can be suppressed.
  90 Optional keywords can be added by choosing them in a list of suggestions of
  91 allowed ones for the main command, for example the "*ASSIMILATION_STUDY*"
  92 command. As an example, one can add an "*AlgorithmParameters*" keyword, as
  93 described in the last part of the section :ref:`section_examples`.
  94
  95 At the end, when all fields or keywords have been correctly defined, each line
  96 of the commands tree must have a green flag. This indicates that the whole case
  97 is valid and completed (and can be saved).
  98
  99   .. _adao_jdcexample00:
 100   .. image:: images/adao_jdcexample01.png
 101     :align: center
 102     :scale: 75%
 103   .. centered::
 104     **Example of a valid ADAO case**
 105
 106 Finally, you have to save your ADAO case by pushing the "*Save*" button
 107 |eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the
 108 "*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location
 109 in your file tree and a name, that will be completed by a "*.comm*" extension
 110 used for JDC EFICAS files. This will generate a pair of files describing the
 111 ADAO case, with the same base name, the first one being completed by a "*.comm*"
 112 extension and the second one by a "*.py*" extension [#]_.
 113
 114 STEP 3: Export the ADAO case as a YACS scheme
 115 ---------------------------------------------
 116
 117 When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
 118 order to execute the data assimilation calculation. This can be easily done by
 119 using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
 120 "*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
 121 menu in the object browser.
 122
 123   .. _adao_exporttoyacs01:
 124   .. image:: images/adao_exporttoyacs.png
 125     :align: center
 126     :scale: 75%
 127   .. centered::
 128     **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
 129
 130 This will lead to automatically generate a YACS scheme, and open the YACS module
 131 on this scheme. The YACS file, associated with the scheme, will be stored in the
 132 same directory and with the same base name as the ADAO saved case, only changing
 133 its extension to "*.xml*". Be careful, *if the XML file name already exist, it
 134 will be overwritten without prompting for replacing the file*.
 135
 136 STEP 4: Supplement and modify the YACS scheme and save it
 137 ---------------------------------------------------------
 138
 139 .. index:: single: Analysis
 140
 141 When the YACS scheme is generated and opened in SALOME through the YACS module
 142 GUI, you can modify or supplement the scheme like any YACS scheme. Nodes or
 143 blocs can be added, copied or modified to elaborate complex analysis, or to
 144 insert data assimilation or optimization capabilities into more complex YACS
 145 calculation schemes. It is recommended to save the modified scheme with a new
 146 name, in order to preserve the XML file in the case you re-export the ADAO case
 147 to YACS.
 148
 149 The main supplement needed in the YACS scheme is a post-processing step. The
 150 evaluation of the results has to be done in the physical context of the
 151 simulation used by the data assimilation procedure. The post-processing can be
 152 provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string,
 153 by templates, or can be build as YACS nodes using all SALOME possibilities.
 154
 155 The YACS scheme has an "*algoResults*" output port of the computation bloc,
 156 which gives access to a "*pyobj*" named hereafter "*ADD*", containing all the
 157 processing results. These results can be obtained by retrieving the named
 158 variables stored along the calculation. The main is the "*Analysis*" one, that
 159 can be obtained by the python command (for example in an in-line script node or
 160 a script provided through the "*UserPostAnalysis*" keyword)::
 161
 162     Analysis = ADD.get("Analysis")[:]
 163
 164 "*Analysis*" is a complex object, similar to a list of values calculated at each
 165 step of data assimilation calculation. In order to get and print the optimal
 166 data assimilation state evaluation, in script provided through the
 167 "*UserPostAnalysis*" keyword, one can use::
 168
 169     Xa = ADD.get("Analysis")[-1]
 170     print "Optimal state:", Xa
 171     print
 172
 173 This ``Xa`` is a vector of values, that represents the solution of the data
 174 assimilation or optimization evaluation problem, noted as :math:`\mathbf{x}^a`
 175 in the section :ref:`section_theory`.
 176
 177 Such command can be used to print results, or to convert these ones to
 178 structures that can be used in the native or external SALOME post-processing. A
 179 simple example is given in the section :ref:`section_examples`.
 180
 181 STEP 5: Execute the YACS case and obtain the results
 182 ----------------------------------------------------
 183
 184 The YACS scheme is now complete and can be executed. Parametrization and
 185 execution of a YACS case is fully compliant with the standard way to deal with a
 186 YACS scheme, and is described in the *YACS module User's Guide*.
 187
 188 To recall the simplest way to proceed, the YACS scheme has to be compiled using
 189 the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the
 190 scheme to run. Then the compiled scheme can be started, executed step by step or
 191 using breakpoints, etc.
 192
 193 The standard output will be pushed into the "*YACS Container Log*", obtained
 194 through the right click menu of the "*proc*" window in the YACS GUI. The errors
 195 are shown either in the "*YACS Container Log*", or at the command line in the
 196 shell window (if SALOME has been launched by its explicit command and not by
 197 menu). As an example, the output of the above simple case is the following::
 198
 199    Entering in the assimilation study
 200    Name is set to........: Test
 201    Algorithm is set to...: Blue
 202    Launching the analyse
 203
 204    Optimal state: [0.5, 0.5, 0.5]
 205
 206 shown in the "*YACS Container Log*".
 207
 208 The execution can also be done using a shell script, as described in the section
 209 :ref:`section_advanced`.
 210
 211 .. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME GUI.
 212
 213 .. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME GUI.
 214
 215 .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`.