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