solve_matrixSolveMatrixSolveMatrixsolve_matrixT_solve_matrix🔗

Short description🔗

solve_matrixSolveMatrixSolveMatrixsolve_matrixT_solve_matrix — Compute the solution of a system of equations.

Signature🔗

solve_matrix( matrix MatrixLHSID, string MatrixLHSType, real Epsilon, matrix MatrixRHSID, out matrix MatrixResultID )

Description🔗

The operator solve_matrixSolveMatrix computes the solution of a system of linear equations or of a linear least squares problem. The input matrices MatrixLHS and MatrixRHS are defined by the matrix handles MatrixLHSIDmatrixLHSIDmatrix_lhsid and MatrixRHSIDmatrixRHSIDmatrix_rhsid. The number of rows of matrices MatrixLHS and MatrixRHS must be identical. The operator returns the matrix handle MatrixResultIDmatrixResultIDmatrix_result_id of the matrix MatrixResult. Access to the elements of the matrix is possible e.g., with the operator get_full_matrixGetFullMatrix.

For linear equation systems, the equations

\[\begin{eqnarray*} \texttt{MatrixLHS} \quad \cdot \quad \texttt{MatrixResult} \quad = \quad \texttt{MatrixRHS} \end{eqnarray*}\]

are solved. Therefore, the matrix MatrixLHS must be a square matrix and the parameter Epsilonepsilonepsilon must be 0. The type of the matrix MatrixLHS can be selected via the parameter MatrixLHSTypematrixLHSTypematrix_lhstype. The following values are supported: 'general'"general" for general, 'symmetric'"symmetric" for symmetric, 'positive_definite'"positive_definite" for symmetric positive definite, 'tridiagonal'"tridiagonal" for tridiagonal, 'upper_triangular'"upper_triangular" for upper triangular, 'permuted_upper_triangular'"permuted_upper_triangular" for permuted upper triangular, 'lower_triangular'"lower_triangular" for lower triangular, and 'permuted_lower_triangular'"permuted_lower_triangular" for permuted lower triangular matrices.

Example:

MatrixLHSTypematrixLHSTypematrix_lhstype = 'positive_definite'"positive_definite", Epsilonepsilonepsilon = 00

\[\begin{eqnarray*} \texttt{MatrixLHS} = \left[ \begin{array}{rrr} 6.0 & 5.0 & 3.0 \\ 5.0 & 7.0 & 3.0 \\ 3.0 & 3.0 & 4.0 \end{array} \right] \qquad \texttt{MatrixRHS} = \left[ \begin{array}{rr} -1.0 & 6.0 \\ 3.0 & -3.0 \\ 5.0 & 4.0 \end{array} \right] \end{eqnarray*}\]

\[\begin{eqnarray*} \to \qquad \texttt{MatrixResult} = \left[ \begin{array}{rr} -2.0 & 3.0 \\ 1.0 & -3.0 \\ 2.0 & 1.0 \end{array} \right] \end{eqnarray*}\]

For linear least squares problems or if Epsilonepsilonepsilon is not 0, the matrix MatrixLHS need not be a square matrix. The linear least squares problem is solved using the singular value decomposition (SVD) of the matrix MatrixLHS by minimizing

\[\begin{eqnarray*} ||\,\texttt{MatrixRHS} \quad - \quad \texttt{MatrixLHS} \quad \cdot \quad \texttt{MatrixResult}\,||. \end{eqnarray*}\]

All singular values less than the value Epsilon \(\times\) the largest singular value are set to 0. For these values no internal division is done to prevent a division by zero. Also, the matrix MatrixLHS may be rank-deficient. The type of matrix must be selected via MatrixLHSTypematrixLHSTypematrix_lhstype = 'general'"general".

Example:

MatrixLHSTypematrixLHSTypematrix_lhstype = 'general'"general", Epsilonepsilonepsilon = 2.2204e-162.2204e-16

\[\begin{eqnarray*} \texttt{MatrixLHS} = \left[ \begin{array}{rrrr} 6.0 & 5.0 & 3.0 \\ 3.0 & 7.0 & -3.0 \\ 5.0 & 12.0 & 4.0 \\ 5.0 & 4.0 & 12.0 \\ 4.0 & 6.0 & 8.0 \end{array} \right] \qquad \texttt{MatrixRHS} = \left[ \begin{array}{r} 29.0 \\ 10.0 \\ 35.0 \\ 43.0 \\ 25.0 \end{array} \right] \end{eqnarray*}\]

\[\begin{eqnarray*} \to \qquad \texttt{MatrixResult} = \left[ \begin{array}{r} 3.4914 \\ 0.7114 \\ 1.6213 \end{array} \right] \end{eqnarray*}\]

Note: The relative accuracy of the floating point representation of the used data type (double) is Epsilonepsilonepsilon = 2.2204e-16.

Attention🔗

For MatrixLHSTypematrixLHSTypematrix_lhstype = 'symmetric'"symmetric", 'positive_definite'"positive_definite", or 'upper_triangular'"upper_triangular" the upper triangular part of the input MatrixLHS must contain the relevant information of the matrix. The strictly lower triangular part of the matrix is not referenced. For MatrixLHSTypematrixLHSTypematrix_lhstype = 'lower_triangular'"lower_triangular" the lower triangular part of the input MatrixLHS must contain the relevant information of the matrix. The strictly upper triangular part of the matrix is not referenced. For MatrixLHSTypematrixLHSTypematrix_lhstype = 'tridiagonal'"tridiagonal", only the main diagonal, the superdiagonal, and the subdiagonal of the input MatrixLHS are used. The other parts of the matrix are not referenced. If the referenced part of the input MatrixLHS 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🔗

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

Matrix handle of the input matrix of the left hand side.

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

The type of the input matrix of the left hand side.

Default: 'general'"general"
List of values: 'general', 'lower_triangular', 'permuted_lower_triangular', 'permuted_upper_triangular', 'positive_definite', 'symmetric', 'tridiagonal', 'upper_triangular'

Epsilonepsilonepsilon (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Type of solving and limitation to set singular values to be 0.

Default: 0.00.0
Suggested values: 0.0, 2.2204e-160.0, 2.2204e-16

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

Matrix handle of the input matrix of right hand side.

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

New matrix handle with the solution.

Result🔗

If the parameters are valid, the operator solve_matrixSolveMatrix 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

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