PZHEEV(3) MathKeisan ScaLAPACK routine 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 version 1.7 13 August 2001 PZHEEV(3)