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.