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

?sysv_rk

Computes the solution to system of linear equations A * X = B for SY matrices.

lapack_int LAPACKE_ssysv_rk (int matrix_layout, char uplo, lapack_int n, lapack_int nrhs, float * A, lapack_int lda, float * e, lapack_int * ipiv, float * B, lapack_int ldb);

lapack_int LAPACKE_dsysv_rk (int matrix_layout, char uplo, lapack_int n, lapack_int nrhs, double * A, lapack_int lda, double * e, lapack_int * ipiv, double * B, lapack_int ldb);

lapack_int LAPACKE_csysv_rk (int matrix_layout, char uplo, lapack_int n, lapack_int nrhs, lapack_complex_float * A, lapack_int lda, lapack_complex_float * e, lapack_int * ipiv, lapack_complex_float * B, lapack_int ldb);

lapack_int LAPACKE_zsysv_rk (int matrix_layout, char uplo, lapack_int n, lapack_int nrhs, lapack_complex_double * A, lapack_int lda, lapack_complex_double * e, lapack_int * ipiv, lapack_complex_double * B, lapack_int ldb);

Description

?sysv_rk computes the solution to a real or complex system of linear equations A * X = B, where A is an n-by-n symmetric matrix and X and B are n-by-nrhs matrices.

The bounded Bunch-Kaufman (rook) diagonal pivoting method is used to factor A as A= P*U*D*(UT)*(PT), if uplo = 'U', or A= P*L*D*(LT)*(PT), if uplo = 'L', where U (or L) is unit upper (or lower) triangular matrix, UT (or LT) is the transpose of U (or L), P is a permutation matrix, PT is the transpose of P, and D is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks.

?sytrf_rk is called to compute the factorization of a real or complex symmetric matrix. The factored form of A is then used to solve the system of equations A * X = B by calling BLAS3 routine ?sytrs_3.

Input Parameters

matrix_layout

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

uplo

Specifies whether the upper or lower triangular part of the symmetric matrix A is stored:

  • = 'U': The upper triangle of A is stored.
  • = 'L': The lower triangle of A is stored.
n

The number of linear equations; that is, the order of the matrix A. n ≥ 0.

nrhs

The number of right-hand sides; that is, the number of columns of the matrix B. nrhs ≥ 0.

A

Array of size max(1, lda*n). On entry, the symmetric matrix A. If uplo = 'U', the leading n-by-n upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If uplo = 'L', the leading n-by-n lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced.

lda

The leading dimension of the array A.

B

Array of size max(1, ldb*nrhs). On entry, the n-by-nrhs right-hand side matrix B.

ldb

The leading dimension of the array B. ldb ≥ max(1, n) for column-major layout and ldbnrhs for row-major layout.

Output Parameters

A

On exit, if info = 0, the diagonal of the block diagonal matrix D and factors U or L as computed by ?sytrf_rk:

  • Only diagonal elements of the symmetric block diagonal matrix D on the diagonal of A; that is, D(k,k) = A(k,k). Superdiagonal (or subdiagonal) elements of D are stored on exit in array e.
  • If uplo = 'U', factor U in the superdiagonal part of A. If uplo = 'L', factor L in the subdiagonal part of A. For more information, see the description of the ?sytrf_rk routine.
e

Array of size n. On exit, contains the output computed by the factorization routine ?sytrf_rk; that is, the superdiagonal (or subdiagonal) elements of the symmetric block diagonal matrix D with 1-by-1 or 2-by-2 diagonal blocks. If uplo = 'U', e(i) = D(i-1,i), i=1:N-1, and e(1) is set to 0. If uplo = 'L', e(i) = D(i+1,i), i=1:N-1, and e(n) is set to 0.

NOTE:
For 1-by-1 diagonal block D(k), where 1 ≤ k ≤ n, the element e(k) is set to 0 in both the uplo = 'U' and uplo = 'L' cases. For more information, see the description of the?sytrf_rk routine.
ipiv

Array of size n. Details of the interchanges and the block structure of D, as determined by ?sytrf_rk. For more information, see the description of the ?sytrf_rk routine.

B

On exit, if info = 0, the n-by-nrhs solution matrix X.

Return Values

This function returns a value info.

= 0: Successful exit.

< 0: If info = -k, the kth argument had an illegal value.

> 0: If info = k, the matrix A is singular. If uplo = 'U', column k in the upper triangular part of A contains all zeros. If uplo = 'L', column k in the lower triangular part of A contains all zeros. Therefore D(k,k) is exactly zero, and superdiagonal elements of column k of U (or subdiagonal elements of column k of L) are all zeros. The factorization has been completed, but the block diagonal matrix D is exactly singular, and division by zero will occur if it is used to solve a system of equations.