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