doc/en/using.rst

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