Developer Reference for Intel® oneAPI Math Kernel Library for Fortran
p?hseqr
Computes eigenvalues and (optionally) the Schur factorization of a matrix reduced to Hessenberg form.
Syntax
call pshseqr(job, compz, n, ilo, ihi, h, desch, wr, wi, z, descz, work, lwork, iwork,
liwork, info)
call pdhseqr(job, compz, n, ilo, ihi, h, desch, wr, wi, z, descz, work, lwork, iwork,
liwork, info)Include Files
mkl_scalapack.h
Description
p?hseqr computes the eigenvalues of an upper Hessenberg matrix H and, optionally, the matrices T and Z from the Schur decomposition H = Z * T * ZT , where T is an upper quasi-triangular matrix (the Schur form), and Z is the orthogonal matrix of Schur vectors.
Optionally Z may be postmultiplied into an input orthogonal matrix Q so that this routine function can give the Schur factorization of a matrix A which has been reduced to the Hessenberg form H by the orthogonal matrix Q : A = Q * H * QT = ( QZ )* T *( QZ ) T .
The code requires the distributed block size to be square and at least 6.
The code requires A and Z to be distributed identically and have identical contexts.
The matrix A must be in upper Hessenberg form. If elements below the subdiagonal are non-zero, the resulting transformations can be nonsimilar.
All eigenvalues are distributed to all the nodes.
Input Parameters
job
(global) CHARACTER *1
= ‘E’: compute eigenvalues only; = ‘S’: compute eigenvalues and the Schur form T.
compz
(global) CHARACTER *1
= ‘N’: no Schur vectors are computed; = ‘I’: z is initialized to the unit matrix and the matrix Z of Schur vectors of H is returned; = ‘V’: z must contain an orthogonal matrix Q on entry, and the product Q * Z is returned.
- n
-
(global ) INTEGER The order of the Hessenberg matrix H . n ≥ 0.
- ilo , ihi
-
(global ) INTEGER It is assumed that H is already upper triangular in rows and columns 1: ilo -1 and ihi +1: n . ilo and ihi are normally set by a previous call to p gebal , and then passed to p?gehrd (Reduces a general matrix to upper Hessenberg form.) when the matrix output by p?gebal is reduced to Hessenberg form. Otherwise ilo and ihi should be set to 1 and n respectively. If n >0, then 1 ≤ ilo ≤ ihi ≤ n . If n = 0, then ilo = 1 and ihi = 0.
- h
-
REAL for pshseqr DOUBLE PRECISION for pdhseqr
(global ) array of size ( desch ( lld_ ), LOCc ( n ))
The upper Hessenberg matrix H .
desch
(global and local) INTEGER array of size dlen_
The array descriptor for the distributed matrix H .
- z
-
REAL for pshseqr DOUBLE PRECISION for pdhseqr (global ) array If compz = ‘V’, on entry z must contain the current matrix Z of accumulated transformations from, for example, p?gehrd . If compz = ‘I’, on entry z need not be set.
descz
(global and local) INTEGER array of size dlen_
The array descriptor for the distributed matrix z .
- work
-
REAL for pshseqr DOUBLE PRECISION for pdhseqr (local workspace) array of size lwork .
- lwork
-
(local ) INTEGER The length of the workspace array work .
If lwork = -1 , then work(1)[0] gets set to the above number and the code returns immediately.
- iwork
-
(local workspace) INTEGER array of size liwork
- liwork
-
(local ) INTEGER The length of the workspace array iwork .
OUTPUT Parameters
h
If job = ‘S’, H is upper quasi-triangular in rows and columns ilo : ihi , with 1-by-1 and 2-by-2 blocks on the main diagonal. The 2-by-2 diagonal blocks (corresponding to complex conjugate pairs of eigenvalues) are returned in standard form, with h ( i , i ) = h ( i +1, i +1) and h ( i +1, i )* h ( i , i +1)<0 . If info = 0 and job = ‘E’, the contents of h are unspecified on exit.
- wr , wi
-
REAL for pshseqr DOUBLE PRECISION for pdhseqr (global ) array of size n
The real and imaginary parts, respectively, of the computed eigenvalues ilo to ihi are stored in the corresponding elements of wr and wi . If two eigenvalues are computed as a complex conjugate pair, they are stored in consecutive elements of wr and wi , say the i -th and ( i +1)th, with wi ( i ) > 0 and wi ( i +1) < 0. If job = ‘S’, the eigenvalues are stored in the same order as on the diagonal of the Schur form returned in h .
- z
-
REAL for pshseqr DOUBLE PRECISION for pdhseqr (global ) array z is updated; transformations are applied only to the submatrix Zz ( ilo : ihi , ilo : ihi ). If compz = ‘N’, z is not referenced. If compz = ‘I’ and info = 0, z contains the orthogonal matrix Z of the Schur vectors of H .
- info
-
INTEGER = 0: successful exit < 0: if info = - i , the i -th argument had an illegal value (see also below for -7777 and -8888).
> 0: if info = i , p?hseqr failed to compute all of the eigenvalues. Elements 1: ilo -1 and i +1: n of wr and wi contain those eigenvalues which have been successfully computed. (Failures are rare.)
If info > 0 and job = ‘E’, then on exit, the remaining unconverged eigenvalues are the eigenvalues of the upper Hessenberg matrix rows and columns ilo through info of the final, output value of H . If info > 0 and job = ‘S’, then on exit (*) (initial value of H )* U = U *(final value of H ) where U is an orthogonal matrix. The final value of H is upper Hessenberg and quasi-triangular in rows and columns info +1 through ihi . If info > 0 and compz = ‘V’, then on exit (final value of Z ) = (initial value of Z )* U where U is the orthogonal matrix in (*) (regardless of the value of job .) If info > 0 and compz = ‘I’, then on exit (final value of Z ) = U where U is the orthogonal matrix in (*) (regardless of the value of job .) If info > 0 and compz = ‘N’, then z is not accessed. = -7777: p laqr0 failed to converge and p laqr1 was called instead. = -8888: p?laqr1 failed to converge and p?laqr0 was called instead.