..
- Copyright (C) 2008-2014 EDF R&D
+ Copyright (C) 2008-2018 EDF R&D
This file is part of SALOME ADAO module.
point for the variational minimization.
In all cases, it is recommended to prefer the :ref:`section_ref_algorithm_3DVAR`
-for its stability as for its behaviour during optimization.
+for its stability as for its behavior during optimization.
Optional and required commands
++++++++++++++++++++++++++++++
-.. index:: single: Background
-.. index:: single: Observation
-.. index:: single: ObservationError
-.. index:: single: ObservationOperator
-.. index:: single: Minimizer
-.. index:: single: Bounds
-.. index:: single: MaximumNumberOfSteps
-.. index:: single: CostDecrementTolerance
-.. index:: single: ProjectedGradientTolerance
-.. index:: single: GradientNormTolerance
-.. index:: single: StoreInternalVariables
-.. index:: single: StoreSupplementaryCalculations
-
The general required commands, available in the editing user interface, are the
following:
- Background
- *Required command*. This indicates the background or initial vector used,
- previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
- "*Vector*" or a *VectorSerie*" type object.
-
- Observation
- *Required command*. This indicates the observation vector used for data
- assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
- is defined as a "*Vector*" or a *VectorSerie* type object.
-
- ObservationError
- *Required command*. This indicates the observation error covariance matrix,
- previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
- object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
- type object.
-
- ObservationOperator
- *Required command*. This indicates the observation operator, previously
- noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
- results :math:`\mathbf{y}` to be compared to observations
- :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
- a "*Matrix*" type one. In the case of "*Function*" type, different
- functional forms can be used, as described in the section
- :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
- included in the observation, the operator has to be applied to a pair
- :math:`(X,U)`.
+ .. include:: snippets/Background.rst
+
+ .. include:: snippets/Observation.rst
+
+ .. include:: snippets/ObservationError.rst
+
+ .. include:: snippets/ObservationOperator.rst
The general optional commands, available in the editing user interface, are
-indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
-optional command "*AlgorithmParameters*" allows to choose the specific options,
+indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
+of the command "*AlgorithmParameters*" allows to choose the specific options,
described hereafter, of the algorithm. See
-:ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
+:ref:`section_ref_options_Algorithm_Parameters` for the good use of this
+command.
The options of the algorithm are the following:
Minimizer
+ .. index:: single: Minimizer
+
This key allows to choose the optimization minimizer. The default choice is
"LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear
(nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is
strongly recommended to stay with the default.
- Example : ``{"Minimizer":"LBFGSB"}``
-
- Bounds
- This key allows to define upper and lower bounds for every state variable
- being optimized. Bounds have to be given by a list of list of pairs of
- lower/upper bounds for each variable, with possibly ``None`` every time
- there is no bound. The bounds can always be specified, but they are taken
- into account only by the constrained optimizers.
-
- Example : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,None],[None,None]]}``
-
- MaximumNumberOfSteps
- This key indicates the maximum number of iterations allowed for iterative
- optimization. The default is 15000, which is very similar to no limit on
- iterations. It is then recommended to adapt this parameter to the needs on
- real problems. For some optimizers, the effective stopping step can be
- slightly different due to algorithm internal control requirements.
-
- Example : ``{"MaximumNumberOfSteps":100}``
+ Example :
+ ``{"Minimizer":"LBFGSB"}``
- CostDecrementTolerance
- This key indicates a limit value, leading to stop successfully the
- iterative optimization process when the cost function decreases less than
- this tolerance at the last step. The default is 1.e-7, and it is
- recommended to adapt it to the needs on real problems.
+ .. include:: snippets/BoundsWithNone.rst
- Example : ``{"CostDecrementTolerance":1.e-7}``
+ .. include:: snippets/MaximumNumberOfSteps.rst
- ProjectedGradientTolerance
- This key indicates a limit value, leading to stop successfully the iterative
- optimization process when all the components of the projected gradient are
- under this limit. It is only used for constrained optimizers. The default is
- -1, that is the internal default of each minimizer (generally 1.e-5), and it
- is not recommended to change it.
+ .. include:: snippets/CostDecrementTolerance.rst
- Example : ``{"ProjectedGradientTolerance":-1}``
+ .. include:: snippets/ProjectedGradientTolerance.rst
- GradientNormTolerance
- This key indicates a limit value, leading to stop successfully the
- iterative optimization process when the norm of the gradient is under this
- limit. It is only used for non-constrained optimizers. The default is
- 1.e-5 and it is not recommended to change it.
-
- Example : ``{"GradientNormTolerance":1.e-5}``
-
- StoreInternalVariables
- This Boolean key allows to store default internal variables, mainly the
- current state during iterative optimization process. Be careful, this can be
- a numerically costly choice in certain calculation cases. The default is
- "False".
-
- Example : ``{"StoreInternalVariables":True}``
+ .. include:: snippets/GradientNormTolerance.rst
StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
+
This list indicates the names of the supplementary variables that can be
available at the end of the algorithm. It involves potentially costly
calculations or memory consumptions. The default is a void list, none of
these variables being calculated and stored by default. The possible names
- are in the following list: ["BMA", "OMA", "OMB", "Innovation"].
+ are in the following list: ["BMA", "CostFunctionJ",
+ "CostFunctionJb", "CostFunctionJo", "CostFunctionJAtCurrentOptimum",
+ "CostFunctionJbAtCurrentOptimum", "CostFunctionJoAtCurrentOptimum",
+ "CurrentState", "CurrentOptimum", "IndexOfOptimum", "Innovation",
+ "InnovationAtCurrentState", "OMA", "OMB",
+ "SimulatedObservationAtBackground", "SimulatedObservationAtCurrentState",
+ "SimulatedObservationAtOptimum", "SimulatedObservationAtCurrentOptimum"].
- Example : ``{"StoreSupplementaryCalculations":["BMA","Innovation"]}``
+ Example :
+ ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
*Tips for this algorithm:*
command is not required for this algorithm, and will not be used. The
simplest way is to give "1" as a STRING.
+Information and variables available at the end of the algorithm
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+At the output, after executing the algorithm, there are variables and
+information originating from the calculation. The description of
+:ref:`section_ref_output_variables` show the way to obtain them by the method
+named ``get`` of the variable "*ADD*" of the post-processing. The input
+variables, available to the user at the output in order to facilitate the
+writing of post-processing procedures, are described in the
+:ref:`subsection_r_o_v_Inventaire`.
+
+The unconditional outputs of the algorithm are the following:
+
+ .. include:: snippets/Analysis.rst
+
+ .. include:: snippets/CostFunctionJ.rst
+
+ .. include:: snippets/CostFunctionJb.rst
+
+ .. include:: snippets/CostFunctionJo.rst
+
+The conditional outputs of the algorithm are the following:
+
+ .. include:: snippets/BMA.rst
+
+ .. include:: snippets/CostFunctionJAtCurrentOptimum.rst
+
+ .. include:: snippets/CostFunctionJbAtCurrentOptimum.rst
+
+ .. include:: snippets/CostFunctionJoAtCurrentOptimum.rst
+
+ .. include:: snippets/CurrentOptimum.rst
+
+ .. include:: snippets/CurrentState.rst
+
+ .. include:: snippets/IndexOfOptimum.rst
+
+ .. include:: snippets/Innovation.rst
+
+ .. include:: snippets/InnovationAtCurrentState.rst
+
+ .. include:: snippets/OMA.rst
+
+ .. include:: snippets/OMB.rst
+
+ .. include:: snippets/SimulatedObservationAtBackground.rst
+
+ .. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
+
+ .. include:: snippets/SimulatedObservationAtCurrentState.rst
+
+ .. include:: snippets/SimulatedObservationAtOptimum.rst
+
See also
++++++++
Bibliographical references:
- [Byrd95]_
- [Morales11]_
+ - [Zhu97]_
