Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of 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(T1, T2, ...). Then it performs bisection on each of the blocks Ti 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 iliun.

If range = 'I', the routine computes eigenvalues w[i] such that iliiu (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 Ti as follows: the block T1 contains rows/columns 1 to isplit[0]; the block T2 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.