2 Copyright (C) 2008-2015 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 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.
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:
39 .. eficas_covariance_matrix:
40 .. image:: images/eficas_covariance_matrix.png
44 **Choosing covariance matrix representation**
46 First matrix form: using "*Matrix*" representation
47 ++++++++++++++++++++++++++++++++++++++++++++++++++
49 .. index:: single: Matrix
50 .. index:: single: BackgroundError
51 .. index:: single: EvolutionError
52 .. index:: single: ObservationError
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.
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}
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
70 BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
74 BackgroundError = numpy.eye(...)
76 Second matrix form: using "*ScalarSparseMatrix*" representation
77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
79 .. index:: single: ScalarSparseMatrix
80 .. index:: single: BackgroundError
81 .. index:: single: EvolutionError
82 .. index:: single: ObservationError
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`:
89 .. math:: \mathbf{M} = m \times \begin{pmatrix}
92 \vdots & \vdots & \vdots & \vdots \\
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
104 or, better, by a "*String*" directly in the ADAO case.
106 Third matrix form: using "*DiagonalSparseMatrix*" representation
107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
109 .. index:: single: DiagonalSparseMatrix
110 .. index:: single: BackgroundError
111 .. index:: single: EvolutionError
112 .. index:: single: ObservationError
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:
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}
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::
133 BackgroundError = [1, 1 ... 1]
137 BackgroundError = numpy.ones(...)