Matrix

class Matrix(*args)

Real rectangular matrix.

Parameters
n_rowsint, n_r > 0, optional

Number of rows. Default is 1.

n_columnsint, n_c > 0, optional

Number of columns. Default is 1.

valuessequence of float with size n_r \times n_c, optional

Values. column-major ordering is used (like Fortran) for reshaping the flat list of values. Default creates a zero matrix.

Examples

Create a matrix

>>> import openturns as ot
>>> M = ot.Matrix(2, 2, range(2 * 2))
>>> print(M)
[[ 0 2 ]
 [ 1 3 ]]

Get or set terms

>>> print(M[0, 0])
0.0
>>> M[0, 0] = 1.
>>> print(M[0, 0])
1.0
>>> print(M[:, 0])
[[ 1 ]
 [ 1 ]]

Create an openturns matrix from a numpy 2d-array (or matrix, or 2d-list)…

>>> import numpy as np
>>> np_2d_array = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> ot_matrix = ot.Matrix(np_2d_array)

and back

>>> np_matrix = np.matrix(ot_matrix)

Basic linear algebra operations (provided the dimensions are compatible)

>>> A = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> B = ot.Matrix(np.eye(2))
>>> C = ot.Matrix(3, 2, [1.] * 3 * 2)
>>> print(A * B - C)
[[ 0 1 ]
 [ 2 3 ]
 [ 4 5 ]]

Methods

clean(self, threshold)

Set elements smaller than a threshold to zero.

computeGram(self[, transpose])

Compute the associated Gram matrix.

computeQR(self[, fullQR, keepIntact])

Compute the QR factorization.

computeSVD(self[, fullSVD, keepIntact])

Compute the singular values decomposition (SVD).

computeSingularValues(self[, keepIntact])

Compute the singular values.

getClassName(self)

Accessor to the object’s name.

getId(self)

Accessor to the object’s id.

getImplementation(self, \*args)

Accessor to the underlying implementation.

getName(self)

Accessor to the object’s name.

getNbColumns(self)

Accessor to the number of columns.

getNbRows(self)

Accessor to the number of rows.

isEmpty(self)

Tell if the matrix is empty.

reshape(self, newRowDim, newColDim)

Reshape the matrix.

reshapeInPlace(self, newRowDim, newColDim)

Reshape the matrix, in place.

setName(self, name)

Accessor to the object’s name.

solveLinearSystem(self, \*args)

Solve a rectangular linear system whose the present matrix is the operator.

transpose(self)

Transpose the matrix.

__init__(self, *args)

Initialize self. See help(type(self)) for accurate signature.

clean(self, threshold)

Set elements smaller than a threshold to zero.

Parameters
thresholdfloat

Threshold for zeroing elements.

Returns
cleaned_matrixMatrix

Input matrix with elements smaller than the threshold set to zero.

computeGram(self, transpose=True)

Compute the associated Gram matrix.

Parameters
transposedbool

Tells if matrix is to be transposed or not. Default value is True

Returns
MMTMatrix

The Gram matrix.

Notes

When transposed is set to True, the method computes cM^t \times \cM. Otherwise it computes \cM \ times \cM^t

Examples

>>> import openturns as ot
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> MtM = M.computeGram()
>>> print(MtM)
[[ 35 44 ]
 [ 44 56 ]]
>>> MMt = M.computeGram(False)
>>> print(MMt)
[[  5 11 17 ]
 [ 11 25 39 ]
 [ 17 39 61 ]]
computeQR(self, fullQR=False, keepIntact=True)

Compute the QR factorization. By default, it is the economic decomposition which is computed.

The economic QR factorization of a rectangular matrix \mat{M} with n_r \geq n_c (more rows than columns) is defined as follows:

\mat{M} = \mat{Q} \mat{R}
        = \mat{Q} \begin{bmatrix} \mat{R_1} \\ \mat{0} \end{bmatrix}
        = \begin{bmatrix} \mat{Q_1}, \mat{Q_2} \end{bmatrix}
          \begin{bmatrix} \mat{R_1} \\ \mat{0} \end{bmatrix}
        = \mat{Q_1} \mat{R_1}

where \mat{R_1} is an n_c \times n_c upper triangular matrix, \mat{Q_1} is n_r \times n_c, \mat{Q_2} is n_r \times (n_r - n_c), and \mat{Q_1} and \mat{Q_2} both have orthogonal columns.

Parameters
full_qrbool, optional

A flag telling whether Q, R or Q1, R1 are returned. Default is False and returns Q1, R1.

keep_intactbool, optional

A flag telling whether the present matrix is preserved or not in the computation of the decomposition. Default is True and leaves the present matrix unchanged.

Returns
Q1Matrix

The orthogonal matrix of the economic QR factorization.

R1TriangularMatrix

The right (upper) triangular matrix of the economic QR factorization.

QMatrix

The orthogonal matrix of the full QR factorization.

RTriangularMatrix

The right (upper) triangular matrix of the full QR factorization.

Notes

The economic QR factorization is often used for solving overdetermined linear systems (where the operator \mat{M} has n_r \geq n_c) in the least-square sense because it implies solving a (simple) triangular system:

\vect{\hat{x}} = \arg\min\limits_{\vect{x} \in \Rset^{n_r}} \|\mat{M} \vect{x} - \vect{b}\|
               = \mat{R_1}^{-1} (\Tr{\mat{Q_1}} \vect{b})

This uses LAPACK’s DGEQRF and DORGQR.

Examples

>>> import openturns as ot
>>> import numpy as np
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> Q1, R1 = M.computeQR()
>>> np.testing.assert_array_almost_equal(Q1 * R1, M)
computeSVD(self, fullSVD=False, keepIntact=True)

Compute the singular values decomposition (SVD).

The singular values decomposition of a rectangular matrix \mat{M} with size n_r > n_c reads:

\mat{M} = \mat{U} \mat{\Sigma} \Tr{\mat{V}}

where \mat{U} is an n_r \times n_r orthogonal matrix, \mat{\Sigma} is an n_r \times n_c diagonal matrix and \mat{V} is an n_c \times n_c orthogonal matrix.

Parameters
fullSVDbool, optional

Whether the null parts of the orthogonal factors are explicitely stored or not. Default is False and computes a reduced SVD.

keep_intactbool, optional

A flag telling whether the present matrix can be overwritten or not. Default is True and leaves the present matrix unchanged.

Returns
singular_valuesPoint

The vector of singular values with size n = \min(n_r, n_c) that form the diagonal of the n_r \times n_c matrix \mat{\Sigma} of the SVD.

USquareMatrix

The left orthogonal matrix of the SVD.

VTSquareMatrix

The transposed right orthogonal matrix of the SVD.

Notes

This uses LAPACK’s DGESDD.

Examples

>>> import openturns as ot
>>> import numpy as np
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> singular_values, U, VT = M.computeSVD(True)
>>> Sigma = ot.Matrix(M.getNbRows(), M.getNbColumns())
>>> for i in range(singular_values.getSize()):
...     Sigma[i, i] = singular_values[i]
>>> np.testing.assert_array_almost_equal(U * Sigma * VT, M)
computeSingularValues(self, keepIntact=True)

Compute the singular values.

Parameters
fullSVDbool, optional

Whether the null parts of the orthogonal factors are explicitely stored or not. Default is False and computes a reduced SVD.

keep_intactbool, optional

A flag telling whether the present matrix can be overwritten or not. Default is True and leaves the present matrix unchanged.

Returns
singular_valuesPoint

The vector of singular values with size n = \min(n_r, n_c) that form the diagonal of the n_r \times n_c matrix \mat{\Sigma} of the SVD decomposition.

See also

computeSVD

Examples

>>> import openturns as ot
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> print(M.computeSingularValues(True))
[9.52552,0.514301]
getClassName(self)

Accessor to the object’s name.

Returns
class_namestr

The object class name (object.__class__.__name__).

getId(self)

Accessor to the object’s id.

Returns
idint

Internal unique identifier.

getImplementation(self, *args)

Accessor to the underlying implementation.

Returns
implImplementation

The implementation class.

getName(self)

Accessor to the object’s name.

Returns
namestr

The name of the object.

getNbColumns(self)

Accessor to the number of columns.

Returns
n_columnsint
getNbRows(self)

Accessor to the number of rows.

Returns
n_rowsint
isEmpty(self)

Tell if the matrix is empty.

Returns
is_emptybool

True if the matrix contains no element.

Examples

>>> import openturns as ot
>>> M = ot.Matrix([[]])
>>> M.isEmpty()
True
reshape(self, newRowDim, newColDim)

Reshape the matrix.

Parameters
newRowDimint

The row dimension of the reshaped matrix.

newColDimint

The column dimension of the reshaped matrix.

Returns
MTMatrix

The reshaped matrix.

Notes

If the size of the reshaped matrix is smaller than the size of the matrix to be reshaped, only the newRowDim\times newColDim first elements are kept (in a column-major storage sense). If the size is greater, the new elements are set to zero.

Examples

>>> import openturns as ot
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> print(M)
[[ 1 2 ]
 [ 3 4 ]
 [ 5 6 ]]
>>> print(M.reshape(1, 6))
1x6
[[ 1 3 5 2 4 6 ]]
>>> print(M.reshape(2, 2))
[[ 1 5 ]
 [ 3 2 ]]
>>> print(M.reshape(2, 6))
2x6
[[ 1 5 4 0 0 0 ]
 [ 3 2 6 0 0 0 ]]
reshapeInPlace(self, newRowDim, newColDim)

Reshape the matrix, in place.

Parameters
newRowDimint

The row dimension of the reshaped matrix.

newColDimint

The column dimension of the reshaped matrix.

Notes

If the size of the reshaped matrix is smaller than the size of the matrix to be reshaped, only the newRowDim\times newColDim first elements are kept (in a column-major storage sense). If the size is greater, the new elements are set to zero. If the size is unchanged, no copy of data is done.

Examples

>>> import openturns as ot
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> print(M)
[[ 1 2 ]
 [ 3 4 ]
 [ 5 6 ]]
>>> M.reshapeInPlace(1, 6)
>>> print(M)
1x6
[[ 1 3 5 2 4 6 ]]
>>> M.reshapeInPlace(2, 2)
>>> print(M)
[[ 1 5 ]
 [ 3 2 ]]
>>> M.reshapeInPlace(2, 6)
>>> print(M)
2x6
[[ 1 5 0 0 0 0 ]
 [ 3 2 0 0 0 0 ]]
setName(self, name)

Accessor to the object’s name.

Parameters
namestr

The name of the object.

solveLinearSystem(self, *args)

Solve a rectangular linear system whose the present matrix is the operator.

Parameters
rhsPoint or Matrix with n_r values or rows, respectively

The right hand side member of the linear system.

keep_intactbool, optional

A flag telling whether the present matrix can be overwritten or not. Default is True and leaves the present matrix unchanged.

Returns
solutionPoint or Matrix

The solution of the rectangular linear system.

Notes

This will handle both matrices and vectors, as well as underdetermined, square or overdetermined linear systems although you’d better type explicitely your matrix if it has some properties that could simplify the resolution (see TriangularMatrix, SquareMatrix).

This uses LAPACK’s DGELSY. The RCOND parameter of this routine can be changed through the MatrixImplementation-DefaultSmallPivot key of the ResourceMap.

Examples

>>> import openturns as ot
>>> import numpy as np
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> b = ot.Point([1.0] * 3)
>>> x = M.solveLinearSystem(b)
>>> np.testing.assert_array_almost_equal(M * x, b)
transpose(self)

Transpose the matrix.

Returns
MTMatrix

The transposed matrix.

Examples

>>> import openturns as ot
>>> M = ot.Matrix([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
>>> print(M)
[[ 1 2 ]
 [ 3 4 ]
 [ 5 6 ]]
>>> print(M.transpose())
[[ 1 3 5 ]
 [ 2 4 6 ]]