doc/en/ref_algorithm_LinearityTest.rst

   1 ..
   2    Copyright (C) 2008-2023 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 .. ------------------------------------ ..
  31 .. include:: snippets/Header2Algo01.rst
  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 .. ------------------------------------ ..
 113 .. include:: snippets/Header2Algo02.rst
 114
 115 .. include:: snippets/CheckingPoint.rst
 116
 117 .. include:: snippets/ObservationOperator.rst
 118
 119 .. ------------------------------------ ..
 120 .. include:: snippets/Header2Algo03Chck.rst
 121
 122 .. include:: snippets/AmplitudeOfInitialDirection.rst
 123
 124 .. include:: snippets/AmplitudeOfTangentPerturbation.rst
 125
 126 .. include:: snippets/EpsilonMinimumExponent.rst
 127
 128 .. include:: snippets/InitialDirection.rst
 129
 130 .. include:: snippets/ResiduFormula_LinearityTest.rst
 131
 132 .. include:: snippets/SetSeed.rst
 133
 134 StoreSupplementaryCalculations
 135   .. index:: single: StoreSupplementaryCalculations
 136
 137   *List of names*. This list indicates the names of the supplementary
 138   variables, that can be available during or at the end of the algorithm, if
 139   they are initially required by the user. Their avalability involves,
 140   potentially, costly calculations or memory consumptions. The default is then
 141   a void list, none of these variables being calculated and stored by default
 142   (excepted the unconditionnal variables). The possible names are in the
 143   following list (the detailed description of each named variable is given in
 144   the following part of this specific algorithmic documentation, in the
 145   sub-section "*Information and variables available at the end of the
 146   algorithm*"): [
 147   "CurrentState",
 148   "Residu",
 149   "SimulatedObservationAtCurrentState",
 150   ].
 151
 152   Example :
 153   ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
 154
 155 .. ------------------------------------ ..
 156 .. include:: snippets/Header2Algo04.rst
 157
 158 .. include:: snippets/Residu.rst
 159
 160 .. ------------------------------------ ..
 161 .. include:: snippets/Header2Algo05.rst
 162
 163 .. include:: snippets/CurrentState.rst
 164
 165 .. include:: snippets/Residu.rst
 166
 167 .. include:: snippets/SimulatedObservationAtCurrentState.rst
 168
 169 .. ------------------------------------ ..
 170 .. _section_ref_algorithm_LinearityTest_examples:
 171 .. include:: snippets/Header2Algo06.rst
 172
 173 - :ref:`section_ref_algorithm_FunctionTest`