Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 11/07/2023
Public

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

Document Table of Contents

?stegr2b

From eigenvalues and initial representations computes the selected eigenvalues and eigenvectors of the real symmetric tridiagonal matrix in parallel on multiple processors.

Syntax

call sstegr2b( jobz, n, d, e, m, w, z, ldz, nzc, isuppz, work, lwork, iwork, liwork, dol, dou, needil, neediu, indwlc, pivmin, scale, wl, wu, vstart, finish, maxcls, ndepth, parity, zoffset, info )

call dstegr2b( jobz, n, d, e, m, w, z, ldz, nzc, isuppz, work, lwork, iwork, liwork, dol, dou, needil, neediu, indwlc, pivmin, scale, wl, wu, vstart, finish, maxcls, ndepth, parity, zoffset, info )

Description

?stegr2b should only be called after a call to ?stegr2a. From eigenvalues and initial representations computed by ?stegr2a, ?stegr2b computes the selected eigenvalues and eigenvectors of the real symmetric tridiagonal matrix in parallel on multiple processors. It is potentially invoked multiple times on a given processor because the locally relevant representation tree might depend on spectral information that is "owned" by other processors and might need to be communicated.

Please note:

  • The calling sequence has two additional integer parameters, dol and dou, that should satisfy mdoudol1. These parameters are only relevant for the case jobz = 'V'. ?stegr2b only computes the eigenvectors corresponding to eigenvalues dol through dou in w. (That is, instead of computing the eigenvectors belonging to w(1) through w(m), only the eigenvectors belonging to eigenvalues w(dol) through w(dou) are computed. In this case, only the eigenvalues dol:dou are guaranteed to be accurately refined to all figures by Rayleigh-Quotient iteration.

  • The additional arguments vstart, finish, ndepth, parity, zoffset are included as a thread-safe implementation equivalent to save variables. These variables store details about the local representation tree which is computed layerwise. For scalability reasons, eigenvalues belonging to the locally relevant representation tree might be computed on other processors. These need to be communicated before the inspection of the RRRs can proceed on any given layer. Note that only when the variable finishequals .TRUE., the computation has ended. All eigenpairs between dol and dou have been computed. m is set to dou - dol + 1.

  • ?stegr2b needs more workspace in z than the sequential ?stegr. It is used to store the conformal embedding of the local representation tree.

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

CHARACTER*1

= 'N': Compute eigenvalues only;

= 'V': Compute eigenvalues and eigenvectors.

n

INTEGER

The order of the matrix. n 0.

d

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

Array of size n

The n diagonal elements of the tridiagonal matrix T. Overwritten on exit.

e

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

Array of size n

The (n-1) subdiagonal elements of the tridiagonal matrix T in elements 1 to n-1 of e. e(n) need not be set on input, but is used internally as workspace. Overwritten on exit.

m

INTEGER

The total number of eigenvalues found in ?stegr2a. 0 mn.

w

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

Array of size n

The first m elements contain approximations to the selected eigenvalues in ascending order. Note that only the eigenvalues from the locally relevant part of the representation tree, that is all the clusters that include eigenvalues from dol:dou, are reliable on this processor. (It does not need to know about any others anyway.)

ldz

INTEGER

The leading dimension of the array z. ldz 1, and if jobz = 'V', then ldz max(1,n).

nzc

INTEGER

The number of eigenvectors to be held in the array z, storing the matrix Z.

lwork

INTEGER

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 routine 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

INTEGER

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 routine 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

INTEGER

From the eigenvalues w(1:m), 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.

needil, neediu

INTEGER

Describes which are the left and right outermost eigenvalues still to be computed. Initially computed by ?larre2a, modified in the course of the algorithm.

pivmin

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

The minimum pivot in the sturm sequence for T.

scale

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

The scaling factor for T. Used for unscaling the eigenvalues at the very end of the algorithm.

wl, wu

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

The interval (wl, wu] contains all the wanted eigenvalues.

vstart

LOGICAL

.TRUE. on initialization, set to .FALSE. afterwards.

finish

LOGICAL

Indicates whether all eigenpairs have been computed.

maxcls

INTEGER

The largest cluster worked on by this processor in the representation tree.

ndepth

INTEGER

The current depth of the representation tree. Set to zero on initial pass, changed when the deeper levels of the representation tree are generated.

parity

INTEGER

An internal parameter needed for the storage of the clusters on the current level of the representation tree.

zoffset

INTEGER

Offset for storing the eigenpairs when z is distributed in 1D-cyclic fashion.

OUTPUT Parameters

z

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

Array of size (ldz, max(1,m) )

If jobz = 'V', and if info = 0, then a subset of the first m columns of the matrix Z, stored in 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).

See dol, dou for more information.

isuppz

INTEGER 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-1 ) through isuppz( 2*i ). 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(1) returns the optimal (and minimal) lwork.

iwork

On exit, if info = 0, iwork(1) returns the optimal liwork.

needil, neediu

Modified in the course of the algorithm.

indwlc

REAL for sstegr2b

DOUBLE PRECISION for dstegr2b

Pointer into the workspace location where the local eigenvalue representations are stored. ("Local eigenvalues" are those relative to the individual shifts of the RRRs.)

vstart

.TRUE. on initialization, set to .FALSE. afterwards.

finish

Indicates whether all eigenpairs have been computed

maxcls

The largest cluster worked on by this processor in the representation tree.

ndepth

The current depth of the representation tree. Set to zero on initial pass, changed when the deeper levels of the representation tree are generated.

parity

An internal parameter needed for the storage of the clusters on the current level of the representation tree.

info

INTEGER

On exit, info

= 0: successful exit

other:if info = -i, the i-th argument had an illegal value

if info = 20x, internal error in ?larrv2.

Here, the digit x = abs( iinfo ) < 10, where iinfo is the nonzero error code returned by ?larrv2

See Also