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 This is a useful algorithm to test the sensitivity, of the error function
  40 :math:`J` in particular, to the state :math:`\mathbf{x}` variations. When a
  41 state is not 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 hypercubes.
  45
  46 Optional and required commands
  47 ++++++++++++++++++++++++++++++
  48
  49 .. index:: single: CheckingPoint
  50 .. index:: single: BackgroundError
  51 .. index:: single: Observation
  52 .. index:: single: ObservationError
  53 .. index:: single: ObservationOperator
  54 .. index:: single: SampleAsnUplet
  55 .. index:: single: SampleAsExplicitHyperCube
  56 .. index:: single: SampleAsMinMaxStepHyperCube
  57 .. index:: single: QualityCriterion
  58 .. index:: single: SetDebug
  59 .. index:: single: StoreSupplementaryCalculations
  60
  61 The general required commands, available in the editing user interface, are the
  62 following:
  63
  64   CheckingPoint
  65     *Required command*. This indicates the vector used as the state around which
  66     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  67     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  68
  69   BackgroundError
  70     *Required command*. This indicates the background error covariance matrix,
  71     previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
  72     type object, a "*ScalarSparseMatrix*" type object, or a
  73     "*DiagonalSparseMatrix*" type object.
  74
  75   Observation
  76     *Required command*. This indicates the observation vector used for data
  77     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
  78     is defined as a "*Vector*" or a *VectorSerie* type object.
  79
  80   ObservationError
  81     *Required command*. This indicates the observation error covariance matrix,
  82     previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
  83     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
  84     type object.
  85
  86   ObservationOperator
  87     *Required command*. This indicates the observation operator, previously
  88     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  89     results :math:`\mathbf{y}` to be compared to observations
  90     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  91     a "*Matrix*" type one. In the case of "*Function*" type, different
  92     functional forms can be used, as described in the section
  93     :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
  94     included in the observation, the operator has to be applied to a pair
  95     :math:`(X,U)`.
  96
  97 The general optional commands, available in the editing user interface, are
  98 indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
  99 optional command "*AlgorithmParameters*" allows to choose the specific options,
 100 described hereafter, of the algorithm. See
 101 :ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
 102
 103 The options of the algorithm are the following:
 104
 105   SampleAsnUplet
 106     This key describes the calculations points as a list of n-uplets, each
 107     n-uplet being a state.
 108
 109     Example : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` for 3 points in a state space of dimension 4
 110
 111   SampleAsExplicitHyperCube
 112     This key describes the calculations points as an hypercube, from which one
 113     gives the list of sampling of each variable as a list. That is then a list
 114     of lists, each of them being potentially of different size.
 115
 116     Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2
 117
 118   SampleAsMinMaxStepHyperCube
 119     This key describes the calculations points as an hypercube from which one
 120     the sampling of each variable by a triplet *[min,max,step]*. That is then a
 121     list of the same size than the one of the state. The bounds are included.
 122
 123     Example : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` for a state space of dimension 2
 124
 125   QualityCriterion
 126     This key indicates the quality criterion, used to find the state estimate.
 127     The default is the usual data assimilation criterion named "DA", the
 128     augmented weighted least squares. The possible criteria has to be in the
 129     following list, where the equivalent names are indicated by the sign "=":
 130     ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS",
 131     "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"].
 132
 133     Example : ``{"QualityCriterion":"DA"}``
 134
 135   SetDebug
 136     This key requires the activation, or not, of the debug mode during the
 137     function evaluation. The default is "True", the choices are "True" or
 138     "False".
 139
 140     Example : ``{"SetDebug":False}``
 141
 142   StoreSupplementaryCalculations
 143     This list indicates the names of the supplementary variables that can be
 144     available at the end of the algorithm. It involves potentially costly
 145     calculations or memory consumptions. The default is a void list, none of
 146     these variables being calculated and stored by default. The possible names
 147     are in the following list: ["CostFunctionJ", "CurrentState", "Innovation",
 148     "ObservedState"].
 149
 150     Example : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "ObservedState"]}``
 151
 152 See also
 153 ++++++++
 154
 155 References to other sections:
 156   - :ref:`section_ref_algorithm_FunctionTest`