Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

?stebz

Computes selected eigenvalues of a real symmetric tridiagonal matrix by bisection.

Syntax

lapack_int
LAPACKE_sstebz
(
char
range
,
char
order
,
lapack_int
n
,
float
vl
,
float
vu
,
lapack_int
il
,
lapack_int
iu
,
float
abstol
,
const
float
*
d
,
const
float
*
e
,
lapack_int
*
m
,
lapack_int
*
nsplit
,
float
*
w
,
lapack_int
*
iblock
,
lapack_int
*
isplit
);
lapack_int
LAPACKE_dstebz
(
char
range
,
char
order
,
lapack_int
n
,
double
vl
,
double
vu
,
lapack_int
il
,
lapack_int
iu
,
double
abstol
,
const
double
*
d
,
const
double
*
e
,
lapack_int
*
m
,
lapack_int
*
nsplit
,
double
*
w
,
lapack_int
*
iblock
,
lapack_int
*
isplit
);
Include Files
  • mkl.h
Description
The routine computes some (or all) of the eigenvalues of a real symmetric tridiagonal matrix
T
 by bisection. The routine searches for zero or negligible off-diagonal elements to see if
T
 splits into block-diagonal form
T
 = diag(
T
1
,
T
2
, ...)
. Then it performs bisection on each of the blocks
T
i
 and returns the block index of each computed eigenvalue, so that a subsequent call to stein can also take advantage of the block structure.
Input Parameters
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
.
order
Must be
'B'
 or
'E'
.
If
order
 =
'B'
, the eigenvalues are to be ordered from smallest to largest within each split-off block.
If
order
 =
'E'
, the eigenvalues for the entire matrix are to be ordered from smallest to largest.
n
The order of the matrix
T
 (
n
≥
 0
).
vl
,
vu
If
range
 =
'V'
, the routine computes eigenvalues
w
[
i
]
 in the half-open interval:
vl
 <
w
[
i
]
)
≤
vu
.
If
range
 =
'A'
 or
'I'
,
vl
 and
vu
 are not referenced.
il
,
iu
Constraint:
1
≤
il
≤
iu
≤
n
.
If
range
 =
'I'
, the routine computes eigenvalues
w
[
i
]
 such that
il
≤
i
≤
iu
 (assuming that the eigenvalues
w
[
i
]
 are in ascending order).
If
range
 =
'A'
 or
'V'
,
il
 and
iu
 are not referenced.
abstol
The absolute tolerance to which each eigenvalue is required. An eigenvalue (or cluster) is considered to have converged if it lies in an interval of width
abstol
.
If
abstol
≤
 0.0
, then the tolerance is taken as
eps*|
T
|
, where
eps
 is the machine precision, and
|
T
|
 is the 1-norm of the matrix
T
.
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).
Output Parameters
m
The actual number of eigenvalues found.
nsplit
The number of diagonal blocks detected in
T
.
w
Array, size at least max(1,
n
). The computed eigenvalues, stored in
w
[0]
 to
w
[
m
 - 1]
.
iblock
,
isplit
Arrays, size at least max(1,
n
).
A positive value
iblock
[i]
 is the block number of the eigenvalue stored in
w
[i]
 (see also
info
).
The leading
nsplit
 elements of
isplit
 contain points at which
T
 splits into blocks
T
i
 as follows: the block
T
1
 contains rows/columns 1 to
isplit
[0]
; the block
T
2
 contains rows/columns
isplit
[0]
+1
 to
isplit
[1]
, and so on.
Return Values
This function returns a value
info
.
If
info
=0
, the execution is successful.
If
info
 = 1
, for
range
 =
'A'
 or
'V'
, the algorithm failed to compute some of the required eigenvalues to the desired accuracy;
iblock
[
i
] < 0 indicates that the eigenvalue stored in
w
[
i
] failed to converge.
If
info
 = 2
, for
range
 =
'I'
, the algorithm failed to compute some of the required eigenvalues. Try calling the routine again with
range
 =
'A'
.
If
info
 = 3
:
for
range
 =
'A'
 or
'V'
, same as
info
 = 1
;
for
range
 =
'I'
, same as
info
 = 2
.
If
info
 = 4
, no eigenvalues have been computed. The floating-point arithmetic on the computer is not behaving as expected.
If
info
 =
-i
, the
i
-th parameter had an illegal value.
Application Notes
The eigenvalues of
T
 are computed to high relative accuracy which means that if they vary widely in magnitude, then any small eigenvalues will be computed more accurately than, for example, with the standard
QR
 method. However, the reduction to tridiagonal form (prior to calling the routine) may exclude the possibility of obtaining high relative accuracy in the small eigenvalues of the original matrix if its eigenvalues vary widely in magnitude.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804