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

?stegr

Computes selected eigenvalues and eigenvectors of a real symmetric tridiagonal matrix.

Syntax

lapack_int LAPACKE_sstegr( int matrix_layout, char jobz, char range, lapack_int n, float* d, float* e, float vl, float vu, lapack_int il, lapack_int iu, float abstol, lapack_int* m, float* w, float* z, lapack_int ldz, lapack_int* isuppz );

lapack_int LAPACKE_dstegr( int matrix_layout, char jobz, char range, lapack_int n, double* d, double* e, double vl, double vu, lapack_int il, lapack_int iu, double abstol, lapack_int* m, double* w, double* z, lapack_int ldz, lapack_int* isuppz );

lapack_int LAPACKE_cstegr( int matrix_layout, char jobz, char range, lapack_int n, float* d, float* e, float vl, float vu, lapack_int il, lapack_int iu, float abstol, lapack_int* m, float* w, lapack_complex_float* z, lapack_int ldz, lapack_int* isuppz );

lapack_int LAPACKE_zstegr( int matrix_layout, char jobz, char range, lapack_int n, double* d, double* e, double vl, double vu, lapack_int il, lapack_int iu, double abstol, lapack_int* m, double* w, lapack_complex_double* z, lapack_int ldz, lapack_int* isuppz );

Include Files

  • mkl.h

Description

The routine computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix T.

The spectrum may be computed either completely or partially by specifying either an interval (vl,vu] or a range of indices il:iu for the desired eigenvalues.

?stegr is a compatibility wrapper around the improved stemr routine. See its description for further details.

Note that the abstol parameter no longer provides any benefit and hence is no longer used.

Input Parameters

matrix_layout

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

jobz

Must be 'N' or 'V'.

If job = 'N', then only eigenvalues are computed.

If job = 'V', then eigenvalues and eigenvectors are computed.

range

Must be 'A' or 'V' or 'I'.

If range = 'A', the routine computes all eigenvalues.

If range = 'V', the routine computes eigenvalues w[i] in the half-open interval:

vl<w[i]vu.

If range = 'I', the routine computes eigenvalues with indices il to iu.

n

The order of the matrix T (n 0).

d, e

Arrays:

d contains the diagonal elements of T.

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

e contains the subdiagonal elements of T in elements 1 to n-1; e(n) need not be set on input, but it is used as a workspace.

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

vl, vu

If range = 'V', the lower and upper bounds of the interval to be searched for eigenvalues.

Constraint: vl< vu.

If range = 'A' or 'I', vl and vu are not referenced.

il, iu

If range = 'I', the indices in ascending order of the smallest and largest eigenvalues to be returned.

Constraint: 1 iliun, if n > 0.

If range = 'A' or 'V', il and iu are not referenced.

abstol

Unused. Was the absolute error tolerance for the eigenvalues/eigenvectors in previous versions.

ldz

The leading dimension of the output array z. Constraints:

ldz 1 if jobz = 'N';

ldz max(1, n) if jobz = 'V'.

Output Parameters

d, e

On exit, d and e are overwritten.

m

The total number of eigenvalues found,

0 mn.

If range = 'A', m = n, and if range = 'I', m = iu-il+1.

w

Array, size at least max(1, n).

The selected eigenvalues in ascending order, stored in w[0] to w[m - 1].

z

Array z(size max(1,ldz*m)).

If jobz = 'V', and if info = 0, the first m columns of z contain the orthonormal eigenvectors of the matrix T corresponding to the selected eigenvalues, with the i-th column of z holding the eigenvector associated with w[i - 1].

If jobz = 'N', then z is not referenced.

Note: if range = 'V', the exact value of m is not known in advance and an upper bound must be used. Using n = m is always safe.

isuppz

Array, size at least (2*max(1, m)).

The support of the eigenvectors in z, that is the indices indicating the nonzero elements in z. The i-th computed eigenvector is nonzero only in elements isuppz[2*i - 2] through isuppz[2*i - 1]. This is relevant in the case when the matrix is split. isuppz is only accessed when jobz = 'V', and n > 0.

Return Values

This function returns a value info.

If info=0, the execution is successful.

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

If info > 0, an internal error occurred.