naginterfaces.library.linsys.complex_​symm_​solve

naginterfaces.library.linsys.complex_symm_solve(uplo, n, a, b)

complex_symm_solve computes the solution to a complex system of linear equations $AX=B$, where $A$ is an $n\times n$ complex symmetric matrix and $X$ and $B$ are $n\times r$ matrices. An estimate of the condition number of $A$ and an error bound for the computed solution are also returned.

For full information please refer to the NAG Library document for f04dh

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f04/f04dhf.html

Parameters

uplostr, length 1

If $uplo=\text{'U'}$, the upper triangle of the matrix $A$ is stored.

If $uplo=\text{'L'}$, the lower triangle of the matrix $A$ is stored.

nint

The number of linear equations $n$, i.e., the order of the matrix $A$.

acomplex, array-like, shape $(n,n)$

The $n\times n$ complex symmetric matrix $A$.

If $uplo=\text{'U'}$, the leading $n$ by $n$ upper triangular part of the array $a$ contains the upper triangular part of the matrix $A$, and the strictly lower triangular part of $a$ is not referenced.

If $uplo=\text{'L'}$, the leading $n$ by $n$ lower triangular part of the array $a$ contains the lower triangular part of the matrix $A$, and the strictly upper triangular part of $a$ is not referenced.

bcomplex, array-like, shape $(n,\text{nrhs})$

The $n\times r$ matrix of right-hand sides $B$.

Returns

acomplex, ndarray, shape $(n,n)$

If no exception is raised, the block diagonal matrix $D$ and the multipliers used to obtain the factor $U$ or $L$ from the factorization $A=UD{U}^T$ or $A=LD{L}^T$ as computed by lapacklin.zsytrf.

ipivint, ndarray, shape $\left(n\right)$

If no exception is raised, details of the interchanges and the block structure of $D$, as determined by lapacklin.zsytrf.

If $ipiv[k-1]>0$, then rows and columns $k$ and $ipiv[k-1]$ were interchanged, and $d_{kk}$ is a $1\times 1$ diagonal block;

if $uplo=\text{'U'}$ and $ipiv[k-1]=ipiv[k-2]<0$, then rows and columns $k-1$ and $-ipiv[k-1]$ were interchanged and $d_{k-1:k,k-1:k}$ is a $2\times 2$ diagonal block;

if $uplo=\text{'L'}$ and $ipiv[k-1]=ipiv\left[k\right]<0$, then rows and columns $k+1$ and $-ipiv[k-1]$ were interchanged and $d_{k:k+1,k:k+1}$ is a $2\times 2$ diagonal block.

bcomplex, ndarray, shape $(n,\text{nrhs})$

If the function exits successfully or $errno$ = $n$ + 1, the $n\times r$ solution matrix $X$.

rcondfloat

If no constraints are violated, an estimate of the reciprocal of the condition number of the matrix $A$, computed as $rcond=1/\left({\parallel A\parallel }_1{\Vert A^{-1}\Vert }_1\right)$.

errbndfloat

If the function exits successfully or $errno$ = $n$ + 1, an estimate of the forward error bound for a computed solution $\hat{x}$, such that ${\parallel \hat{x}-x\parallel }_1/{\parallel x\parallel }_1\le errbnd$, where $\hat{x}$ is a column of the computed solution returned in the array $b$ and $x$ is the corresponding column of the exact solution $X$. If $rcond$ is less than machine precision, $errbnd$ is returned as unity.

Raises

NagValueError

(errno $-3$)

On entry, $\text{nrhs}=⟨value⟩$.

Constraint: $\text{nrhs}\ge 0$.

(errno $-2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $-1$)

On entry, $uplo$ not one of ‘U’ or ‘u’ or ‘L’ or ‘l’: $uplo=⟨value⟩$.

(errno $(i>0)\text{and}(i\le n)$)

Diagonal block $⟨value⟩$ of the block diagonal matrix is zero. The factorization has been completed, but the solution could not be computed.

Warns

NagAlgorithmicWarning

(errno $n+1$)

A solution has been computed, but $rcond$ is less than machine precision so that the matrix $A$ is numerically singular.

Notes

The diagonal pivoting method is used to factor $A$ as $A=UD{U}^T$, if $uplo=\text{'U'}$, or $A=LD{L}^T$, if $uplo=\text{'L'}$, where $U$ (or $L$) is a product of permutation and unit upper (lower) triangular matrices, and $D$ is symmetric and block diagonal with $1\times 1$ and $2\times 2$ diagonal blocks. The factored form of $A$ is then used to solve the system of equations $AX=B$.

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

Higham, N J, 2002, Accuracy and Stability of Numerical Algorithms, (2nd Edition), SIAM, Philadelphia