doc/en/ref_algorithm_TangentTest.rst

   1 ..
   2    Copyright (C) 2008-2014 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 Description
  31 +++++++++++
  32
  33 This algorithm allows to check the quality of the tangent operator, by
  34 calculating a residue with known theoretical properties.
  35
  36 One can observe the following residue, which is the comparison of increments
  37 using the tangent linear operator:
  38
  39 .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{|| \alpha * TangentF_x * \mathbf{dx} ||}
  40
  41 which has to remain stable in :math:`1+O(\alpha)` until the calculation
  42 precision is reached.
  43
  44 When :math:`|R-1|/\alpha` is less or equal to a stable value when :math:`\alpha`
  45 is varying, the tangent is valid, until the calculation precision is reached.
  46
  47 If :math:`|R-1|/\alpha` is really small, the calculation code :math:`F` is
  48 almost linear or quasi-linear (which can be verified by the
  49 :ref:`section_ref_algorithm_LinearityTest`), and the tangent is valid until the
  50 calculation precision is reached.
  51
  52 One take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and
  53 :math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code.
  54
  55 Optional and required commands
  56 ++++++++++++++++++++++++++++++
  57
  58 .. index:: single: CheckingPoint
  59 .. index:: single: ObservationOperator
  60 .. index:: single: AmplitudeOfInitialDirection
  61 .. index:: single: EpsilonMinimumExponent
  62 .. index:: single: InitialDirection
  63 .. index:: single: SetSeed
  64
  65 The general required commands, available in the editing user interface, are the
  66 following:
  67
  68   CheckingPoint
  69     *Required command*. This indicates the vector used as the state around which
  70     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  71     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  72
  73   ObservationOperator
  74     *Required command*. This indicates the observation operator, previously
  75     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  76     results :math:`\mathbf{y}` to be compared to observations
  77     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  78     a "*Matrix*" type one. In the case of "*Function*" type, different
  79     functional forms can be used, as described in the section
  80     :ref:`section_ref_operator_requirements`. If there is some control
  81     :math:`U` included in the observation, the operator has to be applied to a
  82     pair :math:`(X,U)`.
  83
  84 The general optional commands, available in the editing user interface, are
  85 indicated in :ref:`section_ref_assimilation_keywords`. In particular, the
  86 optional command "*AlgorithmParameters*" allows to choose the specific options,
  87 described hereafter, of the algorithm. See
  88 :ref:`section_ref_options_AlgorithmParameters` for the good use of this command.
  89
  90 The options of the algorithm are the following:
  91
  92   AmplitudeOfInitialDirection
  93     This key indicates the scaling of the initial perturbation build as a vector
  94     used for the directional derivative around the nominal checking point. The
  95     default is 1, that means no scaling.
  96
  97     Example : ``{"AmplitudeOfInitialDirection":0.5}``
  98
  99   EpsilonMinimumExponent
 100     This key indicates the minimal exponent value of the power of 10 coefficient
 101     to be used to decrease the increment multiplier. The default is -8, and it
 102     has to be between 0 and -20. For example, its default value leads to
 103     calculate the residue of the scalar product formula with a fixed increment
 104     multiplied from 1.e0 to 1.e-8.
 105
 106     Example : ``{"EpsilonMinimumExponent":-12}``
 107
 108   InitialDirection
 109     This key indicates the vector direction used for the directional derivative
 110     around the nominal checking point. It has to be a vector. If not specified,
 111     this direction defaults to a random perturbation around zero of the same
 112     vector size than the checking point.
 113
 114     Example : ``{"InitialDirection":[0.1,0.1,100.,3}``
 115
 116   SetSeed
 117     This key allow to give an integer in order to fix the seed of the random
 118     generator used to generate the ensemble. A convenient value is for example
 119     1000. By default, the seed is left uninitialized, and so use the default
 120     initialization from the computer.
 121
 122     Example : ``{"SetSeed":1000}``
 123
 124 See also
 125 ++++++++
 126
 127 References to other sections:
 128   - :ref:`section_ref_algorithm_FunctionTest`
 129   - :ref:`section_ref_algorithm_AdjointTest`
 130   - :ref:`section_ref_algorithm_GradientTest`