doc/en/ref_covariance_requirements.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 .. _section_ref_covariance_requirements:
  25
  26 Requirements to describe covariance matrices
  27 --------------------------------------------
  28
  29 Multiple covariance matrices are required to implement the data assimilation or
  30 optimization procedures. The main ones are the background error covariance
  31 matrix, noted as :math:`\mathbf{B}`, and the observation error covariance matrix,
  32 noted as :math:`\mathbf{R}`. Such a matrix is required to be a squared symmetric
  33 semi-definite positive matrix.
  34
  35 There are 3 practical methods for the user to provide a covariance matrix. The
  36 method is chosen by the "*INPUT_TYPE*" keyword of each defined covariance
  37 matrix, as shown by the following figure:
  38
  39   .. eficas_covariance_matrix:
  40   .. image:: images/eficas_covariance_matrix.png
  41     :align: center
  42     :width: 100%
  43   .. centered::
  44     **Choosing covariance matrix representation**
  45
  46 First matrix form: using "*Matrix*" representation
  47 ++++++++++++++++++++++++++++++++++++++++++++++++++
  48
  49 .. index:: single: Matrix
  50 .. index:: single: BackgroundError
  51 .. index:: single: EvolutionError
  52 .. index:: single: ObservationError
  53
  54 This first form is the default and more general one. The covariance matrix
  55 :math:`\mathbf{M}` has to be fully specified. Even if the matrix is symmetric by
  56 nature, the entire :math:`\mathbf{M}` matrix has to be given.
  57
  58 .. math:: \mathbf{M} =  \begin{pmatrix}
  59     m_{11} & m_{12} & \cdots   & m_{1n} \\
  60     m_{21} & m_{22} & \cdots   & m_{2n} \\
  61     \vdots & \vdots & \vdots   & \vdots \\
  62     m_{n1} & \cdots & m_{nn-1} & m_{nn}
  63     \end{pmatrix}
  64
  65 It can be either a Python Numpy array or a matrix, or a list of lists of values
  66 (that is, a list of rows). For example, a simple diagonal unitary background
  67 error covariance matrix :math:`\mathbf{B}` can be described in a Python script
  68 file as::
  69
  70     BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
  71
  72 or::
  73
  74     BackgroundError = numpy.eye(...)
  75
  76 Second matrix form: using "*ScalarSparseMatrix*" representation
  77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  78
  79 .. index:: single: ScalarSparseMatrix
  80 .. index:: single: BackgroundError
  81 .. index:: single: EvolutionError
  82 .. index:: single: ObservationError
  83
  84 On the opposite, this second form is a very simplified method to provide a
  85 matrix. The covariance matrix :math:`\mathbf{M}` is supposed to be a positive
  86 multiple of the identity matrix. This matrix can then be specified in a unique
  87 way by the multiplier :math:`m`:
  88
  89 .. math:: \mathbf{M} =  m \times \begin{pmatrix}
  90     1       & 0      & \cdots   & 0      \\
  91     0       & 1      & \cdots   & 0      \\
  92     \vdots  & \vdots & \vdots   & \vdots \\
  93     0       & \cdots & 0        & 1
  94     \end{pmatrix}
  95
  96 The multiplier :math:`m` has to be a floating point or integer positive value
  97 (if it is negative, which is impossible for a positive covariance matrix, it is
  98 converted to positive value). For example, a simple diagonal unitary background
  99 error covariance matrix :math:`\mathbf{B}` can be described in a python script
 100 file as::
 101
 102     BackgroundError = 1.
 103
 104 or, better, by a "*String*" directly in the ADAO case.
 105
 106 Third matrix form: using "*DiagonalSparseMatrix*" representation
 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 108
 109 .. index:: single: DiagonalSparseMatrix
 110 .. index:: single: BackgroundError
 111 .. index:: single: EvolutionError
 112 .. index:: single: ObservationError
 113
 114 This third form is also a simplified method to provide a matrix, but a little
 115 more powerful than the second one. The covariance matrix :math:`\mathbf{M}` is
 116 already supposed to be diagonal, but the user has to specify all the positive
 117 diagonal values. The matrix can then be specified only by a vector
 118 :math:`\mathbf{V}` which will be set on a diagonal matrix:
 119
 120 .. math:: \mathbf{M} =  \begin{pmatrix}
 121     v_{1}  & 0      & \cdots   & 0      \\
 122     0      & v_{2}  & \cdots   & 0      \\
 123     \vdots & \vdots & \vdots   & \vdots \\
 124     0      & \cdots & 0        & v_{n}
 125     \end{pmatrix}
 126
 127 It can be either a Python Numpy array or a matrix, or a list or a list of list
 128 of positive values (in all cases, if some are negative, which is impossible,
 129 they are converted to positive values). For example, a simple diagonal unitary
 130 background error covariance matrix :math:`\mathbf{B}` can be described in a
 131 python script file as::
 132
 133     BackgroundError = [1, 1 ... 1]
 134
 135 or::
 136
 137     BackgroundError = numpy.ones(...)