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