doc/en/ref_options_AlgorithmParameters.rst

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