PSHSEQR(3) ScaLAPACK routine of NEC Numeric Library Collection PSHSEQR(3)
NAME
PSHSEQR - computes the eigenvalues of an upper Hessenberg matrix H and,
optionally, the matrices T and Z from the Schur decomposition H =
Z*T*Z**T, where T is an upper quasi-triangular matrix (the Schur form),
and Z is the orthogonal matrix of Schur vectors
SYNOPSIS
SUBROUTINE PSHSEQR( JOB, COMPZ, N, ILO, IHI, H, DESCH, WR, WI, Z,
DESCZ, WORK, LWORK, IWORK, LIWORK, INFO )
INTEGER IHI, ILO, INFO, LWORK, LIWORK, N
CHARACTER COMPZ, JOB
INTEGER DESCH( * ), DESCZ( * ), IWORK( * )
REAL H( * ), WI( N ), WORK( * ), WR( N ), Z( * )
PURPOSE
PSHSEQR computes the eigenvalues of an upper Hessenberg matrix H and,
optionally, the matrices T and Z from the Schur decomposition H =
Z*T*Z**T, 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 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*Q**T = (QZ)*T*(QZ)**T.
Notes
=====
Each global data object is described by an associated description vec-
tor. This vector stores the information required to establish the map-
ping between an object element and its corresponding process and memory
location.
Let A be a generic term for any 2D block cyclicly distributed array.
Such a global array has an associated description vector DESCA. In the
following comments, the character _ should be read as "of the global
array".
NOTATION STORED IN EXPLANATION
--------------- -------------- --------------------------------------
DTYPE_A(global) DESCA( DTYPE_ )The descriptor type. In this case,
DTYPE_A = 1.
CTXT_A (global) DESCA( CTXT_ ) The BLACS context handle, indicating
the BLACS process grid A is distribu-
ted over. The context itself is glo-
bal, but the handle (the integer
value) may vary.
M_A (global) DESCA( M_ ) The number of rows in the global
array A.
N_A (global) DESCA( N_ ) The number of columns in the global
array A.
MB_A (global) DESCA( MB_ ) The blocking factor used to distribute
the rows of the array.
NB_A (global) DESCA( NB_ ) The blocking factor used to distribute
the columns of the array.
RSRC_A (global) DESCA( RSRC_ ) The process row over which the first
row of the array A is distributed.
CSRC_A (global) DESCA( CSRC_ ) The process column over which the
first column of the array A is
distributed.
LLD_A (local) DESCA( LLD_ ) The leading dimension of the local
array. LLD_A >= MAX(1,LOCr(M_A)).
Let K be the number of rows or columns of a distributed matrix, and
assume that its process grid has dimension p x q.
LOCr( K ) denotes the number of elements of K that a process would
receive if K were distributed over the p processes of its process col-
umn.
Similarly, LOCc( K ) denotes the number of elements of K that a process
would receive if K were distributed over the q processes of its process
row.
The values of LOCr() and LOCc() may be determined via a call to the
ScaLAPACK tool function, NUMROC:
LOCr( M ) = NUMROC( M, MB_A, MYROW, RSRC_A, NPROW ),
LOCc( N ) = NUMROC( N, NB_A, MYCOL, CSRC_A, NPCOL ). An upper
bound for these quantities may be computed by:
LOCr( M ) <= ceil( ceil(M/MB_A)/NPROW )*MB_A
LOCc( N ) <= ceil( ceil(N/NB_A)/NPCOL )*NB_A
ARGUMENTS
JOB (global input) CHARACTER*1
= 'E': compute eigenvalues only;
= 'S': compute eigenvalues and the Schur form T.
COMPZ (global input) 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 input) INTEGER
The order of the Hessenberg matrix H (and Z if WANTZ).
N >= 0.
ILO (global input) INTEGER
IHI (global input) 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 PSGEBAL, and then passed to PSGEHRD when the
matrix output by PSGEBAL is reduced to Hessenberg form. Other-
wise ILO and IHI should be set to 1 and N respectively. If
N.GT.0, then 1.LE.ILO.LE.IHI.LE.N.
If N = 0, then ILO = 1 and IHI = 0.
H (global input/output) REAL array, dimension (DESCH(LLD_),*)
On entry, the upper Hessenberg matrix H.
On exit, 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).LT.0. If INFO =
0 and JOB = 'E', the contents of H are unspecified on exit.
DESCH (global and local input) INTEGER array of dimension DLEN_.
The array descriptor for the distributed matrix H.
WR (global output) REAL array, dimension (N)
WI (global output) REAL array, dimension (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 con-
jugate 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 (global input/output) REAL array.
If COMPZ = 'V', on entry Z must contain the current matrix Z of
accumulated transformations from, e.g., PSGEHRD, and on exit Z
has been updated; transformations are applied only to the sub-
matrix Z(ILO:IHI,ILO:IHI).
If COMPZ = 'N', Z is not referenced.
If COMPZ = 'I', on entry Z need not be set and on exit,
if INFO = 0, Z contains the orthogonal matrix Z of the Schur
vectors of H.
DESCZ (global and local input) INTEGER array of dimension DLEN_.
The array descriptor for the distributed matrix Z.
WORK (local workspace) REAL array, dimension(LWORK)
LWORK (local input) INTEGER
The length of the workspace array WORK.
IWORK (local workspace) INTEGER array, dimension (LIWORK)
LIWORK (local input) INTEGER
The length of the workspace array IWORK.
INFO (output) INTEGER
= 0: successful exit
.LT. 0: if INFO = -i, the i-th argument had an illegal
value (see also below for -7777 and -8888).
.GT. 0: if INFO = i, PSHSEQR 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 .GT. 0 and JOB = 'E', then on exit, the
remaining unconverged eigenvalues are the eigen-
values of the upper Hessenberg matrix rows and
columns ILO through INFO of the final, output
value of H.
If INFO .GT. 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 .GT. 0 and COMPZ = 'V', then on exit
(final value of Z) = (initial value of Z)*U
where U is the orthogonal matrix in (*) (regard-
less of the value of JOB.)
If INFO .GT. 0 and COMPZ = 'I', then on exit
(final value of Z) = U
where U is the orthogonal matrix in (*) (regard-
less of the value of JOB.)
If INFO .GT. 0 and COMPZ = 'N', then Z is not
accessed.
= -7777: PSLAQR0 failed to converge and PSLAQR1 was called
instead. This could happen. Mostly due to a bug.
= -8888: PSLAQR1 failed to converge and PSLAQR0 was called
instead. This should not happen.
Restrictions: The block size in H and Z must be square and
larger than or equal to six (6) due to restrictions in PSLAQR1,
PSLAQR5 and SLAQR6. Moreover, H and Z need to be distributed
identically with the same context.
ScaLAPACK routine 31 October 2017 PSHSEQR(3)