doc/en/ref_covariance_requirements.rst

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