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

?pteqr

Computes all eigenvalues and (optionally) all eigenvectors of a real symmetric positive-definite tridiagonal matrix.

Syntax

lapack_int LAPACKE_spteqr( int matrix_layout, char compz, lapack_int n, float* d, float* e, float* z, lapack_int ldz );

lapack_int LAPACKE_dpteqr( int matrix_layout, char compz, lapack_int n, double* d, double* e, double* z, lapack_int ldz );

lapack_int LAPACKE_cpteqr( int matrix_layout, char compz, lapack_int n, float* d, float* e, lapack_complex_float* z, lapack_int ldz );

lapack_int LAPACKE_zpteqr( int matrix_layout, char compz, lapack_int n, double* d, double* e, lapack_complex_double* z, lapack_int ldz );

Include Files

  • mkl.h

Description

The routine computes all the eigenvalues and (optionally) all the eigenvectors of a real symmetric positive-definite tridiagonal matrix T. In other words, the routine can compute the spectral factorization: T = Z*Λ*ZT.

Here Λ is a diagonal matrix whose diagonal elements are the eigenvalues λi; Z is an orthogonal matrix whose columns are eigenvectors. Thus,

T*zi = λi*zi for i = 1, 2, ..., n.

(The routine normalizes the eigenvectors so that ||zi||2 = 1.)

You can also use the routine for computing the eigenvalues and eigenvectors of real symmetric (or complex Hermitian) positive-definite matrices A reduced to tridiagonal form T: A = Q*T*QH. In this case, the spectral factorization is as follows: A = Q*T*QH = (QZ)*Λ*(QZ)H. Before calling ?pteqr, you must reduce A to tridiagonal form and generate the explicit matrix Q by calling the following routines:

 

for real matrices:

for complex matrices:

full storage

?sytrd, ?orgtr

?hetrd, ?ungtr

packed storage

?sptrd, ?opgtr

?hptrd, ?upgtr

band storage

?sbtrd(vect='V')

?hbtrd(vect='V')

The routine first factorizes T as L*D*LH where L is a unit lower bidiagonal matrix, and D is a diagonal matrix. Then it forms the bidiagonal matrix B = L*D1/2 and calls ?bdsqr to compute the singular values of B, which are the square roots of the eigenvalues of T.

Input Parameters

matrix_layout

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

compz

Must be 'N' or 'I' or 'V'.

If compz = 'N', the routine computes eigenvalues only.

If compz = 'I', the routine computes the eigenvalues and eigenvectors of the tridiagonal matrix T.

If compz = 'V', the routine computes the eigenvalues and eigenvectors of A (and the array z must contain the matrix Q on entry).

n

The order of the matrix T (n 0).

d, e

Arrays:

d contains the diagonal elements of T.

The size of d must be at least max(1, n).

e contains the off-diagonal elements of T.

The size of e must be at least max(1, n-1).

z

Array, size max(1, ldz*n)

If compz = 'N' or 'I', z need not be set.

If compz = 'V', z must contain the orthogonal matrix used in the reduction to tridiagonal form..

ldz

The leading dimension of z. Constraints:

ldz 1 if compz = 'N';

ldz max(1, n) if compz = 'V' or 'I'.

Output Parameters

d

The n eigenvalues in descending order, unless info > 0.

See also info.

e

On exit, the array is overwritten.

z

If info = 0, contains an n-byn matrix the columns of which are orthonormal eigenvectors. (The i-th column corresponds to the i-th eigenvalue.)

Return Values

This function returns a value info.

If info=0, the execution is successful.

If info = i, the leading minor of order i (and hence T itself) is not positive-definite.

If info = n + i, the algorithm for computing singular values failed to converge; i off-diagonal elements have not converged to zero.

If info = -i, the i-th parameter had an illegal value.

Application Notes

If λi is an exact eigenvalue, and μi is the corresponding computed value, then

|μi - λi| c(n)*ε*K*λi

where c(n) is a modestly increasing function of n, ε is the machine precision, and K = ||DTD||2 *||(DTD)-1||2, D is diagonal with dii = tii-1/2.

If zi is the corresponding exact eigenvector, and wi is the corresponding computed vector, then the angle θ(zi, wi) between them is bounded as follows:

θ(ui, wi) c(n)εK / minij(|λi - λj|/|λi + λj|).

Here minij(|λi - λj|/|λi + λj|) is the relative gap between λi and the other eigenvalues.

The total number of floating-point operations depends on how rapidly the algorithm converges.

Typically, it is about

30n2 if compz = 'N';

6n3 (for complex flavors, 12n3) if compz = 'V' or 'I'.