Developer Reference for Intel® oneAPI Math Kernel Library for C
?larre2a
Given a tridiagonal matrix, sets small off-diagonal elements to zero and for each unreduced block, finds base representations and eigenvalues.
Syntax
void slarre2a(char *range, MKL_INT *n, float *vl, float *vu, MKL_INT *il, MKL_INT *iu,
float *d, float *e, float *e2, float *rtol1, float *rtol2, float *spltol,
MKL_INT *nsplit, MKL_INT *isplit, MKL_INT *m, MKL_INT *dol, MKL_INT *dou,
MKL_INT *needil, MKL_INT *neediu, float *w, float *werr, float *wgap,
MKL_INT *iblock, MKL_INT *indexw, float *gers, float *sdiam, float *pivmin,
float *work, MKL_INT *iwork, float *minrgp, MKL_INT *info);
void dlarre2a(char *range, MKL_INT *n, double *vl, double *vu, MKL_INT *il, MKL_INT *iu,
double *d, double *e, double *e2, double *rtol1, double *rtol2,
double *spltol, MKL_INT *nsplit, MKL_INT *isplit, MKL_INT *m, MKL_INT *dol,
MKL_INT *dou, MKL_INT *needil, MKL_INT *neediu, double *w, double *werr,
double *wgap, MKL_INT *iblock, MKL_INT *indexw, double *gers, double *sdiam,
double *pivmin, double *work, MKL_INT *iwork, double *minrgp,
MKL_INT *info);Include Files
mkl_scalapack.h
Description
To find the desired eigenvalues of a given real symmetric tridiagonal matrix T , ?larre2a sets any “small” off-diagonal elements to zero, and for each unreduced block Ti , it finds
a suitable shift at one end of the block’s spectrum,
the base representation, Ti - σiI = LiDiLiT , and
eigenvalues of each LiDiLiT .
Product and Performance Information Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex . Notice revision #20201201
Input Parameters
- range
-
CHARACTER = ‘A’: (“All”) all eigenvalues will be found. = ‘V’: (“Value”) all eigenvalues in the half-open interval ( vl , vu ] will be found.
= ‘I’: (“Index”) eigenvalues of the entire matrix with the indices in a given range will be found.
- n
-
INTEGER The order of the matrix. n > 0.
- vl , vu
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a If range =’V’, the lower and upper bounds for the eigenvalues. Eigenvalues less than or equal to vl , or greater than vu , will not be returned. vl < vu . If range =’I’ or =’A’, ?larre2a computes bounds on the desired part of the spectrum.
- il , iu
-
INTEGER
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 .
- d
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size n On entry, the n diagonal elements of the tridiagonal matrix T .
- e
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size n
The first ( n -1) entries contain the subdiagonal elements of the tridiagonal matrix T ; e [ n -1] need not be set.
- e2
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size n
The first ( n -1) entries contain the squares of the subdiagonal elements of the tridiagonal matrix T ; e2 [ n -1] need not be set.
- rtol1 , rtol2
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Parameters for bisection. An interval [ left , right ] has converged if right - left < max( rtol1 * gap , rtol2 *max(| left`|, | :code:`right | ) )
- spltol
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a The threshold for splitting.
- dol , dou
-
INTEGER If the user wants to work on only a selected part of the representation tree, he can specify an index range dol : dou . Otherwise, the setting dol =1, dou = n should be applied. Note that dol and dou refer to the order in which the eigenvalues are stored in w .
- work
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Workspace array of size 6* n
- iwork
-
INTEGER Workspace array of size 5* n
- minrgp
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a The minimum relative gap threshold to decide whether an eigenvalue or a cluster boundary is reached.
OUTPUT Parameters
- vl , vu
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a If range =’V’, the lower and upper bounds for the eigenvalues. Eigenvalues less than or equal to vl , or greater than vu , are not returned. vl < vu . If range =’I’ or range =’A’, ?larre2a computes bounds on the desired part of the spectrum.
- d
-
The n diagonal elements of the diagonal matrices Di .
e
e contains the subdiagonal elements of the unit bidiagonal matrices Li . The entries e [ isplit [ i ]], 0 ≤ i < nsplit , contain the base points σi+1 on output .
e2
The entries e2 [ isplit [ i ]], 0 ≤ i < nsplit have been set to zero.
- nsplit
-
INTEGER The number of blocks T splits into. 1 ≤ nsplit ≤ n .
- isplit
-
INTEGER Array of size n The splitting points, at which T breaks up into blocks. The first block consists of rows/columns 1 to isplit (1), the second of rows/columns isplit (1)+1 through isplit (2), etc., and the nsplit -th block consists of rows/columns isplit ( nsplit -1)+1 through isplit ( nsplit )= n . The first block consists of rows/columns 1 to isplit [0], the second of rows/columns isplit [0]+1 through isplit [1], etc., and the nsplit -th block consists of rows/columns isplit [ nsplit -2]+1 through isplit [ nsplit-1 ]= n .
- m
-
The total number of eigenvalues (of all LiDiLiT ) found.
- needil , neediu
-
The indices of the leftmost and rightmost eigenvalues of the root node RRR which are needed to accurately compute the relevant part of the representation tree.
- w
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size n The first m elements contain the eigenvalues. The eigenvalues of each of the blocks, LiDiLiT , are sorted in ascending order ( ?larre2a may use the remaining n - m elements as workspace).
Note that immediately after exiting this function , only the eigenvalues in w with indices in range dol -1: dou -1 rely on this processor because the eigenvalue computation is done in parallel.
- werr
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size n The error bound on the corresponding eigenvalue in w .
Note that immediately after exiting this function , only the uncertainties in werr with indices in range dol -1: dou -1 are reliable on this processor because the eigenvalue computation is done in parallel.
- wgap
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size n The separation from the right neighbor eigenvalue in w . The gap is only with respect to the eigenvalues of the same block as each block has its own representation tree. Exception: at the right end of a block we store the left gap
Note that immediately after exiting this function , only the gaps in wgap with indices in range dol -1: dou -1 are reliable on this processor because the eigenvalue computation is done in parallel.
iblock
Array of size n
The indices of the blocks (submatrices) associated with the corresponding eigenvalues in w ; iblock [ i ]=1 if eigenvalue w [ i ] belongs to the first block from the top, iblock [ i ]=2 if w [ i ] belongs to the second block, and so on .
indexw
Array of size n
The indices of the eigenvalues within each block (submatrix); for example, indexw [ i ]= 10 and iblock [ i ]=2 imply that the ( i +1)-th eigenvalue w [ i ] is the 10th eigenvalue in block 2 .
- gers
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a Array of size 2* n
The n Gerschgorin intervals (the i -th Gerschgorin interval is ( gers [2* i -2], gers [2* i -1]) ).
- pivmin
-
REAL for slarre2a DOUBLE PRECISION for dlarre2a The minimum pivot in the sturm sequence for T .
- info
-
INTEGER = 0: successful exit > 0: A problem occurred in ?larre2a .
< 0: One of the called function s signaled an internal problem. Needs inspection of the corresponding parameter info for further information.
=-1: Problem in ?larrd2 (Computes the eigenvalues of a symmetric tridiagonal matrix to suitable accuracy.) . =-2: Not enough internal iterations to find base representation. =-3: Problem in ?larrb2 (Provides limited bisection to locate eigenvalues for more accuracy.) when computing the refined root representation. =-4: Problem in ?larrb2 when preforming bisection on the desired part of the spectrum. = -9 Problem: m < dou - dol +1, that is the code found fewer eigenvalues than it was supposed to.