Provided by: scalapack-doc_1.5-10_all bug

NAME

       PDSYEV  - compute all eigenvalues and, optionally, eigenvectors of a real symmetric matrix
       A by calling the recommended sequence of ScaLAPACK routines.

SYNOPSIS

       SUBROUTINE PDSYEV( JOBZ, UPLO, N, A, IA, JA, DESCA, W, Z, IZ, JZ, DESCZ, WORK, LWORK, INFO
                          )

           CHARACTER      JOBZ, UPLO

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

           INTEGER        DESCA( * ), DESCZ( * )

           DOUBLE         PRECISION A( * ), W( * ), WORK( * ), Z( * )

           INTEGER        BLOCK_CYCLIC_2D,  DLEN_, DTYPE_, CTXT_, M_, N_, MB_, NB_, RSRC_, CSRC_,
                          LLD_

           PARAMETER      ( BLOCK_CYCLIC_2D = 1, DLEN_ = 9, DTYPE_ = 1, CTXT_ = 2, M_ = 3,  N_  =
                          4, MB_ = 5, NB_ = 6, RSRC_ = 7, CSRC_ = 8, LLD_ = 9 )

           DOUBLE         PRECISION ZERO, ONE

           PARAMETER      ( ZERO = 0.0D+0, ONE = 1.0D+0 )

           INTEGER        ITHVAL

           PARAMETER      ( ITHVAL = 10 )

           LOGICAL        LOWER, WANTZ

           INTEGER        CONTEXTC,  CSRC_A,  I,  IACOL, IAROW, ICOFFA, IINFO, INDD, INDD2, INDE,
                          INDE2, INDTAU, INDWORK, INDWORK2, IROFFA, IROFFZ, ISCALE, IZROW, J,  K,
                          LCM,  LCMQ,  LDC,  LLWORK,  LWMIN, MB_A, MB_Z, MYCOL, MYPCOLC, MYPROWC,
                          MYROW, NB, NB_A, NB_Z, NN, NP, NPCOL, NPCOLC,  NPROCS,  NPROW,  NPROWC,
                          NQ, NRC, QRMEM, RSRC_A, RSRC_Z, SIZEMQRLEFT, SIZEMQRRIGHT

           DOUBLE         PRECISION ANRM, BIGNUM, EPS, RMAX, RMIN, SAFMIN, SIGMA, SMLNUM

           INTEGER        DESCQR( 10 ), IDUM1( 3 ), IDUM2( 3 )

           LOGICAL        LSAME

           INTEGER        ILCM, INDXG2P, NUMROC, SL_GRIDRESHAPE

           DOUBLE         PRECISION PDLAMCH, PDLANSY

           EXTERNAL       LSAME, ILCM, INDXG2P, NUMROC, SL_GRIDRESHAPE, PDLAMCH, PDLANSY

           EXTERNAL       BLACS_GRIDEXIT,  BLACS_GRIDINFO,  CHK1MAT,  DCOPY,  DESCINIT,  DGAMN2D,
                          DGAMX2D, DSCAL, DSTEQR2, PCHK2MAT, PDELGET, PDGEMR2D, PDLASCL, PDLASET,
                          PDORMTR, PDSYTRD, PXERBLA

           INTRINSIC      DBLE, ICHAR, MAX, MIN, MOD, SQRT

PURPOSE

       PDSYEV computes all eigenvalues and, optionally, eigenvectors of a real symmetric matrix A
       by calling the recommended sequence of ScaLAPACK routines.

       In its present form,  PDSYEV  assumes  a  homogeneous  system  and  makes  no  checks  for
       consistency of the eigenvalues or eigenvectors 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 establish 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 column.
       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 DOUBLE PRECISION 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
               submatrix 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, PDSYEV cannot guarantee
               correct error reporting.

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

       Z       (local output) DOUBLE PRECISION 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
               corresponding 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
               submatrix 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) DOUBLE PRECISION array,
               dimension (LWORK)
               Version 1.0:  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=optimal amount of workspace
               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 >= 5*N + SIZESYTRD + 1
               where
                  SIZESYTRD = The workspace requirement for PDSYTRD
                              and is MAX( NB * ( NP +1 ), 3 * NB )
               If eigenvectors are requested (JOBZ = 'V' ) then
                  the amount of workspace required to guarantee that all
                  eigenvectors are computed is:

                  QRMEM = 2*N-2
                  LWMIN = 5*N + N*LDC + MAX( SIZEMQRLEFT, QRMEM ) + 1

               Variable definitions:
                  NB = DESCA( MB_ ) = DESCA( NB_ ) =
                       DESCZ( MB_ ) = DESCZ( NB_ )
                  NN = MAX( N, NB, 2 )
                  DESCA( RSRC_ ) = DESCA( RSRC_ ) = DESCZ( RSRC_ ) =
                                   DESCZ( CSRC_ ) = 0
                  NP = NUMROC( NN, NB, 0, 0, NPROW )
                  NQ = NUMROC( MAX( N, NB, 2 ), NB, 0, 0, NPCOL )
                  NRC = NUMROC( N, NB, MYPROWC, 0, NPROCS)
                  LDC = MAX( 1, NRC )
                  SIZEMQRLEFT = The workspace requirement for PDORMTR
                                when it's SIDE argument is 'L'.

               With MYPROWC defined when a new context is created as:
                  CALL BLACS_GET( DESCA( CTXT_ ), 0, CONTEXTC )
                  CALL BLACS_GRIDINIT( CONTEXTC, 'R', NPROCS, 1 )
                  CALL BLACS_GRIDINFO( CONTEXTC, NPROWC, NPCOLC, MYPROWC,
                                       MYPCOLC )

               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.

       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 DSTEQR2 after a total of 30*N iterations.
                     If INFO = N+1, then PDSYEV has detected heterogeneity
                     by finding that eigenvalues were not identical across
                     the process grid.  In this case, the accuracy of
                     the results from PDSYEV cannot be guaranteed.