doc/en/ref_algorithm_GradientTest.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: GradientTest
  25 .. _section_ref_algorithm_GradientTest:
  26
  27 Checking algorithm "*GradientTest*"
  28 -----------------------------------
  29
  30 .. ------------------------------------ ..
  31 .. include:: snippets/Header2Algo01.rst
  32
  33 This algorithm allows to check the quality of an adjoint 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, one take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and
  39 :math:`\mathbf{dx}=\alpha*\mathbf{dx}_0` with :math:`\alpha_0` a user scaling
  40 of the initial perturbation, with default to 1. :math:`F` is the calculation
  41 code (given here by the user by using the observation operator command
  42 "*ObservationOperator*").
  43
  44 "Taylor" residue
  45 ****************
  46
  47 One observe the residue coming from the Taylor development of the :math:`F`
  48 function, normalized by the value at the nominal point:
  49
  50 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||}
  51
  52 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  53 respect to :math:`\alpha`, it signifies that the gradient is well calculated
  54 until the stopping precision of the quadratic decrease, and that :math:`F` is
  55 not linear.
  56
  57 If the residue is decreasing and the decrease change in :math:`\alpha` with
  58 respect to :math:`\alpha`, until a certain level after which the residue remains
  59 small and constant, it signifies that the :math:`F` is linear and that the
  60 residue is decreasing due to the error coming from :math:`\nabla_xF` term
  61 calculation.
  62
  63 "TaylorOnNorm" residue
  64 **********************
  65
  66 One observe the residue coming from the Taylor development of the :math:`F`
  67 function, with respect to the :math:`\alpha` parameter to the square:
  68
  69 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{\alpha^2}
  70
  71 This is a residue essentially similar to the classical Taylor criterion
  72 previously described, but its behavior can differ depending on the numerical
  73 properties of the calculation.
  74
  75 If the residue is constant until a certain level after which the residue will
  76 growth, it signifies that the gradient is well calculated until this stopping
  77 precision, and that :math:`F` is not linear.
  78
  79 If the residue is systematically growing from a very small value with respect to
  80 :math:`||F(\mathbf{x})||`, it signifies that :math:`F` is (quasi-)linear and
  81 that the gradient calculation is correct until the precision for which the
  82 residue reaches the numerical order of :math:`||F(\mathbf{x})||`.
  83
  84 "Norm" residue
  85 **************
  86
  87 One observe the residue based on the gradient approximation:
  88
  89 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{\alpha}
  90
  91 which has to remain stable until the calculation precision is reached.
  92
  93 .. ------------------------------------ ..
  94 .. include:: snippets/Header2Algo12.rst
  95
  96 .. include:: snippets/FeaturePropDerivativeNeeded.rst
  97
  98 .. include:: snippets/FeaturePropParallelDerivativesOnly.rst
  99
 100 .. ------------------------------------ ..
 101 .. include:: snippets/Header2Algo02.rst
 102
 103 .. include:: snippets/CheckingPoint.rst
 104
 105 .. include:: snippets/ObservationOperator.rst
 106
 107 .. ------------------------------------ ..
 108 .. include:: snippets/Header2Algo03Chck.rst
 109
 110 .. include:: snippets/AmplitudeOfInitialDirection.rst
 111
 112 .. include:: snippets/AmplitudeOfTangentPerturbation.rst
 113
 114 .. include:: snippets/EpsilonMinimumExponent.rst
 115
 116 .. include:: snippets/InitialDirection.rst
 117
 118 .. include:: snippets/NumberOfPrintedDigits.rst
 119
 120 .. include:: snippets/ResiduFormula_GradientTest.rst
 121
 122 .. include:: snippets/SetSeed.rst
 123
 124 StoreSupplementaryCalculations
 125   .. index:: single: StoreSupplementaryCalculations
 126
 127   *List of names*. This list indicates the names of the supplementary
 128   variables, that can be available during or at the end of the algorithm, if
 129   they are initially required by the user. Their availability involves,
 130   potentially, costly calculations or memory consumptions. The default is then
 131   a void list, none of these variables being calculated and stored by default
 132   (excepted the unconditional variables). The possible names are in the
 133   following list (the detailed description of each named variable is given in
 134   the following part of this specific algorithmic documentation, in the
 135   sub-section "*Information and variables available at the end of the
 136   algorithm*"): [
 137   "CurrentState",
 138   "Residu",
 139   "SimulatedObservationAtCurrentState",
 140   ].
 141
 142   Example :
 143   ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
 144
 145 .. ------------------------------------ ..
 146 .. include:: snippets/Header2Algo04.rst
 147
 148 .. include:: snippets/Residu.rst
 149
 150 .. ------------------------------------ ..
 151 .. include:: snippets/Header2Algo05.rst
 152
 153 .. include:: snippets/CurrentState.rst
 154
 155 .. include:: snippets/Residu.rst
 156
 157 .. include:: snippets/SimulatedObservationAtCurrentState.rst
 158
 159 .. ------------------------------------ ..
 160 .. _section_ref_algorithm_GradientTest_examples:
 161
 162 .. include:: snippets/Header2Algo06.rst
 163
 164 - :ref:`section_ref_algorithm_FunctionTest`
 165 - :ref:`section_ref_algorithm_LinearityTest`
 166 - :ref:`section_ref_algorithm_TangentTest`
 167 - :ref:`section_ref_algorithm_AdjointTest`
 168 - :ref:`section_ref_algorithm_LocalSensitivityTest`