Developer Reference for Intel® oneAPI Math Kernel Library for Fortran
?laebz
Computes the number of eigenvalues of a real symmetric tridiagonal matrix which are less than or equal to a given value, and performs other tasks required by the routine ?stebz .
Syntax
call slaebz ( ijob , nitmax , n , mmax , minp , nbmin , abstol , reltol , pivmin , d , e , e2 , nval , ab , c , mout , nab , work , iwork , info )
call dlaebz ( ijob , nitmax , n , mmax , minp , nbmin , abstol , reltol , pivmin , d , e , e2 , nval , ab , c , mout , nab , work , iwork , info )
Include Files
mkl.fi
Description
slaebz dlaebz
The routine ?laebz contains the iteration loops which compute and use the function n(w), which is the count of eigenvalues of a symmetric tridiagonal matrix T less than or equal to its argument w . It performs a choice of two types of loops:
ijob
=1, followed by
ijob
=2: It takes as input a list of intervals and returns a list of sufficiently small intervals whose union contains the same eigenvalues as the union of the original intervals. The input intervals are (ab(j,1),ab(j,2)], j=1,...,minp . The output interval (ab(j,1),ab(j,2)] will contain eigenvalues nab(j,1)+1,...,nab(j,2) , where 1 ≤ j ≤ mout .
ijob
=3: It performs a binary search in each input interval (ab(j,1),ab(j,2)] for a point w(j) such that n(w(j))=nval(j) , and uses c(j) as the starting point of the search. If such a w(j) is found, then on output ab(j,1)=ab(j,2)=w . If no such w(j) is found, then on output (ab(j,1),ab(j,2)] will be a small interval containing the point where n(w) jumps through nval(j), unless that point lies outside the initial interval.
Note that the intervals are in all cases half-open intervals, that is, of the form (a,b] , which includes b but not a .
To avoid underflow, the matrix should be scaled so that its largest element is no greater than overflow^{1/2} * overflow^{1/4} in absolute value. To assure the most accurate computation of small eigenvalues, the matrix should be scaled to be not much smaller than that, either.
Input Parameters
- ijob
-
INTEGER . Specifies what is to be done: = 1: Compute nab for the initial intervals. = 2: Perform bisection iteration to find eigenvalues of T . = 3: Perform bisection iteration to invert n(w), i.e., to find a point which has a specified number of eigenvalues of T to its left. Other values will cause ?laebz to return with info=-1 .
- nitmax
-
INTEGER . The maximum number of “levels” of bisection to be performed, i.e., an interval of width W will not be made smaller than 2^{-nitmax}*W . If not all intervals have converged after nitmax iterations, then info is set to the number of non-converged intervals.
- n
-
INTEGER . The dimension n of the tridiagonal matrix T . It must be at least 1.
- mmax
-
INTEGER . The maximum number of intervals. If more than mmax intervals are generated, then ?laebz will quit with info=mmax+1 .
- minp
-
INTEGER . The initial number of intervals. It may not be greater than mmax .
- nbmin
-
INTEGER . The smallest number of intervals that should be processed using a vector loop. If zero, then only the scalar loop will be used.
- abstol
-
REAL for slaebz DOUBLE PRECISION for dlaebz . The minimum (absolute) width of an interval. When an interval is narrower than abstol , or than reltol times the larger (in magnitude) endpoint, then it is considered to be sufficiently small, i.e., converged. This must be at least zero.
- reltol
-
REAL for slaebz DOUBLE PRECISION for dlaebz . The minimum relative width of an interval. When an interval is narrower than abstol , or than reltol times the larger (in magnitude) endpoint, then it is considered to be sufficiently small, i.e., converged. Note: this should always be at least radix*machineepsilon .
- pivmin
-
REAL for slaebz DOUBLE PRECISION for dlaebz . The minimum absolute value of a “pivot” in the Sturm sequence loop. This value must be at least ( max |e(j)**2|*safe_min ) and at least safe_min , where safe_min is at least the smallest number that can divide one without overflow.
- d , e , e2
-
REAL for slaebz DOUBLE PRECISION for dlaebz . Arrays, dimension ( n ) each. The array d contains the diagonal elements of the tridiagonal matrix T .
The array e contains the off-diagonal elements of the tridiagonal matrix T in positions 1 through n -1. e(n) is arbitrary.
The array e2 contains the squares of the off-diagonal elements of the tridiagonal matrix T . e2(n) is ignored.
- nval
-
INTEGER . Array, dimension ( minp ). If ijob =1 or 2, not referenced. If ijob =3, the desired values of n(w).
- ab
-
REAL for slaebz DOUBLE PRECISION for dlaebz . Array, dimension ( mmax ,2) The endpoints of the intervals. ab (j,1) is a(j), the left endpoint of the j -th interval, and ab (j,2) is b(j), the right endpoint of the j -th interval.
- c
-
REAL for slaebz DOUBLE PRECISION for dlaebz . Array, dimension ( mmax ) If ijob =1, ignored. If ijob =2, workspace. If ijob =3, then on input c(j) should be initialized to the first search point in the binary search.
- nab
-
INTEGER . Array, dimension ( mmax ,2) If ijob =2, then on input, nab (i,j) should be set. It must satisfy the condition: n(ab(i,1)) ≤ nab(i,1) ≤ nab(i,2) ≤ n(ab(i,2)) , which means that in interval i only eigenvalues nab(i,1)+1,...,nab(i,2) are considered. Usually, nab(i,j)=n(ab(i,j)) , from a previous call to ?laebz with ijob =1. If ijob =3, normally, nab should be set to some distinctive value(s) before ?laebz is called.
- work
-
REAL for slaebz DOUBLE PRECISION for dlaebz . Workspace array, dimension ( mmax ).
- iwork
-
INTEGER . Workspace array, dimension ( mmax ).
Output Parameters
- nval
-
The elements of nval will be reordered to correspond with the intervals in ab . Thus, nval(j) on output will not, in general be the same as nval(j) on input, but it will correspond with the interval ( ab(j,1),ab(j,2)] on output.
- ab
-
The input intervals will, in general, be modified, split, and reordered by the calculation.
- mout
-
INTEGER . If ijob =1, the number of eigenvalues in the intervals. If ijob =2 or 3, the number of intervals output. If ijob =3, mout will equal minp .
- nab
-
If ijob =1, then on output nab (i,j) will be set to N ( ab (i,j)). If ijob =2, then on output, nab (i,j) will contain max( na ( k , min( nb(k), N ( ab (i,j)))), where k is the index of the input interval that the output interval ( ab (j,1), ab (j,2)] came from, and na(k) and nb(k) are the input values of nab ( k ,1) and nab ( k ,2). If ijob =3, then on output, nab (i,j) contains N ( ab (i,j)), unless N ( w ) > nval (i) for all search points w , in which case nab (i,1) will not be modified, i.e., the output value will be the same as the input value (modulo reorderings, see nval and ab ), or unless N ( w ) < nval (i) for all search points w , in which case nab (i,2) will not be modified.
info
INTEGER .
If info = 0 - all intervals converged
If info = 1--mmax - the last info interval did not converge.
If info = mmax+1 - more than mmax intervals were generated
Application Notes
This routine is intended to be called only by other LAPACK routines, thus the interface is less user-friendly. It is intended for two purposes:
finding eigenvalues. In this case, ?laebz should have one or more initial intervals set up in ab , and ?laebz should be called with ijob =1. This sets up nab , and also counts the eigenvalues. Intervals with no eigenvalues would usually be thrown out at this point. Also, if not all the eigenvalues in an interval i are desired, nab (i,1) can be increased or nab (i,2) decreased. For example, set nab (i,1)= nab (i,2)-1 to get the largest eigenvalue. ?laebz is then called with ijob =2 and mmax no smaller than the value of mout returned by the call with ijob =1. After this ( ijob =2) call, eigenvalues nab (i,1)+1 through nab (i,2) are approximately ab (i,1) (or ab (i,2)) to the tolerance specified by abstol and reltol .
finding an interval ( a ‘, b ‘] containing eigenvalues w (f),…, w (l). In this case, start with a Gershgorin interval ( a , b ). Set up ab to contain 2 search intervals, both initially ( a , b ). One nval element should contain f-1 and the other should contain l, while c should contain a and b , respectively. nab (i,1) should be -1 and nab (i,2) should be n +1, to flag an error if the desired interval does not lie in ( a , b ). ?laebz is then called with ijob =3. On exit, if w(f-1) < w(f) , then one of the intervals – j – will have ab(j,1)=ab(j,2) and nab(j,1)=nab(j,2)=f-1 , while if, to the specified tolerance, w(f-k)=...=w(f+r) , k > 0 and r ≥ 0 , then the interval will have n(ab(j,1))=nab(j,1)=f-k and n(ab(j,2))=nab(j,2)=f+r . The cases w(l) < w(l+1) and w (l-r)=…= w (l+k) are handled similarly.