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 the data assimilation error function :math:`J` and of the observation
  35 operator, for an priori given states sample. This is a useful algorithm to test
  36 the sensitivity, of the error function :math:`J` in particular, to the state
  37 :math:`\mathbf{x}` variations. When a state is not observable, a *"NaN"* value
  38 is returned.
  39
  40 The sampling of the states :math:`\mathbf{x}` can be given explicitly or under
  41 the form of hypercubes.
  42
  43 Optional and required commands
  44 ++++++++++++++++++++++++++++++
  45
  46 .. index:: single: CheckingPoint
  47 .. index:: single: BackgroundError
  48 .. index:: single: Observation
  49 .. index:: single: ObservationError
  50 .. index:: single: ObservationOperator
  51 .. index:: single: SampleAsnUplet
  52 .. index:: single: SampleAsExplicitHyperCube
  53 .. index:: single: SampleAsMinMaxStepHyperCube
  54 .. index:: single: SetDebug
  55 .. index:: single: StoreSupplementaryCalculations
  56
  57 The general required commands, available in the editing user interface, are the
  58 following:
  59
  60   CheckingPoint
  61     *Required command*. This indicates the vector used as the state around which
  62     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  63     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  64
  65   BackgroundError
  66     *Required command*. This indicates the background error covariance matrix,
  67     previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
  68     type object, a "*ScalarSparseMatrix*" type object, or a
  69     "*DiagonalSparseMatrix*" type object.
  70
  71   Observation
  72     *Required command*. This indicates the observation vector used for data
  73     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
  74     is defined as a "*Vector*" or a *VectorSerie* type object.
  75
  76   ObservationError
  77     *Required command*. This indicates the observation error covariance matrix,
  78     previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
  79     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
  80     type object.
  81
  82   ObservationOperator
  83     *Required command*. This indicates the observation operator, previously
  84     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  85     results :math:`\mathbf{y}` to be compared to observations
  86     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  87     a "*Matrix*" type one. In the case of "*Function*" type, different
  88     functional forms can be used, as described in the section
  89     :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
  90     included in the observation, the operator has to be applied to a pair
  91     :math:`(X,U)`.
  92
  93 The general optional commands, available in the editing user interface, are
  94 indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
  95 optional command "*AlgorithmParameters*" allows to choose the specific options,
  96 described hereafter, of the algorithm. See
  97 :ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
  98
  99 The options of the algorithm are the following:
 100
 101   SampleAsnUplet
 102     This key describes the calculations points as a list of n-uplets, each
 103     n-uplet being a state.
 104
 105   SampleAsExplicitHyperCube
 106     This key describes the calculations points as an hypercube, from which one
 107     gives the list of sampling of each variable as a list. That is then a list
 108     of lists, each of them being potentially of different size.
 109
 110   SampleAsMinMaxStepHyperCube
 111     This key describes the calculations points as an hypercube from which one
 112     the sampling of each variable by a triplet *[min,max,step]*. That is then a
 113     list of the same size then the one of the state.
 114
 115   SetDebug
 116     This key requires the activation, or not, of the debug mode during the
 117     function evaluation. The default is "True", the choices are "True" or
 118     "False".
 119
 120   StoreSupplementaryCalculations
 121     This list indicates the names of the supplementary variables that can be
 122     available at the end of the algorithm. It involves potentially costly
 123     calculations or memory consumptions. The default is a void list, none of
 124     these variables being calculated and stored by default. The possible names
 125     are in the following list: ["CostFunctionJ", "CurrentState", "Innovation",
 126     "ObservedState"].
 127
 128 See also
 129 ++++++++
 130
 131 References to other sections:
 132   - :ref:`section_ref_algorithm_FunctionTest`