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