doc/en/reference.rst

   1 .. _section_reference:
   2
   3 ================================================================================
   4 Reference description of the ADAO commands and keywords
   5 ================================================================================
   6
   7 This section presents the reference description of the ADAO commands and
   8 keywords available through the GUI or through scripts.
   9
  10 Each command or keyword to be defined through the ADAO GUI has some properties.
  11 The first property is to be *required*, *optional* or only factual, describing a
  12 type of input. The second property is to be an "open" variable with a fixed type
  13 but with any value allowed by the type, or a "restricted" variable, limited to
  14 some specified values. The EFICAS editor GUI having build-in validating
  15 capacities, the properties of the commands or keywords given through this GUI
  16 are automatically correct.
  17
  18 The mathematical notations used afterward are explained in the section
  19 :ref:`section_theory`.
  20
  21 Examples of using these commands are available in the section
  22 :ref:`section_examples` and in example files installed with ADAO module.
  23
  24 List of possible input types
  25 ----------------------------
  26
  27 .. index:: single: Dict
  28 .. index:: single: Function
  29 .. index:: single: Matrix
  30 .. index:: single: ScalarSparseMatrix
  31 .. index:: single: DiagonalSparseMatrix
  32 .. index:: single: String
  33 .. index:: single: Script
  34 .. index:: single: Vector
  35
  36 Each ADAO variable has a pseudo-type to help filling it and validation. The
  37 different pseudo-types are:
  38
  39 **Dict**
  40     This indicates a variable that has to be filled by a Python dictionary
  41     ``{"key":"value...}``, usually given either as a string or as a script file.
  42
  43 **Function**
  44     This indicates a variable that has to be filled by a Python function,
  45     usually given as a script file or a component method.
  46
  47 **Matrix**
  48     This indicates a variable that has to be filled by a matrix, usually given
  49     either as a string or as a script file.
  50
  51 **ScalarSparseMatrix**
  52     This indicates a variable that has to be filled by a unique number (which
  53     will be used to multiply an identity matrix), usually given either as a
  54     string or as a script file.
  55
  56 **DiagonalSparseMatrix**
  57     This indicates a variable that has to be filled by a vector (which will be
  58     used to replace the diagonal of an identity matrix), usually given either as
  59     a string or as a script file.
  60
  61 **Script**
  62     This indicates a script given as an external file. It can be described by a
  63     full absolute path name or only by the file name without path. If the file
  64     is given only by a file name without path, and if a study directory is also
  65     indicated, the file is searched in the given directory.
  66
  67 **String**
  68     This indicates a string giving a literal representation of a matrix, a
  69     vector or a vector serie, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a
  70     square 2x2 matrix.
  71
  72 **Vector**
  73     This indicates a variable that has to be filled by a vector, usually given
  74     either as a string or as a script file.
  75
  76 **VectorSerie**
  77     This indicates a variable that has to be filled by a list of
  78     vectors, usually given either as a string or as a script file.
  79
  80 When a command or keyword can be filled by a script file name, the script has to
  81 contain a variable or a method that has the same name as the one to be filled.
  82 In other words, when importing the script in a YACS Python node, it must create
  83 a variable of the good name in the current namespace of the node.
  84
  85 Reference description for ADAO calculation cases
  86 ------------------------------------------------
  87
  88 List of commands and keywords for an ADAO calculation case
  89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  90
  91 .. index:: single: ASSIMILATION_STUDY
  92 .. index:: single: Algorithm
  93 .. index:: single: AlgorithmParameters
  94 .. index:: single: Background
  95 .. index:: single: BackgroundError
  96 .. index:: single: ControlInput
  97 .. index:: single: Debug
  98 .. index:: single: EvolutionError
  99 .. index:: single: EvolutionModel
 100 .. index:: single: InputVariables
 101 .. index:: single: Observation
 102 .. index:: single: ObservationError
 103 .. index:: single: ObservationOperator
 104 .. index:: single: Observers
 105 .. index:: single: OutputVariables
 106 .. index:: single: Study_name
 107 .. index:: single: Study_repertory
 108 .. index:: single: UserDataInit
 109 .. index:: single: UserPostAnalysis
 110
 111 The first set of commands is related to the description of a calculation case,
 112 that is a *Data Assimilation* procedure or an *Optimization* procedure. The
 113 terms are ordered in alphabetical order, except the first, which describes
 114 choice between calculation or checking. The different commands are the
 115 following:
 116
 117 **ASSIMILATION_STUDY**
 118     *Required command*. This is the general command describing the data
 119     assimilation or optimization case. It hierarchically contains all the other
 120     commands.
 121
 122 **Algorithm**
 123     *Required command*. This is a string to indicate the data assimilation or
 124     optimization algorithm chosen. The choices are limited and available through
 125     the GUI. There exists for example "3DVAR", "Blue"... See below the list of
 126     algorithms and associated parameters in the following subsection `Optional
 127     and required commands for calculation algorithms`_.
 128
 129 **AlgorithmParameters**
 130     *Optional command*. This command allows to add some optional parameters to
 131     control the data assimilation or optimization algorithm. Its value is
 132     defined as a "*Dict*" type object. See below the list of algorithms and
 133     associated parameters in the following subsection `Optional and required
 134     commands for calculation algorithms`_.
 135
 136 **Background**
 137     *Required command*. This indicates the background or initial vector used,
 138     previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
 139     "*Vector*" type object.
 140
 141 **BackgroundError**
 142     *Required command*. This indicates the background error covariance matrix,
 143     previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
 144     type object, a "*ScalarSparseMatrix*" type object, or a
 145     "*DiagonalSparseMatrix*" type object.
 146
 147 **ControlInput**
 148     *Optional command*. This indicates the control vector used to force the
 149     evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value
 150     is defined as a "*Vector*" or a *VectorSerie* type object. When there is no
 151     control, it has to be a void string ''.
 152
 153 **Debug**
 154     *Optional command*. This define the level of trace and intermediary debug
 155     information. The choices are limited between 0 (for False) and 1 (for
 156     True).
 157
 158 **EvolutionError**
 159     *Optional command*. This indicates the evolution error covariance matrix,
 160     usually noted as :math:`\mathbf{Q}`. It is defined as a "*Matrix*" type
 161     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
 162     type object.
 163
 164 **EvolutionModel**
 165     *Optional command*. This indicates the evolution model operator, usually
 166     noted :math:`M`, which describes an elementary step of evolution. Its value
 167     is defined as a "*Function*" type object. Different functional forms can be
 168     used, as described in the following subsection `Requirements for functions
 169     describing an operator`_. If there is some control :math:`U` included in the
 170     evolution model, the operator has to be applied to a pair :math:`(X,U)`.
 171
 172 **InputVariables**
 173     *Optional command*. This command allows to indicates the name and size of
 174     physical variables that are bundled together in the state vector. This
 175     information is dedicated to data processed inside an algorithm.
 176
 177 **Observation**
 178     *Required command*. This indicates the observation vector used for data
 179     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
 180     is defined as a "*Vector*" or a *VectorSerie* type object.
 181
 182 **ObservationError**
 183     *Required command*. This indicates the observation error covariance matrix,
 184     previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
 185     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
 186     type object.
 187
 188 **ObservationOperator**
 189     *Required command*. This indicates the observation operator, previously
 190     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
 191     results :math:`\mathbf{y}` to be compared to observations
 192     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object.
 193     Different functional forms can be used, as described in the following
 194     subsection `Requirements for functions describing an operator`_. If there is
 195     some control :math:`U` included in the observation, the operator has to be
 196     applied to a pair :math:`(X,U)`.
 197
 198 **Observers**
 199     *Optional command*. This command allows to set internal observers, that are
 200     functions linked with a particular variable, which will be executed each
 201     time this variable is modified. It is a convenient way to monitor variables
 202     of interest during the data assimilation or optimization process, by
 203     printing or plotting it, etc. Common templates are provided to help the user
 204     to start or to quickly make his case.
 205
 206 **OutputVariables**
 207     *Optional command*. This command allows to indicates the name and size of
 208     physical variables that are bundled together in the output observation
 209     vector. This information is dedicated to data processed inside an algorithm.
 210
 211 **Study_name**
 212     *Required command*. This is an open string to describe the ADAO study by a
 213     name or a sentence.
 214
 215 **Study_repertory**
 216     *Optional command*. If available, this directory is used as base name for
 217     calculation, and used to find all the script files, given by name without
 218     path, that can be used to define some other commands by scripts.
 219
 220 **UserDataInit**
 221     *Optional command*. This commands allows to initialize some parameters or
 222     data automatically before data assimilation or optimisation algorithm input
 223     processing. It indicates a script file name to be executed before entering
 224     in initialization phase of chosen variables.
 225
 226 **UserPostAnalysis**
 227     *Optional command*. This commands allows to process some parameters or data
 228     automatically after data assimilation or optimization algorithm processing.
 229     Its value is defined as a script file or a string, allowing to put
 230     post-processing code directly inside the ADAO case. Common templates are
 231     provided to help the user to start or to quickly make his case.
 232
 233 Optional and required commands for calculation algorithms
 234 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 235
 236 .. index:: single: 3DVAR
 237 .. index:: single: Blue
 238 .. index:: single: ExtendedBlue
 239 .. index:: single: EnsembleBlue
 240 .. index:: single: KalmanFilter
 241 .. index:: single: ExtendedKalmanFilter
 242 .. index:: single: UnscentedKalmanFilter
 243 .. index:: single: LinearLeastSquares
 244 .. index:: single: NonLinearLeastSquares
 245 .. index:: single: ParticleSwarmOptimization
 246 .. index:: single: QuantileRegression
 247
 248 .. index:: single: AlgorithmParameters
 249 .. index:: single: Bounds
 250 .. index:: single: CostDecrementTolerance
 251 .. index:: single: GradientNormTolerance
 252 .. index:: single: GroupRecallRate
 253 .. index:: single: MaximumNumberOfSteps
 254 .. index:: single: Minimizer
 255 .. index:: single: NumberOfInsects
 256 .. index:: single: ProjectedGradientTolerance
 257 .. index:: single: QualityCriterion
 258 .. index:: single: Quantile
 259 .. index:: single: SetSeed
 260 .. index:: single: StoreInternalVariables
 261 .. index:: single: StoreSupplementaryCalculations
 262 .. index:: single: SwarmVelocity
 263
 264 Each algorithm can be controlled using some generic or specific options, given
 265 through the "*AlgorithmParameters*" optional command in a script file or a
 266 sring, as follows for example in a file::
 267
 268     AlgorithmParameters = {
 269         "Minimizer" : "LBFGSB",
 270         "MaximumNumberOfSteps" : 25,
 271         "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
 272         }
 273
 274 To give the "*AlgorithmParameters*" values by string, one must enclose a
 275 standard dictionnary definition between simple quotes, as for example::
 276
 277     '{"Minimizer":"LBFGSB","MaximumNumberOfSteps":25}'
 278
 279 This section describes the available options algorithm by algorithm. In
 280 addition, for each algorithm, the required commands/keywords are given, being
 281 described in `List of commands and keywords for an ADAO calculation case`_. If
 282 an option is specified by the user for an algorithm that doesn't support it, the
 283 option is simply left unused and don't stop the treatment. The meaning of the
 284 acronyms or particular names can be found in the :ref:`genindex` or the
 285 :ref:`section_glossary`.
 286
 287 **"Blue"**
 288
 289   *Required commands*
 290     *"Background", "BackgroundError",
 291     "Observation", "ObservationError",
 292     "ObservationOperator"*
 293
 294   StoreInternalVariables
 295     This boolean key allows to store default internal variables, mainly the
 296     current state during iterative optimization process. Be careful, this can be
 297     a numerically costly choice in certain calculation cases. The default is
 298     "False".
 299
 300   StoreSupplementaryCalculations
 301     This list indicates the names of the supplementary variables that can be
 302     available at the end of the algorithm. It involves potentially costly
 303     calculations. The default is a void list, none of these variables being
 304     calculated and stored by default. The possible names are in the following
 305     list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation",
 306     "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
 307
 308 **"ExtendedBlue"**
 309
 310   *Required commands*
 311     *"Background", "BackgroundError",
 312     "Observation", "ObservationError",
 313     "ObservationOperator"*
 314
 315   StoreInternalVariables
 316     This boolean key allows to store default internal variables, mainly the
 317     current state during iterative optimization process. Be careful, this can be
 318     a numerically costly choice in certain calculation cases. The default is
 319     "False".
 320
 321   StoreSupplementaryCalculations
 322     This list indicates the names of the supplementary variables that can be
 323     available at the end of the algorithm. It involves potentially costly
 324     calculations. The default is a void list, none of these variables being
 325     calculated and stored by default. The possible names are in the following
 326     list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation",
 327     "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
 328
 329 **"LinearLeastSquares"**
 330
 331   *Required commands*
 332     *"Observation", "ObservationError",
 333     "ObservationOperator"*
 334
 335   StoreInternalVariables
 336     This boolean key allows to store default internal variables, mainly the
 337     current state during iterative optimization process. Be careful, this can be
 338     a numerically costly choice in certain calculation cases. The default is
 339     "False".
 340
 341   StoreSupplementaryCalculations
 342     This list indicates the names of the supplementary variables that can be
 343     available at the end of the algorithm. It involves potentially costly
 344     calculations. The default is a void list, none of these variables being
 345     calculated and stored by default. The possible names are in the following
 346     list: ["OMA"].
 347
 348 **"3DVAR"**
 349
 350   *Required commands*
 351     *"Background", "BackgroundError",
 352     "Observation", "ObservationError",
 353     "ObservationOperator"*
 354
 355   Minimizer
 356     This key allows to choose the optimization minimizer. The default choice is
 357     "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
 358     minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear
 359     constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS"
 360     (nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is
 361     recommended to stay with the default.
 362
 363   Bounds
 364     This key allows to define upper and lower bounds for every state variable
 365     being optimized. Bounds can be given by a list of list of pairs of
 366     lower/upper bounds for each variable, with possibly ``None`` every time
 367     there is no bound. The bounds can always be specified, but they are taken
 368     into account only by the constrained minimizers.
 369
 370   MaximumNumberOfSteps
 371     This key indicates the maximum number of iterations allowed for iterative
 372     optimization. The default is 15000, which is very similar to no limit on
 373     iterations. It is then recommended to adapt this parameter to the needs on
 374     real problems. For some minimizers, the effective stopping step can be
 375     slightly different of the limit due to algorithm internal control
 376     requirements.
 377
 378   CostDecrementTolerance
 379     This key indicates a limit value, leading to stop successfully the
 380     iterative optimization process when the cost function decreases less than
 381     this tolerance at the last step. The default is 1.e-7, and it is
 382     recommended to adapt it to the needs on real problems.
 383
 384   ProjectedGradientTolerance
 385     This key indicates a limit value, leading to stop successfully the iterative
 386     optimization process when all the components of the projected gradient are
 387     under this limit. It is only used for constrained minimizers. The default is
 388     -1, that is the internal default of each minimizer (generally 1.e-5), and it
 389     is not recommended to change it.
 390
 391   GradientNormTolerance
 392     This key indicates a limit value, leading to stop successfully the
 393     iterative optimization process when the norm of the gradient is under this
 394     limit. It is only used for non-constrained minimizers.  The default is
 395     1.e-5 and it is not recommended to change it.
 396
 397   StoreInternalVariables
 398     This boolean key allows to store default internal variables, mainly the
 399     current state during iterative optimization process. Be careful, this can be
 400     a numerically costly choice in certain calculation cases. The default is
 401     "False".
 402
 403   StoreSupplementaryCalculations
 404     This list indicates the names of the supplementary variables that can be
 405     available at the end of the algorithm. It involves potentially costly
 406     calculations. The default is a void list, none of these variables being
 407     calculated and stored by default. The possible names are in the following
 408     list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation",
 409     "SigmaObs2", "MahalanobisConsistency"].
 410
 411 **"NonLinearLeastSquares"**
 412
 413   *Required commands*
 414     *"Background",
 415     "Observation", "ObservationError",
 416     "ObservationOperator"*
 417
 418   Minimizer
 419     This key allows to choose the optimization minimizer. The default choice is
 420     "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
 421     minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear
 422     constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS"
 423     (nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is
 424     recommended to stay with the default.
 425
 426   Bounds
 427     This key allows to define upper and lower bounds for every state variable
 428     being optimized. Bounds can be given by a list of list of pairs of
 429     lower/upper bounds for each variable, with possibly ``None`` every time
 430     there is no bound. The bounds can always be specified, but they are taken
 431     into account only by the constrained minimizers.
 432
 433   MaximumNumberOfSteps
 434     This key indicates the maximum number of iterations allowed for iterative
 435     optimization. The default is 15000, which is very similar to no limit on
 436     iterations. It is then recommended to adapt this parameter to the needs on
 437     real problems. For some minimizers, the effective stopping step can be
 438     slightly different due to algorithm internal control requirements.
 439
 440   CostDecrementTolerance
 441     This key indicates a limit value, leading to stop successfully the
 442     iterative optimization process when the cost function decreases less than
 443     this tolerance at the last step. The default is 1.e-7, and it is
 444     recommended to adapt it to the needs on real problems.
 445
 446   ProjectedGradientTolerance
 447     This key indicates a limit value, leading to stop successfully the iterative
 448     optimization process when all the components of the projected gradient are
 449     under this limit. It is only used for constrained minimizers. The default is
 450     -1, that is the internal default of each minimizer (generally 1.e-5), and it
 451     is not recommended to change it.
 452
 453   GradientNormTolerance
 454     This key indicates a limit value, leading to stop successfully the
 455     iterative optimization process when the norm of the gradient is under this
 456     limit. It is only used for non-constrained minimizers.  The default is
 457     1.e-5 and it is not recommended to change it.
 458
 459   StoreInternalVariables
 460     This boolean key allows to store default internal variables, mainly the
 461     current state during iterative optimization process. Be careful, this can be
 462     a numerically costly choice in certain calculation cases. The default is
 463     "False".
 464
 465   StoreSupplementaryCalculations
 466     This list indicates the names of the supplementary variables that can be
 467     available at the end of the algorithm. It involves potentially costly
 468     calculations. The default is a void list, none of these variables being
 469     calculated and stored by default. The possible names are in the following
 470     list: ["BMA", "OMA", "OMB", "Innovation"].
 471
 472 **"EnsembleBlue"**
 473
 474   *Required commands*
 475     *"Background", "BackgroundError",
 476     "Observation", "ObservationError",
 477     "ObservationOperator"*
 478
 479   SetSeed
 480     This key allow to give an integer in order to fix the seed of the random
 481     generator used to generate the ensemble. A convenient value is for example
 482     1000. By default, the seed is left uninitialized, and so use the default
 483     initialization from the computer.
 484
 485 **"KalmanFilter"**
 486
 487   *Required commands*
 488     *"Background", "BackgroundError",
 489     "Observation", "ObservationError",
 490     "ObservationOperator"*
 491
 492   EstimationOf
 493     This key allows to choose the type of estimation to be performed. It can be
 494     either state-estimation, with a value of "State", or parameter-estimation,
 495     with a value of "Parameters". The default choice is "State".
 496
 497   StoreInternalVariables
 498     This boolean key allows to store default internal variables, mainly the
 499     current state during iterative optimization process. Be careful, this can be
 500     a numerically costly choice in certain calculation cases. The default is
 501     "False".
 502
 503   StoreSupplementaryCalculations
 504     This list indicates the names of the supplementary variables that can be
 505     available at the end of the algorithm. It involves potentially costly
 506     calculations. The default is a void list, none of these variables being
 507     calculated and stored by default. The possible names are in the following
 508     list: ["APosterioriCovariance", "BMA", "Innovation"].
 509
 510 **"ExtendedKalmanFilter"**
 511
 512   *Required commands*
 513     *"Background", "BackgroundError",
 514     "Observation", "ObservationError",
 515     "ObservationOperator"*
 516
 517   Bounds
 518     This key allows to define upper and lower bounds for every state variable
 519     being optimized. Bounds can be given by a list of list of pairs of
 520     lower/upper bounds for each variable, with extreme values every time there
 521     is no bound. The bounds can always be specified, but they are taken into
 522     account only by the constrained minimizers.
 523
 524   ConstrainedBy
 525     This key allows to define the method to take bounds into account. The
 526     possible methods are in the following list: ["EstimateProjection"].
 527
 528   EstimationOf
 529     This key allows to choose the type of estimation to be performed. It can be
 530     either state-estimation, with a value of "State", or parameter-estimation,
 531     with a value of "Parameters". The default choice is "State".
 532
 533   StoreInternalVariables
 534     This boolean key allows to store default internal variables, mainly the
 535     current state during iterative optimization process. Be careful, this can be
 536     a numerically costly choice in certain calculation cases. The default is
 537     "False".
 538
 539   StoreSupplementaryCalculations
 540     This list indicates the names of the supplementary variables that can be
 541     available at the end of the algorithm. It involves potentially costly
 542     calculations. The default is a void list, none of these variables being
 543     calculated and stored by default. The possible names are in the following
 544     list: ["APosterioriCovariance", "BMA", "Innovation"].
 545
 546 **"UnscentedKalmanFilter"**
 547
 548   *Required commands*
 549     *"Background", "BackgroundError",
 550     "Observation", "ObservationError",
 551     "ObservationOperator"*
 552
 553   Bounds
 554     This key allows to define upper and lower bounds for every state variable
 555     being optimized. Bounds can be given by a list of list of pairs of
 556     lower/upper bounds for each variable, with extreme values every time there
 557     is no bound. The bounds can always be specified, but they are taken into
 558     account only by the constrained minimizers.
 559
 560   ConstrainedBy
 561     This key allows to define the method to take bounds into account. The
 562     possible methods are in the following list: ["EstimateProjection"].
 563
 564   EstimationOf
 565     This key allows to choose the type of estimation to be performed. It can be
 566     either state-estimation, with a value of "State", or parameter-estimation,
 567     with a value of "Parameters". The default choice is "State".
 568
 569   Alpha, Beta, Kappa, Reconditioner
 570     These keys are internal scaling parameters. "Alpha" requires a value between
 571     1.e-4 and 1. "Beta" has an optimal value of 2 for gaussian *a priori*
 572     distribution. "Kappa" requires an integer value, and the right default is
 573     obtained by setting it to 0. "Reconditioner" requires a value between 1.e-3
 574     and 10, it defaults to 1.
 575
 576   StoreInternalVariables
 577     This boolean key allows to store default internal variables, mainly the
 578     current state during iterative optimization process. Be careful, this can be
 579     a numerically costly choice in certain calculation cases. The default is
 580     "False".
 581
 582   StoreSupplementaryCalculations
 583     This list indicates the names of the supplementary variables that can be
 584     available at the end of the algorithm. It involves potentially costly
 585     calculations. The default is a void list, none of these variables being
 586     calculated and stored by default. The possible names are in the following
 587     list: ["APosterioriCovariance", "BMA", "Innovation"].
 588
 589 **"ParticleSwarmOptimization"**
 590
 591   *Required commands*
 592     *"Background", "BackgroundError",
 593     "Observation", "ObservationError",
 594     "ObservationOperator"*
 595
 596   MaximumNumberOfSteps
 597     This key indicates the maximum number of iterations allowed for iterative
 598     optimization. The default is 50, which is an arbitrary limit. It is then
 599     recommended to adapt this parameter to the needs on real problems.
 600
 601   NumberOfInsects
 602     This key indicates the number of insects or particles in the swarm. The
 603     default is 100, which is a usual default for this algorithm.
 604
 605   SwarmVelocity
 606     This key indicates the part of the insect velocity which is imposed by the
 607     swarm. It is a positive floating point value. The default value is 1.
 608
 609   GroupRecallRate
 610     This key indicates the recall rate at the best swarm insect. It is a
 611     floating point value between 0 and 1. The default value is 0.5.
 612
 613   QualityCriterion
 614     This key indicates the quality criterion, minimized to find the optimal
 615     state estimate. The default is the usual data assimilation criterion named
 616     "DA", the augmented ponderated least squares. The possible criteria has to
 617     be in the following list, where the equivalent names are indicated by "=":
 618     ["AugmentedPonderatedLeastSquares"="APLS"="DA",
 619     "PonderatedLeastSquares"="PLS", "LeastSquares"="LS"="L2",
 620     "AbsoluteValue"="L1", "MaximumError"="ME"]
 621
 622   SetSeed
 623     This key allow to give an integer in order to fix the seed of the random
 624     generator used to generate the ensemble. A convenient value is for example
 625     1000. By default, the seed is left uninitialized, and so use the default
 626     initialization from the computer.
 627
 628   StoreInternalVariables
 629     This boolean key allows to store default internal variables, mainly the
 630     current state during iterative optimization process. Be careful, this can be
 631     a numerically costly choice in certain calculation cases. The default is
 632     "False".
 633
 634   StoreSupplementaryCalculations
 635     This list indicates the names of the supplementary variables that can be
 636     available at the end of the algorithm. It involves potentially costly
 637     calculations. The default is a void list, none of these variables being
 638     calculated and stored by default. The possible names are in the following
 639     list: ["BMA", "OMA", "OMB", "Innovation"].
 640
 641 **"QuantileRegression"**
 642
 643   *Required commands*
 644     *"Background",
 645     "Observation",
 646     "ObservationOperator"*
 647
 648   Quantile
 649     This key allows to define the real value of the desired quantile, between
 650     0 and 1. The default is 0.5, corresponding to the median.
 651
 652   Minimizer
 653     This key allows to choose the optimization minimizer. The default choice
 654     and only available choice is "MMQR" (Majorize-Minimize for Quantile
 655     Regression).
 656
 657   MaximumNumberOfSteps
 658     This key indicates the maximum number of iterations allowed for iterative
 659     optimization. The default is 15000, which is very similar to no limit on
 660     iterations. It is then recommended to adapt this parameter to the needs on
 661     real problems.
 662
 663   CostDecrementTolerance
 664     This key indicates a limit value, leading to stop successfully the
 665     iterative optimization process when the cost function or the surrogate
 666     decreases less than this tolerance at the last step. The default is 1.e-6,
 667     and it is recommended to adapt it to the needs on real problems.
 668
 669   StoreInternalVariables
 670     This boolean key allows to store default internal variables, mainly the
 671     current state during iterative optimization process. Be careful, this can be
 672     a numerically costly choice in certain calculation cases. The default is
 673     "False".
 674
 675   StoreSupplementaryCalculations
 676     This list indicates the names of the supplementary variables that can be
 677     available at the end of the algorithm. It involves potentially costly
 678     calculations. The default is a void list, none of these variables being
 679     calculated and stored by default. The possible names are in the following
 680     list: ["BMA", "OMA", "OMB", "Innovation"].
 681
 682 Reference description for ADAO checking cases
 683 ---------------------------------------------
 684
 685 List of commands and keywords for an ADAO checking case
 686 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 687
 688 .. index:: single: CHECKING_STUDY
 689 .. index:: single: Algorithm
 690 .. index:: single: AlgorithmParameters
 691 .. index:: single: CheckingPoint
 692 .. index:: single: Debug
 693 .. index:: single: ObservationOperator
 694 .. index:: single: Study_name
 695 .. index:: single: Study_repertory
 696 .. index:: single: UserDataInit
 697
 698 The second set of commands is related to the description of a checking case,
 699 that is a procedure to check required properties on information somewhere else
 700 by a calculation case. The terms are ordered in alphabetical order, except the
 701 first, which describes choice between calculation or checking. The different
 702 commands are the following:
 703
 704 **CHECKING_STUDY**
 705     *Required command*. This is the general command describing the checking
 706     case. It hierarchically contains all the other commands.
 707
 708 **Algorithm**
 709     *Required command*. This is a string to indicate the test algorithm chosen.
 710     The choices are limited and available through the GUI. There exists for
 711     example "FunctionTest", "AdjointTest"... See below the list of algorithms
 712     and associated parameters in the following subsection `Optional and required
 713     commands for checking algorithms`_.
 714
 715 **AlgorithmParameters** *Optional command*. This command allows to add some
 716     optional parameters to control the data assimilation or optimization
 717     algorithm. It is defined as a "*Dict*" type object, that is, given as a
 718     script. See below the list of algorithms and associated parameters in the
 719     following subsection `Optional and required commands for checking
 720     algorithms`_.
 721
 722 **CheckingPoint**
 723     *Required command*. This indicates the vector used, previously noted as
 724     :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
 725
 726 **Debug**
 727     *Optional command*. This define the level of trace and intermediary debug
 728     information. The choices are limited between 0 (for False) and 1 (for
 729     True).
 730
 731 **ObservationOperator**
 732     *Required command*. This indicates the observation operator, previously
 733     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
 734     results :math:`\mathbf{y}` to be compared to observations
 735     :math:`\mathbf{y}^o`. It is defined as a "*Function*" type object. Different
 736     functional forms can be used, as described in the following subsection
 737     `Requirements for functions describing an operator`_. If there is some
 738     control :math:`U` included in the observation, the operator has to be
 739     applied to a pair :math:`(X,U)`.
 740
 741 **Study_name**
 742     *Required command*. This is an open string to describe the study by a name
 743     or a sentence.
 744
 745 **Study_repertory**
 746     *Optional command*. If available, this directory is used as base name for
 747     calculation, and used to find all the script files, given by name without
 748     path, that can be used to define some other commands by scripts.
 749
 750 **UserDataInit**
 751     *Optional command*. This commands allows to initialize some parameters or
 752     data automatically before data assimilation algorithm processing.
 753
 754 Optional and required commands for checking algorithms
 755 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 756
 757 .. index:: single: AdjointTest
 758 .. index:: single: FunctionTest
 759 .. index:: single: GradientTest
 760 .. index:: single: LinearityTest
 761 .. index:: single: ObserverTest
 762
 763 .. index:: single: AlgorithmParameters
 764 .. index:: single: AmplitudeOfInitialDirection
 765 .. index:: single: EpsilonMinimumExponent
 766 .. index:: single: InitialDirection
 767 .. index:: single: ResiduFormula
 768 .. index:: single: SetSeed
 769
 770 We recall that each algorithm can be controlled using some generic or specific
 771 options, given through the "*AlgorithmParameters*" optional command, as follows
 772 for example::
 773
 774     AlgorithmParameters = {
 775         "AmplitudeOfInitialDirection" : 1,
 776         "EpsilonMinimumExponent" : -8,
 777         }
 778
 779 If an option is specified by the user for an algorithm that doesn't support it,
 780 the option is simply left unused and don't stop the treatment. The meaning of
 781 the acronyms or particular names can be found in the :ref:`genindex` or the
 782 :ref:`section_glossary`. In addition, for each algorithm, the required
 783 commands/keywords are given, being described in `List of commands and keywords
 784 for an ADAO checking case`_.
 785
 786 **"AdjointTest"**
 787
 788   *Required commands*
 789     *"CheckingPoint",
 790     "ObservationOperator"*
 791
 792   AmplitudeOfInitialDirection
 793     This key indicates the scaling of the initial perturbation build as a vector
 794     used for the directional derivative around the nominal checking point. The
 795     default is 1, that means no scaling.
 796
 797   EpsilonMinimumExponent
 798     This key indicates the minimal exponent value of the power of 10 coefficient
 799     to be used to decrease the increment multiplier. The default is -8, and it
 800     has to be between 0 and -20. For example, its default value leads to
 801     calculate the residue of the formula with a fixed increment multiplied from
 802     1.e0 to 1.e-8.
 803
 804   InitialDirection
 805     This key indicates the vector direction used for the directional derivative
 806     around the nominal checking point. It has to be a vector. If not specified,
 807     this direction defaults to a random perturbation around zero of the same
 808     vector size than the checking point.
 809
 810   SetSeed
 811     This key allow to give an integer in order to fix the seed of the random
 812     generator used to generate the ensemble. A convenient value is for example
 813     1000. By default, the seed is left uninitialized, and so use the default
 814     initialization from the computer.
 815
 816 **"FunctionTest"**
 817
 818   *Required commands*
 819     *"CheckingPoint",
 820     "ObservationOperator"*
 821
 822   NumberOfPrintedDigits
 823     This key indicates the number of digits of precision for floating point
 824     printed output. The default is 5, with a minimum of 0.
 825
 826   NumberOfRepetition
 827     This key indicates the number of time to repeat the function evaluation. The
 828     default is 1.
 829
 830   SetDebug
 831     This key requires the activation, or not, of the debug mode during the
 832     function evaluation. The default is "True", the choices are "True" or
 833     "False".
 834
 835 **"GradientTest"**
 836
 837   *Required commands*
 838     *"CheckingPoint",
 839     "ObservationOperator"*
 840
 841   AmplitudeOfInitialDirection
 842     This key indicates the scaling of the initial perturbation build as a vector
 843     used for the directional derivative around the nominal checking point. The
 844     default is 1, that means no scaling.
 845
 846   EpsilonMinimumExponent
 847     This key indicates the minimal exponent value of the power of 10 coefficient
 848     to be used to decrease the increment multiplier. The default is -8, and it
 849     has to be between 0 and -20. For example, its default value leads to
 850     calculate the residue of the scalar product formula with a fixed increment
 851     multiplied from 1.e0 to 1.e-8.
 852
 853   InitialDirection
 854     This key indicates the vector direction used for the directional derivative
 855     around the nominal checking point. It has to be a vector. If not specified,
 856     this direction defaults to a random perturbation around zero of the same
 857     vector size than the checking point.
 858
 859   ResiduFormula
 860     This key indicates the residue formula that has to be used for the test. The
 861     default choice is "Taylor", and the possible ones are "Taylor" (residue of
 862     the Taylor development of the operator, which has to decrease with the
 863     square power of the perturbation) and "Norm" (residue obtained by taking the
 864     norm of the Taylor development at zero order approximation, which
 865     approximate the gradient, and which has to remain constant).
 866
 867   SetSeed
 868     This key allow to give an integer in order to fix the seed of the random
 869     generator used to generate the ensemble. A convenient value is for example
 870     1000. By default, the seed is left uninitialized, and so use the default
 871     initialization from the computer.
 872
 873 **"LinearityTest"**
 874
 875   *Required commands*
 876     *"CheckingPoint",
 877     "ObservationOperator"*
 878
 879   AmplitudeOfInitialDirection
 880     This key indicates the scaling of the initial perturbation build as a vector
 881     used for the directional derivative around the nominal checking point. The
 882     default is 1, that means no scaling.
 883
 884   EpsilonMinimumExponent
 885     This key indicates the minimal exponent value of the power of 10 coefficient
 886     to be used to decrease the increment multiplier. The default is -8, and it
 887     has to be between 0 and -20. For example, its default value leads to
 888     calculate the residue of the scalar product formula with a fixed increment
 889     multiplied from 1.e0 to 1.e-8.
 890
 891   InitialDirection
 892     This key indicates the vector direction used for the directional derivative
 893     around the nominal checking point. It has to be a vector. If not specified,
 894     this direction defaults to a random perturbation around zero of the same
 895     vector size than the checking point.
 896
 897   ResiduFormula
 898     This key indicates the residue formula that has to be used for the test. The
 899     default choice is "CenteredDL", and the possible ones are "CenteredDL"
 900     (residue of the difference between the function at nominal point and the
 901     values with positive and negative increments, which has to stay very small),
 902     "Taylor" (residue of the Taylor development of the operator normalized by
 903     the nominal value, which has to stay very small), "NominalTaylor" (residue
 904     of the order 1 approximations of the operator, normalized to the nominal
 905     point, which has to stay close to 1), and "NominalTaylorRMS" (residue of the
 906     order 1 approximations of the operator, normalized by RMS to the nominal
 907     point, which has to stay close to 0).
 908
 909   SetSeed
 910     This key allow to give an integer in order to fix the seed of the random
 911     generator used to generate the ensemble. A convenient value is for example
 912     1000. By default, the seed is left uninitialized, and so use the default
 913     initialization from the computer.
 914
 915 **"ObserverTest"**
 916
 917   *Required commands*
 918     *"Observers"*
 919
 920   *Tip for this command:*
 921     Because *"CheckingPoint"* and *"ObservationOperator"* are required commands
 922     for ALL checking algorithms in the interface, you have to provide a value
 923     for them, despite the fact that these commands are not required for
 924     *"ObserverTest"*, and will not be used. The easiest way is to give "1" as a
 925     STRING for both, *"ObservationOperator"* having to be of type *Matrix*.
 926
 927 Requirements for functions describing an operator
 928 -------------------------------------------------
 929
 930 The operators for observation and evolution are required to implement the data
 931 assimilation or optimization procedures. They include the physical simulation by
 932 numerical calculations, but also the filtering and restriction to compare the
 933 simulation to observation. The evolution operator is considered here in its
 934 incremental form, representing the transition between two successive states, and
 935 is then similar to the observation operator.
 936
 937 Schematically, an operator has to give a output solution given the input
 938 parameters. Part of the input parameters can be modified during the optimization
 939 procedure. So the mathematical representation of such a process is a function.
 940 It was briefly described in the section :ref:`section_theory` and is generalized
 941 here by the relation:
 942
 943 .. math:: \mathbf{y} = O( \mathbf{x} )
 944
 945 between the pseudo-observations :math:`\mathbf{y}` and the parameters
 946 :math:`\mathbf{x}` using the observation or evolution operator :math:`O`. The
 947 same functional representation can be used for the linear tangent model
 948 :math:`\mathbf{O}` of :math:`O` and its adjoint :math:`\mathbf{O}^*`, also
 949 required by some data assimilation or optimization algorithms.
 950
 951 On input and output of these operators, the :math:`\mathbf{x}` and
 952 :math:`\mathbf{y}` variables or their increments are mathematically vectors,
 953 and they are given as non-orented vectors (of type list or Numpy array) or
 954 oriented ones (of type Numpy matrix).
 955
 956 Then, **to describe completely an operator, the user has only to provide a
 957 function that fully and only realize the functional operation**.
 958
 959 This function is usually given as a script that can be executed in a YACS node.
 960 This script can without difference launch external codes or use internal SALOME
 961 calls and methods. If the algorithm requires the 3 aspects of the operator
 962 (direct form, tangent form and adjoint form), the user has to give the 3
 963 functions or to approximate them.
 964
 965 There are 3 practical methods for the user to provide an operator functional
 966 representation. These methods are chosen in the "*FROM*"  field of each operator
 967 having a "*Function*" value as "*INPUT_TYPE*", as shown by the following figure:
 968
 969   .. eficas_operator_function:
 970   .. image:: images/eficas_operator_function.png
 971     :align: center
 972     :width: 100%
 973   .. centered::
 974     **Choosing an operator functional representation**
 975
 976 First functional form: using "*ScriptWithOneFunction*"
 977 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 978
 979 .. index:: single: ScriptWithOneFunction
 980 .. index:: single: DirectOperator
 981 .. index:: single: DifferentialIncrement
 982 .. index:: single: CenteredFiniteDifference
 983
 984 The first one consist in providing only one potentially non-linear function, and
 985 to approximate the tangent and the adjoint operators. This is done by using the
 986 keyword "*ScriptWithOneFunction*" for the description of the chosen operator in
 987 the ADAO GUI. The user have to provide the function in a script, with a
 988 mandatory name "*DirectOperator*". For example, the script can follow the
 989 template::
 990
 991     def DirectOperator( X ):
 992         """ Direct non-linear simulation operator """
 993         ...
 994         ...
 995         ...
 996         return Y=O(X)
 997
 998 In this case, the user has also provide a value for the differential increment
 999 (or keep the devault value), using through the GUI the keyword
1000 "*DifferentialIncrement*", which has a default value of 1%. This coefficient
1001 will be used in the finite difference approximation to build the tangent and
1002 adjoint operators. The finite difference approximation order can also be chosen
1003 through the GUI, using the keyword "*CenteredFiniteDifference*", with 0 for an
1004 uncentered schema of first order (which is the default value), and with 1 for a
1005 centered schema of second order (of twice the first order computational cost).
1006
1007 This first operator definition form allows easily to test the functional form
1008 before its use in an ADAO case, greatly reducing the complexity of
1009 operator implementation.
1010
1011 **Important warning:** the name "*DirectOperator*" is mandatory, and the type of
1012 the ``X`` argument can be either a list, a numpy array or a numpy 1D-matrix. The
1013 user has to treat these cases in his function.
1014
1015 Second functional form: using "*ScriptWithFunctions*"
1016 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1017
1018 .. index:: single: ScriptWithFunctions
1019 .. index:: single: DirectOperator
1020 .. index:: single: TangentOperator
1021 .. index:: single: AdjointOperator
1022
1023 **In general, it is recommended to use the first functionnal form rather than
1024 the second one. A small performance improvement is not a good reason to use a
1025 detailled implementation as this second functional form.**
1026
1027 The second one consist in providing directly the three associated operators
1028 :math:`O`, :math:`\mathbf{O}` and :math:`\mathbf{O}^*`. This is done by using
1029 the keyword "*ScriptWithFunctions*" for the description of the chosen operator
1030 in the ADAO GUI. The user have to provide three functions in one script, with
1031 three mandatory names "*DirectOperator*", "*TangentOperator*" and
1032 "*AdjointOperator*". For example, the script can follow the template::
1033
1034     def DirectOperator( X ):
1035         """ Direct non-linear simulation operator """
1036         ...
1037         ...
1038         ...
1039         return something like Y
1040
1041     def TangentOperator( (X, dX) ):
1042         """ Tangent linear operator, around X, applied to dX """
1043         ...
1044         ...
1045         ...
1046         return something like Y
1047
1048     def AdjointOperator( (X, Y) ):
1049         """ Adjoint operator, around X, applied to Y """
1050         ...
1051         ...
1052         ...
1053         return something like X
1054
1055 Another time, this second operator definition allow easily to test the
1056 functional forms before their use in an ADAO case, reducing the complexity of
1057 operator implementation.
1058
1059 For some algorithms, it is required that the tangent and adjoint functions can
1060 return the matrix equivalent to the linear operator. In this case, when
1061 respectivly the ``dX`` or the ``Y`` arguments are ``None``, the user has to
1062 return the associated matrix.
1063
1064 **Important warning:** the names "*DirectOperator*", "*TangentOperator*" and
1065 "*AdjointOperator*" are mandatory, and the type of the ``X``, Y``, ``dX``
1066 arguments can be either a python list, a numpy array or a numpy 1D-matrix. The
1067 user has to treat these cases in his script.
1068
1069 Third functional form: using "*ScriptWithSwitch*"
1070 +++++++++++++++++++++++++++++++++++++++++++++++++
1071
1072 .. index:: single: ScriptWithSwitch
1073 .. index:: single: DirectOperator
1074 .. index:: single: TangentOperator
1075 .. index:: single: AdjointOperator
1076
1077 **It is recommended not to use this third functional form without a solid
1078 numerical or physical reason. A performance improvement is not a good reason to
1079 use the implementation complexity of this third functional form. Only an
1080 inability to use the first or second forms justifies the use of the third.**
1081
1082 This third form give more possibilities to control the execution of the three
1083 functions representing the operator, allowing advanced usage and control over
1084 each execution of the simulation code. This is done by using the keyword
1085 "*ScriptWithSwitch*" for the description of the chosen operator in the ADAO GUI.
1086 The user have to provide a switch in one script to control the execution of the
1087 direct, tangent and adjoint forms of its simulation code. The user can then, for
1088 example, use other approximations for the tangent and adjoint codes, or
1089 introduce more complexity in the argument treatment of the functions. But it
1090 will be far more complicated to implement and debug.
1091
1092 If, however, you want to use this third form, we recommend using the following
1093 template for the switch. It requires an external script or code named here
1094 "*Physical_simulation_functions.py*", containing three functions named
1095 "*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously.
1096 Here is the switch template::
1097
1098     import Physical_simulation_functions
1099     import numpy, logging
1100     #
1101     method = ""
1102     for param in computation["specificParameters"]:
1103         if param["name"] == "method":
1104             method = param["value"]
1105     if method not in ["Direct", "Tangent", "Adjoint"]:
1106         raise ValueError("No valid computation method is given")
1107     logging.info("Found method is \'%s\'"%method)
1108     #
1109     logging.info("Loading operator functions")
1110     Function = Physical_simulation_functions.DirectOperator
1111     Tangent  = Physical_simulation_functions.TangentOperator
1112     Adjoint  = Physical_simulation_functions.AdjointOperator
1113     #
1114     logging.info("Executing the possible computations")
1115     data = []
1116     if method == "Direct":
1117         logging.info("Direct computation")
1118         Xcurrent = computation["inputValues"][0][0][0]
1119         data = Function(numpy.matrix( Xcurrent ).T)
1120     if method == "Tangent":
1121         logging.info("Tangent computation")
1122         Xcurrent  = computation["inputValues"][0][0][0]
1123         dXcurrent = computation["inputValues"][0][0][1]
1124         data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
1125     if method == "Adjoint":
1126         logging.info("Adjoint computation")
1127         Xcurrent = computation["inputValues"][0][0][0]
1128         Ycurrent = computation["inputValues"][0][0][1]
1129         data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
1130     #
1131     logging.info("Formatting the output")
1132     it = numpy.ravel(data)
1133     outputValues = [[[[]]]]
1134     for val in it:
1135       outputValues[0][0][0].append(val)
1136     #
1137     result = {}
1138     result["outputValues"]        = outputValues
1139     result["specificOutputInfos"] = []
1140     result["returnCode"]          = 0
1141     result["errorMessage"]        = ""
1142
1143 All various modifications could be done from this template hypothesis.
1144
1145 Special case of controled evolution or observation operator
1146 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1147
1148 In some cases, the evolution or the observation operator is required to be
1149 controled by an external input control, given *a priori*. In this case, the
1150 generic form of the incremental model is slightly modified as follows:
1151
1152 .. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
1153
1154 where :math:`\mathbf{u}` is the control over one state increment. In this case,
1155 the direct operator has to be applied to a pair of variables :math:`(X,U)`.
1156 Schematically, the operator has to be set as::
1157
1158     def DirectOperator( (X, U) ):
1159         """ Direct non-linear simulation operator """
1160         ...
1161         ...
1162         ...
1163         return something like X(n+1) (evolution) or Y(n+1) (observation)
1164
1165 The tangent and adjoint operators have the same signature as previously, noting
1166 that the derivatives has to be done only partially against :math:`\mathbf{x}`.
1167 In such a case with explicit control, only the second functional form (using
1168 "*ScriptWithFunctions*") and third functional form (using "*ScriptWithSwitch*")
1169 can be used.
1170
1171 Requirements to describe covariance matrices
1172 --------------------------------------------
1173
1174 Multiple covariance matrices are required to implement the data assimilation or
1175 optimization procedures. The main ones are the background error covariance
1176 matrix, noted as :math:`\mathbf{B}`, and the observation error covariance matrix,
1177 noted as :math:`\mathbf{R}`. Such a matrix is required to be a squared symetric
1178 semi-definite positive matrix.
1179
1180 There are 3 practical methods for the user to provide a covariance matrix. These
1181 methods are chosen by the "*INPUT_TYPE*" keyword of each defined covariance
1182 matrix, as shown by the following figure:
1183
1184   .. eficas_covariance_matrix:
1185   .. image:: images/eficas_covariance_matrix.png
1186     :align: center
1187     :width: 100%
1188   .. centered::
1189     **Choosing covariance matrix representation**
1190
1191 First matrix form: using "*Matrix*" representation
1192 ++++++++++++++++++++++++++++++++++++++++++++++++++
1193
1194 .. index:: single: Matrix
1195 .. index:: single: BackgroundError
1196 .. index:: single: EvolutionError
1197 .. index:: single: ObservationError
1198
1199 This first form is the default and more general one. The covariance matrix
1200 :math:`\mathbf{M}` has to be fully specified. Even if the matrix is symetric by
1201 nature, the entire :math:`\mathbf{M}` matrix has to be given.
1202
1203 .. math:: \mathbf{M} =  \begin{pmatrix}
1204     m_{11} & m_{12} & \cdots   & m_{1n} \\
1205     m_{21} & m_{22} & \cdots   & m_{2n} \\
1206     \vdots & \vdots & \vdots   & \vdots \\
1207     m_{n1} & \cdots & m_{nn-1} & m_{nn}
1208     \end{pmatrix}
1209
1210 It can be either a Python Numpy array or a matrix, or a list of lists of values
1211 (that is, a list of rows). For example, a simple diagonal unitary background
1212 error covariance matrix :math:`\mathbf{B}` can be described in a Python script
1213 file as::
1214
1215     BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
1216
1217 or::
1218
1219     BackgroundError = numpy.eye(...)
1220
1221 Second matrix form: using "*ScalarSparseMatrix*" representation
1222 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1223
1224 .. index:: single: ScalarSparseMatrix
1225 .. index:: single: BackgroundError
1226 .. index:: single: EvolutionError
1227 .. index:: single: ObservationError
1228
1229 On the opposite, this second form is a very simplified method to provide a
1230 matrix. The covariance matrix :math:`\mathbf{M}` is supposed to be a positive
1231 multiple of the identity matrix. This matrix can then be specified in a unique
1232 way by the multiplier :math:`m`:
1233
1234 .. math:: \mathbf{M} =  m \times \begin{pmatrix}
1235     1       & 0      & \cdots   & 0      \\
1236     0       & 1      & \cdots   & 0      \\
1237     \vdots  & \vdots & \vdots   & \vdots \\
1238     0       & \cdots & 0        & 1
1239     \end{pmatrix}
1240
1241 The multiplier :math:`m` has to be a floating point or integer positive value
1242 (if it is negative, which is impossible for a positive covariance matrix, it is
1243 converted to positive value). For example, a simple diagonal unitary background
1244 error covariance matrix :math:`\mathbf{B}` can be described in a python script
1245 file as::
1246
1247     BackgroundError = 1.
1248
1249 or, better, by a "*String*" directly in the ADAO case.
1250
1251 Third matrix form: using "*DiagonalSparseMatrix*" representation
1252 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1253
1254 .. index:: single: DiagonalSparseMatrix
1255 .. index:: single: BackgroundError
1256 .. index:: single: EvolutionError
1257 .. index:: single: ObservationError
1258
1259 This third form is also a simplified method to provide a matrix, but a little
1260 more powerful than the second one. The covariance matrix :math:`\mathbf{M}` is
1261 already supposed to be diagonal, but the user has to specify all the positive
1262 diagonal values. The matrix can then be specified only by a vector
1263 :math:`\mathbf{V}` which will be set on a diagonal matrix:
1264
1265 .. math:: \mathbf{M} =  \begin{pmatrix}
1266     v_{1}  & 0      & \cdots   & 0      \\
1267     0      & v_{2}  & \cdots   & 0      \\
1268     \vdots & \vdots & \vdots   & \vdots \\
1269     0      & \cdots & 0        & v_{n}
1270     \end{pmatrix}
1271
1272 It can be either a Python Numpy array or a matrix, or a list or a list of list
1273 of positive values (in all cases, if some are negative, which is impossible,
1274 they are converted to positive values). For example, a simple diagonal unitary
1275 background error covariance matrix :math:`\mathbf{B}` can be described in a
1276 python script file as::
1277
1278     BackgroundError = [1, 1 ... 1]
1279
1280 or::
1281
1282     BackgroundError = numpy.ones(...)