doc/en/ref_algorithm_TangentTest.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: TangentTest
  25 .. _section_ref_algorithm_TangentTest:
  26
  27 Checking algorithm "*TangentTest*"
  28 ----------------------------------
  29
  30 .. ------------------------------------ ..
  31 .. include:: snippets/Header2Algo01.rst
  32
  33 This algorithm allows to check the quality of the tangent operator, by
  34 calculating a residue whose theoretical properties are known. The test is
  35 applicable to any operator, of evolution :math:`\mathcal{D}` or observation
  36 :math:`\mathcal{H}`.
  37
  38 For all formulas, with :math:`\mathbf{x}` the current verification point, we
  39 take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and
  40 :math:`\mathbf{dx}=\alpha_0*\mathbf{dx}_0` with :math:`\alpha_0` a scaling user
  41 parameter, defaulting to 1. :math:`F` is the computational operator or code
  42 (which is here defined by the observation operator command
  43 "*ObservationOperator*").
  44
  45 One can observe the following residue, which is the comparison of increments
  46 using the tangent linear operator:
  47
  48 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{|| \alpha * TangentF_x * \mathbf{dx} ||}
  49
  50 which has to remain stable in :math:`1+O(\alpha)` until the calculation
  51 precision is reached.
  52
  53 When :math:`|R-1|/\alpha` is less or equal to a stable value when :math:`\alpha`
  54 is varying, the tangent is valid, until the calculation precision is reached.
  55
  56 If :math:`|R-1|/\alpha` is really small, the calculation code :math:`F` is
  57 almost linear or quasi-linear (which can be verified by the
  58 :ref:`section_ref_algorithm_LinearityTest`), and the tangent is valid until the
  59 calculation precision is reached.
  60
  61 .. ------------------------------------ ..
  62 .. include:: snippets/Header2Algo12.rst
  63
  64 .. include:: snippets/FeaturePropDerivativeNeeded.rst
  65
  66 .. ------------------------------------ ..
  67 .. include:: snippets/Header2Algo02.rst
  68
  69 .. include:: snippets/CheckingPoint.rst
  70
  71 .. include:: snippets/ObservationOperator.rst
  72
  73 .. ------------------------------------ ..
  74 .. include:: snippets/Header2Algo03Chck.rst
  75
  76 .. include:: snippets/AmplitudeOfInitialDirection.rst
  77
  78 .. include:: snippets/AmplitudeOfTangentPerturbation.rst
  79
  80 .. include:: snippets/EpsilonMinimumExponent.rst
  81
  82 .. include:: snippets/InitialDirection.rst
  83
  84 .. include:: snippets/NumberOfPrintedDigits.rst
  85
  86 .. include:: snippets/SetSeed.rst
  87
  88 StoreSupplementaryCalculations
  89   .. index:: single: StoreSupplementaryCalculations
  90
  91   *List of names*. This list indicates the names of the supplementary
  92   variables, that can be available during or at the end of the algorithm, if
  93   they are initially required by the user. Their availability involves,
  94   potentially, costly calculations or memory consumptions. The default is then
  95   a void list, none of these variables being calculated and stored by default
  96   (excepted the unconditional variables). The possible names are in the
  97   following list (the detailed description of each named variable is given in
  98   the following part of this specific algorithmic documentation, in the
  99   sub-section "*Information and variables available at the end of the
 100   algorithm*"): [
 101   "CurrentState",
 102   "Residu",
 103   "SimulatedObservationAtCurrentState",
 104   ].
 105
 106   Example :
 107   ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
 108
 109 .. ------------------------------------ ..
 110 .. include:: snippets/Header2Algo04.rst
 111
 112 .. include:: snippets/Residu.rst
 113
 114 .. ------------------------------------ ..
 115 .. include:: snippets/Header2Algo05.rst
 116
 117 .. include:: snippets/CurrentState.rst
 118
 119 .. include:: snippets/Residu.rst
 120
 121 .. include:: snippets/SimulatedObservationAtCurrentState.rst
 122
 123 .. ------------------------------------ ..
 124 .. _section_ref_algorithm_TangentTest_examples:
 125
 126 .. include:: snippets/Header2Algo06.rst
 127
 128 - :ref:`section_ref_algorithm_FunctionTest`
 129 - :ref:`section_ref_algorithm_LinearityTest`
 130 - :ref:`section_ref_algorithm_AdjointTest`
 131 - :ref:`section_ref_algorithm_GradientTest`
 132 - :ref:`section_ref_algorithm_LocalSensitivityTest`