doc/fr/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 des options d'un algorithme par "*AlgorithmParameters*"
  31 -------------------------------------------------------------------
  32
  33 Chaque algorithme peut être contrôlé en utilisant des options ou des paramètres
  34 particuliers. Ils sont donnés à travers la commande optionnelle "*Parameters*"
  35 incluse dans la commande obligatoire "*AlgorithmParameters*".
  36
  37 Il existe plusieurs méthodes pratiques pour fournir ces options, que ce soit en
  38 utilisant l'interface graphique EFICAS d'ADAO (GUI) ou l'interface textuelle
  39 (TUI). La méthode est déterminée de la manière suivante :
  40
  41 #. Soit en interface graphique (GUI), à l'aide du mot-clé "*Parameters*" dans
  42    la commande "*AlgorithmParameters*", qui permet de choisir entre
  43    "*Defaults*" (utilisation de mots-clés explicites pré-remplis par les
  44    valeurs par défaut des paramètres) et "*Dict*" (utilisation d'un
  45    dictionnaire pour renseigner les mots-clés nécessaires),
  46 #. Soit en interface graphique (GUI), uniquement dans le cas "*Dict*" de
  47    "*Parameters*", par le mot-clé "*FROM*" inclus qui permet de choisir entre une
  48    entrée par chaîne de caractères ou une entrée par fichier de script Python.
  49 #. Soit en interface textuelle (TUI), à l'aide du mot-clé "*Parameters*" dans
  50    la commande "*AlgorithmParameters*", de manière semblable à l'interface
  51    graphique, en renseignant les mots-clés explicites décrits dans la
  52    documentation de chaque algorithme.
  53 #. Soit en interface textuelle (TUI), à l'aide du mot-clé "*Parameters*" dans
  54    la commande "*AlgorithmParameters*", en fournissant un script contenant un
  55    dictionnaire similaire aux méthodes deux et trois et compatibles avec ces
  56    entrées en GUI.
  57
  58 Ces deux dernières options sont celles que l'on peut utiliser dans l'interface
  59 textuelle (TUI) de manière similaire et compatible aux deux précédentes basées
  60 sur l'interface graphique (GUI).
  61
  62 Si une option ou un paramètre est spécifié par l'utilisateur pour un algorithme
  63 qui ne la supporte pas, cette option est simplement ignorée (laissée
  64 inutilisée) et ne bloque pas le traitement. La signification des acronymes ou
  65 des noms particuliers peut être trouvée dans l'index ou dans le
  66 :ref:`section_glossary`.
  67
  68 Première méthode (GUI) : utiliser les mots-clés explicites pré-remplis
  69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  70
  71 Pour donner les valeurs des paramètres par les mots-clés explicites pré-remplis,
  72 directement dans l'interface graphique, l'utilisateur sélectionne le type
  73 "*Defaults*" dans le mot-clé "*Parameters*", puis les mots-clés dans la liste
  74 prévue "*Parameters[Algo]*" qui apparaît, associée à l'algorithme choisi, comme
  75 montré dans la figure qui suit :
  76
  77   .. adao_algopar_defaults:
  78   .. image:: images/adao_algopar_defaults.png
  79     :align: center
  80     :width: 100%
  81   .. centered::
  82     **Utiliser les mots-clés explicites pré-remplis pour les paramètres algorithmiques**
  83
  84 Chaque paramètre est optionnel, et il présente sa valeur par défaut lorsqu'il
  85 est sélectionné par l'utilisateur. On peut alors modifier sa valeur, ou la
  86 renseigner dans le cas de listes par exemple.
  87
  88 C'est la manière recommandée pour modifier uniquement une partie des paramètres
  89 algorithmiques de manière sûre. Cette méthode ne permet de définir que les
  90 paramètres autorisés pour un algorithme donné, et les valeurs définies ne sont
  91 pas conservées si l'utilisateur change d'algorithme.
  92
  93 Cette méthode n'est naturellement pas utilisable en interface TUI.
  94
  95 Deuxième méthode (GUI) : utiliser une chaîne de caractères dans l'interface graphique
  96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  97
  98 Pour donner les valeurs des paramètres par une chaîne de caractères, directement
  99 dans l'interface graphique, l'utilisateur sélectionne le type "*Dict*" dans le
 100 mot-clé "*Parameters*", puis le type "*String*" dans le mot-clé "*FROM*" de la
 101 commande "*Dict*" qui apparaît, comme montré dans la figure qui suit :
 102
 103   .. adao_algopar_string:
 104   .. image:: images/adao_algopar_string.png
 105     :align: center
 106     :width: 100%
 107   .. centered::
 108     **Utiliser une chaîne de caractères pour les paramètres algorithmiques**
 109
 110 Dans le champ de saisie, il faut utiliser des guillemets simples pour une
 111 définition standard de dictionnaire, comme par exemple::
 112
 113     '{"MaximumNumberOfIterations":25,"SetSeed":1000}'
 114
 115 C'est la manière recommandée pour définir des paramètres algorithmiques. Cette
 116 méthode permet en particulier de conserver des options ou des paramètres pour
 117 d'autres algorithmes que celui que l'on utilise au moment présent. Cela
 118 facilite le changement d'algorithme ou la conservation de valeurs par défaut
 119 différentes des défauts standards.
 120
 121 Troisième méthode (GUI) : utiliser un fichier externe de script Python
 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 123
 124 Pour donner les valeurs des paramètres par un fichier de script Python externe,
 125 l'utilisateur sélectionne dans l'interface graphique le type "*Dict*" dans le
 126 mot-clé "*Parameters*", puis le type "*Script*" dans le mot-clé "*FROM*" de la
 127 commande "*Dict*" qui apparaît, comme montré dans la figure qui suit :
 128
 129   .. :adao_algopar_script
 130   .. image:: images/adao_algopar_script.png
 131     :align: center
 132     :width: 100%
 133   .. centered::
 134     **Utiliser un fichier externe pour les paramètres algorithmiques**
 135
 136 Ce fichier script Python externe, nommé par exemple ici ``myParameters.py``,
 137 doit définir une variable de type dictionnaire au nom imposé "*Parameters*" ou
 138 "*AlgorithmParameters*", à la manière de l'exemple qui suit :
 139
 140 .. code-block:: python
 141     :caption: myParameters.py : fichier de paramètres
 142
 143     AlgorithmParameters = {
 144         "MaximumNumberOfIterations" : 25,
 145         "StoreSupplementaryCalculations" : [
 146             "CurrentState",
 147             "APosterioriCovariance",
 148             "OMA",
 149             ],
 150         }
 151
 152 De plus, le fichier peut contenir d'autres commandes Python. Cette méthode
 153 permet aussi, comme la précédente, de conserver de manière externe des options
 154 ou des paramètres pour d'autres algorithmes que celui que l'on utilise.
 155
 156 Quatrième méthode (TUI) : utiliser les mots-clés explicites documentés
 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 158
 159 Dans l'interface textuelle (TUI), le contrôle des algorithmes se fait en
 160 utilisant la commande "*setAlgorithmParameters*". Elle permet de renseigner ou
 161 de définir les mots-clés décrits dans la documentation de chaque cas de calcul
 162 ADAO. Pour mémoire, ces mots-clés sont les mêmes que ceux qui sont présentés
 163 dans l'interface graphique.
 164
 165 Pour cela, un dictionnaire des couples "mot-clé/valeurs" peut être donné comme
 166 argument du mot-clé "*Parameters*" de la commande. Pour un  cas de calcul TUI
 167 nommé par exemple ``case``, la syntaxe ressemble au code suivant :
 168
 169 .. code-block:: python
 170
 171     [...]
 172     case.setAlgorithmParameters(
 173         Algorithm='3DVAR',
 174         Parameters={
 175             "MaximumNumberOfIterations" : 25,
 176             "StoreSupplementaryCalculations" : [
 177                 "CurrentState",
 178                 "APosterioriCovariance",
 179                 "OMA",
 180                 ],
 181             },
 182         )
 183     [...]
 184
 185 Les valeurs des arguments peuvent évidemment provenir d'évaluations Python ou
 186 de variables précédemment définies, facilitant l'insertion des commandes ADAO
 187 dans le flot du scripting Python d'une étude.
 188
 189 Cinquième méthode (TUI) : utiliser un fichier externe de script Python
 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 191
 192 Dans l'interface textuelle (TUI), un fichier peut être donné comme argument de
 193 manière identique et compatible avec la troisième méthode dédiée à l'interface
 194 graphique (GUI). Un fichier externe de script Python nommé ``myParameters.py``,
 195 et contenant par exemple les informations déjà mentionnées pour la troisième
 196 méthode, est le suivant :
 197
 198 .. code-block:: python
 199     :caption: Version simple de myParameters.py
 200
 201     AlgorithmParameters = {
 202         "MaximumNumberOfIterations" : 25,
 203         "StoreSupplementaryCalculations" : [
 204             "CurrentState",
 205             "APosterioriCovariance",
 206             "OMA",
 207             ],
 208         }
 209
 210 Pour un  cas de calcul TUI nommé par exemple ``case``, qui doit lire ce
 211 fichier, la commande en interface textuelle utilise l'argument "*Script*" sous
 212 la forme suivante :
 213
 214 .. code-block:: python
 215
 216     [...]
 217     case.setAlgorithmParameters( Algorithm = "3DVAR", Script = "myParameters.py" )
 218     [...]
 219
 220 De manière alternative et complètement équivalente, pour être conforme à la
 221 définition requise par la commande "*setAlgorithmParameters*", on peut utiliser
 222 dans le script Python externe ``myParameters.py`` la dénomination
 223 "*Parameters*" à la place de "*AlgorithmParameters*" sous la forme :
 224
 225 .. code-block:: python
 226     :caption: Version simple de myParameters.py
 227
 228     Parameters = {
 229         "MaximumNumberOfIterations" : 25,
 230         "StoreSupplementaryCalculations" : [
 231             "CurrentState",
 232             "APosterioriCovariance",
 233             "OMA",
 234             ],
 235         }
 236
 237 La commande de chargement en interface textuelle reste identique. On peut aussi
 238 rajouter dans le script externe le nom de l'algorithme avec son propre mot-clé
 239 "*Algorithm*" (qui dans ce cas est requis, et qui ne peut pas être inclus comme
 240 une option dans "*AlgorithmParameters*") :
 241
 242 .. code-block:: python
 243     :caption: Version complète de myParameters.py
 244     :name: myParameters.py
 245
 246     Algorithm='3DVAR'
 247     Parameters = {
 248         "MaximumNumberOfIterations" : 25,
 249         "StoreSupplementaryCalculations" : [
 250             "CurrentState",
 251             "APosterioriCovariance",
 252             "OMA",
 253             ],
 254         }
 255
 256 La commande de chargement en interface textuelle se simplifie alors pour ne
 257 plus comporter qu'un seul argument :
 258
 259 .. code-block:: python
 260
 261     [...]
 262     case.setAlgorithmParameters(Script = "myParameters.py")
 263     [...]
 264
 265 Cette dernière forme est la plus simple pour paramétrer entièrement les entrées
 266 d'algorithmes dans un script Python externe, qui peut ainsi être contrôlé ou
 267 généré par un processus plus vaste de construction d'étude incluant les
 268 commandes ADAO.