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



NAME
       PZHEEV  - compute selected eigenvalues and, optionally, eigenvectors of
       a real symmetric matrix A by calling the recommended sequence of ScaLA-
       PACK routines

SYNOPSIS
       SUBROUTINE PZHEEV( JOBZ,  UPLO,  N,  A,  IA,  JA,  DESCA, W, Z, IZ, JZ,
                          DESCZ, WORK, LWORK, RWORK, LRWORK, INFO )

           CHARACTER      JOBZ, UPLO

           INTEGER        IA, INFO, IZ, JA, JZ, LRWORK, LWORK, N

           INTEGER        DESCA( * ), DESCZ( * )

           DOUBLE         PRECISION RWORK( * ), W( * )

           COMPLEX*16     A( * ), WORK( * ), Z( * )

PURPOSE
       PZHEEV computes selected eigenvalues and, optionally, eigenvectors of a
       real  symmetric  matrix A by calling the recommended sequence of ScaLA-
       PACK routines.  In its present form, PZHEEV assumes a homogeneous  sys-
       tem  and  makes  only spot checks of the consistency of the eigenvalues
       across the different processes.  Because of this, it is possible that a
       heterogeneous  system  may  return  incorrect results without any error
       messages.


       Notes
       =====
       A description vector is associated with  each  2D  block-cyclicly  dis-
       tributed matrix.  This vector stores the information required to estab-
       lish the mapping between a matrix entry and its  corresponding  process
       and memory location.

       In  the  following  comments, the character _ should be read as "of the
       distributed matrix".  Let A be a generic term for any 2D block cyclicly
       distributed matrix.  Its description vector is DESCA:

       NOTATION        STORED IN      EXPLANATION
       --------------- -------------- --------------------------------------
       DTYPE_A(global) DESCA( DTYPE_) The descriptor type.
       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 distributed
                                      matrix A.
       N_A    (global) DESCA( N_ )    The number of columns in the distri-
                                      buted matrix A.
       MB_A   (global) DESCA( MB_ )   The blocking factor used to distribute
                                      the rows of A.
       NB_A   (global) DESCA( NB_ )   The blocking factor used to distribute
                                      the columns of A.
       RSRC_A (global) DESCA( RSRC_ ) The process row over which the first
                                      row  of  the  matrix  A  is distributed.
       CSRC_A (global) DESCA( CSRC_ ) The process column over which the
                                      first column of A is distributed.  LLD_A
       (local)  DESCA( LLD_ )  The leading dimension of the local
                                      array storing the local blocks of the
                                      distributed matrix A.
                                      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 ).


ARGUMENTS
       NP  =  the number of rows local to a given process.  NQ = the number of
       columns local to a given process.

       JOBZ    (global input) CHARACTER*1
               Specifies whether or not to compute the eigenvectors:
               = 'N':  Compute eigenvalues only.
               = 'V':  Compute eigenvalues and eigenvectors.

       UPLO    (global input) CHARACTER*1
               Specifies whether the upper or lower  triangular  part  of  the
               symmetric matrix A is stored:
               = 'U':  Upper triangular
               = 'L':  Lower triangular

       N       (global input) INTEGER
               The number of rows and columns of the matrix A.  N >= 0.

       A       (local input/workspace) block cyclic COMPLEX*16 array,
               global  dimension (N, N), local dimension ( LLD_A, LOCc(JA+N-1)
               )

               On entry, the symmetric matrix A.  If  UPLO  =  'U',  only  the
               upper  triangular  part  of A is used to define the elements of
               the symmetric matrix.  If UPLO = 'L', only the lower triangular
               part  of  A  is  used  to  define the elements of the symmetric
               matrix.

               On exit, the lower triangle (if UPLO='L') or the upper triangle
               (if UPLO='U') of A, including the diagonal, is destroyed.

       IA      (global input) INTEGER
               A's global row index, which points to the beginning of the sub-
               matrix which is to be operated on.

       JA      (global input) INTEGER
               A's global column index, which points to the beginning  of  the
               submatrix which is to be operated on.

       DESCA   (global and local input) INTEGER array of dimension DLEN_.
               The  array  descriptor for the distributed matrix A.  If DESCA(
               CTXT_ ) is incorrect, PZHEEV  cannot  guarantee  correct  error
               reporting.

       W       (global output) DOUBLE PRECISION array, dimension (N)
               On normal exit, the first M entries contain the selected eigen-
               values in ascending order.

       Z       (local output) COMPLEX*16 array,
               global dimension (N, N), local dimension (LLD_Z,  LOCc(JZ+N-1))
               If  JOBZ  =  'V',  then on normal exit the first M columns of Z
               contain the orthonormal eigenvectors of the matrix  correspond-
               ing  to the selected eigenvalues.  If JOBZ = 'N', then Z is not
               referenced.

       IZ      (global input) INTEGER
               Z's global row index, which points to the beginning of the sub-
               matrix which is to be operated on.

       JZ      (global input) INTEGER
               Z's  global  column index, which points to the beginning of the
               submatrix which is to be operated on.

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

       WORK    (local workspace/output) COMPLEX*16 array,
               dimension  (LWORK)  On  output,  WORK(1)  returns the workspace
               needed to guarantee completion.  If the  input  parameters  are
               incorrect, WORK(1) may also be incorrect.

               If  JOBZ='N'  WORK(1) = minimal workspace for eigenvalues only.
               If JOBZ='V' WORK(1) = minimal workspace  required  to  generate
               all the eigenvectors.

       LWORK   (local input) INTEGER
               See  below  for  definitions of variables used to define LWORK.
               If no eigenvectors are requested (JOBZ =  'N')  then  LWORK  >=
               MAX( NB*( NP0+1 ), 3 ) +3*N If eigenvectors are requested (JOBZ
               = 'V' ) then the amount of workspace required: LWORK >= (NP0  +
               NQ0 + NB)*NB + 3*N + N^2

               Variable definitions: NB = DESCA( MB_ ) = DESCA( NB_ ) = DESCZ(
               MB_ ) = DESCZ( NB_ ) NP0 = NUMROC( NN, NB, 0, 0, NPROW ) NQ0  =
               NUMROC( MAX( N, NB, 2 ), NB, 0, 0, NPCOL )

               If  LWORK = -1, the LWORK is global input and a workspace query
               is assumed; the routine only calculates the  minimum  size  for
               the  WORK  array.   The  required  workspace is returned as the
               first element of  WORK  and  no  error  message  is  issued  by
               PXERBLA.

       RWORK   (local workspace/output) COMPLEX*16 array,
               dimension (LRWORK) On output RWORK(1) returns the DOUBLE PRECI-
               SION workspace needed to guarantee completion.   If  the  input
               parameters are incorrect, RWORK(1) may also be incorrect.

       LRWORK  (local input) INTEGER
               Size  of RWORK array.  If eigenvectors are desired (JOBZ = 'V')
               then LRWORK >= 2*N + 2*N-2  If  eigenvectors  are  not  desired
               (JOBZ = 'N') then LRWORK >= 2*N

               If  LRWORK  =  -1,  the  LRWORK is global input and a workspace
               query is assumed; the routine only calculates the minimum  size
               for the RWORK array.  The required workspace is returned as the
               first element of RWORK  and  no  error  message  is  issued  by
               PXERBLA.

       INFO    (global output) INTEGER
               = 0:  successful exit
               <  0:   If the i-th argument is an array and the j-entry had an
               illegal value, then INFO = -(i*100+j), if the i-th argument  is
               a  scalar  and  had an illegal value, then INFO = -i.  > 0:  If
               INFO = 1 through N, the i(th) eigenvalue did  not  converge  in
               ZSTEQR2  after a total of 30*N iterations.  If INFO = N+1, then
               PZHEEV has detected heterogeneity by finding  that  eigenvalues
               were  not identical across the process grid.  In this case, the
               accuracy of the results from PZHEEV cannot be guaranteed.


ALIGNMENT REQUIREMENTS
       The distributed submatrices A(IA:*,  JA:*)  and  C(IC:IC+M-1,JC:JC+N-1)
       must verify some alignment properties, namely the following expressions
       should be true:

       ( MB_A.EQ.NB_A.EQ.MB_Z .AND. IROFFA.EQ.IROFFZ .AND.  IROFFA.EQ.0  .AND.
       IAROW.EQ.IZROW  )  where  IROFFA  = MOD( IA-1, MB_A ) and ICOFFA = MOD(
       JA-1, NB_A ).



ScaLAPACK routine               31 October 2017                      PZHEEV(3)