doc/en/ref_algorithm_GradientTest.rst

   1 ..
   2    Copyright (C) 2008-2015 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`. :math:`F` is the calculation code.
  39
  40 "Taylor" residue
  41 ****************
  42
  43 One observe the residue coming from the Taylor development of the :math:`F`
  44 function, normalized by the value at the nominal point:
  45
  46 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||}
  47
  48 If the residue is decreasing and the decrease change in :math:`\alpha^2` with
  49 respect to :math:`\alpha`, until a certain level after which the residue remains
  50 small and constant, it signifies that the :math:`F` is linear and that the
  51 residue is decreasing due to the error coming from :math:`\nabla_xF` term
  52 calculation.
  53
  54 "Norm" residue
  55 **************
  56
  57 One observe the residue based on the gradient approximation:
  58
  59 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{\alpha}
  60
  61 which has to remain stable until the calculation precision is reached.
  62
  63 Optional and required commands
  64 ++++++++++++++++++++++++++++++
  65
  66 .. index:: single: AlgorithmParameters
  67 .. index:: single: CheckingPoint
  68 .. index:: single: ObservationOperator
  69 .. index:: single: AmplitudeOfInitialDirection
  70 .. index:: single: EpsilonMinimumExponent
  71 .. index:: single: InitialDirection
  72 .. index:: single: ResiduFormula
  73 .. index:: single: SetSeed
  74
  75 The general required commands, available in the editing user interface, are the
  76 following:
  77
  78   CheckingPoint
  79     *Required command*. This indicates the vector used as the state around which
  80     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  81     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  82
  83   ObservationOperator
  84     *Required command*. This indicates the observation operator, previously
  85     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  86     results :math:`\mathbf{y}` to be compared to observations
  87     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  88     a "*Matrix*" type one. In the case of "*Function*" type, different
  89     functional forms can be used, as described in the section
  90     :ref:`section_ref_operator_requirements`. If there is some control
  91     :math:`U` included in the observation, the operator has to be applied to a
  92     pair :math:`(X,U)`.
  93
  94 The general optional commands, available in the editing user interface, are
  95 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
  96 of the command "*AlgorithmParameters*" allow to choose the specific options,
  97 described hereafter, of the algorithm. See
  98 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
  99 command.
 100
 101 The options of the algorithm are the following:
 102
 103   AmplitudeOfInitialDirection
 104     This key indicates the scaling of the initial perturbation build as a vector
 105     used for the directional derivative around the nominal checking point. The
 106     default is 1, that means no scaling.
 107
 108     Example : ``{"AmplitudeOfInitialDirection":0.5}``
 109
 110   EpsilonMinimumExponent
 111     This key indicates the minimal exponent value of the power of 10 coefficient
 112     to be used to decrease the increment multiplier. The default is -8, and it
 113     has to be between 0 and -20. For example, its default value leads to
 114     calculate the residue of the scalar product formula with a fixed increment
 115     multiplied from 1.e0 to 1.e-8.
 116
 117     Example : ``{"EpsilonMinimumExponent":-12}``
 118
 119   InitialDirection
 120     This key indicates the vector direction used for the directional derivative
 121     around the nominal checking point. It has to be a vector. If not specified,
 122     this direction defaults to a random perturbation around zero of the same
 123     vector size than the checking point.
 124
 125     Example : ``{"InitialDirection":[0.1,0.1,100.,3}``
 126
 127   ResiduFormula
 128     This key indicates the residue formula that has to be used for the test. The
 129     default choice is "Taylor", and the possible ones are "Taylor" (residue of
 130     the Taylor development of the operator, which has to decrease with the
 131     square power of the perturbation) and "Norm" (residue obtained by taking the
 132     norm of the Taylor development at zero order approximation, which
 133     approximate the gradient, and which has to remain constant).
 134
 135     Example : ``{"ResiduFormula":"Taylor"}``
 136
 137   SetSeed
 138     This key allow to give an integer in order to fix the seed of the random
 139     generator used to generate the ensemble. A convenient value is for example
 140     1000. By default, the seed is left uninitialized, and so use the default
 141     initialization from the computer.
 142
 143     Example : ``{"SetSeed":1000}``
 144
 145 See also
 146 ++++++++
 147
 148 References to other sections:
 149   - :ref:`section_ref_algorithm_FunctionTest`
 150   - :ref:`section_ref_algorithm_TangentTest`
 151   - :ref:`section_ref_algorithm_AdjointTest`