doc/en/ref_algorithm_LinearityTest.rst

   1 ..
   2    Copyright (C) 2008-2024 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. The test is applicable to any operator, of evolution
  36 :math:`\mathcal{D}` or observation :math:`\mathcal{H}`.
  37
  38 In any cases, with :math:`\mathbf{x}` the current verification point, one take
  39 :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and
  40 :math:`\mathbf{dx}=\alpha*\mathbf{dx}_0` with :math:`\alpha_0`a user scale
  41 parameter, at 1 by default. :math:`F` is the calculation code (given here by
  42 the user by using the observation operator command "*ObservationOperator*").
  43
  44 "CenteredDL" residue
  45 ********************
  46
  47 One observe the following residue, coming from the centered difference of the
  48 :math:`F` values at nominal point and at perturbed points, normalized by the
  49 value at the nominal point:
  50
  51 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) + F(\mathbf{x}-\alpha*\mathbf{dx}) - 2*F(\mathbf{x}) ||}{|| F(\mathbf{x}) ||}
  52
  53 If it stays constantly really small with respect to 1, the linearity hypothesis
  54 of :math:`F` is verified.
  55
  56 If the residue is varying, or if it is of order 1 or more, and it is small only
  57 at a certain order of increment, the linearity hypothesis of :math:`F` is not
  58 verified.
  59
  60 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  61 respect to :math:`\alpha`, it signifies that the gradient is correctly
  62 calculated until the stopping level of the quadratic decrease.
  63
  64 "Taylor" residue
  65 ****************
  66
  67 One observe the residue coming from the Taylor development of the :math:`F`
  68 function, normalized by the value at the nominal point:
  69
  70 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||}
  71
  72 If it stay constantly really small with respect to 1, the linearity hypothesis
  73 of :math:`F` is verified.
  74
  75 If the residue is varying, or if it is of order 1 or more, and it is small only
  76 at a certain order of increment, the linearity hypothesis of :math:`F` is not
  77 verified.
  78
  79 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  80 respect to :math:`\alpha`, it signifies that the gradient is correctly
  81 calculated until the stopping level of the quadratic decrease.
  82
  83 "NominalTaylor" residue
  84 ***********************
  85
  86 One observe the residue build from two approximations of order 1 of
  87 :math:`F(\mathbf{x})`, normalized by the value at the nominal point:
  88
  89 .. 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}) ||)
  90
  91 If the residue stays constant equal to 1 at less than 2 or 3 percents (that that
  92 :math:`|R-1|` stays equal to 2 or 3 percents), the linearity hypothesis of
  93 :math:`F` is verified.
  94
  95 If it is equal to 1 only on part of the variation domain of increment
  96 :math:`\alpha`, it is on this sub-domain that the linearity hypothesis of
  97 :math:`F` is verified.
  98
  99 "NominalTaylorRMS" residue
 100 **************************
 101
 102 One observe the residue build from two approximations of order 1 of
 103 :math:`F(\mathbf{x})`, normalized by the value at the nominal point, on which
 104 one estimate the quadratic root mean square (RMS) with the value at the nominal
 105 point:
 106
 107 .. 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}) ||)
 108
 109 If it stay constantly equal to 0 at less than 1 or 2 percents, the linearity
 110 hypothesis of :math:`F` is verified.
 111
 112 If it is equal to 0 only on part of the variation domain of increment
 113 :math:`\alpha`, it is on this sub-domain that the linearity hypothesis of
 114 :math:`F` is verified.
 115
 116 .. ------------------------------------ ..
 117 .. include:: snippets/Header2Algo12.rst
 118
 119 .. include:: snippets/FeaturePropDerivativeNeeded.rst
 120
 121 .. include:: snippets/FeaturePropParallelDerivativesOnly.rst
 122
 123 .. ------------------------------------ ..
 124 .. include:: snippets/Header2Algo02.rst
 125
 126 .. include:: snippets/CheckingPoint.rst
 127
 128 .. include:: snippets/ObservationOperator.rst
 129
 130 .. ------------------------------------ ..
 131 .. include:: snippets/Header2Algo03Chck.rst
 132
 133 .. include:: snippets/AmplitudeOfInitialDirection.rst
 134
 135 .. include:: snippets/AmplitudeOfTangentPerturbation.rst
 136
 137 .. include:: snippets/EpsilonMinimumExponent.rst
 138
 139 .. include:: snippets/InitialDirection.rst
 140
 141 .. include:: snippets/NumberOfPrintedDigits.rst
 142
 143 .. include:: snippets/ResiduFormula_LinearityTest.rst
 144
 145 .. include:: snippets/SetSeed.rst
 146
 147 StoreSupplementaryCalculations
 148   .. index:: single: StoreSupplementaryCalculations
 149
 150   *List of names*. This list indicates the names of the supplementary
 151   variables, that can be available during or at the end of the algorithm, if
 152   they are initially required by the user. Their availability involves,
 153   potentially, costly calculations or memory consumptions. The default is then
 154   a void list, none of these variables being calculated and stored by default
 155   (excepted the unconditional variables). The possible names are in the
 156   following list (the detailed description of each named variable is given in
 157   the following part of this specific algorithmic documentation, in the
 158   sub-section "*Information and variables available at the end of the
 159   algorithm*"): [
 160   "CurrentState",
 161   "Residu",
 162   "SimulatedObservationAtCurrentState",
 163   ].
 164
 165   Example :
 166   ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
 167
 168 .. ------------------------------------ ..
 169 .. include:: snippets/Header2Algo04.rst
 170
 171 .. include:: snippets/Residu.rst
 172
 173 .. ------------------------------------ ..
 174 .. include:: snippets/Header2Algo05.rst
 175
 176 .. include:: snippets/CurrentState.rst
 177
 178 .. include:: snippets/Residu.rst
 179
 180 .. include:: snippets/SimulatedObservationAtCurrentState.rst
 181
 182 .. ------------------------------------ ..
 183 .. _section_ref_algorithm_LinearityTest_examples:
 184
 185 .. include:: snippets/Header2Algo06.rst
 186
 187 - :ref:`section_ref_algorithm_FunctionTest`