doc/en/ref_algorithm_GradientTest.rst

   1 ..
   2    Copyright (C) 2008-2018 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 Description
  31 +++++++++++
  32
  33 This algorithm allows to check the quality of the adjoint 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` with :math:`\alpha_0` a user scaling
  39 of the initial perturbation, with default to 1. :math:`F` is the calculation
  40 code.
  41
  42 "Taylor" residue
  43 ****************
  44
  45 One observe the residue coming from the Taylor development of the :math:`F`
  46 function, normalized by the value at the nominal point:
  47
  48 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||}
  49
  50 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  51 respect to :math:`\alpha`, it signifies that the gradient is well calculated
  52 until the stopping precision of the quadratic decrease, and that :math:`F` is
  53 not linear.
  54
  55 If the residue is decreasing and the decrease change in :math:`\alpha` with
  56 respect to :math:`\alpha`, until a certain level after which the residue remains
  57 small and constant, it signifies that the :math:`F` is linear and that the
  58 residue is decreasing due to the error coming from :math:`\nabla_xF` term
  59 calculation.
  60
  61 "TaylorOnNorm" residue
  62 **********************
  63
  64 One observe the residue coming from the Taylor development of the :math:`F`
  65 function, with respect to the :math:`\alpha` parameter to the square:
  66
  67 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{\alpha^2}
  68
  69 This is a residue essentially similar to the classical Taylor criterion
  70 previously described, but its behavior can differ depending on the numerical
  71 properties of the calculation.
  72
  73 If the residue is constant until a certain level after which the residue will
  74 growth, it signifies that the gradient is well calculated until this stopping
  75 precision, and that :math:`F` is not linear.
  76
  77 If the residue is systematically growing from a very small value with respect to
  78 :math:`||F(\mathbf{x})||`, it signifies that :math:`F` is (quasi-)linear and
  79 that the gradient calculation is correct until the precision for which the
  80 residue reaches the numerical order of :math:`||F(\mathbf{x})||`.
  81
  82 "Norm" residue
  83 **************
  84
  85 One observe the residue based on the gradient approximation:
  86
  87 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{\alpha}
  88
  89 which has to remain stable until the calculation precision is reached.
  90
  91 Optional and required commands
  92 ++++++++++++++++++++++++++++++
  93
  94 .. index:: single: AlgorithmParameters
  95 .. index:: single: CheckingPoint
  96 .. index:: single: ObservationOperator
  97 .. index:: single: AmplitudeOfInitialDirection
  98 .. index:: single: EpsilonMinimumExponent
  99 .. index:: single: InitialDirection
 100 .. index:: single: ResiduFormula
 101 .. index:: single: SetSeed
 102 .. index:: single: StoreSupplementaryCalculations
 103
 104 The general required commands, available in the editing user interface, are the
 105 following:
 106
 107   .. include:: snippets/CheckingPoint.rst
 108
 109   .. include:: snippets/ObservationOperator.rst
 110
 111 The general optional commands, available in the editing user interface, are
 112 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
 113 of the command "*AlgorithmParameters*" allow to choose the specific options,
 114 described hereafter, of the algorithm. See
 115 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
 116 command.
 117
 118 The options of the algorithm are the following:
 119
 120   .. include:: snippets/AmplitudeOfInitialDirection.rst
 121
 122   .. include:: snippets/EpsilonMinimumExponent.rst
 123
 124   .. include:: snippets/InitialDirection.rst
 125
 126   .. include:: snippets/SetSeed.rst
 127
 128   ResiduFormula
 129     .. index:: single: ResiduFormula
 130
 131     This key indicates the residue formula that has to be used for the test. The
 132     default choice is "Taylor", and the possible ones are "Taylor" (normalized
 133     residue of the Taylor development of the operator, which has to decrease
 134     with the square power of the perturbation), "TaylorOnNorm" (residue of the
 135     Taylor development of the operator with respect to the perturbation to the
 136     square, which has to remain constant) and "Norm" (residue obtained by taking
 137     the norm of the Taylor development at zero order approximation, which
 138     approximate the gradient, and which has to remain constant).
 139
 140     Example :
 141     ``{"ResiduFormula":"Taylor"}``
 142
 143   StoreSupplementaryCalculations
 144     .. index:: single: StoreSupplementaryCalculations
 145
 146     This list indicates the names of the supplementary variables that can be
 147     available at the end of the algorithm. It involves potentially costly
 148     calculations or memory consumptions. The default is a void list, none of
 149     these variables being calculated and stored by default. The possible names
 150     are in the following list: ["CurrentState", "Residu",
 151     "SimulatedObservationAtCurrentState"].
 152
 153     Example :
 154     ``{"StoreSupplementaryCalculations":["CurrentState"]}``
 155
 156 Information and variables available at the end of the algorithm
 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 158
 159 At the output, after executing the algorithm, there are variables and
 160 information originating from the calculation. The description of
 161 :ref:`section_ref_output_variables` show the way to obtain them by the method
 162 named ``get`` of the variable "*ADD*" of the post-processing. The input
 163 variables, available to the user at the output in order to facilitate the
 164 writing of post-processing procedures, are described in the
 165 :ref:`subsection_r_o_v_Inventaire`.
 166
 167 The unconditional outputs of the algorithm are the following:
 168
 169   .. include:: snippets/Residu.rst
 170
 171 The conditional outputs of the algorithm are the following:
 172
 173   .. include:: snippets/CurrentState.rst
 174
 175   .. include:: snippets/SimulatedObservationAtCurrentState.rst
 176
 177 See also
 178 ++++++++
 179
 180 References to other sections:
 181   - :ref:`section_ref_algorithm_FunctionTest`
 182   - :ref:`section_ref_algorithm_LinearityTest`
 183   - :ref:`section_ref_algorithm_TangentTest`
 184   - :ref:`section_ref_algorithm_AdjointTest`