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)