doc/en/ref_algorithm_LinearityTest.rst

   1 ..
   2    Copyright (C) 2008-2015 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: LinearityTest
  25 .. _section_ref_algorithm_LinearityTest:
  26
  27 Checking algorithm "*LinearityTest*"
  28 ------------------------------------
  29
  30 Description
  31 +++++++++++
  32
  33 This algorithm allows to check the linear quality of the operator, by
  34 calculating a residue with known theoretical properties. Different residue
  35 formula are available.
  36
  37 In any cases, one take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and
  38 :math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code.
  39
  40 "CenteredDL" residue
  41 ********************
  42
  43 One observe the following residue, coming from the centered difference of the
  44 :math:`F` values at nominal point and at perturbed points, normalized by the
  45 value at the nominal point:
  46
  47 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) + F(\mathbf{x}-\alpha*\mathbf{dx}) - 2*F(\mathbf{x}) ||}{|| F(\mathbf{x}) ||}
  48
  49 If it stays constantly really small with respect to 1, the linearity hypothesis
  50 of :math:`F` is verified.
  51
  52 If the residue is varying, or if it is of order 1 or more, and it is small only
  53 at a certain order of increment, the linearity hypothesis of :math:`F` is not
  54 verified.
  55
  56 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  57 respect to :math:`\alpha`, it signifies that the gradient is correctly
  58 calculated until the stopping level of the quadratic decrease.
  59
  60 "Taylor" residue
  61 ****************
  62
  63 One observe the residue coming from the Taylor development of the :math:`F`
  64 function, normalized by the value at the nominal point:
  65
  66 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||}
  67
  68 If it stay constantly really small with respect to 1, the linearity hypothesis
  69 of :math:`F` is verified.
  70
  71 If the residue is varying, or if it is of order 1 or more, and it is small only
  72 at a certain order of increment, the linearity hypothesis of :math:`F` is not
  73 verified.
  74
  75 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  76 respect to :math:`\alpha`, it signifies that the gradient is correctly
  77 calculated until the stopping level of the quadratic decrease.
  78
  79 "NominalTaylor" residue
  80 ***********************
  81
  82 One observe the residue build from two approximations of order 1 of
  83 :math:`F(\mathbf{x})`, normalized by the value at the nominal point:
  84
  85 .. math:: R(\alpha) = \max(|| F(\mathbf{x}+\alpha*\mathbf{dx}) - \alpha * F(\mathbf{dx}) || / || F(\mathbf{x}) ||,|| F(\mathbf{x}-\alpha*\mathbf{dx}) + \alpha * F(\mathbf{dx}) || / || F(\mathbf{x}) ||)
  86
  87 If the residue stays constant equal to 1 at less than 2 or 3 percents (that that
  88 :math:`|R-1|` stays equal to 2 or 3 percents), the linearity hypothesis of
  89 :math:`F` is verified.
  90
  91 If it is equal to 1 only on part of the variation domain of increment
  92 :math:`\alpha`, it is on this sub-domain that the linearity hypothesis of
  93 :math:`F` is verified.
  94
  95 "NominalTaylorRMS" residue
  96 **************************
  97
  98 One observe the residue build from two approximations of order 1 of
  99 :math:`F(\mathbf{x})`, normalized by the value at the nominal point, on which
 100 one estimate the quadratic root mean square (RMS) with the value at the nominal
 101 point:
 102
 103 .. math:: R(\alpha) = \max(RMS( F(\mathbf{x}), F(\mathbf{x}+\alpha*\mathbf{dx}) - \alpha * F(\mathbf{dx}) ) / || F(\mathbf{x}) ||,RMS( F(\mathbf{x}), F(\mathbf{x}-\alpha*\mathbf{dx}) + \alpha * F(\mathbf{dx}) ) / || F(\mathbf{x}) ||)
 104
 105 If it stay constantly equal to 0 at less than 1 or 2 percents, the linearity
 106 hypothesis of :math:`F` is verified.
 107
 108 If it is equal to 0 only on part of the variation domain of increment
 109 :math:`\alpha`, it is on this sub-domain that the linearity hypothesis of
 110 :math:`F` is verified.
 111
 112 Optional and required commands
 113 ++++++++++++++++++++++++++++++
 114
 115 .. index:: single: AlgorithmParameters
 116 .. index:: single: CheckingPoint
 117 .. index:: single: ObservationOperator
 118 .. index:: single: AmplitudeOfInitialDirection
 119 .. index:: single: EpsilonMinimumExponent
 120 .. index:: single: InitialDirection
 121 .. index:: single: ResiduFormula
 122 .. index:: single: SetSeed
 123
 124 The general required commands, available in the editing user interface, are the
 125 following:
 126
 127   CheckingPoint
 128     *Required command*. This indicates the vector used as the state around which
 129     to perform the required check, noted :math:`\mathbf{x}` and similar to the
 130     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
 131
 132   ObservationOperator
 133     *Required command*. This indicates the observation operator, previously
 134     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
 135     results :math:`\mathbf{y}` to be compared to observations
 136     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
 137     a "*Matrix*" type one. In the case of "*Function*" type, different
 138     functional forms can be used, as described in the section
 139     :ref:`section_ref_operator_requirements`. If there is some control
 140     :math:`U` included in the observation, the operator has to be applied to a
 141     pair :math:`(X,U)`.
 142
 143 The general optional commands, available in the editing user interface, are
 144 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
 145 of the command "*AlgorithmParameters*" allow to choose the specific options,
 146 described hereafter, of the algorithm. See
 147 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
 148 command.
 149
 150 The options of the algorithm are the following:
 151
 152   AmplitudeOfInitialDirection
 153     This key indicates the scaling of the initial perturbation build as a vector
 154     used for the directional derivative around the nominal checking point. The
 155     default is 1, that means no scaling.
 156
 157     Example : ``{"AmplitudeOfInitialDirection":0.5}``
 158
 159   EpsilonMinimumExponent
 160     This key indicates the minimal exponent value of the power of 10 coefficient
 161     to be used to decrease the increment multiplier. The default is -8, and it
 162     has to be between 0 and -20. For example, its default value leads to
 163     calculate the residue of the scalar product formula with a fixed increment
 164     multiplied from 1.e0 to 1.e-8.
 165
 166     Example : ``{"EpsilonMinimumExponent":-12}``
 167
 168   InitialDirection
 169     This key indicates the vector direction used for the directional derivative
 170     around the nominal checking point. It has to be a vector. If not specified,
 171     this direction defaults to a random perturbation around zero of the same
 172     vector size than the checking point.
 173
 174     Example : ``{"InitialDirection":[0.1,0.1,100.,3}``
 175
 176   ResiduFormula
 177     This key indicates the residue formula that has to be used for the test. The
 178     default choice is "CenteredDL", and the possible ones are "CenteredDL"
 179     (residue of the difference between the function at nominal point and the
 180     values with positive and negative increments, which has to stay very small),
 181     "Taylor" (residue of the Taylor development of the operator normalized by
 182     the nominal value, which has to stay very small), "NominalTaylor" (residue
 183     of the order 1 approximations of the operator, normalized to the nominal
 184     point, which has to stay close to 1), and "NominalTaylorRMS" (residue of the
 185     order 1 approximations of the operator, normalized by RMS to the nominal
 186     point, which has to stay close to 0).
 187
 188     Example : ``{"ResiduFormula":"CenteredDL"}``
 189
 190   SetSeed
 191     This key allow to give an integer in order to fix the seed of the random
 192     generator used to generate the ensemble. A convenient value is for example
 193     1000. By default, the seed is left uninitialized, and so use the default
 194     initialization from the computer.
 195
 196     Example : ``{"SetSeed":1000}``
 197
 198 See also
 199 ++++++++
 200
 201 References to other sections:
 202   - :ref:`section_ref_algorithm_FunctionTest`