ILMathlinsolve Method (InArraycomplex, InArraycomplex, MatrixProperties, Boolean)

public static RetArray<complex> linsolve(
	InArray<complex> A,
	InArray<complex> B,
	ref MatrixProperties props,
	bool throwException = true
)

Public Shared Function linsolve ( 
	A As InArray(Of complex),
	B As InArray(Of complex),
	ByRef props As MatrixProperties,
	Optional throwException As Boolean = true
) As RetArray(Of complex)

Dim A As InArray(Of complex)
Dim B As InArray(Of complex)
Dim props As MatrixProperties
Dim throwException As Boolean
Dim returnValue As RetArray(Of complex)

returnValue = ILMath.linsolve(A, B, 
	props, throwException)

Parameters

A

Type: ILNumericsInArraycomplex
Input matrix A. Size [n, q].

B

Type: ILNumericsInArraycomplex
Right hand side B. Size [n, m].

props

Type: ILNumericsMatrixProperties
[Input, Output] Known / determined matrix properties of A.

throwException (Optional)

Type: SystemBoolean
[Optional] Throws an ArgumentException if A was found to be singular or a specific property in props could not be confirmed. Default: true.

Return Value

If no specific properties of A are given in props and depending on the actual structure and properties of A the equation system is solved with different approaches:

• If A is square (q == n) and an upper or lower triangular matrix, the system is solved via backward- or forward substitution and the LAPACK function ?trtrs.
  Examples

  ---

  Copy

  Array<complex> A = randn<complex>(4,4); // construct 4 x 4 matrix
              Array<complex> B = vector<complex>(1.0,2.0,3.0);
              Array<complex> x = linsolve(A,B);

• if A is square, symmetric /hermitian and positive definite A is decomposed into a triangular equation system using cholesky factorization and solved via back-/ forward substitution.

• otherwise, if A is only square it will be decomposed into upper and lower triangular matrices using LU decomposition and the system is than solved with the triangular result.
• otherwise, if A' is [n, q] with q != n, the system is solved using qr(InArraycomplex) decomposition. Note that A can be rank deficient.

Specifying known properties of A in props may saves some time in determining these properties. If, for example, A is known to be positive definite, providing PositivDefinite allows the algorithm to perform cholesky factorization with A. However, linsolve(InArraycomplex, InArraycomplex, MatrixProperties, Boolean) determines advantageous properties automatically if required.

After returning the props structure can be inspected fo the matrix properties of A found during the computations. Any bits changed in props by the function reflect the path taken within linsolve(InArraycomplex, InArraycomplex, MatrixProperties, Boolean). However, linsolve(InArraycomplex, InArraycomplex, MatrixProperties, Boolean) does not determine all properties of A automatically. If, let's say: A is found to be singular, the function returns (or throws an exception) without determining further properties of A. In order to query specific properties of A other functionality may be more appropriate.

If throwException is false inspecting the props structure on return is required to verify that a valid solution has been computed. If A was found to be singular and throwException is false then props will have the Singular flag set. If the computation was performed by QR decomposition for a non-square matrix A then the RankDeficient flag may be set.

The internal storage order of A and/or B may be silently changed by this function. The reason is that most functionality is performed in native LAPACK routines which require a certain storage layout (mostly ColumnMajor). Be prepared that both arrays may point to different memory regions for element storage afterwards! This does not, however, affect the handling of the array with common high level functionality (subarrays, element access etc.).

[ILNumerics Computing Engine]

Reference