2 Copyright (C) 2008-2016 EDF R&D
4 This file is part of SALOME ADAO module.
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.
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.
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
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
24 .. _section_ref_covariance_requirements:
26 Requirements to describe covariance matrices
27 --------------------------------------------
29 .. index:: single: covariance matrix
30 .. index:: single: background error covariances
31 .. index:: single: observation error covariances
32 .. index:: single: covariances
34 In general, a covariance matrix (or a variance-covariance matrix) has to be
35 squared, symetric, 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):
42 .. math:: \mathbf{M} = \mathbf{\Sigma} * \mathbf{C} * \mathbf{\Sigma}
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}`.
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:
53 .. eficas_covariance_matrix:
54 .. image:: images/eficas_covariance_matrix.png
58 **Choosing covariance matrix representation**
60 First matrix form: using "*Matrix*" representation
61 ++++++++++++++++++++++++++++++++++++++++++++++++++
63 .. index:: single: Matrix
64 .. index:: single: BackgroundError
65 .. index:: single: EvolutionError
66 .. index:: single: ObservationError
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.
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}
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
84 BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
88 BackgroundError = numpy.eye(...)
90 Second matrix form: using "*ScalarSparseMatrix*" representation
91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
93 .. index:: single: ScalarSparseMatrix
94 .. index:: single: BackgroundError
95 .. index:: single: EvolutionError
96 .. index:: single: ObservationError
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`:
103 .. math:: \mathbf{M} = m \times \begin{pmatrix}
104 1 & 0 & \cdots & 0 \\
105 0 & 1 & \cdots & 0 \\
106 \vdots & \vdots & \vdots & \vdots \\
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
118 or, better, by a "*String*" directly in the ADAO case.
120 Third matrix form: using "*DiagonalSparseMatrix*" representation
121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
123 .. index:: single: DiagonalSparseMatrix
124 .. index:: single: BackgroundError
125 .. index:: single: EvolutionError
126 .. index:: single: ObservationError
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:
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}
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::
147 BackgroundError = [1, 1 ... 1]
151 BackgroundError = numpy.ones(...)