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 .. index:: single: TangentTest
 763
 764 .. index:: single: AlgorithmParameters
 765 .. index:: single: AmplitudeOfInitialDirection
 766 .. index:: single: EpsilonMinimumExponent
 767 .. index:: single: InitialDirection
 768 .. index:: single: ResiduFormula
 769 .. index:: single: SetSeed
 770
 771 We recall that each algorithm can be controlled using some generic or specific
 772 options, given through the "*AlgorithmParameters*" optional command, as follows
 773 for example::
 774
 775     AlgorithmParameters = {
 776         "AmplitudeOfInitialDirection" : 1,
 777         "EpsilonMinimumExponent" : -8,
 778         }
 779
 780 If an option is specified by the user for an algorithm that doesn't support it,
 781 the option is simply left unused and don't stop the treatment. The meaning of
 782 the acronyms or particular names can be found in the :ref:`genindex` or the
 783 :ref:`section_glossary`. In addition, for each algorithm, the required
 784 commands/keywords are given, being described in `List of commands and keywords
 785 for an ADAO checking case`_.
 786
 787 **"AdjointTest"**
 788
 789   *Required commands*
 790     *"CheckingPoint",
 791     "ObservationOperator"*
 792
 793   AmplitudeOfInitialDirection
 794     This key indicates the scaling of the initial perturbation build as a vector
 795     used for the directional derivative around the nominal checking point. The
 796     default is 1, that means no scaling.
 797
 798   EpsilonMinimumExponent
 799     This key indicates the minimal exponent value of the power of 10 coefficient
 800     to be used to decrease the increment multiplier. The default is -8, and it
 801     has to be between 0 and -20. For example, its default value leads to
 802     calculate the residue of the formula with a fixed increment multiplied from
 803     1.e0 to 1.e-8.
 804
 805   InitialDirection
 806     This key indicates the vector direction used for the directional derivative
 807     around the nominal checking point. It has to be a vector. If not specified,
 808     this direction defaults to a random perturbation around zero of the same
 809     vector size than the checking point.
 810
 811   SetSeed
 812     This key allow to give an integer in order to fix the seed of the random
 813     generator used to generate the ensemble. A convenient value is for example
 814     1000. By default, the seed is left uninitialized, and so use the default
 815     initialization from the computer.
 816
 817 **"FunctionTest"**
 818
 819   *Required commands*
 820     *"CheckingPoint",
 821     "ObservationOperator"*
 822
 823   NumberOfPrintedDigits
 824     This key indicates the number of digits of precision for floating point
 825     printed output. The default is 5, with a minimum of 0.
 826
 827   NumberOfRepetition
 828     This key indicates the number of time to repeat the function evaluation. The
 829     default is 1.
 830
 831   SetDebug
 832     This key requires the activation, or not, of the debug mode during the
 833     function evaluation. The default is "True", the choices are "True" or
 834     "False".
 835
 836 **"GradientTest"**
 837
 838   *Required commands*
 839     *"CheckingPoint",
 840     "ObservationOperator"*
 841
 842   AmplitudeOfInitialDirection
 843     This key indicates the scaling of the initial perturbation build as a vector
 844     used for the directional derivative around the nominal checking point. The
 845     default is 1, that means no scaling.
 846
 847   EpsilonMinimumExponent
 848     This key indicates the minimal exponent value of the power of 10 coefficient
 849     to be used to decrease the increment multiplier. The default is -8, and it
 850     has to be between 0 and -20. For example, its default value leads to
 851     calculate the residue of the scalar product formula with a fixed increment
 852     multiplied from 1.e0 to 1.e-8.
 853
 854   InitialDirection
 855     This key indicates the vector direction used for the directional derivative
 856     around the nominal checking point. It has to be a vector. If not specified,
 857     this direction defaults to a random perturbation around zero of the same
 858     vector size than the checking point.
 859
 860   ResiduFormula
 861     This key indicates the residue formula that has to be used for the test. The
 862     default choice is "Taylor", and the possible ones are "Taylor" (residue of
 863     the Taylor development of the operator, which has to decrease with the
 864     square power of the perturbation) and "Norm" (residue obtained by taking the
 865     norm of the Taylor development at zero order approximation, which
 866     approximate the gradient, and which has to remain constant).
 867
 868   SetSeed
 869     This key allow to give an integer in order to fix the seed of the random
 870     generator used to generate the ensemble. A convenient value is for example
 871     1000. By default, the seed is left uninitialized, and so use the default
 872     initialization from the computer.
 873
 874 **"LinearityTest"**
 875
 876   *Required commands*
 877     *"CheckingPoint",
 878     "ObservationOperator"*
 879
 880   AmplitudeOfInitialDirection
 881     This key indicates the scaling of the initial perturbation build as a vector
 882     used for the directional derivative around the nominal checking point. The
 883     default is 1, that means no scaling.
 884
 885   EpsilonMinimumExponent
 886     This key indicates the minimal exponent value of the power of 10 coefficient
 887     to be used to decrease the increment multiplier. The default is -8, and it
 888     has to be between 0 and -20. For example, its default value leads to
 889     calculate the residue of the scalar product formula with a fixed increment
 890     multiplied from 1.e0 to 1.e-8.
 891
 892   InitialDirection
 893     This key indicates the vector direction used for the directional derivative
 894     around the nominal checking point. It has to be a vector. If not specified,
 895     this direction defaults to a random perturbation around zero of the same
 896     vector size than the checking point.
 897
 898   ResiduFormula
 899     This key indicates the residue formula that has to be used for the test. The
 900     default choice is "CenteredDL", and the possible ones are "CenteredDL"
 901     (residue of the difference between the function at nominal point and the
 902     values with positive and negative increments, which has to stay very small),
 903     "Taylor" (residue of the Taylor development of the operator normalized by
 904     the nominal value, which has to stay very small), "NominalTaylor" (residue
 905     of the order 1 approximations of the operator, normalized to the nominal
 906     point, which has to stay close to 1), and "NominalTaylorRMS" (residue of the
 907     order 1 approximations of the operator, normalized by RMS to the nominal
 908     point, which has to stay close to 0).
 909
 910   SetSeed
 911     This key allow to give an integer in order to fix the seed of the random
 912     generator used to generate the ensemble. A convenient value is for example
 913     1000. By default, the seed is left uninitialized, and so use the default
 914     initialization from the computer.
 915
 916 **"ObserverTest"**
 917
 918   *Required commands*
 919     *"Observers"*
 920
 921   *Tip for this command:*
 922     Because *"CheckingPoint"* and *"ObservationOperator"* are required commands
 923     for ALL checking algorithms in the interface, you have to provide a value
 924     for them, despite the fact that these commands are not required for
 925     *"ObserverTest"*, and will not be used. The easiest way is to give "1" as a
 926     STRING for both, *"ObservationOperator"* having to be of type *Matrix*.
 927
 928 **"TangentTest"**
 929
 930   *Required commands*
 931     *"CheckingPoint",
 932     "ObservationOperator"*
 933
 934   AmplitudeOfInitialDirection
 935     This key indicates the scaling of the initial perturbation build as a vector
 936     used for the directional derivative around the nominal checking point. The
 937     default is 1, that means no scaling.
 938
 939   EpsilonMinimumExponent
 940     This key indicates the minimal exponent value of the power of 10 coefficient
 941     to be used to decrease the increment multiplier. The default is -8, and it
 942     has to be between 0 and -20. For example, its default value leads to
 943     calculate the residue of the scalar product formula with a fixed increment
 944     multiplied from 1.e0 to 1.e-8.
 945
 946   InitialDirection
 947     This key indicates the vector direction used for the directional derivative
 948     around the nominal checking point. It has to be a vector. If not specified,
 949     this direction defaults to a random perturbation around zero of the same
 950     vector size than the checking point.
 951
 952   SetSeed
 953     This key allow to give an integer in order to fix the seed of the random
 954     generator used to generate the ensemble. A convenient value is for example
 955     1000. By default, the seed is left uninitialized, and so use the default
 956     initialization from the computer.
 957
 958 Requirements for functions describing an operator
 959 -------------------------------------------------
 960
 961 The operators for observation and evolution are required to implement the data
 962 assimilation or optimization procedures. They include the physical simulation by
 963 numerical calculations, but also the filtering and restriction to compare the
 964 simulation to observation. The evolution operator is considered here in its
 965 incremental form, representing the transition between two successive states, and
 966 is then similar to the observation operator.
 967
 968 Schematically, an operator has to give a output solution given the input
 969 parameters. Part of the input parameters can be modified during the optimization
 970 procedure. So the mathematical representation of such a process is a function.
 971 It was briefly described in the section :ref:`section_theory` and is generalized
 972 here by the relation:
 973
 974 .. math:: \mathbf{y} = O( \mathbf{x} )
 975
 976 between the pseudo-observations :math:`\mathbf{y}` and the parameters
 977 :math:`\mathbf{x}` using the observation or evolution operator :math:`O`. The
 978 same functional representation can be used for the linear tangent model
 979 :math:`\mathbf{O}` of :math:`O` and its adjoint :math:`\mathbf{O}^*`, also
 980 required by some data assimilation or optimization algorithms.
 981
 982 On input and output of these operators, the :math:`\mathbf{x}` and
 983 :math:`\mathbf{y}` variables or their increments are mathematically vectors,
 984 and they are given as non-orented vectors (of type list or Numpy array) or
 985 oriented ones (of type Numpy matrix).
 986
 987 Then, **to describe completely an operator, the user has only to provide a
 988 function that fully and only realize the functional operation**.
 989
 990 This function is usually given as a script that can be executed in a YACS node.
 991 This script can without difference launch external codes or use internal SALOME
 992 calls and methods. If the algorithm requires the 3 aspects of the operator
 993 (direct form, tangent form and adjoint form), the user has to give the 3
 994 functions or to approximate them.
 995
 996 There are 3 practical methods for the user to provide an operator functional
 997 representation. These methods are chosen in the "*FROM*"  field of each operator
 998 having a "*Function*" value as "*INPUT_TYPE*", as shown by the following figure:
 999
1000   .. eficas_operator_function:
1001   .. image:: images/eficas_operator_function.png
1002     :align: center
1003     :width: 100%
1004   .. centered::
1005     **Choosing an operator functional representation**
1006
1007 First functional form: using "*ScriptWithOneFunction*"
1008 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1009
1010 .. index:: single: ScriptWithOneFunction
1011 .. index:: single: DirectOperator
1012 .. index:: single: DifferentialIncrement
1013 .. index:: single: CenteredFiniteDifference
1014
1015 The first one consist in providing only one potentially non-linear function, and
1016 to approximate the tangent and the adjoint operators. This is done by using the
1017 keyword "*ScriptWithOneFunction*" for the description of the chosen operator in
1018 the ADAO GUI. The user have to provide the function in a script, with a
1019 mandatory name "*DirectOperator*". For example, the script can follow the
1020 template::
1021
1022     def DirectOperator( X ):
1023         """ Direct non-linear simulation operator """
1024         ...
1025         ...
1026         ...
1027         return Y=O(X)
1028
1029 In this case, the user has also provide a value for the differential increment
1030 (or keep the devault value), using through the GUI the keyword
1031 "*DifferentialIncrement*", which has a default value of 1%. This coefficient
1032 will be used in the finite difference approximation to build the tangent and
1033 adjoint operators. The finite difference approximation order can also be chosen
1034 through the GUI, using the keyword "*CenteredFiniteDifference*", with 0 for an
1035 uncentered schema of first order (which is the default value), and with 1 for a
1036 centered schema of second order (of twice the first order computational cost).
1037
1038 This first operator definition form allows easily to test the functional form
1039 before its use in an ADAO case, greatly reducing the complexity of
1040 operator implementation.
1041
1042 **Important warning:** the name "*DirectOperator*" is mandatory, and the type of
1043 the ``X`` argument can be either a list, a numpy array or a numpy 1D-matrix. The
1044 user has to treat these cases in his function.
1045
1046 Second functional form: using "*ScriptWithFunctions*"
1047 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1048
1049 .. index:: single: ScriptWithFunctions
1050 .. index:: single: DirectOperator
1051 .. index:: single: TangentOperator
1052 .. index:: single: AdjointOperator
1053
1054 **In general, it is recommended to use the first functionnal form rather than
1055 the second one. A small performance improvement is not a good reason to use a
1056 detailled implementation as this second functional form.**
1057
1058 The second one consist in providing directly the three associated operators
1059 :math:`O`, :math:`\mathbf{O}` and :math:`\mathbf{O}^*`. This is done by using
1060 the keyword "*ScriptWithFunctions*" for the description of the chosen operator
1061 in the ADAO GUI. The user have to provide three functions in one script, with
1062 three mandatory names "*DirectOperator*", "*TangentOperator*" and
1063 "*AdjointOperator*". For example, the script can follow the template::
1064
1065     def DirectOperator( X ):
1066         """ Direct non-linear simulation operator """
1067         ...
1068         ...
1069         ...
1070         return something like Y
1071
1072     def TangentOperator( (X, dX) ):
1073         """ Tangent linear operator, around X, applied to dX """
1074         ...
1075         ...
1076         ...
1077         return something like Y
1078
1079     def AdjointOperator( (X, Y) ):
1080         """ Adjoint operator, around X, applied to Y """
1081         ...
1082         ...
1083         ...
1084         return something like X
1085
1086 Another time, this second operator definition allow easily to test the
1087 functional forms before their use in an ADAO case, reducing the complexity of
1088 operator implementation.
1089
1090 For some algorithms, it is required that the tangent and adjoint functions can
1091 return the matrix equivalent to the linear operator. In this case, when
1092 respectivly the ``dX`` or the ``Y`` arguments are ``None``, the user has to
1093 return the associated matrix.
1094
1095 **Important warning:** the names "*DirectOperator*", "*TangentOperator*" and
1096 "*AdjointOperator*" are mandatory, and the type of the ``X``, Y``, ``dX``
1097 arguments can be either a python list, a numpy array or a numpy 1D-matrix. The
1098 user has to treat these cases in his script.
1099
1100 Third functional form: using "*ScriptWithSwitch*"
1101 +++++++++++++++++++++++++++++++++++++++++++++++++
1102
1103 .. index:: single: ScriptWithSwitch
1104 .. index:: single: DirectOperator
1105 .. index:: single: TangentOperator
1106 .. index:: single: AdjointOperator
1107
1108 **It is recommended not to use this third functional form without a solid
1109 numerical or physical reason. A performance improvement is not a good reason to
1110 use the implementation complexity of this third functional form. Only an
1111 inability to use the first or second forms justifies the use of the third.**
1112
1113 This third form give more possibilities to control the execution of the three
1114 functions representing the operator, allowing advanced usage and control over
1115 each execution of the simulation code. This is done by using the keyword
1116 "*ScriptWithSwitch*" for the description of the chosen operator in the ADAO GUI.
1117 The user have to provide a switch in one script to control the execution of the
1118 direct, tangent and adjoint forms of its simulation code. The user can then, for
1119 example, use other approximations for the tangent and adjoint codes, or
1120 introduce more complexity in the argument treatment of the functions. But it
1121 will be far more complicated to implement and debug.
1122
1123 If, however, you want to use this third form, we recommend using the following
1124 template for the switch. It requires an external script or code named here
1125 "*Physical_simulation_functions.py*", containing three functions named
1126 "*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously.
1127 Here is the switch template::
1128
1129     import Physical_simulation_functions
1130     import numpy, logging
1131     #
1132     method = ""
1133     for param in computation["specificParameters"]:
1134         if param["name"] == "method":
1135             method = param["value"]
1136     if method not in ["Direct", "Tangent", "Adjoint"]:
1137         raise ValueError("No valid computation method is given")
1138     logging.info("Found method is \'%s\'"%method)
1139     #
1140     logging.info("Loading operator functions")
1141     Function = Physical_simulation_functions.DirectOperator
1142     Tangent  = Physical_simulation_functions.TangentOperator
1143     Adjoint  = Physical_simulation_functions.AdjointOperator
1144     #
1145     logging.info("Executing the possible computations")
1146     data = []
1147     if method == "Direct":
1148         logging.info("Direct computation")
1149         Xcurrent = computation["inputValues"][0][0][0]
1150         data = Function(numpy.matrix( Xcurrent ).T)
1151     if method == "Tangent":
1152         logging.info("Tangent computation")
1153         Xcurrent  = computation["inputValues"][0][0][0]
1154         dXcurrent = computation["inputValues"][0][0][1]
1155         data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
1156     if method == "Adjoint":
1157         logging.info("Adjoint computation")
1158         Xcurrent = computation["inputValues"][0][0][0]
1159         Ycurrent = computation["inputValues"][0][0][1]
1160         data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
1161     #
1162     logging.info("Formatting the output")
1163     it = numpy.ravel(data)
1164     outputValues = [[[[]]]]
1165     for val in it:
1166       outputValues[0][0][0].append(val)
1167     #
1168     result = {}
1169     result["outputValues"]        = outputValues
1170     result["specificOutputInfos"] = []
1171     result["returnCode"]          = 0
1172     result["errorMessage"]        = ""
1173
1174 All various modifications could be done from this template hypothesis.
1175
1176 Special case of controled evolution or observation operator
1177 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1178
1179 In some cases, the evolution or the observation operator is required to be
1180 controled by an external input control, given *a priori*. In this case, the
1181 generic form of the incremental model is slightly modified as follows:
1182
1183 .. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
1184
1185 where :math:`\mathbf{u}` is the control over one state increment. In this case,
1186 the direct operator has to be applied to a pair of variables :math:`(X,U)`.
1187 Schematically, the operator has to be set as::
1188
1189     def DirectOperator( (X, U) ):
1190         """ Direct non-linear simulation operator """
1191         ...
1192         ...
1193         ...
1194         return something like X(n+1) (evolution) or Y(n+1) (observation)
1195
1196 The tangent and adjoint operators have the same signature as previously, noting
1197 that the derivatives has to be done only partially against :math:`\mathbf{x}`.
1198 In such a case with explicit control, only the second functional form (using
1199 "*ScriptWithFunctions*") and third functional form (using "*ScriptWithSwitch*")
1200 can be used.
1201
1202 Requirements to describe covariance matrices
1203 --------------------------------------------
1204
1205 Multiple covariance matrices are required to implement the data assimilation or
1206 optimization procedures. The main ones are the background error covariance
1207 matrix, noted as :math:`\mathbf{B}`, and the observation error covariance matrix,
1208 noted as :math:`\mathbf{R}`. Such a matrix is required to be a squared symetric
1209 semi-definite positive matrix.
1210
1211 There are 3 practical methods for the user to provide a covariance matrix. These
1212 methods are chosen by the "*INPUT_TYPE*" keyword of each defined covariance
1213 matrix, as shown by the following figure:
1214
1215   .. eficas_covariance_matrix:
1216   .. image:: images/eficas_covariance_matrix.png
1217     :align: center
1218     :width: 100%
1219   .. centered::
1220     **Choosing covariance matrix representation**
1221
1222 First matrix form: using "*Matrix*" representation
1223 ++++++++++++++++++++++++++++++++++++++++++++++++++
1224
1225 .. index:: single: Matrix
1226 .. index:: single: BackgroundError
1227 .. index:: single: EvolutionError
1228 .. index:: single: ObservationError
1229
1230 This first form is the default and more general one. The covariance matrix
1231 :math:`\mathbf{M}` has to be fully specified. Even if the matrix is symetric by
1232 nature, the entire :math:`\mathbf{M}` matrix has to be given.
1233
1234 .. math:: \mathbf{M} =  \begin{pmatrix}
1235     m_{11} & m_{12} & \cdots   & m_{1n} \\
1236     m_{21} & m_{22} & \cdots   & m_{2n} \\
1237     \vdots & \vdots & \vdots   & \vdots \\
1238     m_{n1} & \cdots & m_{nn-1} & m_{nn}
1239     \end{pmatrix}
1240
1241 It can be either a Python Numpy array or a matrix, or a list of lists of values
1242 (that is, a list of rows). For example, a simple diagonal unitary background
1243 error covariance matrix :math:`\mathbf{B}` can be described in a Python script
1244 file as::
1245
1246     BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
1247
1248 or::
1249
1250     BackgroundError = numpy.eye(...)
1251
1252 Second matrix form: using "*ScalarSparseMatrix*" representation
1253 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1254
1255 .. index:: single: ScalarSparseMatrix
1256 .. index:: single: BackgroundError
1257 .. index:: single: EvolutionError
1258 .. index:: single: ObservationError
1259
1260 On the opposite, this second form is a very simplified method to provide a
1261 matrix. The covariance matrix :math:`\mathbf{M}` is supposed to be a positive
1262 multiple of the identity matrix. This matrix can then be specified in a unique
1263 way by the multiplier :math:`m`:
1264
1265 .. math:: \mathbf{M} =  m \times \begin{pmatrix}
1266     1       & 0      & \cdots   & 0      \\
1267     0       & 1      & \cdots   & 0      \\
1268     \vdots  & \vdots & \vdots   & \vdots \\
1269     0       & \cdots & 0        & 1
1270     \end{pmatrix}
1271
1272 The multiplier :math:`m` has to be a floating point or integer positive value
1273 (if it is negative, which is impossible for a positive covariance matrix, it is
1274 converted to positive value). For example, a simple diagonal unitary background
1275 error covariance matrix :math:`\mathbf{B}` can be described in a python script
1276 file as::
1277
1278     BackgroundError = 1.
1279
1280 or, better, by a "*String*" directly in the ADAO case.
1281
1282 Third matrix form: using "*DiagonalSparseMatrix*" representation
1283 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1284
1285 .. index:: single: DiagonalSparseMatrix
1286 .. index:: single: BackgroundError
1287 .. index:: single: EvolutionError
1288 .. index:: single: ObservationError
1289
1290 This third form is also a simplified method to provide a matrix, but a little
1291 more powerful than the second one. The covariance matrix :math:`\mathbf{M}` is
1292 already supposed to be diagonal, but the user has to specify all the positive
1293 diagonal values. The matrix can then be specified only by a vector
1294 :math:`\mathbf{V}` which will be set on a diagonal matrix:
1295
1296 .. math:: \mathbf{M} =  \begin{pmatrix}
1297     v_{1}  & 0      & \cdots   & 0      \\
1298     0      & v_{2}  & \cdots   & 0      \\
1299     \vdots & \vdots & \vdots   & \vdots \\
1300     0      & \cdots & 0        & v_{n}
1301     \end{pmatrix}
1302
1303 It can be either a Python Numpy array or a matrix, or a list or a list of list
1304 of positive values (in all cases, if some are negative, which is impossible,
1305 they are converted to positive values). For example, a simple diagonal unitary
1306 background error covariance matrix :math:`\mathbf{B}` can be described in a
1307 python script file as::
1308
1309     BackgroundError = [1, 1 ... 1]
1310
1311 or::
1312
1313     BackgroundError = numpy.ones(...)