doc/en/ref_options_AlgorithmParameters.rst

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