PDLAQR3(3)    ScaLAPACK routine of NEC Numeric Library Collection   PDLAQR3(3)



NAME
       PDLAQR3 - accepts as input an upper Hessenberg matrix H and performs an
       orthogonal similarity transformation designed  to  detect  and  deflate
       fully converged eigenvalues from a trailing principal submatrix

SYNOPSIS
       RECURSIVE SUBROUTINE PDLAQR3(
                           WANTT,  WANTZ,  N,  KTOP, KBOT, NW, H, DESCH, ILOZ,
                           IHIZ, Z, DESCZ, NS, ND, SR, SI, V,  DESCV,  NH,  T,
                           DESCT,  NV,  WV, DESCW, WORK, LWORK, IWORK, LIWORK,
                           RECLEVEL )

           INTEGER         IHIZ, ILOZ, KBOT, KTOP, LWORK, N, ND, NH,  NS,  NV,
                           NW, LIWORK, RECLEVEL

           LOGICAL         WANTT, WANTZ

           NTEGER          DESCH(  *  ),  DESCZ(  * ), DESCT( * ), DESCV( * ),
                           DESCW( * ), IWORK( * )

           DOUBLE          PRECISION H( * ), SI( KBOT ), SR( KBOT ), T(  *  ),
                           V( * ), WORK( * ), WV( * ), Z( * )

PURPOSE
       Aggressive early deflation:

       This  subroutine accepts as input an upper Hessenberg matrix H and per-
       forms an orthogonal similarity transformation designed  to  detect  and
       deflate  fully  converged  eigenvalues from a trailing principal subma-
       trix.  On output H has been overwritten by a new Hessenberg matrix that
       is  a perturbation of an orthogonal similarity transformation of H.  It
       is to be hoped that the final version of H has  many  zero  subdiagonal
       entries.


       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
       WANTT   (global input) LOGICAL
               If  .TRUE.,  then  the  Hessenberg matrix H is fully updated so
               that the quasi-triangular Schur  factor  may  be  computed  (in
               cooperation with the calling subroutine).
               If  .FALSE.,  then  only enough of H is updated to preserve the
               eigenvalues.

       WANTZ   (global input) LOGICAL
               If .TRUE., then the orthogonal matrix Z is updated so  so  that
               the  orthogonal  Schur  factor  may be computed (in cooperation
               with the calling subroutine).
               If .FALSE., then Z is not referenced.

       N       (global input) INTEGER
               The order of the matrix H and (if WANTZ is .TRUE.) the order of
               the orthogonal matrix Z.

       KTOP    (global input) INTEGER
               It is assumed that either KTOP = 1 or H(KTOP,KTOP-1)=0.
               KBOT  and  KTOP  together determine an isolated block along the
               diagonal of the Hessenberg matrix.

       KBOT    (global input) INTEGER
               It is  assumed  without  a  check  that  either  KBOT  =  N  or
               H(KBOT+1,KBOT)=0.  KBOT and KTOP together determine an isolated
               block along the diagonal of the Hessenberg matrix.

       NW      (global input) INTEGER
               Deflation window size.  1 .LE. NW .LE. (KBOT-KTOP+1).

       H        (local  input/output)  DOUBLE   PRECISION   array,   dimension
       (DESCH(LLD_),*)
               On input the initial N-by-N section of H stores the  Hessenberg
               matrix undergoing aggressive early deflation.
               On  output  H  has been transformed by an orthogonal similarity
               transformation, perturbed, and the returned to Hessenberg  form
               that (it is to be hoped) has some zero subdiagonal entries.

       DESCH   (global and local input) INTEGER array of dimension DLEN_.
               The array descriptor for the distributed matrix H.

       ILOZ    (global input) INTEGER

       IHIZ    (global input) INTEGER
               Specify  the rows of Z to which transformations must be applied
               if WANTZ is .TRUE.. 1 .LE. ILOZ .LE. IHIZ .LE. N.

       Z       (input/output) DOUBLE PRECISION array, dimension
                  (DESCH(LLD_),*) IF WANTZ is  .TRUE.,  then  on  output,  the
               orthogonal  similarity  transformation mentioned above has been
               accumulated into Z(ILOZ:IHIZ,ILO:IHI) from the right.
               If WANTZ is .FALSE., then Z is unreferenced.

       DESCZ   (global and local input) INTEGER array of dimension DLEN_.
               The array descriptor for the distributed matrix Z.

       NS      (global output) INTEGER
               The number of unconverged (ie approximate) eigenvalues returned
               in  SR and SI that may be used as shifts by the calling subrou-
               tine.

       ND      (global output) INTEGER
               The number of converged eigenvalues uncovered by  this  subrou-
               tine.

       SR      (global output) DOUBLE PRECISION array, dimension KBOT

       SI      (global output) DOUBLE PRECISION array, dimension KBOT
               On  output,  the real and imaginary parts of approximate eigen-
               values that may be used for shifts are  stored  in  SR(KBOT-ND-
               NS+1) through SR(KBOT-ND) and SI(KBOT-ND-NS+1) through SI(KBOT-
               ND), respectively.
               The real and  imaginary  parts  of  converged  eigenvalues  are
               stored  in  SR(KBOT-ND+1)  through  SR(KBOT)  and SI(KBOT-ND+1)
               through SI(KBOT), respectively.

       V        (global   workspace)   DOUBLE   PRECISION   array,   dimension
       (DESCV(LLD_),*)
               An NW-by-NW distributed work array.

       DESCV   (global and local input) INTEGER array of dimension DLEN_.
               The array descriptor for the distributed matrix V.

       NH      (input) INTEGER scalar
               The number of columns of T.  NH.GE.NW.

       T       (global workspace) DOUBLE PRECISION array, dimension
                  (DESCV(LLD_),*)

       DESCT   (global and local input) INTEGER array of dimension DLEN_.
               The array descriptor for the distributed matrix T.

       NV      (global input) INTEGER
               The number of rows of work array WV  available  for  workspace.
               NV.GE.NW.

       WV        (global   workspace)   DOUBLE   PRECISION   array,  dimension
       (DESCW(LLD_),*)

       DESCW   (global and local input) INTEGER array of dimension DLEN_.
               The array descriptor for the distributed matrix WV.

       WORK    (local workspace) DOUBLE PRECISION array, dimension LWORK.
               On  exit, WORK(1) is set to an estimate of the optimal value of
               LWORK for the given values of N, NW, KTOP and KBOT.

       LWORK   (local input) INTEGER
               The dimension of the work array WORK.  LWORK =  2*NW  suffices,
               but  greater efficiency may result from larger values of LWORK.

               If LWORK = -1, then a workspace query is assumed; PDLAQR3  only
               estimates the optimal workspace size for the given values of N,
               NW, KTOP and KBOT.  The estimate is returned  in  WORK(1).   No
               error  message related to LWORK is issued by XERBLA.  Neither H
               nor Z are accessed.

       IWORK   (local workspace) INTEGER array, dimension (LIWORK)

       LIWORK  (local input) INTEGER
               The length of the workspace array IWORK



ScaLAPACK routine               31 October 2017                     PDLAQR3(3)