doc/reference.rst

   1 .. _section_reference:
   2
   3 ================================================================================
   4 Reference description of the ADAO commands and keywords
   5 ================================================================================
   6
   7
   8 This section presents the reference description of the commands and keywords
   9 available through the GUI or through scripts.
  10
  11 Each command or keyword to be defined through the ADAO GUI has some properties.
  12 The first property is to be a required command, an optional command or a keyword
  13 describing a type of input. The second property is to be an "open" variable with
  14 a fixed type but with any value allowed by the type, or a "restricted" variable,
  15 limited to some specified values. The mathematical notations used afterwards are
  16 explained in the section :ref:`section_theory`.
  17
  18 List of possible input types
  19 ++++++++++++++++++++++++++++
  20
  21 .. index:: single: Dict
  22 .. index:: single: Function
  23 .. index:: single: Matrix
  24 .. index:: single: String
  25 .. index:: single: Script
  26 .. index:: single: Vector
  27
  28 The different type-style commands are:
  29
  30 :Dict:
  31     *Type of an input*. This indicates a variable that has to be filled by a
  32     dictionary, usually given as a script.
  33
  34 :Function:
  35     *Type of an input*. This indicates a variable that has to be filled by a
  36     function, usually given as a script.
  37
  38 :Matrix:
  39     *Type of an input*. This indicates a variable that has to be filled by a
  40     matrix, usually given either as a string or as a script.
  41
  42 :String:
  43     *Type of an input*. This indicates a string, such as a name or a literal
  44     representation of a matrix or vector, such as "1 2 ; 3 4".
  45
  46 :Script:
  47     *Type of an input*. This indicates a script given as an external file.
  48
  49 :Vector:
  50     *Type of an input*. This indicates a variable that has to be filled by a
  51     vector, usually given either as a string or as a script.
  52
  53 List of commands
  54 ++++++++++++++++
  55
  56 .. index:: single: ASSIMILATION_STUDY
  57 .. index:: single: Algorithm
  58 .. index:: single: AlgorithmParameters
  59 .. index:: single: Background
  60 .. index:: single: BackgroundError
  61 .. index:: single: Debug
  62 .. index:: single: InputVariables
  63 .. index:: single: Observation
  64 .. index:: single: ObservationError
  65 .. index:: single: ObservationOperator
  66 .. index:: single: Observers
  67 .. index:: single: OutputVariables
  68 .. index:: single: Study_name
  69 .. index:: single: Study_repertory
  70 .. index:: single: UserDataInit
  71 .. index:: single: UserPostAnalysis
  72
  73 The different commands are the following:
  74
  75 :ASSIMILATION_STUDY:
  76     *Required command*. This is the general command describing an ADAO case. It
  77     hierarchicaly contains all the other commands.
  78
  79 :Algorithm:
  80     *Required command*. This is a string to indicates the data assimilation
  81     algorithm chosen. The choices are limited and available through the GUI.
  82     There exists for example: "3DVAR", "Blue"... See below the list of
  83     algorithms and associated parameters.
  84
  85 :AlgorithmParameters:
  86     *Optional command*. This command allows to add some optional parameters to
  87     control the data assimilation algorithm calculation. It is defined as a
  88     "*Dict*" type object.  See below the list of algorithms and associated
  89     parameters.
  90
  91 :Background:
  92     *Required command*. This indicates the backgroud vector used for data
  93     assimilation, previously noted as :math:`\mathbf{x}^b`. It is defined as a
  94     "*Vector*" type object, that is, given either as a string or as a script.
  95
  96 :BackgroundError:
  97     *Required command*. This indicates the backgroud error covariance matrix,
  98     previously noted as :math:`\mathbf{B}`.It is defined as a "*Matrix*" type
  99     object, that is, given either as a string or as a script.
 100
 101 :Debug:
 102     *Required command*. This let choose the level of trace and intermediary
 103     debug informations. The choices are limited between 0 (for False) and 1 (for
 104     True) and available through the GUI.
 105
 106 :InputVariables:
 107     *Optional command*. This command allows to indicates the name and size of
 108     physical variables that are bundled together in the control vector. This
 109     information is dedicated to data processed inside of data assimilation
 110     algorithm.
 111
 112 :Observation:
 113     *Required command*. This indicates the observation vector used for data
 114     assimilation, previously noted as :math:`\mathbf{y}^o`. It is defined as a
 115     "*Vector*" type object, that is, given either as a string or as a script.
 116
 117 :ObservationError:
 118     *Required command*. This indicates the observation error covariance matrix,
 119     previously noted as :math:`\mathbf{R}`.It is defined as a "*Matrix*" type
 120     object, that is, given either as a string or as a script.
 121
 122 :ObservationOperator:
 123     *Required command*. This indicates the observation operator, previously
 124     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}`
 125     to results :math:`\mathbf{y}` to be compared to observations
 126     :math:`\mathbf{y}^o`.
 127
 128 :Observers:
 129     *Optional command*. This command allows to set internal observers, that are
 130     functions linked with a particular variable, which will be executed each
 131     time this variable is modified. It is a convenient way to monitor interest
 132     variables during the data assimilation process, by printing or plotting it,
 133     etc.
 134
 135 :OutputVariables:
 136     *Optional command*. This command allows to indicates the name and size of
 137     physical variables that are bundled together in the output observation
 138     vector. This information is dedicated to data processed inside of data
 139     assimilation algorithm.
 140
 141 :Study_name:
 142     *Required command*. This is an open string to describe the study by a name
 143     or a sentence.
 144
 145 :Study_repertory:
 146     *Optional command*. If available, this repertory is used to find all the
 147     script files that can be used to define some other commands by scripts.
 148
 149 :UserDataInit:
 150     *Optional command*. This commands allows to initialise some parameters or
 151     data automatically before data assimilation algorithm processing.
 152
 153 :UserPostAnalysis:
 154     *Optional command*. This commands allows to process some parameters or data
 155     automatically after data assimilation algorithm processing. It is defined as
 156     a script or a string, allowing to put simple code directly inside the ADAO
 157     case.
 158
 159 .. _subsection_algo_options:
 160
 161 List of possible options for the algorithms
 162 +++++++++++++++++++++++++++++++++++++++++++
 163
 164 .. index:: single: Blue
 165 .. index:: single: LinearLeastSquares
 166 .. index:: single: 3DVAR
 167 .. index:: single: NonLinearLeastSquares
 168 .. index:: single: EnsembleBlue
 169 .. index:: single: QuantileRegression
 170
 171 .. index:: single: AlgorithmParameters
 172 .. index:: single: Minimizer
 173 .. index:: single: Bounds
 174 .. index:: single: MaximumNumberOfSteps
 175 .. index:: single: CalculateAPosterioriCovariance
 176 .. index:: single: CostDecrementTolerance
 177 .. index:: single: ProjectedGradientTolerance
 178 .. index:: single: GradientNormTolerance
 179 .. index:: single: SetSeed
 180 .. index:: single: Quantile
 181
 182 Each algorithm can be controled using some generic or specific options given
 183 throught the "*AlgorithmParameters*" optional command, as follows::
 184
 185     AlgorithmParameters = {
 186         "Minimizer" : "CG",
 187         "MaximumNumberOfSteps" : 10,
 188         }
 189
 190 This section describes the available options by algorithm. If an option is
 191 specified for an algorithm that doesn't support it, the option is simply left
 192 unused.
 193
 194 :"Blue":
 195
 196     :CalculateAPosterioriCovariance:
 197       This boolean key allows to enable the calculation and the storage of the
 198       covariance matrix of a posteriori anlysis errors. Be careful, this is a
 199       numericaly costly step. The default is "False".
 200
 201 :"LinearLeastSquares":
 202     no option
 203
 204 :"3DVAR":
 205
 206     :Minimizer:
 207       This key allows to choose the optimization minimizer. The default choice
 208       is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
 209       minimizer, see [Byrd95]_ and [Zhu97]_), "TNC" (nonlinear constrained
 210       minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
 211       unconstrained minimizer), "NCG" (Newton CG minimizer).
 212
 213     :Bounds:
 214       This key allows to define upper and lower bounds for every control
 215       variable being optimized. Bounds can be given by a list of list of pairs
 216       of lower/upper bounds for each variable, with possibly ``None`` every time
 217       there is no bound. The bounds can always be specified, but they are taken
 218       into account only by the constrained minimizers.
 219
 220     :MaximumNumberOfSteps:
 221       This key indicates the maximum number of iterations allowed for iterative
 222       optimization. The default is 15000, which very similar to no limit on
 223       iterations. It is then recommended to adapt this parameter to the needs on
 224       real problems. For some minimizers, the effective stopping step can be
 225       slightly different due to algorihtm internal control requirements.
 226
 227     :CalculateAPosterioriCovariance:
 228       This boolean key allows to enable the calculation and the storage of the
 229       covariance matrix of a posteriori anlysis errors. Be careful, this is a
 230       numericaly costly step. The default is "False".
 231
 232     :CostDecrementTolerance:
 233       This key indicates a limit value, leading to stop successfully the
 234       iterative optimization process when the cost function decreases less than
 235       this tolerance at the last step. The default is 10e-7, and it is
 236       recommended to adapt it the needs on real problems.
 237
 238     :ProjectedGradientTolerance:
 239       This key indicates a limit value, leading to stop successfully the
 240       iterative optimization process when all the components of the projected
 241       gradient are under this limit. It is only used for constrained algorithms.
 242       The default is -1, that is the internal default of each algorithm, and it
 243       is not recommended to change it.
 244
 245     :GradientNormTolerance:
 246       This key indicates a limit value, leading to stop successfully the
 247       iterative optimization process when the norm of the gradient is under this
 248       limit. It is only used for non-constrained algorithms.  The default is
 249       10e-5 and it is not recommended to change it.
 250
 251 :"NonLinearLeastSquares":
 252
 253     :Minimizer:
 254       This key allows to choose the optimization minimizer. The default choice
 255       is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
 256       minimizer, see [Byrd95]_ and [Zhu97]_), "TNC" (nonlinear constrained
 257       minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
 258       unconstrained minimizer), "NCG" (Newton CG minimizer).
 259
 260     :Bounds:
 261       This key allows to define upper and lower bounds for every control
 262       variable being optimized. Bounds can be given by a list of list of pairs
 263       of lower/upper bounds for each variable, with possibly ``None`` every time
 264       there is no bound. The bounds can always be specified, but they are taken
 265       into account only by the constrained minimizers.
 266
 267     :MaximumNumberOfSteps:
 268       This key indicates the maximum number of iterations allowed for iterative
 269       optimization. The default is 15000, which very similar to no limit on
 270       iterations. It is then recommended to adapt this parameter to the needs on
 271       real problems. For some minimizers, the effective stopping step can be
 272       slightly different due to algorihtm internal control requirements.
 273
 274     :CostDecrementTolerance:
 275       This key indicates a limit value, leading to stop successfully the
 276       iterative optimization process when the cost function decreases less than
 277       this tolerance at the last step. The default is 10e-7, and it is
 278       recommended to adapt it the needs on real problems.
 279
 280     :ProjectedGradientTolerance:
 281       This key indicates a limit value, leading to stop successfully the
 282       iterative optimization process when all the components of the projected
 283       gradient are under this limit. It is only used for constrained algorithms.
 284       The default is -1, that is the internal default of each algorithm, and it
 285       is not recommended to change it.
 286
 287     :GradientNormTolerance:
 288       This key indicates a limit value, leading to stop successfully the
 289       iterative optimization process when the norm of the gradient is under this
 290       limit. It is only used for non-constrained algorithms.  The default is
 291       10e-5 and it is not recommended to change it.
 292
 293 :"EnsembleBlue":
 294
 295     :SetSeed:
 296       This key allow to give an integer in order to fix the seed of the random
 297       generator used to generate the ensemble. A convenient value is for example
 298       1000. By default, the seed is left uninitialized, and so use the default
 299       initialization from the computer.
 300
 301 :"QuantileRegression":
 302
 303     :Quantile:
 304       This key allows to define the real value of the desired quantile, between
 305       0 and 1. The default is 0.5, corresponding to the median.
 306
 307     :Minimizer:
 308       This key allows to choose the optimization minimizer. The default choice
 309       and only available choice is "MMQR" (Majorize-Minimize for Quantile
 310       Regression).
 311
 312     :MaximumNumberOfSteps:
 313       This key indicates the maximum number of iterations allowed for iterative
 314       optimization. The default is 15000, which very similar to no limit on
 315       iterations. It is then recommended to adapt this parameter to the needs on
 316       real problems.
 317
 318     :CostDecrementTolerance:
 319       This key indicates a limit value, leading to stop successfully the
 320       iterative optimization process when the cost function or the surrogate
 321       decreases less than this tolerance at the last step. The default is 10e-6,
 322       and it is recommended to adapt it the needs on real problems.
 323
 324 Examples of using these commands are available in the section
 325 :ref:`section_examples` and in example files installed with ADAO module.