doc/en/ref_options_AlgorithmParameters.rst

   1 ..
   2    Copyright (C) 2008-2020 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 3 practical methods for the user of the EFICAS graphical user
  38 interface of ADAO (GUI) to provide these options. The method is determined as
  39 follows in the ADAO EFICAS graphical user interface:
  40
  41 #. firstly using the "*Parameters*" keyword in the "*AlgorithmParameters*"
  42    command, which allows to choose between "*Defaults*" (use of explicit
  43    pre-filled keywords by default parameters values) and "*Dict*" (use of a
  44    dictionary to fill the necessary keywords),
  45 #. then secondly or thirdly, only in the "*Dict*" case of "*Parameters*", by
  46    the included keyword "*FROM*" which allows to choose between a string entry
  47    and a Python script file entry.
  48
  49 These two last options can be also used in the ADAO textual interface (TUI),
  50 through the keywords "*Parameters*" and "*Script*" of the corresponding command
  51 "*AlgorithmParameters*" (see the :ref:`section_tui` part for detailed
  52 description).
  53
  54 If an option or a parameter is specified by the user for an algorithm that does
  55 not support it, the option is simply ignored (left unused) and don't stop the
  56 treatment. The meaning of the acronyms or particular names can be found in the
  57 :ref:`genindex` or the :ref:`section_glossary`.
  58
  59 First method : using explicit pre-filled keywords
  60 +++++++++++++++++++++++++++++++++++++++++++++++++
  61
  62 To give the parameters values by explicit pre-filled keywords, directly in the
  63 graphical interface, the user selects the type "*Defaults*" in the keyword
  64 "*Parameters*", then the keywords in the given "*Parameters[Algo]*" list which
  65 appears, linked with the chosen algorithm, as shown in the following figure:
  66
  67   .. adao_algopar_defaults:
  68   .. image:: images/adao_algopar_defaults.png
  69     :align: center
  70     :width: 100%
  71   .. centered::
  72     **Using explicit pre-filled keywords for algorithmic parameters**
  73
  74 Each parameter is optional, and it is presented with its default value when it
  75 is selected by the user. One can then modify its value, or fill it in list cases
  76 for example.
  77
  78 It is the recommended way to modify only some algorithmic parameters in a safe
  79 way. This method allows only to define authorized parameters for a given
  80 algorithm, and the defined values are not kept if the user changes the
  81 algorithm.
  82
  83 This method is naturally not usable in TUI interface.
  84
  85 Second method : using a string in the graphical interface
  86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  87
  88 To give the parameters values as a string, directly in the graphical interface,
  89 the user selects the type "*Dict*" in the keyword "*Parameters*", then the type
  90 "*String*" in the keyword "*FROM*" of the "*Dict*" command which appears, as
  91 shown in the following figure:
  92
  93   .. :adao_algopar_string
  94   .. image:: images/adao_algopar_string.png
  95     :align: center
  96     :width: 100%
  97   .. centered::
  98     **Using a string for algorithmic parameters**
  99
 100 In the entry, one must enclose a standard dictionary definition between simple
 101 quotes, as for example::
 102
 103     '{"MaximumNumberOfSteps":25,"SetSeed":1000}'
 104
 105 It is the recommended way to define algorithmic parameters. This method allows
 106 in particular to keep options or parameters for other algorithms than the
 107 currently used one. It is then easier to change of algorithm or to keep default
 108 values different of the standard defaults.
 109
 110 In the textual interface TUI, the dictionary has only to be given as argument
 111 of the "*Parameters*" keyword.
 112
 113 Third method : using an external Python script file
 114 +++++++++++++++++++++++++++++++++++++++++++++++++++
 115
 116 To give the parameters values as an external Python script file, the user
 117 selects in the graphical interface the type "*Dict*" in the keyword
 118 "*Parameters*", then the type "*Script*" in the keyword "*FROM*" of the "*Dict*"
 119 command which appears, as shown in the following figure:
 120
 121   .. :adao_algopar_script
 122   .. image:: images/adao_algopar_script.png
 123     :align: center
 124     :width: 100%
 125   .. centered::
 126     **Using an external file for algorithmic parameters**
 127
 128 This external Python script file has then to define a variable with the required
 129 name "*AlgorithmParameters*", as in the following example::
 130
 131     AlgorithmParameters = {
 132         "MaximumNumberOfSteps" : 25,
 133         "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
 134         }
 135
 136 The file can also contain other Python commands. This method also allows, as
 137 the previous one, to keep options or parameters for other algorithms than the
 138 currently used one.
 139
 140 In the textual interface TUI, the file name has only to be given as argument of
 141 the "*Script*" keyword.