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 .. index:: single: StoreSupplementaryCalculations
  58
  59 The general required commands, available in the editing user interface, are the
  60 following:
  61
  62   CheckingPoint
  63     *Required command*. This indicates the vector used as the state around which
  64     to perform the required check, noted :math:`\mathbf{x}` and similar to the
  65     background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
  66
  67   ObservationOperator
  68     *Required command*. This indicates the observation operator, previously
  69     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  70     results :math:`\mathbf{y}` to be compared to observations
  71     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  72     a "*Matrix*" type one. In the case of "*Function*" type, different
  73     functional forms can be used, as described in the section
  74     :ref:`section_ref_operator_requirements`. If there is some control
  75     :math:`U` included in the observation, the operator has to be applied to a
  76     pair :math:`(X,U)`.
  77
  78 The general optional commands, available in the editing user interface, are
  79 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
  80 of the command "*AlgorithmParameters*" allow to choose the specific options,
  81 described hereafter, of the algorithm. See
  82 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
  83 command.
  84
  85 The options of the algorithm are the following:
  86
  87   AmplitudeOfInitialDirection
  88     This key indicates the scaling of the initial perturbation build as a vector
  89     used for the directional derivative around the nominal checking point. The
  90     default is 1, that means no scaling.
  91
  92     Example : ``{"AmplitudeOfInitialDirection":0.5}``
  93
  94   EpsilonMinimumExponent
  95     This key indicates the minimal exponent value of the power of 10 coefficient
  96     to be used to decrease the increment multiplier. The default is -8, and it
  97     has to be between 0 and -20. For example, its default value leads to
  98     calculate the residue of the formula with a fixed increment multiplied from
  99     1.e0 to 1.e-8.
 100
 101     Example : ``{"EpsilonMinimumExponent":-12}``
 102
 103   InitialDirection
 104     This key indicates the vector direction used for the directional derivative
 105     around the nominal checking point. It has to be a vector. If not specified,
 106     this direction defaults to a random perturbation around zero of the same
 107     vector size than the checking point.
 108
 109     Example : ``{"InitialDirection":[0.1,0.1,100.,3}``
 110
 111   SetSeed
 112     This key allow to give an integer in order to fix the seed of the random
 113     generator used to generate the ensemble. A convenient value is for example
 114     1000. By default, the seed is left uninitialized, and so use the default
 115     initialization from the computer.
 116
 117     Example : ``{"SetSeed":1000}``
 118
 119   StoreSupplementaryCalculations
 120     This list indicates the names of the supplementary variables that can be
 121     available at the end of the algorithm. It involves potentially costly
 122     calculations or memory consumptions. The default is a void list, none of
 123     these variables being calculated and stored by default. The possible names
 124     are in the following list: ["CurrentState", "Residu",
 125     "SimulatedObservationAtCurrentState"].
 126
 127     Example : ``{"StoreSupplementaryCalculations":["CurrentState"]}``
 128
 129 Information and variables available at the end of the algorithm
 130 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 131
 132 At the output, after executing the algorithm, there are variables and
 133 information originating from the calculation. The description of
 134 :ref:`section_ref_output_variables` show the way to obtain them by the method
 135 named ``get`` of the variable "*ADD*" of the post-processing. The input
 136 variables, available to the user at the output in order to facilitate the
 137 writing of post-processing procedures, are described in the
 138 :ref:`subsection_r_o_v_Inventaire`.
 139
 140 The unconditional outputs of the algorithm are the following:
 141
 142   Residu
 143     *List of values*. Each element is the value of the particular residu
 144     verified during a checking algorithm, in the order of the tests.
 145
 146     Example : ``r = ADD.get("Residu")[:]``
 147
 148 The conditional outputs of the algorithm are the following:
 149
 150   CurrentState
 151     *List of vectors*. Each element is a usual state vector used during the
 152     optimization algorithm procedure.
 153
 154     Example : ``Xs = ADD.get("CurrentState")[:]``
 155
 156   SimulatedObservationAtCurrentState
 157     *List of vectors*. Each element is an observed vector at the current state,
 158     that is, in the observation space.
 159
 160     Example : ``hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 161
 162 See also
 163 ++++++++
 164
 165 References to other sections:
 166   - :ref:`section_ref_algorithm_FunctionTest`
 167   - :ref:`section_ref_algorithm_LinearityTest`
 168   - :ref:`section_ref_algorithm_TangentTest`
 169   - :ref:`section_ref_algorithm_GradientTest`