Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

?pstrf

Computes the Cholesky factorization with complete pivoting of a real symmetric (complex Hermitian) positive semidefinite matrix.

Syntax

lapack_int LAPACKE_spstrf( int matrix_layout, char uplo, lapack_int n, float* a, lapack_int lda, lapack_int* piv, lapack_int* rank, float tol );

lapack_int LAPACKE_dpstrf( int matrix_layout, char uplo, lapack_int n, double* a, lapack_int lda, lapack_int* piv, lapack_int* rank, double tol );

lapack_int LAPACKE_cpstrf( int matrix_layout, char uplo, lapack_int n, lapack_complex_float* a, lapack_int lda, lapack_int* piv, lapack_int* rank, float tol );

lapack_int LAPACKE_zpstrf( int matrix_layout, char uplo, lapack_int n, lapack_complex_double* a, lapack_int lda, lapack_int* piv, lapack_int* rank, double tol );

Include Files

  • mkl.h

Description

The routine computes the Cholesky factorization with complete pivoting of a real symmetric (complex Hermitian) positive semidefinite matrix. The form of the factorization is:

  • PT * A * P = UT * U, if uplo ='U' for real flavors,

  • PT * A * P = UH * U, if uplo ='U' for complex flavors,

  • PT * A * P = L * LT, if uplo ='L' for real flavors,

  • PT * A * P = L * LH, if uplo ='L' for complex flavors,

where P is a permutation matrix stored as vector piv, and U and L are upper and lower triangular matrices, respectively.

This algorithm does not attempt to check that A is positive semidefinite. This version of the algorithm calls level 3 BLAS.

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

uplo

Must be 'U' or 'L'.

Indicates whether the upper or lower triangular part of A is stored:

If uplo = 'U', the array a stores the upper triangular part of the matrix A, and the strictly lower triangular part of the matrix is not referenced.

If uplo = 'L', the array a stores the lower triangular part of the matrix A, and the strictly upper triangular part of the matrix is not referenced.

n

The order of matrix A; n 0.

a

Array a, size max(1,lda*n). The array a contains either the upper or the lower triangular part of the matrix A (see uplo). .

tol

User defined tolerance. If tol < 0, then n*ε*max(Ak,k), where ε is the machine precision, will be used (see Error Analysis for the definition of machine precision). The algorithm terminates at the (k-1)-st step, if the pivot tol.

lda

The leading dimension of a; at least max(1, n).

Output Parameters

a

If info = 0, the factor U or L from the Cholesky factorization is as described in Description.

piv

Array, size at least max(1, n). The array piv is such that the nonzero entries are Ppiv[k-1],k (1 kn).

rank

The rank of a given by the number of steps the algorithm completed.

Return Values

This function returns a value info.

If info = 0, the execution is successful.

If info = -k, the k-th argument had an illegal value.

If info > 0, the matrix A is either rank deficient with a computed rank as returned in rank, or is not positive semidefinite.