doc/en/ref_assimilation_keywords.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: ASSIMILATION_STUDY
  25 .. _section_ref_assimilation_keywords:
  26
  27 List of commands and keywords for an ADAO calculation case
  28 ----------------------------------------------------------
  29
  30 .. index:: single: Algorithm
  31 .. index:: single: AlgorithmParameters
  32 .. index:: single: Background
  33 .. index:: single: BackgroundError
  34 .. index:: single: ControlInput
  35 .. index:: single: Debug
  36 .. index:: single: EvolutionError
  37 .. index:: single: EvolutionModel
  38 .. index:: single: InputVariables
  39 .. index:: single: Observation
  40 .. index:: single: ObservationError
  41 .. index:: single: ObservationOperator
  42 .. index:: single: Observer
  43 .. index:: single: Observers
  44 .. index:: single: Observer Template
  45 .. index:: single: OutputVariables
  46 .. index:: single: Study_name
  47 .. index:: single: Study_repertory
  48 .. index:: single: UserDataInit
  49 .. index:: single: UserPostAnalysis
  50 .. index:: single: UserPostAnalysis Template
  51
  52 This set of commands is related to the description of a calculation case,
  53 that is a *Data Assimilation* procedure or an *Optimization* procedure. The
  54 terms are ordered in alphabetical order, except the first, which describes
  55 choice between calculation or checking.
  56
  57 The different commands are the following:
  58
  59   **ASSIMILATION_STUDY**
  60     *Required command*. This is the general command describing the data
  61     assimilation or optimization case. It hierarchically contains all the other
  62     commands.
  63
  64   Algorithm
  65     *Required command*. This is a string to indicate the data assimilation or
  66     optimization algorithm chosen. The choices are limited and available through
  67     the GUI. There exists for example "3DVAR", "Blue"... See below the list of
  68     algorithms and associated parameters, each described by a subsection.
  69
  70   AlgorithmParameters
  71     *Optional command*. This command allows to add some optional parameters to
  72     control the data assimilation or optimization algorithm. Its value is
  73     defined as a "*Dict*" type object. See the section
  74     :ref:`section_ref_options_AlgorithmParameters` for for the correct use of
  75     this command.
  76
  77   Background
  78     *Required command*. This indicates the background or initial vector used,
  79     previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
  80     "*Vector*" type object.
  81
  82   BackgroundError
  83     *Required command*. This indicates the background error covariance matrix,
  84     previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
  85     type object, a "*ScalarSparseMatrix*" type object, or a
  86     "*DiagonalSparseMatrix*" type object.
  87
  88   ControlInput
  89     *Optional command*. This indicates the control vector used to force the
  90     evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value
  91     is defined as a "*Vector*" or a *VectorSerie* type object. When there is no
  92     control, it has to be a void string ''.
  93
  94   Debug
  95     *Optional command*. This define the level of trace and intermediary debug
  96     information. The choices are limited between 0 (for False) and 1 (for
  97     True).
  98
  99   EvolutionError
 100     *Optional command*. This indicates the evolution error covariance matrix,
 101     usually noted as :math:`\mathbf{Q}`. It is defined as a "*Matrix*" type
 102     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
 103     type object.
 104
 105   EvolutionModel
 106     *Optional command*. This indicates the evolution model operator, usually
 107     noted :math:`M`, which describes an elementary step of evolution. Its value
 108     is defined as a "*Function*" type object or a "*Matrix*" type one. In the
 109     case of "*Function*" type, different functional forms can be used, as
 110     described in the section :ref:`section_ref_operator_requirements`. If there
 111     is some control :math:`U` included in the evolution model, the operator has
 112     to be applied to a pair :math:`(X,U)`.
 113
 114   InputVariables
 115     *Optional command*. This command allows to indicates the name and size of
 116     physical variables that are bundled together in the state vector. This
 117     information is dedicated to data processed inside an algorithm.
 118
 119   Observation
 120     *Required command*. This indicates the observation vector used for data
 121     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
 122     is defined as a "*Vector*" or a *VectorSerie* type object.
 123
 124   ObservationError
 125     *Required command*. This indicates the observation error covariance matrix,
 126     previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
 127     object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
 128     type object.
 129
 130   ObservationOperator
 131     *Required command*. This indicates the observation operator, previously
 132     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
 133     results :math:`\mathbf{y}` to be compared to observations
 134     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
 135     a "*Matrix*" type one. In the case of "*Function*" type, different
 136     functional forms can be used, as described in the section
 137     :ref:`section_ref_operator_requirements`. If there is some control
 138     :math:`U` included in the observation, the operator has to be applied to a
 139     pair :math:`(X,U)`.
 140
 141   Observers
 142     *Optional command*. This command allows to set internal observers, that are
 143     functions linked with a particular variable, which will be executed each
 144     time this variable is modified. It is a convenient way to monitor variables
 145     of interest during the data assimilation or optimization process, by
 146     printing or plotting it, etc. Common templates are provided to help the user
 147     to start or to quickly make his case.
 148
 149   OutputVariables
 150     *Optional command*. This command allows to indicates the name and size of
 151     physical variables that are bundled together in the output observation
 152     vector. This information is dedicated to data processed inside an algorithm.
 153
 154   Study_name
 155     *Required command*. This is an open string to describe the ADAO study by a
 156     name or a sentence.
 157
 158   Study_repertory
 159     *Optional command*. If available, this directory is used as base name for
 160     calculation, and used to find all the script files, given by name without
 161     path, that can be used to define some other commands by scripts.
 162
 163   UserDataInit
 164     *Optional command*. This commands allows to initialize some parameters or
 165     data automatically before algorithm input processing. It indicates a script
 166     file name to be executed before entering in initialization phase of chosen
 167     variables.
 168
 169   UserPostAnalysis
 170     *Optional command*. This commands allows to process some parameters or data
 171     automatically after data assimilation or optimization algorithm processing.
 172     Its value is defined as a script file or a string, allowing to put
 173     post-processing code directly inside the ADAO case. Common templates are
 174     provided to help the user to start or to quickly make his case.