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