doc/en/ref_options_AlgorithmParameters.rst

   1 ..
   2    Copyright (C) 2008-2015 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 EFICAS:
  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 doesn't 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 EFICAS graphical interface, the user selects the type "*Defaults*" in the
  52 keyword "*Parameters*", then the keywords in the given "*Parameters[Algo]*" list
  53 which appears, linked with the chosen algorithm, as shown in the following
  54 figure:
  55
  56   .. adao_algopar_defaults:
  57   .. image:: images/adao_algopar_defaults.png
  58     :align: center
  59     :width: 100%
  60   .. centered::
  61     **Using explicit pre-filled keywords for algorithmic parameters**
  62
  63 Each parameter is optional, and it is presented with its default value when it
  64 is selected by the user. One can then modify its value, or fill it in list cases
  65 for example.
  66
  67 It is the recommended way to modify only some algorithmic parameters in a safe
  68 way. This method allows only to define authorized paramters for a given
  69 algorithm, and the defined values are not keeped if the user changes the
  70 algorithm.
  71
  72 Second method : using a string in EFICAS
  73 ++++++++++++++++++++++++++++++++++++++++
  74
  75 To give the parameters values as a string, directly in the EFICAS graphical
  76 interface, the user selects the type "*Dict*" in the keyword "*Parameters*",
  77 then the type "*String*" in the keyword "*FROM*" of the "*Dict*" command which
  78 appears, as shown in the following figure:
  79
  80   .. :adao_algopar_string
  81   .. image:: images/adao_algopar_string.png
  82     :align: center
  83     :width: 100%
  84   .. centered::
  85     **Using a string for algorithmic parameters**
  86
  87 In the entry, one must enclose a standard dictionary definition between simple
  88 quotes, as for example::
  89
  90     '{"MaximumNumberOfSteps":25,"SetSeed":1000}'
  91
  92 It is the recommended way to define algorithmic parameters. This method allows
  93 in particular to keep options or parameters for other algorithms than the
  94 currently used one. It is then easier to change of algorithm or to keep default
  95 values different of the standard defaults.
  96
  97 Third method : using an external Python script file
  98 ++++++++++++++++++++++++++++++++++++++++++++++++++
  99
 100 To give the parameters values as an external Python script file, the user
 101 selects in EFICAS the type "*Dict*" in the keyword "*Parameters*", then the type
 102 "*Script*" in the keyword "*FROM*" of the "*Dict*" command which appears, as
 103 shown in the following figure:
 104
 105   .. :adao_algopar_script
 106   .. image:: images/adao_algopar_script.png
 107     :align: center
 108     :width: 100%
 109   .. centered::
 110     **Using an external file for algorithmic parameters**
 111
 112 This external Python script file has then to define a variable with the required
 113 name "*AlgorithmParameters*", as in the following example::
 114
 115     AlgorithmParameters = {
 116         "MaximumNumberOfSteps" : 25,
 117         "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
 118         }
 119
 120 The file can also contain other Python commands. This method also allows, as the
 121 previous one, to keep options or parameters for other algorithms than the
 122 currently used one.