naginterfaces.library.lapacklin.dpstrf

naginterfaces.library.lapacklin.dpstrf(uplo, n, a, tol=- 1)

dpstrf computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix.

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f07/f07kdf.html

Parameters

uplostr, length 1

Specifies whether the upper or lower triangular part of $A$ is stored and how $A$ is to be factorized.

$uplo=\text{'U'}$

The upper triangular part of $A$ is stored and $A$ is factorized as $U^{T}U$, where $U$ is upper triangular.

$uplo=\text{'L'}$

The lower triangular part of $A$ is stored and $A$ is factorized as $L{L}^T$, where $L$ is lower triangular.

nint

$n$, the order of the matrix $A$.

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

The $n\times n$ symmetric positive semidefinite matrix $A$.

tolfloat, optional

User defined tolerance. If $tol<0$, $n\times {\text{max}}_{k=1,n}\left|A_{kk}\right|\times \text{machine precision}$ will be used. The algorithm terminates at the $r$th step if the $(r+1)$th step pivot $<tol$.

Returns

afloat, ndarray, shape $(n,n)$

If $uplo=\text{'U'}$, the first $rank$ rows of the upper triangle of $A$ are overwritten with the nonzero elements of the Cholesky factor $U$, and the remaining rows of the triangle are destroyed.

If $uplo=\text{'L'}$, the first $rank$ columns of the lower triangle of $A$ are overwritten with the nonzero elements of the Cholesky factor $L$, and the remaining columns of the triangle are destroyed.

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

$piv$ is such that the nonzero entries of $P$ are $P(piv[\text{k}-1],\text{k})=1$, for $\text{k}=1,2,\dots ,n$.

rankint

The computed rank of $A$ given by the number of steps the algorithm completed.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $uplo$.

Constraint: $uplo=\text{'U'}$ or $\text{'L'}$.

(errno $-2$)

On entry, error in parameter $n$.

Constraint: $n\ge 0$.

Warns

NagAlgorithmicWarning

(errno $1$)

The matrix $A$ is not positive definite. It is either positive semidefinite with computed rank as returned in $rank$ and less than $n$, or it may be indefinite, see Further Comments.

Notes

dpstrf forms the Cholesky factorization of a real symmetric positive semidefinite matrix $A$ either as $P^{T}AP=U^{T}U$ if $uplo=\text{'U'}$ or $P^{T}AP=L{L}^T$ if $uplo=\text{'L'}$, where $P$ is a permutation matrix, $U$ is an upper triangular matrix and $L$ is lower triangular.

This algorithm does not attempt to check that $A$ is positive semidefinite.

References

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

Lucas, C, 2004, LAPACK-style codes for Level 2 and 3 pivoted Cholesky factorizations, LAPACK Working Note No. 161. Technical Report CS-04-522, Department of Computer Science, University of Tennessee, 107 Ayres Hall, Knoxville, TN 37996-1301, USA, https://www.netlib.org/lapack/lawnspdf/lawn161.pdf