doc/en/ref_algorithm_SamplingTest.rst

   1 ..
   2    Copyright (C) 2008-2014 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. index:: single: SamplingTest
  25 .. _section_ref_algorithm_SamplingTest:
  26
  27 Checking algorithm "*SamplingTest*"
  28 -----------------------------------
  29
  30 Description
  31 +++++++++++
  32
  33 This algorithm allows to calculate the values, linked to a :math:`\mathbf{x}`
  34 state, of a general error function :math:`J` of type :math:`L^1`, :math:`L^2` or
  35 :math:`L^{\infty}`, with or without weights, and of the observation operator,
  36 for an priori given states sample. The default error function is the augmented
  37 weighted least squares function, classicaly used in data assimilation.
  38
  39 It is useful to test the sensitivity, of the error function :math:`J`, in
  40 particular, to the state :math:`\mathbf{x}` variations. When a state is not
  41 observable, a *"NaN"* value is returned.
  42
  43 The sampling of the states :math:`\mathbf{x}` can be given explicitly or under
  44 the form of hyper-cubes, explicit or sampled. Be careful to the size of the
  45 hyper-cube (and then to the number of calculations) that can be reached, it can
  46 be big very quickly.
  47
  48 Optional and required commands
  49 ++++++++++++++++++++++++++++++
  50
  51 .. index:: single: CheckingPoint
  52 .. index:: single: BackgroundError
  53 .. index:: single: Observation
  54 .. index:: single: ObservationError
  55 .. index:: single: ObservationOperator
  56 .. index:: single: SampleAsnUplet
  57 .. index:: single: SampleAsExplicitHyperCube
  58 .. index:: single: SampleAsMinMaxStepHyperCube
  59 .. index:: single: SampleAsIndependantRandomVariables
  60 .. index:: single: QualityCriterion
  61 .. index:: single: SetDebug
  62 .. index:: single: SetSeed
  63 .. index:: single: StoreSupplementaryCalculations
  64
  65 The general required commands, available in the editing user interface, are the
  66 following:
  67
  68   CheckingPoint
  69     *Required command*. This indicates the vector used as the state around which
  70     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  71     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  72
  73   BackgroundError
  74     *Required command*. This indicates the background error covariance matrix,
  75     previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
  76     type object, a "*ScalarSparseMatrix*" type object, or a
  77     "*DiagonalSparseMatrix*" type object.
  78
  79   Observation
  80     *Required command*. This indicates the observation vector used for data
  81     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
  82     is defined as a "*Vector*" or a *VectorSerie* type object.
  83
  84   ObservationError
  85     *Required command*. This indicates the observation error covariance matrix,
  86     previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
  87     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
  88     type object.
  89
  90   ObservationOperator
  91     *Required command*. This indicates the observation operator, previously
  92     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  93     results :math:`\mathbf{y}` to be compared to observations
  94     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  95     a "*Matrix*" type one. In the case of "*Function*" type, different
  96     functional forms can be used, as described in the section
  97     :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
  98     included in the observation, the operator has to be applied to a pair
  99     :math:`(X,U)`.
 100
 101 The general optional commands, available in the editing user interface, are
 102 indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
 103 optional command "*AlgorithmParameters*" allows to choose the specific options,
 104 described hereafter, of the algorithm. See
 105 :ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
 106
 107 The options of the algorithm are the following:
 108
 109   SampleAsnUplet
 110     This key describes the calculations points as a list of n-uplets, each
 111     n-uplet being a state.
 112
 113     Example : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
 114
 115   SampleAsExplicitHyperCube
 116     This key describes the calculations points as an hyper-cube, from a given
 117     list of explicit sampling of each variable as a list. That is then a list of
 118     lists, each of them being potentially of different size.
 119
 120     Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2
 121
 122   SampleAsMinMaxStepHyperCube
 123     This key describes the calculations points as an hyper-cube, from a given
 124     list of implicit sampling of each variable by a triplet *[min,max,step]*.
 125     That is then a list of the same size than the one of the state. The bounds
 126     are included.
 127
 128     Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
 129
 130   SampleAsIndependantRandomVariables
 131     This key describes the calculations points as an hyper-cube, for which the
 132     points on each axis come from a independant random sampling of the axis
 133     variable, under the specification of the distribution, its parameters and
 134     the number of points in the sample, as a list ``['distribution',
 135     [parametres], nombre]`` for each axis. The possible distributions are
 136     'normal' of parameters (mean,std), 'lognormal' of parameters (mean,sigma),
 137     'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That
 138     is then a list of the same size than the one of the state.
 139
 140     Example : ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3],['uniform',[-2,2],4]]`` for a state space of dimension 2
 141
 142   QualityCriterion
 143     This key indicates the quality criterion, used to find the state estimate.
 144     The default is the usual data assimilation criterion named "DA", the
 145     augmented weighted least squares. The possible criteria has to be in the
 146     following list, where the equivalent names are indicated by the sign "=":
 147     ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS",
 148     "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"].
 149
 150     Example : ``{"QualityCriterion":"DA"}``
 151
 152   SetDebug
 153     This key requires the activation, or not, of the debug mode during the
 154     function evaluation. The default is "True", the choices are "True" or
 155     "False".
 156
 157     Example : ``{"SetDebug":False}``
 158
 159   SetSeed
 160     This key allow to give an integer in order to fix the seed of the random
 161     generator used to generate the ensemble. A convenient value is for example
 162     1000. By default, the seed is left uninitialized, and so use the default
 163     initialization from the computer.
 164
 165     Example : ``{"SetSeed":1000}``
 166
 167   StoreSupplementaryCalculations
 168     This list indicates the names of the supplementary variables that can be
 169     available at the end of the algorithm. It involves potentially costly
 170     calculations or memory consumptions. The default is a void list, none of
 171     these variables being calculated and stored by default. The possible names
 172     are in the following list: ["CostFunctionJ", "CurrentState", "Innovation",
 173     "ObservedState"].
 174
 175     Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "ObservedState"]}``
 176
 177 See also
 178 ++++++++
 179
 180 References to other sections:
 181   - :ref:`section_ref_algorithm_FunctionTest`