doc/en/ref_algorithm_TangentTest.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: 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: AlgorithmParameters
  59 .. index:: single: CheckingPoint
  60 .. index:: single: ObservationOperator
  61 .. index:: single: AmplitudeOfInitialDirection
  62 .. index:: single: EpsilonMinimumExponent
  63 .. index:: single: InitialDirection
  64 .. index:: single: SetSeed
  65
  66 The general required commands, available in the editing user interface, are the
  67 following:
  68
  69   CheckingPoint
  70     *Required command*. This indicates the vector used as the state around which
  71     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  72     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  73
  74   ObservationOperator
  75     *Required command*. This indicates the observation operator, previously
  76     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  77     results :math:`\mathbf{y}` to be compared to observations
  78     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  79     a "*Matrix*" type one. In the case of "*Function*" type, different
  80     functional forms can be used, as described in the section
  81     :ref:`section_ref_operator_requirements`. If there is some control
  82     :math:`U` included in the observation, the operator has to be applied to a
  83     pair :math:`(X,U)`.
  84
  85 The general optional commands, available in the editing user interface, are
  86 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
  87 of the command "*AlgorithmParameters*" allow to choose the specific options,
  88 described hereafter, of the algorithm. See
  89 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
  90 command.
  91
  92 The options of the algorithm are the following:
  93
  94   AmplitudeOfInitialDirection
  95     This key indicates the scaling of the initial perturbation build as a vector
  96     used for the directional derivative around the nominal checking point. The
  97     default is 1, that means no scaling.
  98
  99     Example : ``{"AmplitudeOfInitialDirection":0.5}``
 100
 101   EpsilonMinimumExponent
 102     This key indicates the minimal exponent value of the power of 10 coefficient
 103     to be used to decrease the increment multiplier. The default is -8, and it
 104     has to be between 0 and -20. For example, its default value leads to
 105     calculate the residue of the scalar product formula with a fixed increment
 106     multiplied from 1.e0 to 1.e-8.
 107
 108     Example : ``{"EpsilonMinimumExponent":-12}``
 109
 110   InitialDirection
 111     This key indicates the vector direction used for the directional derivative
 112     around the nominal checking point. It has to be a vector. If not specified,
 113     this direction defaults to a random perturbation around zero of the same
 114     vector size than the checking point.
 115
 116     Example : ``{"InitialDirection":[0.1,0.1,100.,3}``
 117
 118   SetSeed
 119     This key allow to give an integer in order to fix the seed of the random
 120     generator used to generate the ensemble. A convenient value is for example
 121     1000. By default, the seed is left uninitialized, and so use the default
 122     initialization from the computer.
 123
 124     Example : ``{"SetSeed":1000}``
 125
 126 See also
 127 ++++++++
 128
 129 References to other sections:
 130   - :ref:`section_ref_algorithm_FunctionTest`
 131   - :ref:`section_ref_algorithm_AdjointTest`
 132   - :ref:`section_ref_algorithm_GradientTest`