doc/fr/reference.rst

   1 .. _section_reference:
   2
   3 ================================================================================
   4 Description de référence des commandes et mots-clés ADAO
   5 ================================================================================
   6
   7 Cette section présente la description de référence des commandes et mots-clés
   8 ADAO disponibles à travers l'interface graphique (GUI) ou à travers des scripts.
   9 Chaque commande ou mot-clé à définir par l'interface graphique (GUI) a des
  10 propriétés particulières. La première propriété est d'être *requise*,
  11 *optionnelle* ou simplement utile, décrivant un type d'entrée. La seconde
  12 propriété est d'être une variable "ouverte" avec un type fixé mais avec
  13 n'importe quelle valeur autorisée par le type, ou une variable "fermée", limitée
  14 à des valeurs spécifiées. L'éditeur graphique EFICAS disposant de capacités
  15 intrinsèques de validation, les propriétés des commandes ou mots-clés données à
  16 l'aide de l'interface graphique sont automatiquement correctes.
  17
  18 Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
  19 :ref:`section_theory`.
  20
  21 Des exemples sur l'usage de ces commandes sont disponibles dans la section
  22 :ref:`section_examples` et dans les fichiers d'exemple installés avec le module
  23 ADAO.
  24
  25 Liste des types d'entrées possibles
  26 -----------------------------------
  27
  28 .. index:: single: Dict
  29 .. index:: single: Function
  30 .. index:: single: Matrix
  31 .. index:: single: ScalarSparseMatrix
  32 .. index:: single: DiagonalSparseMatrix
  33 .. index:: single: String
  34 .. index:: single: Script
  35 .. index:: single: Vector
  36
  37 Chaque variable ADAO présente un pseudo-type qui aide à la remplir et à la
  38 valider. Les différents pseudo-types sont:
  39
  40 **Dict**
  41     Cela indique une variable qui doit être remplie avec un dictionnaire Python
  42     ``{"clé":"valeur"...}``, usuellement donné soit par une chaîne de caractères
  43     soit par un fichier script.
  44
  45 **Function**
  46     Cela indique une variable qui doit être donnée comme une fonction Python,
  47     usuellement donnée soit par une chaîne de caractères soit par un fichier
  48     script.
  49
  50 **Matrix**
  51     Cela indique une variable qui doit être donnée comme une matrice,
  52     usuellement donnée soit par une chaîne de caractères soit par un fichier
  53     script.
  54
  55 **ScalarSparseMatrix**
  56     Cela indique une variable qui doit être donnée comme un nombre unique (qui
  57     sera utilisé pour multiplier une matrice identité), usuellement donné soit
  58     par une chaîne de caractères soit par un fichier script.
  59
  60 **DiagonalSparseMatrix**
  61     Cela indique une variable qui doit , (qui sera
  62     utilisé pour remplacer la diagonale d'une matrice identité), usuellement
  63     donné soit par une chaîne de caractères soit par un fichier script.
  64
  65 **Script**
  66     Cela indique un script donné comme un fichier externe. Il peut être désigné
  67     par un nom de fichier avec chemin complet ou seulement par un nom de fichier
  68     sans le chemin. Si le fichier est donné uniquement par un nom sans chemin,
  69     et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans
  70     le répertoire d'étude donné.
  71
  72 **String**
  73     Cela indique une chaîne de caractères fournissant une représentation
  74     littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme
  75     par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille
  76     2x2.
  77
  78 **Vector**
  79     Cela indique une variable qui doit être remplie comme un vecteur,
  80     usuellement donné soit par une chaîne de caractères soit par un fichier
  81     script.
  82
  83 **VectorSerie**
  84     Cela indique une variable qui doit être remplie comme une liste de vecteurs,
  85     usuellement donnée soit par une chaîne de caractères soit par un fichier
  86     script.
  87
  88 Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script,
  89 ce script doit présenter une variable ou une méthode que porte le même nom que
  90 la variable à remplir. En d'autres mots, lorsque l'on importe le script dans un
  91 noeud Python de YACS, il doit créer une variable du bon nom dans l'espace de
  92 nommage courant du noeud.
  93
  94 Description de référence pour les cas de calcul ADAO
  95 ----------------------------------------------------
  96
  97 Liste des commandes et mots-clés pour un cas de calcul ADAO
  98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  99
 100 .. index:: single: ASSIMILATION_STUDY
 101 .. index:: single: Algorithm
 102 .. index:: single: AlgorithmParameters
 103 .. index:: single: Background
 104 .. index:: single: BackgroundError
 105 .. index:: single: ControlInput
 106 .. index:: single: Debug
 107 .. index:: single: EvolutionError
 108 .. index:: single: EvolutionModel
 109 .. index:: single: InputVariables
 110 .. index:: single: Observation
 111 .. index:: single: ObservationError
 112 .. index:: single: ObservationOperator
 113 .. index:: single: Observers
 114 .. index:: single: OutputVariables
 115 .. index:: single: Study_name
 116 .. index:: single: Study_repertory
 117 .. index:: single: UserDataInit
 118 .. index:: single: UserPostAnalysis
 119
 120 La première série de commandes est liée à la description d'un cas de calcul, qui
 121 est une procédure d'*Assimilation de Données* ou d'*Optimisation*. Les termes
 122 sont classés par ordre alphabétique, sauf le premier, qui décrit le choix entre
 123 le calcul ou la vérification. Les différentes commandes sont les suivantes:
 124
 125 **ASSIMILATION_STUDY**
 126     *Commande obligatoire*. C'est la commande générale qui décrit le cas
 127     d'assimilation de données ou d'optimisation. Elle contient hiérarchiquement
 128     toutes les autres commandes.
 129
 130 **Algorithm**
 131     *Commande obligatoire*. C'est une chaîne de caractère qui indique l'algorithme
 132     d'assimilation de données ou d'optimisation choisi. Les choix sont limités
 133     et disponibles à travers l'interface graphique. Il existe par exemple le
 134     "3DVAR", le "Blue"... Voir plus loin la liste des algorithmes et des
 135     paramètres associés dans la sous-section `Commandes optionnelles et requises
 136     pour les algorithmes de calcul`_.
 137
 138 **AlgorithmParameters**
 139     *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour
 140     contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa
 141     valeur est définie comme un objet de type "*Dict*". Voir plus loin la liste
 142     des algorithmes et des paramètres associés dans la sous-section `Commandes
 143     optionnelles et requises pour les algorithmes de calcul`_.
 144
 145 **Background**
 146     *Commande obligatoire*. Elle définit le vecteur d'ébauche ou
 147     d'initialisation, noté précédemment :math:`\mathbf{x}^b`. Sa valeur est
 148     définie comme un objet de type "*Vector*".
 149
 150 **BackgroundError**
 151     *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
 152     d'ébauche, notée précédemment :math:`\mathbf{B}`. Sa valeur est définie
 153     comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
 154     type "*DiagonalSparseMatrix*".
 155
 156 **ControlInput**
 157     *Commande optionnelle*. Elle indique le vecteur de contrôle utilisé pour
 158     forcer le modèle d'évolution à chaque pas, usuellement noté
 159     :math:`\mathbf{U}`. Sa valeur est définie comme un objet de type "*Vector*"
 160     ou de type *VectorSerie*. Lorsqu'il n'y a pas de contrôle, sa valeur doit
 161     être une chaîne vide ''.
 162
 163 **Debug**
 164     *Commande optionnelle*. Elle définit le niveau de sorties et d'informations
 165     intermédiaires de débogage. Les choix sont limités entre 0 (pour False) and
 166     1 (pour True).
 167
 168 **EvolutionError**
 169     *Commande optionnelle*. Elle définit la matrice de covariance des erreurs
 170     d'évolution, usuellement notée :math:`\mathbf{Q}`.  Sa valeur est définie
 171     comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
 172     type "*DiagonalSparseMatrix*".
 173
 174 **EvolutionModel**
 175     *Commande optionnelle*. Elle indique l'opérateur d'évolution du modèle,
 176     usuellement noté :math:`M`, qui décrit un pas élémentaire d'évolution. Sa
 177     valeur est définie comme un objet de type "*Function*". Différentes formes
 178     fonctionnelles peuvent être utilisées, comme décrit dans la sous-section
 179     suivante `Exigences pour les fonctions décrivant un opérateur`_. Si un
 180     contrôle :math:`U` est inclus dans le modèle d'évolution, l'opérateur doit
 181     être appliqué à une paire :math:`(X,U)`.
 182
 183 **InputVariables**
 184     *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
 185     variables physiques qui sont rassemblées dans le vecteur d'état. Cette
 186     information est destinée à être utilisée dans le traitement algorithmique
 187     interne des données.
 188
 189 **Observation**
 190     *Commande obligatoire*. Elle définit le vecteur d'observation utilisé en
 191     assimilation de données ou en optimisation, et noté précédemment
 192     :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type "*Vector*"
 193     ou de type *VectorSerie*".
 194
 195 **ObservationError**
 196     *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
 197     d'ébauche, notée précédemment :math:`\mathbf{R}`. Sa valeur est définie
 198     comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
 199     type "*DiagonalSparseMatrix*".
 200
 201 **ObservationOperator**
 202     *Commande obligatoire*. Elle indique l'opérateur d'observation, notée
 203     précédemment :math:`H`, qui transforme les paramètres d'entrée
 204     :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux
 205     observations :math:`\mathbf{y}^o`.  Sa valeur est définie comme un objet de
 206     type "*Function*". Différentes formes fonctionnelles peuvent être utilisées,
 207     comme décrit dans la sous-section suivante `Exigences pour les fonctions
 208     décrivant un opérateur`_. Si un contrôle :math:`U` est inclus dans le modèle
 209     d'observation, l'opérateur doit être appliqué à une paire :math:`(X,U)`.
 210
 211 **Observers**
 212     *Commande optionnelle*. Elle permet de définir des observateurs internes,
 213     qui sont des fonctions liées à une variable particulière, qui sont exécutées
 214     chaque fois que cette variable est modifiée. C'est une manière pratique de
 215     suivre des variables d'intérêt durant le processus d'assimilation de données
 216     ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples
 217     courants (squelettes) sont fournis pour aider l'utilisateur ou pour
 218     faciliter l'élaboration d'un cas.
 219
 220 **OutputVariables**
 221     *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
 222     variables physiques qui sont rassemblées dans le vecteur d'observation.
 223     Cette information est destinée à être utilisée dans le traitement
 224     algorithmique interne des données.
 225
 226 **Study_name**
 227     *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
 228     décrire l'étude ADAO par un nom ou une déclaration.
 229
 230 **Study_repertory**
 231     *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
 232     pour les calculs, et il est utilisé pour trouver les fichiers de script,
 233     donnés par nom sans répertoire, qui peuvent être utilisés pour définir
 234     certaines variables.
 235
 236 **UserDataInit**
 237     *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
 238     certaines données automatiquement avant le traitement de données d'entrée
 239     pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
 240     nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
 241     variables choisies.
 242
 243 **UserPostAnalysis**
 244     *Commande optionnelle*. Elle permet de traiter des paramètres ou des
 245     résultats après le déroulement de l'algorithme d'assimilation de données ou
 246     d'optimisation. Sa valeur est définie comme un fichier script ou une chaîne
 247     de caractères, permettant de produire directement du code de post-processing
 248     dans un cas ADAO. Des exemples courants (squelettes) sont fournis pour aider
 249     l'utilisateur ou pour faciliter l'élaboration d'un cas.
 250
 251 Commandes optionnelles et requises pour les algorithmes de calcul
 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 253
 254 .. index:: single: 3DVAR
 255 .. index:: single: Blue
 256 .. index:: single: ExtendedBlue
 257 .. index:: single: EnsembleBlue
 258 .. index:: single: KalmanFilter
 259 .. index:: single: ExtendedKalmanFilter
 260 .. index:: single: UnscentedKalmanFilter
 261 .. index:: single: LinearLeastSquares
 262 .. index:: single: NonLinearLeastSquares
 263 .. index:: single: ParticleSwarmOptimization
 264 .. index:: single: QuantileRegression
 265
 266 .. index:: single: AlgorithmParameters
 267 .. index:: single: Bounds
 268 .. index:: single: CostDecrementTolerance
 269 .. index:: single: GradientNormTolerance
 270 .. index:: single: GroupRecallRate
 271 .. index:: single: MaximumNumberOfSteps
 272 .. index:: single: Minimizer
 273 .. index:: single: NumberOfInsects
 274 .. index:: single: ProjectedGradientTolerance
 275 .. index:: single: QualityCriterion
 276 .. index:: single: Quantile
 277 .. index:: single: SetSeed
 278 .. index:: single: StoreInternalVariables
 279 .. index:: single: StoreSupplementaryCalculations
 280 .. index:: single: SwarmVelocity
 281
 282 Chaque algorithme peut être contrôlé en utilisant des options génériques ou
 283 particulières, données à travers la commande optionnelle "*AlgorithmParameters*"
 284 dans un fichier script ou une chaîne de caractères, à la manière de l'exemple
 285 qui suit dans un fichier::
 286
 287     AlgorithmParameters = {
 288         "Minimizer" : "LBFGSB",
 289         "MaximumNumberOfSteps" : 25,
 290         "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
 291         }
 292
 293 Pour donner les valeurs de la commande "*AlgorithmParameters*" par une chaîne de
 294 caractères, on doit utiliser des guillemets simples pour fournir une définition
 295 standard de dictionnaire, comme par exemple::
 296
 297     '{"Minimizer":"LBFGSB","MaximumNumberOfSteps":25}'
 298
 299 Cette section décrit les options disponibles algorithme par algorithme. De plus,
 300 pour chaque algorithme, les commandes/mots-clés obligatoires sont indiqués. Si
 301 une option est spécifiée par l'utilisateur pour un algorithme qui ne la supporte
 302 pas, cette option est simplement laissée inutilisée et ne bloque pas le
 303 traitement. La signification des acronymes ou des noms particuliers peut être
 304 trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`.
 305
 306 **"Blue"**
 307
 308   *Commandes obligatoires*
 309     *"Background", "BackgroundError",
 310     "Observation", "ObservationError",
 311     "ObservationOperator"*
 312
 313   StoreInternalVariables
 314     Cette clé booléenne permet de stocker les variables internes par défaut,
 315     principalement l'état courant lors d'un processus itératif. Attention, cela
 316     peut être un choix numériquement coûteux dans certains cas de calculs. La
 317     valeur par défaut est "False".
 318
 319   StoreSupplementaryCalculations
 320     Cette liste indique les noms des variables supplémentaires qui peuvent être
 321     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 322     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 323     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 324     dans la liste suivante : ["APosterioriCovariance", "BMA", "OMA", "OMB",
 325     "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
 326
 327 **"ExtendedBlue"**
 328
 329   *Commandes obligatoires*
 330     *"Background", "BackgroundError",
 331     "Observation", "ObservationError",
 332     "ObservationOperator"*
 333
 334   StoreInternalVariables
 335     Cette clé booléenne permet de stocker les variables internes par défaut,
 336     principalement l'état courant lors d'un processus itératif. Attention, cela
 337     peut être un choix numériquement coûteux dans certains cas de calculs. La
 338     valeur par défaut est "False".
 339
 340   StoreSupplementaryCalculations
 341     Cette liste indique les noms des variables supplémentaires qui peuvent être
 342     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 343     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 344     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 345     dans la liste suivante : ["APosterioriCovariance", "BMA", "OMA", "OMB",
 346     "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
 347
 348 **"LinearLeastSquares"**
 349
 350   *Commandes obligatoires*
 351     *"Observation", "ObservationError",
 352     "ObservationOperator"*
 353
 354   StoreInternalVariables
 355     Cette clé booléenne permet de stocker les variables internes par défaut,
 356     principalement l'état courant lors d'un processus itératif. Attention, cela
 357     peut être un choix numériquement coûteux dans certains cas de calculs. La
 358     valeur par défaut est "False".
 359
 360   StoreSupplementaryCalculations
 361     Cette liste indique les noms des variables supplémentaires qui peuvent être
 362     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 363     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 364     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 365     dans la liste suivante : ["OMA"].
 366
 367 **"3DVAR"**
 368
 369   *Commandes obligatoires*
 370     *"Background", "BackgroundError",
 371     "Observation", "ObservationError",
 372     "ObservationOperator"*
 373
 374   Minimizer
 375     Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par
 376     défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non
 377     linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), "TNC"
 378     (minimisation non linéaire sous contraintes), "CG" (minimisation non
 379     linéaire sans contraintes), "BFGS" (minimisation non linéaire sans
 380     contraintes), "NCG" (minimisation de type gradient conjugué de Newton). On
 381     conseille de conserver la valeur par défaut.
 382
 383   Bounds
 384     Cette clé permet de définir des bornes supérieure et inférieure pour
 385     chaque variable d'état optimisée. Les bornes peuvent être données par une
 386     liste de liste de paires de bornes inférieure/supérieure pour chaque
 387     variable, avec une valeur ``None`` chaque fois qu'il n'y a pas de borne. Les
 388     bornes peuvent toujours être spécifiées, mais seuls les optimiseurs sous
 389     contraintes les prennent en compte.
 390
 391   MaximumNumberOfSteps
 392     Cette clé indique le nombre maximum d'itérations possibles en optimisation
 393     itérative. Le défaut est 15000, qui est très similaire à une absence de
 394     limite sur les itérations. Il est ainsi recommandé d'adapter ce paramètre
 395     aux besoins pour des problèmes réels. Pour certains optimiseurs, le nombre
 396     de pas effectif d'arrêt peut être légèrement différent de la limite à cause
 397     d'exigences de contrôle interne de l'algorithme.
 398
 399   CostDecrementTolerance
 400     Cette clé indique une valeur limite, conduisant à arrêter le processus
 401     itératif d'optimisation lorsque la fonction coût décroît moins que cette
 402     tolérance au dernier pas. Le défaut est de 1.e-7, et il est recommandé
 403     de l'adapter aux besoins pour des problèmes réels.
 404
 405   ProjectedGradientTolerance
 406     Cette clé indique une valeur limite, conduisant à arrêter le processus
 407     itératif d'optimisation lorsque toutes les composantes du gradient projeté
 408     sont en-dessous de cette limite. C'est utilisé uniquement par les
 409     optimiseurs sous contraintes. Le défaut est -1, qui désigne le défaut
 410     interne de chaque optimiseur (usuellement 1.e-5), et il n'est pas recommandé
 411     de le changer.
 412
 413   GradientNormTolerance
 414     Cette clé indique une valeur limite, conduisant à arrêter le processus
 415     itératif d'optimisation lorsque la norme du gradient est en dessous de cette
 416     limite. C'est utilisé uniquement par les optimiseurs sans contraintes. Le
 417     défaut est 1.e-5 et il n'est pas recommandé de le changer.
 418
 419   StoreInternalVariables
 420     Cette clé booléenne permet de stocker les variables internes par défaut,
 421     principalement l'état courant lors d'un processus itératif. Attention, cela
 422     peut être un choix numériquement coûteux dans certains cas de calculs. La
 423     valeur par défaut est "False".
 424
 425   StoreSupplementaryCalculations
 426     Cette liste indique les noms des variables supplémentaires qui peuvent être
 427     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 428     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 429     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 430     dans la liste suivante : ["APosterioriCovariance", "BMA", "OMA", "OMB",
 431     "Innovation", "SigmaObs2", "MahalanobisConsistency"].
 432
 433 **"NonLinearLeastSquares"**
 434
 435   *Commandes obligatoires*
 436     *"Background",
 437     "Observation", "ObservationError",
 438     "ObservationOperator"*
 439
 440   Minimizer
 441     Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par
 442     défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non
 443     linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), "TNC"
 444     (minimisation non linéaire sous contraintes), "CG" (minimisation non
 445     linéaire sans contraintes), "BFGS" (minimisation non linéaire sans
 446     contraintes), "NCG" (minimisation de type gradient conjugué de Newton). On
 447     conseille de conserver la valeur par défaut.
 448
 449   Bounds
 450     Cette clé permet de définir des bornes supérieure et inférieure pour
 451     chaque variable d'état optimisée. Les bornes peuvent être données par une
 452     liste de liste de paires de bornes inférieure/supérieure pour chaque
 453     variable, avec une valeur ``None`` chaque fois qu'il n'y a pas de borne. Les
 454     bornes peuvent toujours être spécifiées, mais seuls les optimiseurs sous
 455     contraintes les prennent en compte.
 456
 457   MaximumNumberOfSteps
 458     Cette clé indique le nombre maximum d'itérations possibles en optimisation
 459     itérative. Le défaut est 15000, qui est très similaire à une absence de
 460     limite sur les itérations. Il est ainsi recommandé d'adapter ce paramètre
 461     aux besoins pour des problèmes réels. Pour certains optimiseurs, le nombre
 462     de pas effectif d'arrêt peut être légèrement différent de la limite à cause
 463     d'exigences de contrôle interne de l'algorithme.
 464
 465   CostDecrementTolerance
 466     Cette clé indique une valeur limite, conduisant à arrêter le processus
 467     itératif d'optimisation lorsque la fonction coût décroît moins que cette
 468     tolérance au dernier pas. Le défaut est de 1.e-7, et il est recommandé
 469     de l'adapter aux besoins pour des problèmes réels.
 470
 471   ProjectedGradientTolerance
 472     Cette clé indique une valeur limite, conduisant à arrêter le processus
 473     itératif d'optimisation lorsque toutes les composantes du gradient projeté
 474     sont en-dessous de cette limite. C'est utilisé uniquement par les
 475     optimiseurs sous contraintes. Le défaut est -1, qui désigne le défaut
 476     interne de chaque optimiseur (usuellement 1.e-5), et il n'est pas recommandé
 477     de le changer.
 478
 479   GradientNormTolerance
 480     Cette clé indique une valeur limite, conduisant à arrêter le processus
 481     itératif d'optimisation lorsque la norme du gradient est en dessous de cette
 482     limite. C'est utilisé uniquement par les optimiseurs sans contraintes. Le
 483     défaut est 1.e-5 et il n'est pas recommandé de le changer.
 484
 485   StoreInternalVariables
 486     Cette clé booléenne permet de stocker les variables internes par défaut,
 487     principalement l'état courant lors d'un processus itératif. Attention, cela
 488     peut être un choix numériquement coûteux dans certains cas de calculs. La
 489     valeur par défaut est "False".
 490
 491   StoreSupplementaryCalculations
 492     Cette liste indique les noms des variables supplémentaires qui peuvent être
 493     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 494     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 495     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 496     dans la liste suivante : ["APosterioriCovariance", "BMA", "OMA", "OMB",
 497     "Innovation", "SigmaObs2", "MahalanobisConsistency"].
 498
 499 **"EnsembleBlue"**
 500
 501   *Commandes obligatoires*
 502     *"Background", "BackgroundError",
 503     "Observation", "ObservationError",
 504     "ObservationOperator"*
 505
 506   SetSeed
 507     Cette clé permet de donner un nombre entier pour fixer la graine du
 508     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
 509     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
 510     utilise ainsi l'initialisation de l'ordinateur.
 511
 512 **"KalmanFilter"**
 513
 514   *Commandes obligatoires*
 515     *"Background", "BackgroundError",
 516     "Observation", "ObservationError",
 517     "ObservationOperator"*
 518
 519   EstimationOf
 520     Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
 521     soit une estimation de l'état, avec la valeur "State", ou une estimation de
 522     paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
 523
 524   StoreInternalVariables
 525     Cette clé booléenne permet de stocker les variables internes par défaut,
 526     principalement l'état courant lors d'un processus itératif. Attention, cela
 527     peut être un choix numériquement coûteux dans certains cas de calculs. La
 528     valeur par défaut est "False".
 529
 530   StoreSupplementaryCalculations
 531     Cette liste indique les noms des variables supplémentaires qui peuvent être
 532     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 533     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 534     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 535     dans la liste suivante : ["APosterioriCovariance", "BMA", "Innovation"].
 536
 537 **"ExtendedKalmanFilter"**
 538
 539   *Commandes obligatoires*
 540     *"Background", "BackgroundError",
 541     "Observation", "ObservationError",
 542     "ObservationOperator"*
 543
 544   Bounds
 545     Cette clé permet de définir des bornes supérieure et inférieure pour chaque
 546     variable d'état optimisée. Les bornes peuvent être données par une liste de
 547     liste de paires de bornes inférieure/supérieure pour chaque variable, avec
 548     une valeur extrême chaque fois qu'il n'y a pas de borne. Les bornes peuvent
 549     toujours être spécifiées, mais seuls les optimiseurs sous contraintes les
 550     prennent en compte.
 551
 552   ConstrainedBy
 553     Cette clé permet de définir la méthode pour prendre en compte les bornes. Les
 554     méthodes possibles sont dans la liste suivante : ["EstimateProjection"].
 555
 556   EstimationOf
 557     Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
 558     soit une estimation de l'état, avec la valeur "State", ou une estimation de
 559     paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
 560
 561   StoreInternalVariables
 562     Cette clé booléenne permet de stocker les variables internes par défaut,
 563     principalement l'état courant lors d'un processus itératif. Attention, cela
 564     peut être un choix numériquement coûteux dans certains cas de calculs. La
 565     valeur par défaut est "False".
 566
 567   StoreSupplementaryCalculations
 568     Cette liste indique les noms des variables supplémentaires qui peuvent être
 569     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 570     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 571     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 572     dans la liste suivante : ["APosterioriCovariance", "BMA", "Innovation"].
 573
 574 **"UnscentedKalmanFilter"**
 575
 576   *Commandes obligatoires*
 577     *"Background", "BackgroundError",
 578     "Observation", "ObservationError",
 579     "ObservationOperator"*
 580
 581   Bounds
 582     Cette clé permet de définir des bornes supérieure et inférieure pour chaque
 583     variable d'état optimisée. Les bornes peuvent être données par une liste de
 584     liste de paires de bornes inférieure/supérieure pour chaque variable, avec
 585     une valeur extrême chaque fois qu'il n'y a pas de borne. Les bornes peuvent
 586     toujours être spécifiées, mais seuls les optimiseurs sous contraintes les
 587     prennent en compte.
 588
 589   ConstrainedBy
 590     Cette clé permet de définir la méthode pour prendre en compte les bornes. Les
 591     méthodes possibles sont dans la liste suivante : ["EstimateProjection"].
 592
 593   EstimationOf
 594     Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
 595     soit une estimation de l'état, avec la valeur "State", ou une estimation de
 596     paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
 597
 598   Alpha, Beta, Kappa, Reconditioner
 599     Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert
 600     une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour
 601     une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière,
 602     dont la bonne valeur par défaut est obtenue en la mettant à 0.
 603     "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut
 604     étant 1.
 605
 606   StoreInternalVariables
 607     Cette clé booléenne permet de stocker les variables internes par défaut,
 608     principalement l'état courant lors d'un processus itératif. Attention, cela
 609     peut être un choix numériquement coûteux dans certains cas de calculs. La
 610     valeur par défaut est "False".
 611
 612   StoreSupplementaryCalculations
 613     Cette liste indique les noms des variables supplémentaires qui peuvent être
 614     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 615     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 616     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 617     dans la liste suivante : ["APosterioriCovariance", "BMA", "Innovation"].
 618
 619 **"ParticleSwarmOptimization"**
 620
 621   *Commandes obligatoires*
 622     *"Background", "BackgroundError",
 623     "Observation", "ObservationError",
 624     "ObservationOperator"*
 625
 626   MaximumNumberOfSteps
 627     Cette clé indique le nombre maximum d'itérations possibles en optimisation
 628     itérative. Le défaut est 50, qui est une limite arbitraire. Il est ainsi
 629     recommandé d'adapter ce paramètre aux besoins pour des problèmes réels.
 630
 631   NumberOfInsects
 632     Cette clé indique le nombre d'insectes ou de particules dans l'essaim. La
 633     valeur par défaut est 100, qui est une valeur par défaut usuelle pour cet
 634     algorithme.
 635
 636   SwarmVelocity
 637     Cette clé indique la part de la vitesse d'insecte qui est imposée par
 638     l'essaim. C'est une valeur réelle positive. Le défaut est de 1.
 639
 640   GroupRecallRate
 641     Cette clé indique le taux de rappel vers le meilleur insecte de l'essaim.
 642     C'est une valeur réelle comprise entre 0 et 1. Le défaut est de 0.5.
 643
 644   QualityCriterion
 645     Cette clé indique le critère de qualité, qui est minimisé pour trouver
 646     l'estimation optimale de l'état. Le défaut est le critère usuel de
 647     l'assimilation de données nommé "DA", qui est le critère de moindres carrés
 648     pondérés augmentés. Les critères possibles sont dans la liste suivante, dans
 649     laquelle les noms équivalents sont indiqués par "=" :
 650     ["AugmentedPonderatedLeastSquares"="APLS"="DA",
 651     "PonderatedLeastSquares"="PLS", "LeastSquares"="LS"="L2",
 652     "AbsoluteValue"="L1", "MaximumError"="ME"]
 653
 654   SetSeed
 655     Cette clé permet de donner un nombre entier pour fixer la graine du
 656     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
 657     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
 658     utilise ainsi l'initialisation par défaut de l'ordinateur.
 659
 660   StoreInternalVariables
 661     Cette clé booléenne permet de stocker les variables internes par défaut,
 662     principalement l'état courant lors d'un processus itératif. Attention, cela
 663     peut être un choix numériquement coûteux dans certains cas de calculs. La
 664     valeur par défaut est "False".
 665
 666   StoreSupplementaryCalculations
 667     Cette liste indique les noms des variables supplémentaires qui peuvent être
 668     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 669     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 670     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 671     dans la liste suivante : ["BMA", "OMA", "OMB", "Innovation"].
 672
 673 **"QuantileRegression"**
 674
 675   *Commandes obligatoires*
 676     *"Background",
 677     "Observation",
 678     "ObservationOperator"*
 679
 680   Quantile
 681     Cette clé permet de définir la valeur réelle du quantile recherché, entre 0
 682     et 1. La valeur par défaut est 0.5, correspondant à la médiane.
 683
 684   Minimizer
 685     Cette clé permet de choisir l'optimiseur pour l'optimisation. Le choix par
 686     défaut et le seul disponible est "MMQR" (Majorize-Minimize for Quantile
 687     Regression).
 688
 689   MaximumNumberOfSteps
 690     Cette clé indique le nombre maximum d'itérations possibles en optimisation
 691     itérative. Le défaut est 15000, qui est très similaire à une absence de
 692     limite sur les itérations. Il est ainsi recommandé d'adapter ce paramètre
 693     aux besoins pour des problèmes réels.
 694
 695   CostDecrementTolerance
 696     Cette clé indique une valeur limite, conduisant à arrêter le processus
 697     itératif d'optimisation lorsque la fonction coût décroît moins que cette
 698     tolérance au dernier pas. Le défaut est de 1.e-6, et il est recommandé de
 699     l'adapter aux besoins pour des problèmes réels.
 700
 701   StoreInternalVariables
 702     Cette clé booléenne permet de stocker les variables internes par défaut,
 703     principalement l'état courant lors d'un processus itératif. Attention, cela
 704     peut être un choix numériquement coûteux dans certains cas de calculs. La
 705     valeur par défaut est "False".
 706
 707   StoreSupplementaryCalculations
 708     Cette liste indique les noms des variables supplémentaires qui peuvent être
 709     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 710     calculs coûteux. La valeur par défaut est une liste vide, aucune de ces
 711     variables n'étant calculée et stockée par défaut. Les noms possibles sont
 712     dans la liste suivante : ["BMA", "OMA", "OMB", "Innovation"].
 713
 714 Description de référence pour les cas de vérification ADAO
 715 ----------------------------------------------------------
 716
 717 Liste des commandes et mots-clés pour un cas de vérification ADAO
 718 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 719
 720 .. index:: single: CHECKING_STUDY
 721 .. index:: single: Algorithm
 722 .. index:: single: AlgorithmParameters
 723 .. index:: single: CheckingPoint
 724 .. index:: single: Debug
 725 .. index:: single: ObservationOperator
 726 .. index:: single: Study_name
 727 .. index:: single: Study_repertory
 728 .. index:: single: UserDataInit
 729
 730 Le second jeu de commandes est liée à la description d'un cas de vérification,
 731 qui est une procédure pour vérifier les propriétés requises ailleurs sur
 732 l'information par un cas de calcul. Les termes sont classés par ordre
 733 alphabétique, sauf le premier, qui décrit le choix entre le calcul ou la
 734 vérification. Les différentes commandes sont les suivantes:
 735
 736 **CHECKING_STUDY**
 737     *Commande obligatoire*. C'est la commande générale qui décrit le cas de
 738     vérification. Elle contient hiérarchiquement toutes les autres commandes.
 739
 740 **Algorithm**
 741     *Commande obligatoire*. C'est une chaîne de caractère qui indique
 742     l'algorithme de test choisi. Les choix sont limités et disponibles à travers
 743     l'interface graphique. Il existe par exemple "FunctionTest",
 744     "AdjointTest"... Voir plus loin la liste des algorithmes et des paramètres
 745     associés dans la sous-section `Commandes optionnelles et requises pour les
 746     algorithmes de vérification`_.
 747
 748 **AlgorithmParameters**
 749     *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour
 750     contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa
 751     valeur est définie comme un objet de type "*Dict*". Voir plus loin la liste
 752     des algorithmes et des paramètres associés dans la sous-section `Commandes
 753     optionnelles et requises pour les algorithmes de vérification`_.
 754
 755 **CheckingPoint**
 756     *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour
 757     duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à
 758     l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type
 759     "*Vector*".
 760
 761 **Debug**
 762     *Commande optionnelle*. Elle définit le niveau de sorties et d'informations
 763     intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et
 764     1 (pour True).
 765
 766 **ObservationOperator**
 767     *Commande obligatoire*. Elle indique l'opérateur d'observation, notée
 768     précédemment :math:`H`, qui transforme les paramètres d'entrée
 769     :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux
 770     observations :math:`\mathbf{y}^o`.  Sa valeur est définie comme un objet de
 771     type "*Function*". Différentes formes fonctionnelles peuvent être utilisées,
 772     comme décrit dans la sous-section suivante `Exigences pour les fonctions
 773     décrivant un opérateur`_. Si un contrôle :math:`U` est inclus dans le modèle
 774     d'observation, l'opérateur doit être appliqué à une paire :math:`(X,U)`.
 775
 776 **Observers**
 777     *Commande optionnelle*. Elle permet de définir des observateurs internes,
 778     qui sont des fonctions liées à une variable particulière, qui sont exécutées
 779     chaque fois que cette variable est modifiée. C'est une manière pratique de
 780     suivre des variables d'intérêt durant le processus d'assimilation de données
 781     ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples
 782     courants (squelettes) sont fournis pour aider l'utilisateur ou pour
 783     faciliter l'élaboration d'un cas.
 784
 785 **Study_name**
 786     *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
 787     décrire l'étude ADAO par un nom ou une déclaration.
 788
 789 **Study_repertory**
 790     *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
 791     pour les calculs, et il est utilisé pour trouver les fichiers de script,
 792     donnés par nom sans répertoire, qui peuvent être utilisés pour définir
 793     certaines variables.
 794
 795 **UserDataInit**
 796     *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
 797     certaines données automatiquement avant le traitement de données d'entrée
 798     pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
 799     nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
 800     variables choisies.
 801
 802 Commandes optionnelles et requises pour les algorithmes de vérification
 803 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 804
 805 .. index:: single: AdjointTest
 806 .. index:: single: FunctionTest
 807 .. index:: single: GradientTest
 808 .. index:: single: LinearityTest
 809 .. index:: single: ObserverTest
 810 .. index:: single: TangentTest
 811
 812 .. index:: single: AlgorithmParameters
 813 .. index:: single: AmplitudeOfInitialDirection
 814 .. index:: single: EpsilonMinimumExponent
 815 .. index:: single: InitialDirection
 816 .. index:: single: ResiduFormula
 817 .. index:: single: SetSeed
 818
 819 On rappelle que chaque algorithme peut être contrôlé en utilisant des options
 820 génériques ou particulières, données à travers la commande optionnelle
 821 "*AlgorithmParameters*", à la manière de l'exemple qui suit dans un fichier::
 822
 823     AlgorithmParameters = {
 824         "AmplitudeOfInitialDirection" : 1,
 825         "EpsilonMinimumExponent" : -8,
 826         }
 827
 828 Si une option est spécifiée par l'utilisateur pour un algorithme qui ne la
 829 supporte pas, cette option est simplement laissée inutilisée et ne bloque pas le
 830 traitement. La signification des acronymes ou des noms particuliers peut être
 831 trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`. De plus, pour
 832 chaque algorithme, les commandes/mots-clés sont donnés, décrits dans `Liste des
 833 commandes et mots-clés pour un cas de vérification ADAO`_.
 834
 835 **"AdjointTest"**
 836
 837   *Commandes obligatoires*
 838     *"CheckingPoint",
 839     "ObservationOperator"*
 840
 841   AmplitudeOfInitialDirection
 842     Cette clé indique la mise à l'échelle de la perturbation initiale construite
 843     comme un vecteur utilisé pour la dérivée directionnelle autour du point
 844     nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
 845     de mise à l'échelle.
 846
 847   EpsilonMinimumExponent
 848     Cette clé indique la valeur de l'exposant minimal du coefficient en
 849     puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
 850     de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
 851     -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
 852     formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
 853
 854   InitialDirection
 855     Cette clé indique la direction vectorielle utilisée pour la dérivée
 856     directionnelle autour du point nominal de vérification. Cela doit être un
 857     vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
 858     perturbation par défaut autour de zéro de la même taille vectorielle que le
 859     point de vérification.
 860
 861   SetSeed
 862     Cette clé permet de donner un nombre entier pour fixer la graine du
 863     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
 864     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
 865     utilise ainsi l'initialisation par défaut de l'ordinateur.
 866
 867 **"FunctionTest"**
 868
 869   *Commandes obligatoires*
 870     *"CheckingPoint",
 871     "ObservationOperator"*
 872
 873   NumberOfPrintedDigits
 874     Cette clé indique le nombre de décimales de précision pour les affichages de
 875     valeurs réelles. La valeur par défaut est de 5, avec un minimum de 0.
 876
 877   NumberOfRepetition
 878     Cette clé indique le nombre de fois où répéter l'évaluation de la fonction.
 879     La valeur vaut 1.
 880
 881   SetDebug
 882     Cette clé requiert l'activation, ou pas, du mode de débogage durant
 883     l'évaluation de la fonction. La valeur par défaut est "True", les choix sont
 884     "True" ou "False".
 885
 886 **"GradientTest"**
 887
 888   *Commandes obligatoires*
 889     *"CheckingPoint",
 890     "ObservationOperator"*
 891
 892   AmplitudeOfInitialDirection
 893     Cette clé indique la mise à l'échelle de la perturbation initiale construite
 894     comme un vecteur utilisé pour la dérivée directionnelle autour du point
 895     nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
 896     de mise à l'échelle.
 897
 898   EpsilonMinimumExponent
 899     Cette clé indique la valeur de l'exposant minimal du coefficient en
 900     puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
 901     de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
 902     -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
 903     formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
 904
 905   InitialDirection
 906     Cette clé indique la direction vectorielle utilisée pour la dérivée
 907     directionnelle autour du point nominal de vérification. Cela doit être un
 908     vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
 909     perturbation par défaut autour de zéro de la même taille vectorielle que le
 910     point de vérification.
 911
 912   ResiduFormula
 913     Cette clé indique la formule de résidu qui doit être utilisée pour le test.
 914     Le choix par défaut est "Taylor", et les choix possibles sont "Taylor"
 915     (résidu du développement de Taylor de l'opérateur, qui doit décroître comme
 916     le carré de la perturbation) et "Norm" (résidu obtenu en prenant la norme du
 917     développement de Taylor à l'ordre 0, qui approxime le gradient, et qui doit
 918     rester constant).
 919
 920   SetSeed
 921     Cette clé permet de donner un nombre entier pour fixer la graine du
 922     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
 923     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
 924     utilise ainsi l'initialisation par défaut de l'ordinateur.
 925
 926 **"LinearityTest"**
 927
 928   *Commandes obligatoires*
 929     *"CheckingPoint",
 930     "ObservationOperator"*
 931
 932   AmplitudeOfInitialDirection
 933     Cette clé indique la mise à l'échelle de la perturbation initiale construite
 934     comme un vecteur utilisé pour la dérivée directionnelle autour du point
 935     nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
 936     de mise à l'échelle.
 937
 938   EpsilonMinimumExponent
 939     Cette clé indique la valeur de l'exposant minimal du coefficient en
 940     puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
 941     de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
 942     -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
 943     formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
 944
 945   InitialDirection
 946     Cette clé indique la direction vectorielle utilisée pour la dérivée
 947     directionnelle autour du point nominal de vérification. Cela doit être un
 948     vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
 949     perturbation par défaut autour de zero de la même taille vectorielle que le
 950     point de vérification.
 951
 952   ResiduFormula
 953     Cette clé indique la formule de résidu qui doit être utilisée pour le test.
 954     Le choix par défaut est "CenteredDL", et les choix possibles sont
 955     "CenteredDL" (résidu de la différence entre la fonction au point nominal et
 956     ses valeurs avec des incréments positif et négatif, qui doit rester très
 957     faible), "Taylor" (résidu du développement de Taylor de l'opérateur
 958     normalisé par sa valeur nominal, qui doit rester très faible),
 959     "NominalTaylor" (résidu de l'approximation à l'ordre 1 de l'opérateur,
 960     normalisé au point nominal, qui doit rester proche de 1), et
 961     "NominalTaylorRMS" (résidu de l'approximation à l'ordre 1 de l'opérateur,
 962     normalisé par l'écart quadratique moyen (RMS) au point nominal, qui doit
 963     rester proche de 0).
 964
 965   SetSeed
 966     Cette clé permet de donner un nombre entier pour fixer la graine du
 967     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
 968     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
 969     utilise ainsi l'initialisation par défaut de l'ordinateur.
 970
 971 **"ObserverTest"**
 972
 973   *Commandes obligatoires*
 974     *"Observers"*
 975
 976   *Astuce pour cette commande :*
 977     Comme les commandes *"CheckingPoint"* et *"ObservationOperator"* sont
 978     requises pour TOUS les algorithmes de vérification dans l'interface, vous
 979     devez fournir une valeur, malgré le fait que ces commandes ne sont pas
 980     requises pour *"ObserverTest"*, et ne seront pas utilisées. La manière la
 981     plus simple est de donner "1" comme un STRING pour les deux,
 982     l'*"ObservationOperator"* devant être de type *Matrix*.
 983
 984 **"TangentTest"**
 985
 986   *Commandes obligatoires*
 987     *"CheckingPoint",
 988     "ObservationOperator"*
 989
 990   AmplitudeOfInitialDirection
 991     Cette clé indique la mise à l'échelle de la perturbation initiale construite
 992     comme un vecteur utilisé pour la dérivée directionnelle autour du point
 993     nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
 994     de mise à l'échelle.
 995
 996   EpsilonMinimumExponent
 997     Cette clé indique la valeur de l'exposant minimal du coefficient en
 998     puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
 999     de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
1000     -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
1001     formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
1002
1003   InitialDirection
1004     Cette clé indique la direction vectorielle utilisée pour la dérivée
1005     directionnelle autour du point nominal de vérification. Cela doit être un
1006     vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
1007     perturbation par défaut autour de zero de la même taille vectorielle que le
1008     point de vérification.
1009
1010   SetSeed
1011     Cette clé permet de donner un nombre entier pour fixer la graine du
1012     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
1013     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
1014     utilise ainsi l'initialisation par défaut de l'ordinateur.
1015
1016 Exigences pour les fonctions décrivant un opérateur
1017 ---------------------------------------------------
1018
1019 Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en
1020 oeuvre les procédures d'assimilation de données ou d'optimisation. Ils
1021 comprennent la simulation physique par des calculs numériques, mais aussi le
1022 filtrage et de restriction pour comparer la simulation à l'observation.
1023 L'opérateur d'évolution est ici considéré dans sa forme incrémentale, qui
1024 représente la transition entre deux états successifs, et il est alors similaire
1025 à l'opérateur d'observation.
1026
1027 Schématiquement, un opérateur doit donner une solution étant donné les
1028 paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au
1029 cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un
1030 tel processus est une fonction. Il a été brièvement décrit dans la section
1031 :ref:`section_theory` et il est généralisée ici par la relation:
1032
1033 .. math:: \mathbf{y} = O( \mathbf{x} )
1034
1035 entre les pseudo-observations :math:`\mathbf{y}` et les paramètres
1036 :math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution
1037 :math:`O`. La même représentation fonctionnelle peut être utilisée pour le
1038 modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint
1039 :math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes
1040 d'assimilation de données ou d'optimisation.
1041
1042 En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et
1043 :math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et
1044 ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur
1045 Numpy) ou orientés (de type matrice Numpy).
1046
1047 Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à
1048 fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière
1049 complète**.
1050
1051 Cette fonction est généralement donnée comme un script qui peut être exécuté
1052 dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes
1053 externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme
1054 nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme
1055 adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer.
1056
1057 Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation
1058 fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*"
1059 de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le
1060 montre la figure suivante:
1061
1062   .. eficas_operator_function:
1063   .. image:: images/eficas_operator_function.png
1064     :align: center
1065     :width: 100%
1066   .. centered::
1067     **Choisir une représentation fonctionnelle de l'opérateur**
1068
1069 Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*"
1070 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1071
1072 .. index:: single: ScriptWithOneFunction
1073 .. index:: single: DirectOperator
1074 .. index:: single: DifferentialIncrement
1075 .. index:: single: CenteredFiniteDifference
1076
1077 La première consiste à ne fournir qu'une seule fonction potentiellement non
1078 linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en
1079 utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de
1080 l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir
1081 la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par
1082 exemple, le script peut suivre le modèle suivant::
1083
1084     def DirectOperator( X ):
1085         """ Opérateur direct de simulation non-linéaire """
1086         ...
1087         ...
1088         ...
1089         return Y=O(X)
1090
1091 Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément
1092 différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface
1093 graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par
1094 défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies
1095 pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation
1096 différences finies peut aussi être choisi à travers l'interface, en utilisant le
1097 mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du
1098 premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du
1099 second ordre (qui coûte numériquement deux fois plus cher que le premier ordre).
1100
1101 Cette première forme de définition de l'opérateur permet aisément de tester la
1102 forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la
1103 complexité de l'implémentation de l'opérateur.
1104
1105 **Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le
1106 type de l'argument X peut être une liste, un vecteur ou une matrice Numpy.
1107 L'utilisateur doit traiter ces cas dans sa fonction.
1108
1109 Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*"
1110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1111
1112 .. index:: single: ScriptWithFunctions
1113 .. index:: single: DirectOperator
1114 .. index:: single: TangentOperator
1115 .. index:: single: AdjointOperator
1116
1117 **En général, il est recommandé d'utiliser la première forme fonctionnelle
1118 plutôt que la seconde. Un petit accroissement de performances n'est pas une
1119 bonne raison pour utiliser l'implémentation détaillée de cette seconde forme
1120 fonctionnelle.**
1121
1122 La seconde consiste à fournir directement les trois opérateurs liés :math:`O`,
1123 :math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le
1124 mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans
1125 l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions
1126 dans un script, avec trois noms obligatoires "*DirectOperator*",
1127 "*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre
1128 le squelette suivant::
1129
1130     def DirectOperator( X ):
1131         """ Opérateur direct de simulation non-linéaire """
1132         ...
1133         ...
1134         ...
1135         return quelque chose comme Y
1136
1137     def TangentOperator( (X, dX) ):
1138         """ Opérateur linéaire tangent, autour de X, appliqué à dX """
1139         ...
1140         ...
1141         ...
1142         return quelque chose comme Y
1143
1144     def AdjointOperator( (X, Y) ):
1145         """ Opérateur adjoint, autour de X, appliqué à Y """
1146         ...
1147         ...
1148         ...
1149         return quelque chose comme X
1150
1151 Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tester
1152 les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la
1153 complexité de l'implémentation de l'opérateur.
1154
1155 Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse
1156 renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque,
1157 respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur
1158 doit renvoyer la matrice associée.
1159
1160 **Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*"
1161 et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``,
1162 ``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy.
1163 L'utilisateur doit traiter ces cas dans ses fonctions.
1164
1165 Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*"
1166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1167
1168 .. index:: single: ScriptWithSwitch
1169 .. index:: single: DirectOperator
1170 .. index:: single: TangentOperator
1171 .. index:: single: AdjointOperator
1172
1173 **Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans
1174 une solide raison numérique ou physique. Un accroissement de performances n'est
1175 pas une bonne raison pour utiliser la complexité de cette troisième forme
1176 fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes
1177 justifie l'usage de la troisième.**
1178
1179 La troisième forme donne de plus grandes possibilités de contrôle de l'exécution
1180 des trois fonctions représentant l'opérateur, permettant un usage et un contrôle
1181 avancés sur chaque exécution du code de simulation. C'est réalisable en
1182 utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à
1183 travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script
1184 unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente
1185 et adjointe du code de simulation. L'utilisateur peut alors, par exemple,
1186 utiliser des approximations pour les codes tangent et adjoint, ou introduire une
1187 plus grande complexité du traitement des arguments des fonctions. Mais cette
1188 démarche sera plus difficile à implémenter et à déboguer.
1189
1190 Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se
1191 baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier
1192 script ou un code externe nommé ici "*Physical_simulation_functions.py*",
1193 contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" and
1194 "*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage::
1195
1196     import Physical_simulation_functions
1197     import numpy, logging
1198     #
1199     method = ""
1200     for param in computation["specificParameters"]:
1201         if param["name"] == "method":
1202             method = param["value"]
1203     if method not in ["Direct", "Tangent", "Adjoint"]:
1204         raise ValueError("No valid computation method is given")
1205     logging.info("Found method is \'%s\'"%method)
1206     #
1207     logging.info("Loading operator functions")
1208     Function = Physical_simulation_functions.DirectOperator
1209     Tangent  = Physical_simulation_functions.TangentOperator
1210     Adjoint  = Physical_simulation_functions.AdjointOperator
1211     #
1212     logging.info("Executing the possible computations")
1213     data = []
1214     if method == "Direct":
1215         logging.info("Direct computation")
1216         Xcurrent = computation["inputValues"][0][0][0]
1217         data = Function(numpy.matrix( Xcurrent ).T)
1218     if method == "Tangent":
1219         logging.info("Tangent computation")
1220         Xcurrent  = computation["inputValues"][0][0][0]
1221         dXcurrent = computation["inputValues"][0][0][1]
1222         data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
1223     if method == "Adjoint":
1224         logging.info("Adjoint computation")
1225         Xcurrent = computation["inputValues"][0][0][0]
1226         Ycurrent = computation["inputValues"][0][0][1]
1227         data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
1228     #
1229     logging.info("Formatting the output")
1230     it = numpy.ravel(data)
1231     outputValues = [[[[]]]]
1232     for val in it:
1233       outputValues[0][0][0].append(val)
1234     #
1235     result = {}
1236     result["outputValues"]        = outputValues
1237     result["specificOutputInfos"] = []
1238     result["returnCode"]          = 0
1239     result["errorMessage"]        = ""
1240
1241 Toutes les modifications envisageables peuvent être faites à partir de cette
1242 hypothèse de squelette.
1243
1244 Cas spécial d'un opérateur d'évolution avec contrôle
1245 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1246
1247 Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé
1248 par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la
1249 forme générique du modèle incrémental est légèrement modifié comme suit:
1250
1251 .. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
1252
1253 où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. Dans ce cas,
1254 l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`.
1255 Schématiquement, l'opérateur doit être constuit comme suit::
1256
1257     def DirectOperator( (X, U) ):
1258         """ Opérateur direct de simulation non-linéaire """
1259         ...
1260         ...
1261         ...
1262         return quelque chose comme X(n+1) (évolution) ou Y(n+1) (observation)
1263
1264 Les opérateurs tangent et adjoint ont la même signature que précédemment, en
1265 notant que les dérivées doivent être faites seulement partiellement par rapport
1266 à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième
1267 forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme
1268 fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées.
1269
1270 Exigences pour décrire les matrices de covariance
1271 -------------------------------------------------
1272
1273 De multiples matrices de covariance sont nécessaires pour mettre en oeuvre des
1274 procédures d'assimilation de données ou d'optimisation. Les principales sont la
1275 matrice de covariance des erreurs d'ébauche, notée :math:`\mathbf{B}`, et la
1276 matrice de covariance des erreurs d'observation, notée :math:`\mathbf{R}`. Une
1277 telle matrice doit être une matrice carré symétrique semi-définie positive.
1278
1279 Il y a 3 méthodes pratiques pour l'utilisateur pour fournir une matrice de
1280 covariance. Ces méthodes sont choisies à l'aide du mot-clé "*INPUT_TYPE*" de
1281 chaque matrice de covariance, comme montré dans la figure qui suit :
1282
1283   .. eficas_covariance_matrix:
1284   .. image:: images/eficas_covariance_matrix.png
1285     :align: center
1286     :width: 100%
1287   .. centered::
1288     **Choisir la représentation d'une matrice de covariance**
1289
1290 Première forme matricielle : utiliser la représentation "*Matrix*"
1291 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1292
1293 .. index:: single: Matrix
1294 .. index:: single: BackgroundError
1295 .. index:: single: EvolutionError
1296 .. index:: single: ObservationError
1297
1298 La première forme est le défaut et la plus générale. La matrice de covariance
1299 :math:`\mathbf{M}` doit être entièrement spécifiée. Même si la matrice est
1300 symétrique par nature, la totalité de la matrice :math:`\mathbf{M}` doit être
1301 donnée.
1302
1303 .. math:: \mathbf{M} =  \begin{pmatrix}
1304     m_{11} & m_{12} & \cdots   & m_{1n} \\
1305     m_{21} & m_{22} & \cdots   & m_{2n} \\
1306     \vdots & \vdots & \vdots   & \vdots \\
1307     m_{n1} & \cdots & m_{nn-1} & m_{nn}
1308     \end{pmatrix}
1309
1310
1311 Cela peut être réalisé soit par un vecteur ou une matrice Numpy, soit par une
1312 liste de listes de valeurs (c'est-à-dire une liste de lignes). Par exemple, une
1313 matrice simple diagonale unitaire de covariances des erreurs d'ébauche
1314 :math:`\mathbf{B}` peut être décrite dans un fichier de script Python par::
1315
1316     BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
1317
1318 ou::
1319
1320     BackgroundError = numpy.eye(...)
1321
1322 Seconde forme matricielle : utiliser la représentation "*ScalarSparseMatrix*"
1323 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1324
1325 .. index:: single: ScalarSparseMatrix
1326 .. index:: single: BackgroundError
1327 .. index:: single: EvolutionError
1328 .. index:: single: ObservationError
1329
1330 Au contraire, la seconde forme matricielle est une méthode très simplifiée pour
1331 définir une matrice. La matrice de covariance :math:`\mathbf{M}` est supposée
1332 être un multiple positif de la matrice identité. Cette matrice peut alors être
1333 spécifiée de manière unique par le multiplicateur :math:`m`:
1334
1335 .. math:: \mathbf{M} =  m \times \begin{pmatrix}
1336     1       & 0      & \cdots   & 0      \\
1337     0       & 1      & \cdots   & 0      \\
1338     \vdots  & \vdots & \vdots   & \vdots \\
1339     0       & \cdots & 0        & 1
1340     \end{pmatrix}
1341
1342 Le multiplicateur :math:`m` doit être un nombre réel ou entier positif (s'il
1343 est négatif, ce qui est impossible car une matrice de covariance est positive,
1344 il est convertit en nombre positif). Par exemple, une simple matrice diagonale
1345 unitaire de covariances des erreurs d'ébauche :math:`\mathbf{B}` peut être
1346 décrite dans un fichier de script Python par::
1347
1348     BackgroundError = 1.
1349
1350 ou, mieux, par un "*String*" directement dans le cas ADAO.
1351
1352 Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*"
1353 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1354
1355 .. index:: single: DiagonalSparseMatrix
1356 .. index:: single: BackgroundError
1357 .. index:: single: EvolutionError
1358 .. index:: single: ObservationError
1359
1360 La troisième forme est aussi une méthode simplifiée pour fournir la matrice,
1361 mais un peu plus puissante que la seconde. La matrice de covariance
1362 :math:`\mathbf{M}` est toujours considérée comme diagonale, mais l'utilisateur
1363 doit spécifier toutes les valeurs positives situées sur la diagonale. La matrice
1364 peut alors être définie uniquement par un vecteur :math:`\mathbf{V}` qui se
1365 retrouve ensuite sur la diagonale:
1366
1367 .. math:: \mathbf{M} =  \begin{pmatrix}
1368     v_{1}  & 0      & \cdots   & 0      \\
1369     0      & v_{2}  & \cdots   & 0      \\
1370     \vdots & \vdots & \vdots   & \vdots \\
1371     0      & \cdots & 0        & v_{n}
1372     \end{pmatrix}
1373
1374 Cela peut être réalisé soit par vecteur ou une matrice Numpy, soit par
1375 une liste, soit par une liste de listes de valeurs positives (dans tous les cas,
1376 si certaines valeurs sont négatives, elles sont converties en valeurs
1377 positives). Par exemple, un matrice simple diagonale unitaire des covariances
1378 des erreurs d'ébauche :math:`\mathbf{B}` peut être décrite dans un fichier de
1379 script Python par::
1380
1381     BackgroundError = [1, 1 ... 1]
1382
1383 ou::
1384
1385     BackgroundError = numpy.ones(...)