Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

Contents

?stegr2

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

Syntax

void sstegr2
(
char*
jobz
,
char*
range
,
MKL_INT*
n
,
float*
d
,
float*
e
,
float*
vl
,
float*
vu
,
MKL_INT*
il
,
MKL_INT*
iu
,
MKL_INT*
m
,
float*
w
,
float*
z
,
MKL_INT*
ldz
,
MKL_INT*
nzc
,
MKL_INT*
isuppz
,
float*
work
,
MKL_INT*
lwork
,
MKL_INT*
iwork
,
MKL_INT*
liwork
,
MKL_INT*
dol
,
MKL_INT*
dou
,
MKL_INT*
zoffset
,
MKL_INT*
info
);
void dstegr2
(
char*
jobz
,
char*
range
,
MKL_INT*
n
,
double*
d
,
double*
e
,
double*
vl
,
double*
vu
,
MKL_INT*
il
,
MKL_INT*
iu
,
MKL_INT*
m
,
double*
w
,
double*
z
,
MKL_INT*
ldz
,
MKL_INT*
nzc
,
MKL_INT*
isuppz
,
double*
work
,
MKL_INT*
lwork
,
MKL_INT*
iwork
,
MKL_INT*
liwork
,
MKL_INT*
dol
,
MKL_INT*
dou
,
MKL_INT*
zoffset
,
MKL_INT*
info
);
Include Files
  • mkl_scalapack.h
Description
?stegr2
 computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix
T
. It is invoked in the ScaLAPACK MRRR driver
p?syevr
 and the corresponding Hermitian version either when only eigenvalues are to be computed, or when only a single processor is used (the sequential-like case).
?stegr2
 has been adapted from LAPACK's
?stegr
. Please note the following crucial changes.
  1. The calling sequence has two additional integer parameters,
    dol
     and
    dou
    , that should satisfy
    m
    ≥
    dou
    ≥
    dol
    ≥
    1.
    ?stegr2
    only
     computes the eigenpairs corresponding to eigenvalues
    dol
     through
    dou
     in
    w
    , indexed
    dol
    -1 through
    dou
    -1
    . (That is, instead of computing the eigenpairs belonging to
    w
    [0] through
    w
    [
    m
    -1]
    , only the eigenvectors belonging to eigenvalues
    w
    [
    dol
    -1] through
    w
    [
    dou
    -1]
     are computed. In this case, only the eigenvalues
    dol
     through
    dou
     are guaranteed to be fully accurate.
  2. m
     is
    not
     the number of eigenvalues specified by
    range
    , but is
    m
     =
    dou
     -
    dol
     + 1. This concerns the case where only eigenvalues are computed, but on more than one processor. Thus, in this case
    m
     refers to the number of eigenvalues computed on this processor.
  3. The arrays
    w
     and
    z
     might not contain all the wanted eigenpairs locally, instead this information is distributed over other processors.
Product and Performance Information
Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.
Notice revision #20201201
Input Parameters
jobz
= 'N': Compute eigenvalues only;
= 'V': Compute eigenvalues and eigenvectors.
range
= 'A': all eigenvalues will be found.
= 'V': all eigenvalues in the half-open interval (
vl
,
vu
] will be found.
= 'I':
eigenvalues of the entire matrix with the indices in a given range
 will be found.
n
The order of the matrix.
n
≥
 0.
d
Array of size
n
On entry, the
n
 diagonal elements of the tridiagonal matrix
T
. Overwritten on exit.
e
Array of size
n
On entry, the (
n
-1) subdiagonal elements of the tridiagonal matrix
T
 in elements
0 to
n
-2
 of
e
.
e
[
n
-1]
 need not be set on input, but is used internally as workspace. Overwritten on exit.
vl
vu
If
range
='V', the lower and upper bounds of the interval to be searched for eigenvalues.
vl
 <
vu
.
Not referenced if
range
 = 'A' or 'I'.
il, iu
If
range
='I', the indices (in ascending order) of the
smallest eigenvalue, to be returned in
w
[
il
-1], and largest eigenvalue, to be returned in
w
[
iu
-1]
.
1
≤
il
≤
iu
≤
n
, if
n
 > 0.
Not referenced if
range
 = 'A' or 'V'.
ldz
The leading dimension of the array
z
.
ldz
≥
 1, and if
jobz
 = 'V', then
ldz
≥
 max(1,
n
).
nzc
The number of eigenvectors to be held in the array
z
, storing the matrix
Z
.
If
range
 = 'A', then
nzc
≥
 max(1,
n
).
If
range
 = 'V', then
nzc
≥
 the number of eigenvalues in (
vl
,
vu
].
If
range
 = 'I', then
nzc
≥
iu
-
il
+1.
If
nzc
 = -1, then a workspace query is assumed; the
function
calculates the number of columns of the matrix
Z
 that are needed to hold the eigenvectors. This value is returned as the first entry of the
z
 array, and no error message related to
nzc
 is issued.
lwork
The size of the array
work
.
lwork
≥
 max(1,18*
n
)
if
jobz
 = 'V', and
lwork
≥
 max(1,12*
n
) if
jobz
 = 'N'. If
lwork
 = -1, then a workspace query is assumed; the
function
only calculates the optimal size of the
work
 array, returns this value as the first entry of the
work
 array, and no error message related to
lwork
 is issued.
liwork
The size of the array
iwork
.
liwork
≥
 max(1,10*
n
) if the eigenvectors are desired, and
liwork
≥
 max(1,8*
n
) if only the eigenvalues are to be computed.
If
liwork
 = -1, then a workspace query is assumed; the
function
only calculates the optimal size of the
iwork
 array, returns this value as the first entry of the
iwork
 array, and no error message related to
liwork
 is issued.
dol
,
dou
From the eigenvalues
w
[0] through
w
[
m
-1]
, only eigenvectors
Z
(:,
dol
) to
Z
(:,
dou
) are computed.
If
dol
 > 1, then
Z
(:,
dol
-1-
zoffset
) is used and overwritten.
If
dou
 <
m
, then
Z
(:,
dou
+1-
zoffset
) is used and overwritten.
zoffset
Offset for storing the eigenpairs when
z
 is distributed in 1D-cyclic fashion
OUTPUT Parameters
m
Globally summed over all processors,
m
 equals the total number of eigenvalues found. 0
≤
m
≤
n
. If
range
 = 'A',
m
 =
n
, and if
range
 = 'I',
m
 =
iu
-
il
+1. The local output equals
m
 =
dou
 -
dol
 + 1.
w
Array of size
n
The first
m
 elements contain the selected eigenvalues in ascending order. Note that immediately after exiting this
function
, only the eigenvalues
indexed
dol
-1 through
dou
-1
 are reliable on this processor because the eigenvalue computation is done in parallel. Other processors will hold reliable information on other parts of the
w
 array. This information is communicated in the ScaLAPACK driver.
z
Array of size
ldz
 * max(1,
m
)
.
If
jobz
 = 'V', and if
info
 = 0, then the first
m
 columns of the matrix
Z
 stored in
z
 contain some of 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: the user must ensure that at least max(1,
m
) columns
of the matrix
 are supplied in the array
z
; if
range
 = 'V', the exact value of
m
 is not known in advance and can be computed with a workspace query by setting
nzc
 = -1, see below.
isuppz
array of size 2*max(1,
m
)
The support of the eigenvectors in
z
, i.e., 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 set if
n
>2.
work
On exit, if
info
 = 0,
work
[0]
 returns the optimal (and minimal)
lwork
.
iwork
On exit, if
info
 = 0,
iwork
[0]
 returns the optimal
liwork
.
info
On exit,
info
= 0: successful exit
other:if
info
 = -
i
, the
i
-th argument had an illegal value
if
info
 = 10X, internal error in
?larre2
,
if
info
 = 20X, internal error in
?larrv
.
Here, the digit X = ABS(
iinfo
 ) < 10, where
iinfo
 is the nonzero error code returned by
?larre2
 or
?larrv
, respectively.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.