doc/en/ref_observations_requirements.rst

   1 ..
   2    Copyright (C) 2008-2024 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 .. _section_ref_observations_requirements:
  25
  26 Requirements for observation or experimental measurements description
  27 ---------------------------------------------------------------------
  28
  29 .. index:: single: setObservation
  30 .. index:: single: setObservationError
  31
  32 The whole set of measurements of the physical system we are considering are
  33 called "*observations*", or even simply "*an observation*". As already
  34 mentioned in :ref:`section_theory`, this observation is noted in the most
  35 generic way by:
  36
  37 .. math:: \mathbf{y}^o
  38
  39 It can depend in general of the space and the time, and even of parametric
  40 variables, and this in a more or less complex way. We usually particularize the
  41 time dependence by considering that, at each instant, the quantity
  42 :math:`\mathbf{y}^o` is a vector of :math:`\mbox{I\hspace{-.15em}R}^d` (with
  43 the dimension :math:`d` of the space being able to possibly vary in time). In
  44 other words, **an observation is a (temporal) series of (varied)
  45 measurements**. One will thus speak in an equivalent way of an observation
  46 (vector), of a series or a vector of observations, and of a set of
  47 observations. In its greatest generality, the sequential aspect of the series
  48 of observations is related jointly to space, and/or to time, and/or to a
  49 parametric dependence.
  50
  51 We can classify the ways of representing the observation according to the uses
  52 that we have afterwards and the links with the algorithmic methods. The
  53 classification that we propose is the following, each category being detailed
  54 below:
  55
  56 #. `Use of a single spatial observation`_
  57 #. `Use of a time series of spatial observations`_
  58 #. `Use of a single spatio-temporal observation`_
  59 #. `Use of a parameterized series of spatial observations`_
  60
  61 The numerical representations of the observations use all the possibilities
  62 described in the :ref:`section_ref_entry_types`. We specialize their uses here
  63 to indicate different possible ways of writing this information.
  64
  65 Use of a single spatial observation
  66 +++++++++++++++++++++++++++++++++++
  67
  68 .. index:: single: Vector
  69 .. index:: single: DataFile
  70
  71 This refers to the use of a vector series dependent only on space. This
  72 observation is moreover used at once, i.e. being completely known at the
  73 beginning of the algorithmic analysis. This can for example be a spatial field
  74 of measurements, or several fields physically homogeneous or not.
  75
  76 - The mathematical representation is :math:`\mathbf{y}^o\,\in\,\mbox{I\hspace{-.15em}R}^d`.
  77
  78 - The canonical numerical representation is **a vector**.
  79
  80 - The numerical representation in ADAO is done with the keyword "*Vector*". All
  81   the information, declared in one of the following representations, is
  82   transformed into a single vector (note: lists and tuples are equivalent):
  83
  84     - "*numpy.array*" variable : ``numpy.array([1, 2, 3])``
  85     - "*list*" variable        : ``[1, 2, 3]``
  86     - string variable          : ``'1 2 3'``
  87     - string variable          : ``'1,2,3'``
  88     - string variable          : ``'1;2;3'``
  89     - string variable          : ``'[1,2,3]'``
  90     - Python data file, with variable "*Observation*" in the namespace, indicated by the keyword "*Script*" with the condition ``Vector=True``
  91     - data text file (TXT, CSV, TSV, DAT), with variable pointer by name in column or row, indicated by the keyword "*DataFile*" with the condition ``Vector=True``
  92     - binary data file (NPY, NPZ), with variable pointer by name, indicated by the keyword "*DataFile*" with the condition ``Vector=True``
  93
  94 Examples of statements in TUI interface:
  95 ::
  96
  97     case.setObservation( Vector = [1, 2, 3] )
  98     case.setObservation( Vector = numpy.array([1, 2, 3]) )
  99     case.setObservation( Vector = '1 2 3' )
 100     case.setObservation( Vector=True, Script = 'script.py' )
 101     case.setObservation( Vector=True, DataFile = 'data.csv' )
 102     case.setObservation( Vector=True, DataFile = 'data.npy' )
 103
 104 Use note: in a given study, only the last record (whether a single vector or a
 105 series of vectors) can be used, as only one observation concept exists per ADAO
 106 study.
 107
 108 Use of a time series of spatial observations
 109 ++++++++++++++++++++++++++++++++++++++++++++
 110
 111 .. index:: single: VectorSerie
 112 .. index:: single: DataFile
 113
 114 This refers to a vector ordered series of observations, dependent on space and
 115 time. At a given instant, it is assumed that only the observations of the
 116 current and previous instants are known. The successive observations in time
 117 are indexed by :math:`n`, their instant of existence or of reference. This can
 118 for example be a spatial field of measurements, physically homogeneous or not,
 119 of which we consider a history.
 120
 121 - The mathematical representation is :math:`\forall\,n\in\{0...N\},\,\mathbf{y}^o_n\,\in\mbox{I\hspace{-.15em}R}^d`.
 122
 123 - The canonical numerical representation is **an ordered series of vectors**.
 124
 125 - The numerical representation in ADAO is done with the keyword
 126   "*VectorSeries*". The current indexing of the information is used to
 127   represent the time index when declaring in one of the following
 128   representations, and the information is transformed into an ordered series of
 129   vectors (note: lists and tuples are equivalent):
 130
 131     - "*list*" of "*numpy.array*"       : ``[numpy.array([1,2,3]), numpy.array([1,2,3])]``
 132     - "*numpy.array*" of "*list*"       : ``numpy.array([[1,2,3], [1,2,3]])``
 133     - "*list*" of "*list*"              : ``[[1,2,3], [1,2,3]]``
 134     - "*list*" of string variables      : ``['1 2 3', '1 2 3']``
 135     - "*list*" of string variables      : ``['1;2;3', '1;2;3']``
 136     - "*list*" of string variables      : ``['[1,2,3]', '[1,2,3]']``
 137     - string of "*list*"                : ``'[[1,2,3], [1,2,3]]'``
 138     - string of "*list*"                : ``'1 2 3 ; 1 2 3'``
 139     - Python data file, with variable "*Observation*" in the namespace, indicated by the keyword "*Script*" with the condition ``VectorSerie=True``
 140     - data text file (TXT, CSV, TSV), with variable pointer by name in column or row, indicated by the keyword "*DataFile*" with the condition ``VectorSerie=True``
 141     - binary data file (NPY, NPZ), with variable pointer by name, indicated by the keyword "*DataFile*" with the condition ``VectorSerie=True``
 142
 143 Examples of statements in TUI interface:
 144 ::
 145
 146     case.setObservation( VectorSerie = [[1,2,3], [1,2,3]] )
 147     case.setObservation( VectorSerie = [numpy.array([1,2,3]), numpy.array([1,2,3])] )
 148     case.setObservation( VectorSerie =  ['1 2 3', '1 2 3'] )
 149     case.setObservation( VectorSerie =  '[[1,2,3], [1,2,3]]' )
 150     case.setObservation( VectorSerie =  '1 2 3 ; 1 2 3' )
 151     case.setObservation( VectorSerie=True, Script = 'script.py' )
 152     case.setObservation( VectorSerie=True, DataFile = 'data.csv' )
 153     case.setObservation( VectorSerie=True, DataFile = 'data.npy' )
 154
 155 Use note: in a given study, only the last record (whether a single vector or a
 156 series of vectors) can be used, as only one observation concept exists per ADAO
 157 study.
 158
 159 Use of a single spatio-temporal observation
 160 +++++++++++++++++++++++++++++++++++++++++++
 161
 162 This single spatio-temporal observation is similar to the previous one in its
 163 representation as a vector series, but it imposes that it must be used in a
 164 single run, i.e. by being fully known at the beginning of the algorithmic
 165 analysis. It can therefore be represented as an indexed series, in the same way
 166 as for a `Use of a time series of spatial observations`_.
 167
 168 Use of a parameterized series of spatial observations
 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 170
 171 One represents now a collection of observations parameterized by an index or a
 172 discrete parameter. This form is still similar to the previous one. It is
 173 therefore representable as an indexed series, in the same way as for a `Use of
 174 a time series of spatial observations`_.
 175
 176 General comments on the observations
 177 ++++++++++++++++++++++++++++++++++++
 178
 179 .. warning::
 180
 181   When the assimilation explicitly establishes a **temporal iterative
 182   process**, as in state data assimilation, **the first observation is not used
 183   but must be present in the data description of a ADAO case**. By convention,
 184   it is therefore considered to be available at the same time as the draft time
 185   value, and does not lead to a correction at that time. The numbering of the
 186   observations starts at 0 by convention, so it is only from number 1 that the
 187   observation values are used in the temporal iterative algorithms.
 188
 189 Observations can be provided by single time steps or by successive windows for
 190 iterative algorithms. In this case, a series of observations must be provided
 191 for each algorithmic iteration relative to a time window. In practice, for each
 192 window, we provide a series as in a `Use of a time series of spatial
 193 observations`_.
 194
 195 The observation acquisition options are richer in the TUI textual interface, as
 196 not all options are necessarily available in the GUI.
 197
 198 For data entry via files, please refer to the description of the possibilities
 199 around the keyword "*DataFile*" in the :ref:`section_ref_entry_types_info`.