doc/en/ref_options_AlgorithmParameters.rst

   1 ..
   2    Copyright (C) 2008-2024 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 .. index:: single: AlgorithmParameters
  25 .. index:: single: Parameters
  26 .. index:: single: Defaults
  27 .. index:: single: setAlgorithmParameters
  28 .. _section_ref_options_Algorithm_Parameters:
  29
  30 Description of options of an algorithm by "*AlgorithmParameters*"
  31 -----------------------------------------------------------------
  32
  33 Each algorithm can be controlled using some specific options or parameters. They
  34 are given through the "*Parameters*" optional command included in the mandatory
  35 command "*AlgorithmParameters*".
  36
  37 There are several convenient methods for providing these options, either using
  38 the ADAO EFICAS graphical interface (GUI) or the textual interface (TUI). The
  39 method is determined as follows:
  40
  41 #. Either in the graphical user interface (GUI), using the "*Parameters*"
  42    keyword in the "*AlgorithmParameters*" command, which allows you to choose
  43    between "*Defaults*" (use of explicit keywords pre-populated by the default
  44    values of the parameters) and "*Dict*" (use of a dictionary to fill in the
  45    necessary keywords),
  46 #. Or in the graphical user interface (GUI), only in the case "*Dict*" of
  47    "*Parameters*", by the included keyword "*FROM*" which allows to choose
  48    between an entry by string or an entry by Python script file.
  49 #. Or in textual interface (TUI), using the "*Parameters*" keyword in the
  50    "*AlgorithmParameters*" command, in a similar way to the graphical
  51    interface, by filling in the explicit keywords described in the
  52    documentation of each algorithm.
  53 #. Or in textual interface (TUI), using the keyword "*Parameters*" in the
  54    command "*AlgorithmParameters*", providing a script containing a dictionary
  55    similar to methods two and three and compatible with these GUI entries.
  56
  57 These last two options are the ones that can be used in the textual interface
  58 (TUI) in a similar and compatible way to the two previous ones based on the
  59 graphical interface (GUI).
  60
  61 If an option or a parameter is specified by the user for an algorithm that does
  62 not support it, the option is simply ignored (left unused) and don't stop the
  63 treatment. The meaning of the acronyms or particular names can be found in the
  64 index or the :ref:`section_glossary`.
  65
  66 First method (GUI): using explicit pre-filled keywords
  67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  68
  69 To give the parameters values by explicit pre-filled keywords, directly in the
  70 graphical interface, the user selects the type "*Defaults*" in the keyword
  71 "*Parameters*", then the keywords in the given "*Parameters[Algo]*" list which
  72 appears, linked with the chosen algorithm, as shown in the following figure:
  73
  74   .. adao_algopar_defaults:
  75   .. image:: images/adao_algopar_defaults.png
  76     :align: center
  77     :width: 100%
  78   .. centered::
  79     **Using explicit pre-filled keywords for algorithmic parameters**
  80
  81 Each parameter is optional, and it is presented with its default value when it
  82 is selected by the user. One can then modify its value, or fill it in list cases
  83 for example.
  84
  85 It is the recommended way to modify only some algorithmic parameters in a safe
  86 way. This method allows only to define authorized parameters for a given
  87 algorithm, and the defined values are not kept if the user changes the
  88 algorithm.
  89
  90 This method is naturally not usable in TUI interface.
  91
  92 Second method(GUI): using a string in the graphical interface
  93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  94
  95 To give the parameters values as a string, directly in the graphical interface,
  96 the user selects the type "*Dict*" in the keyword "*Parameters*", then the type
  97 "*String*" in the keyword "*FROM*" of the "*Dict*" command which appears, as
  98 shown in the following figure:
  99
 100   .. :adao_algopar_string
 101   .. image:: images/adao_algopar_string.png
 102     :align: center
 103     :width: 100%
 104   .. centered::
 105     **Using a string for algorithmic parameters**
 106
 107 In the entry, one must enclose a standard dictionary definition between simple
 108 quotes, as for example::
 109
 110     '{"MaximumNumberOfIterations":25,"SetSeed":1000}'
 111
 112 It is the recommended way to define algorithmic parameters. This method allows
 113 in particular to keep options or parameters for other algorithms than the
 114 currently used one. It is then easier to change of algorithm or to keep default
 115 values different of the standard defaults.
 116
 117 Third method (GUI): using an external Python script file
 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 119
 120 To give the parameters values as an external Python script file, the user
 121 selects in the graphical interface the type "*Dict*" in the keyword
 122 "*Parameters*", then the type "*Script*" in the keyword "*FROM*" of the "*Dict*"
 123 command which appears, as shown in the following figure:
 124
 125   .. :adao_algopar_script
 126   .. image:: images/adao_algopar_script.png
 127     :align: center
 128     :width: 100%
 129   .. centered::
 130     **Using an external file for algorithmic parameters**
 131
 132 This external Python script file, named for example here ``myParameters.py``,
 133 must define a dictionary variable with the imposed name "*Parameters*" or
 134 "*AlgorithmParameters*", like the following example:
 135
 136 .. code-block:: python
 137     :caption: myParameters.py: parameters file
 138
 139     AlgorithmParameters = {
 140         "MaximumNumberOfIterations" : 25,
 141         "StoreSupplementaryCalculations" : [
 142             "CurrentState",
 143             "APosterioriCovariance",
 144             "OMA",
 145             ],
 146         }
 147
 148 Moreover, the file can contain other Python commands. This method also allows,
 149 like the previous one, to keep externally options or parameters for other
 150 algorithms than the one we are using.
 151
 152 Fourth method (TUI): use explicit documented keywords
 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 154
 155 In the textual interface (TUI), the control of the algorithms is done by using
 156 the command "*setAlgorithmParameters*". It allows to fill in or define the
 157 keywords described in the documentation of each ADAO calculation case. Just to
 158 remind you, these keywords are the same as the ones presented in the graphical
 159 interface.
 160
 161 To do this, a dictionary of "keyword/value" pairs can be given as an argument
 162 to the "*Parameters*" keyword of the command. For a TUI calculation case named
 163 for example ``case``, the syntax looks like the following code:
 164
 165 .. code-block:: python
 166
 167     [...]
 168     case.setAlgorithmParameters(
 169         Algorithm='3DVAR',
 170         Parameters={
 171             "MaximumNumberOfIterations" : 25,
 172             "StoreSupplementaryCalculations" : [
 173                 "CurrentState",
 174                 "APosterioriCovariance",
 175                 "OMA",
 176                 ],
 177             },
 178         )
 179     [...]
 180
 181 The argument values can obviously come from Python evaluations or previously
 182 defined variables, making it easy to insert ADAO commands into the Python
 183 scripting flow of a study.
 184
 185 Fifth method (TUI): use an external Python script file
 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 187
 188 In the textual interface (TUI), a file can be given as argument in the same and
 189 compatible way as the third method dedicated to the graphical interface (GUI).
 190 An external Python script file named ``myParameters.py``, and containing for
 191 example the information already mentioned for the third method, is the
 192 following:
 193
 194 .. code-block:: python
 195     :caption: Simple version of myParameters.py
 196
 197     AlgorithmParameters = {
 198         "MaximumNumberOfIterations" : 25,
 199         "StoreSupplementaryCalculations" : [
 200             "CurrentState",
 201             "APosterioriCovariance",
 202             "OMA",
 203             ],
 204         }
 205
 206 For a TUI computation case named for example ``case``, which has to read this
 207 file, the textual interface command uses the argument "*Script*" in the
 208 following form:
 209
 210 .. code-block:: python
 211
 212     [...]
 213     case.setAlgorithmParameters( Algorithm = "3DVAR", Script = "myParameters.py" )
 214     [...]
 215
 216 Alternatively and completely equivalently, to comply with the definition
 217 required by the "*setAlgorithmParameters*" command, one can use in the external
 218 Python script ``myParameters.py`` the name "*Parameters*" instead of
 219 "*AlgorithmParameters*" in the form:
 220
 221 .. code-block:: python
 222     :caption: Simple version of myParameters.py
 223
 224     Parameters = {
 225         "MaximumNumberOfIterations" : 25,
 226         "StoreSupplementaryCalculations" : [
 227             "CurrentState",
 228             "APosterioriCovariance",
 229             "OMA",
 230             ],
 231         }
 232
 233 The loading command in the textual interface remains the same. One can also add
 234 in the external script the name of the algorithm with its own keyword
 235 "*Algorithm*" (which in this case is required, and cannot be included as an
 236 option in "*AlgorithmParameters*"):
 237
 238 .. code-block:: python
 239     :caption: Full version of myParameters.py
 240     :name: myParameters.py
 241
 242     Algorithm='3DVAR'
 243     Parameters = {
 244         "MaximumNumberOfIterations" : 25,
 245         "StoreSupplementaryCalculations" : [
 246             "CurrentState",
 247             "APosterioriCovariance",
 248             "OMA",
 249             ],
 250         }
 251
 252 The textual interface loading command is then simplified to a single argument:
 253
 254 .. code-block:: python
 255
 256     [...]
 257     case.setAlgorithmParameters(Script = "myParameters.py")
 258     [...]
 259
 260 This last form is the simplest way to fully parameterize algorithm inputs in an
 261 external Python script, which can then be controlled or generated by a wider
 262 process of study building including the ADAO commands.