..
- Copyright (C) 2008-2014 EDF R&D
+ Copyright (C) 2008-2017 EDF R&D
This file is part of SALOME ADAO module.
for an priori given states sample. The default error function is the augmented
weighted least squares function, classicaly used in data assimilation.
-This is a useful algorithm to test the sensitivity, of the error function
-:math:`J` in particular, to the state :math:`\mathbf{x}` variations. When a
-state is not observable, a *"NaN"* value is returned.
+It is useful to test the sensitivity, of the error function :math:`J`, in
+particular, to the state :math:`\mathbf{x}` variations. When a state is not
+observable, a *"NaN"* value is returned.
The sampling of the states :math:`\mathbf{x}` can be given explicitly or under
-the form of hypercubes.
+the form of hyper-cubes, explicit or sampled using classic distributions. Be
+careful to the size of the hyper-cube (and then to the number of calculations)
+that can be reached, it can be big very quickly.
+
+To be visible by the user, the results of sampling has to be explicitly asked
+for. One use for that, on the desired variable, the final saving through
+"*UserPostAnalysis*" or the treatment during the calculation by "*observer*".
+
+To perform distributed or more complex sampling, see other modules available in
+SALOME : PARAMETRIC or OPENTURNS.
Optional and required commands
++++++++++++++++++++++++++++++
+.. index:: single: AlgorithmParameters
.. index:: single: CheckingPoint
.. index:: single: BackgroundError
.. index:: single: Observation
.. index:: single: SampleAsnUplet
.. index:: single: SampleAsExplicitHyperCube
.. index:: single: SampleAsMinMaxStepHyperCube
+.. index:: single: SampleAsIndependantRandomVariables
.. index:: single: QualityCriterion
.. index:: single: SetDebug
+.. index:: single: SetSeed
.. index:: single: StoreSupplementaryCalculations
The general required commands, available in the editing user interface, are the
:math:`(X,U)`.
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*" allow 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:
Example : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
SampleAsExplicitHyperCube
- This key describes the calculations points as an hypercube, from which one
- gives the list of sampling of each variable as a list. That is then a list
- of lists, each of them being potentially of different size.
+ This key describes the calculations points as an hyper-cube, from a given
+ list of explicit sampling of each variable as a list. That is then a list of
+ lists, each of them being potentially of different size.
- Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2
+ Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2
SampleAsMinMaxStepHyperCube
- This key describes the calculations points as an hypercube from which one
- the sampling of each variable by a triplet *[min,max,step]*. That is then a
- list of the same size than the one of the state. The bounds are included.
+ This key describes the calculations points as an hyper-cube, from a given
+ list of implicit sampling of each variable by a triplet *[min,max,step]*.
+ That is then a list of the same size than the one of the state. The bounds
+ are included.
Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
+ SampleAsIndependantRandomVariables
+ This key describes the calculations points as an hyper-cube, for which the
+ points on each axis come from a independant random sampling of the axis
+ variable, under the specification of the distribution, its parameters and
+ the number of points in the sample, as a list ``['distribution',
+ [parametres], nombre]`` for each axis. The possible distributions are
+ 'normal' of parameters (mean,std), 'lognormal' of parameters (mean,sigma),
+ 'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That
+ is then a list of the same size than the one of the state.
+
+ Example : ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2
+
QualityCriterion
This key indicates the quality criterion, used to find the state estimate.
The default is the usual data assimilation criterion named "DA", the
Example : ``{"SetDebug":False}``
+ SetSeed
+ This key allow to give an integer in order to fix the seed of the random
+ generator used to generate the ensemble. A convenient value is for example
+ 1000. By default, the seed is left uninitialized, and so use the default
+ initialization from the computer.
+
+ Example : ``{"SetSeed":1000}``
+
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: ["CostFunctionJ", "CurrentState", "Innovation",
- "ObservedState"].
+ are in the following list: ["CostFunctionJ", "CostFunctionJb",
+ "CostFunctionJo", "CurrentState", "InnovationAtCurrentState",
+ "SimulatedObservationAtCurrentState"].
+
+ Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
+
+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:
+
+ CostFunctionJ
+ *List of values*. Each element is a value of the error function :math:`J`.
+
+ Example : ``J = ADD.get("CostFunctionJ")[:]``
- Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "ObservedState"]}``
+ CostFunctionJb
+ *List of values*. Each element is a value of the error function :math:`J^b`,
+ that is of the background difference part.
+
+ Example : ``Jb = ADD.get("CostFunctionJb")[:]``
+
+ CostFunctionJo
+ *List of values*. Each element is a value of the error function :math:`J^o`,
+ that is of the observation difference part.
+
+ Example : ``Jo = ADD.get("CostFunctionJo")[:]``
+
+The conditional outputs of the algorithm are the following:
+
+ CurrentState
+ *List of vectors*. Each element is a usual state vector used during the
+ optimization algorithm procedure.
+
+ Example : ``Xs = ADD.get("CurrentState")[:]``
+
+ InnovationAtCurrentState
+ *List of vectors*. Each element is an innovation vector at current state.
+
+ Example : ``ds = ADD.get("InnovationAtCurrentState")[-1]``
+
+ SimulatedObservationAtCurrentState
+ *List of vectors*. Each element is an observed vector at the current state,
+ that is, in the observation space.
+
+ Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
See also
++++++++
References to other sections:
- :ref:`section_ref_algorithm_FunctionTest`
+
+References to other SALOME modules:
+ - PARAMETRIC, see the *User guide of PARAMETRIC module* in the main "*Help*" menu of SALOME platform
+ - OPENTURNS, see the *User guide of OPENTURNS module* in the main "*Help*" menu of SALOME platform
