3 ================================================================================
4 Reference description of the ADAO commands and keywords
5 ================================================================================
8 This section presents the reference description of the commands and keywords
9 available through the GUI or through scripts.
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`.
18 List of possible input types
19 ++++++++++++++++++++++++++++
21 .. index:: single: Dict
22 .. index:: single: Function
23 .. index:: single: Matrix
24 .. index:: single: String
25 .. index:: single: Script
26 .. index:: single: Vector
28 The different type-style commands are:
31 *Type of an input*. This indicates a variable that has to be filled by a
32 dictionary, usually given as a script.
35 *Type of an input*. This indicates a variable that has to be filled by a
36 function, usually given as a script.
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.
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".
47 *Type of an input*. This indicates a script given as an external file.
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.
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
73 The different commands are the following:
76 *Required command*. This is the general command describing an ADAO case. It
77 hierarchicaly contains all the other commands.
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.
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
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.
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.
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.
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
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.
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.
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`.
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,
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.
142 *Required command*. This is an open string to describe the study by a name
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.
150 *Optional command*. This commands allows to initialise some parameters or
151 data automatically before data assimilation algorithm processing.
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
159 .. _subsection_algo_options:
161 List of possible options for the algorithms
162 +++++++++++++++++++++++++++++++++++++++++++
164 .. index:: single: Blue
165 .. index:: single: LinearLeastSquares
166 .. index:: single: 3DVAR
167 .. index:: single: NonLinearLeastSquares
168 .. index:: single: EnsembleBlue
169 .. index:: single: QuantileRegression
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
182 Each algorithm can be controled using some generic or specific options given
183 throught the "*AlgorithmParameters*" optional command, as follows::
185 AlgorithmParameters = {
187 "MaximumNumberOfSteps" : 10,
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
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".
201 :"LinearLeastSquares":
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).
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.
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.
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".
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.
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.
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.
251 :"NonLinearLeastSquares":
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).
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.
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.
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.
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.
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.
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.
301 :"QuantileRegression":
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.
308 This key allows to choose the optimization minimizer. The default choice
309 and only available choice is "MMQR" (Majorize-Minimize for Quantile
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
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.
324 Examples of using these commands are available in the section
325 :ref:`section_examples` and in example files installed with ADAO module.