decompose_matrixDecomposeMatrixDecomposeMatrixdecompose_matrixT_decompose_matrix🔗

Short description🔗

decompose_matrixDecomposeMatrixDecomposeMatrixdecompose_matrixT_decompose_matrix — Decompose a matrix.

Signature🔗

decompose_matrix( matrix MatrixID, string MatrixType, out matrix Matrix1ID, out matrix Matrix2ID )

Description🔗

The operator decompose_matrixDecomposeMatrix decomposes the square input Matrix given by the matrix handle MatrixIDmatrixIDmatrix_id. The results are stored in two generated matrices Matrix1 and Matrix2. The operator returns the matrix handles Matrix1IDmatrix1IDmatrix_1id and Matrix2IDmatrix2IDmatrix_2id. Access to the elements of the matrices is possible e.g., with the operator get_full_matrixGetFullMatrix.

The type of the input Matrix can be selected via the parameter MatrixTypematrixTypematrix_type. The following values are supported: 'general'"general" for general, 'symmetric'"symmetric" for symmetric, 'positive_definite'"positive_definite" for symmetric positive definite, and 'tridiagonal'"tridiagonal" for tridiagonal matrices.

The decomposition MatrixTypematrixTypematrix_type = 'general'"general" or 'tridiagonal'"tridiagonal" is a LU factorization (Lower/Upper) with the form

\[\begin{eqnarray*} \texttt{Matrix} \quad = \quad \texttt{Matrix1} \quad \cdot \quad \texttt{Matrix2}. \end{eqnarray*}\]

The output Matrix1 is a lower triangular matrix with unit diagonal elements and interchanged rows. The output Matrix2 is an upper triangular matrix.

Example for a factorization of a general matrix:

\[\begin{eqnarray*} \texttt{Matrix} = \left[ \begin{array}{rrr} 5.0 & -3.0 & 1.0 \\ 0.0 & 2.0 & -1.0 \\ -5.0 & -1.0 & 5.0 \end{array} \right] \end{eqnarray*}\]

\[\begin{eqnarray*} \to \qquad \texttt{Matrix1} = \left[ \begin{array}{ccc} 1 & 0 & 0 \\ 0.0 & -0.5 & 1 \\ -1.0 & 1 & 0 \end{array} \right] \qquad \texttt{Matrix2} = \left[ \begin{array}{ccc} 5.0 & -3.0 & 1.0 \\ 0 & -4.0 & 6.0 \\ 0 & 0 & 2.0 \end{array} \right] \end{eqnarray*}\]

Example for a factorization of a tridiagonal matrix:

\[\begin{eqnarray*} \texttt{Matrix} = \left[ \begin{array}{rrrr} -8.0 & -8.0 & 0.0 & 0.0 \\ -8.0 & 6.0 & -4.0 & 0.0 \\ 0.0 & 7.0 & -2.0 & 7.0 \\ 0.0 & 0.0 & 5.0 & -3.0 \end{array} \right] \end{eqnarray*}\]

\[\begin{eqnarray*} \to \qquad \texttt{Matrix1} = \left[ \begin{array}{cccc} 1 & 0 & 0 & 0 \\ 1.0 & 1 & 0 & 0 \\ 0.0 & 0.5 & 0.0 & 1 \\ 0.0 & 0.0 & 1 & 0 \end{array} \right] \qquad \texttt{Matrix2} = \left[ \begin{array}{cccc} -8.0 & -8.0 & 0.0 & 0.0 \\ 0 & 14.0 & -4.0 & 0.0 \\ 0 & 0 & 5.0 & -3.0 \\ 0 & 0 & 0 & 7.0 \end{array} \right] \end{eqnarray*}\]

For MatrixTypematrixTypematrix_type = 'symmetric'"symmetric" the factorization is a UDU\(^T\) decomposition (Upper/Diagonal/Upper) with the form

\[\begin{eqnarray*} \texttt{Matrix} \quad = \quad \texttt{Matrix1} \quad \cdot \quad \texttt{Matrix2} \quad \cdot \quad \texttt{Matrix1}^T \end{eqnarray*}\]

where the output Matrix1 is an upper triangular matrix with interchanged columns. The output matrix Matrix2 is a symmetric block diagonal matrix with \(1\times 1\) and \(2\times 2\) diagonal blocks.

Example for a factorization of a symmetric matrix:

\[\begin{eqnarray*} \texttt{Matrix} = \left[ \begin{array}{rrrr} 3.0 & -2.0 & 7.0 & -1.0 \\ -2.0 & -2.0 & 4.0 & 0.0 \\ 7.0 & 4.0 & 8.0 & 1.0 \\ -1.0 & 0.0 & 1.0 & 0.0 \end{array} \right] \end{eqnarray*}\]

\[\begin{eqnarray*} \to \qquad \texttt{Matrix1} = \left[ \begin{array}{cccc} 0 & 0 & 1 & 0.0 \\ 0 & 1 & 0.0 & 2.0 \\ 1 & -1.0 & -1.0 & -10.0 \\ 0 & 0 & 0 & 1 \end{array} \right] \qquad \texttt{Matrix2} = \left[ \begin{array}{cccc} 27.0 & 0 & 0 & 0 \\ 0 & -2.0 & 0 & 0 \\ 0 & 0 & 3.0 & -1.0 \\ 0 & 0 & -1.0 & 0.0 \end{array} \right] \end{eqnarray*}\]

For MatrixTypematrixTypematrix_type = 'positive_definite'"positive_definite" a Cholesky factorization is computed with the form

\[\begin{eqnarray*} \texttt{Matrix} \quad = \quad \texttt{Matrix1} \quad \cdot \quad \texttt{Matrix2}. \end{eqnarray*}\]

where the output Matrix1 is a lower triangular matrix and the output matrix Matrix2 is an upper triangular matrix. Furthermore, the Matrix2 is the transpose of the matrix Matrix1.

Example for a factorization of a positive definite matrix:

\[\begin{eqnarray*} \texttt{Matrix} = \left[ \begin{array}{rrr} 9.0 & 12.0 & -6.0 \\ 12.0 & 17.0 & -7.0 \\ -6.0 & -7.0 & 14.0 \end{array} \right] \end{eqnarray*}\]

\[\begin{eqnarray*} \to \qquad \texttt{Matrix1} = \left[ \begin{array}{ccc} 3.0 & 0 & 0 \\ 4.0 & 1.0 & 0 \\ -2.0 & 1.0 & 3.0 \end{array} \right] \qquad \texttt{Matrix2} = \left[ \begin{array}{ccc} 3.0 & 4.0 & -2.0 \\ 0 & 1.0 & 1.0 \\ 0 & 0 & 3.0 \end{array} \right] \end{eqnarray*}\]

It should be noted that in the examples there are differences in the meaning of the values of the output matrices: If a value is shown as an integer number, e.g., 0 or 1, the value of this element is per definition this certain value. If the number is shown as a floating point number, e.g., 0.0 or 1.0, the value is computed by the operator.

Attention🔗

For MatrixTypematrixTypematrix_type = 'symmetric'"symmetric" or 'positive_definite'"positive_definite", the upper triangular part of the input Matrix must contain the relevant information of the matrix. The strictly lower triangular part of the matrix is not referenced. For MatrixTypematrixTypematrix_type = 'tridiagonal'"tridiagonal", only the main diagonal, the superdiagonal, and the subdiagonal of the input Matrix are used. The other parts of the matrix are not referenced. If the referenced part of the input Matrix is not of the specified type, an exception is raised.

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters🔗

MatrixIDmatrixIDmatrix_id (input_control) matrix → (handle)HTuple (HHandle)HMatrix, HTuple (IntPtr)HHandleHtuple (handle)

Matrix handle of the input matrix.

MatrixTypematrixTypematrix_type (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Type of the input matrix.

Default: 'general'"general"
List of values: 'general', 'positive_definite', 'symmetric', 'tridiagonal'

Matrix1IDmatrix1IDmatrix_1id (output_control) matrix → (handle)HTuple (HHandle)HMatrix, HTuple (IntPtr)HHandleHtuple (handle)

Matrix handle with the output matrix 1.

Matrix2IDmatrix2IDmatrix_2id (output_control) matrix → (handle)HTuple (HHandle)HMatrix, HTuple (IntPtr)HHandleHtuple (handle)

Matrix handle with the output matrix 2.

Result🔗

If the parameters are valid, the operator decompose_matrixDecomposeMatrix returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

create_matrixCreateMatrix

Possible successors

get_full_matrixGetFullMatrix, get_value_matrixGetValueMatrix

Alternatives

orthogonal_decompose_matrixOrthogonalDecomposeMatrix, solve_matrixSolveMatrix

References🔗

David Poole: “Linear Algebra: A Modern Introduction”; Thomson; Belmont; 2006.

Gene H. Golub, Charles F. van Loan: “Matrix Computations”; The Johns Hopkins University Press; Baltimore and London; 1996.

Module🔗

Foundation