PSSYEVR(3) ScaLAPACK routine of NEC Numeric Library Collection PSSYEVR(3)
NAME
PSSYEVR - computes selected eigenvalues and, optionally, eigenvectors
of a real symmetric matrix A distributed in 2D blockcyclic format by
calling the recommended sequence of ScaLAPACK routines
SYNOPSIS
SUBROUTINE PSSYEVR( JOBZ, RANGE, UPLO, N, A, IA, JA, DESCA, VL, VU, IL,
IU, M, NZ, W, Z, IZ, JZ, DESCZ, WORK, LWORK, IWORK, LIWORK,INFO )
CHARACTER JOBZ, RANGE, UPLO
INTEGER IA, IL, INFO, IU, IZ, JA, JZ, LIWORK, LWORK, M, N,
NZ
REAL VL, VU
INTEGER DESCA( * ), DESCZ( * ), IWORK( * )
REAL A( * ), W( * ), WORK( * ), Z( * )
PURPOSE
PSSYEVR computes selected eigenvalues and, optionally, eigenvectors of
a real symmetric matrix A distributed in 2D blockcyclic format by call-
ing the recommended sequence of ScaLAPACK routines.
First, the matrix A is reduced to real symmetric tridiagonal form.
Then, the eigenproblem is solved using the parallel MRRR algorithm.
Last, if eigenvectors have been computed, a backtransformation is done.
Upon successful completion, each processor stores a copy of all com-
puted eigenvalues in W. The eigenvector matrix Z is stored in 2D block-
cyclic format distributed over all processors.
Note that subsets of eigenvalues/vectors can be selected by specifying
a range of values or a range of indices for the desired eigenvalues.
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, or
DESCZ for the descriptor of Z, etc. The length of a ScaLAPACK descrip-
tor is nine. 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
PSSYEVR assumes IEEE 754 standard compliant arithmetic.
ARGUMENTS
JOBZ (global input) CHARACTER*1
Specifies whether or not to compute the eigenvectors:
= 'N': Compute eigenvalues only.
= 'V': Compute eigenvalues and eigenvectors.
RANGE (global input) CHARACTER*1
= 'A': all eigenvalues will be found.
= 'V': all eigenvalues in the interval [VL,VU] will be found.
= 'I': the IL-th through IU-th eigenvalues will be found.
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) 2D block cyclic REAL array,
global dimension (N, N),
local dimension ( LLD_A, LOCc(JA+N-1) ),
(see Notes below for more detailed explanation of 2d arrays)
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.
It should be set to 1 when operating on a full matrix.
JA (global input) INTEGER
A's global column index, which points to the beginning of the
submatrix which is to be operated on.
It should be set to 1 when operating on a full matrix.
DESCA (global and local input) INTEGER array of dimension DLEN=9.
The array descriptor for the distributed matrix A.
The descriptor stores details about the 2D block-cyclic stor-
age, see the notes below.
If DESCA is incorrect, PSSYEVR cannot guarantee correct error
reporting.
Also note the array alignment requirements specified below.
VL (global input) REAL
If RANGE='V', the lower bound of the interval to be searched
for eigenvalues. Not referenced if RANGE = 'A' or 'I'.
VU (global input) REAL
If RANGE='V', the upper bound of the interval to be searched
for eigenvalues. Not referenced if RANGE = 'A' or 'I'.
IL (global input) INTEGER
If RANGE='I', the index (from smallest to largest) of the
smallest eigenvalue to be returned. IL >= 1.
Not referenced if RANGE = 'A'.
IU (global input) INTEGER
If RANGE='I', the index (from smallest to largest) of the
largest eigenvalue to be returned. min(IL,N) <= IU <= N.
Not referenced if RANGE = 'A'.
M (global output) INTEGER
Total number of eigenvalues found. 0 <= M <= N.
NZ (global output) INTEGER
Total number of eigenvectors computed. 0 <= NZ <= M.
The number of columns of Z that are filled.
If JOBZ .NE. 'V', NZ is not referenced.
If JOBZ .EQ. 'V', NZ = M
W (global output) REAL array, dimension (N)
Upon successful exit, the first M entries contain the selected
eigenvalues in ascending order.
Z (local output) REAL array, global dimension (N, N),
local dimension ( LLD_Z, LOCc(JZ+N-1) )
(see Notes below for more detailed explanation of 2d arrays)
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.
It should be set to 1 when operating on a full matrix.
JZ (global input) INTEGER
Z's global column index, which points to the beginning of the
submatrix which is to be operated on.
It should be set to 1 when operating on a full matrix.
DESCZ (global and local input) INTEGER array of dimension DLEN_.
The array descriptor for the distributed matrix Z.
The context DESCZ( CTXT_ ) must equal DESCA( CTXT_ ).
Also note the array alignment requirements specified below.
WORK (local workspace/output) REAL array,
dimension (LWORK)
On return, WORK(1) contains the optimal amount of workspace
required for efficient execution.
if JOBZ='N' WORK(1) = optimal amount of workspace
required to compute the eigenvalues.
if JOBZ='V' WORK(1) = optimal amount of workspace
required to compute eigenvalues and eigenvectors.
LWORK (local input) INTEGER
Size of WORK, must be at least 3. See below for definitions of
variables used to define LWORK. If no eigenvectors are
requested (JOBZ = 'N') then
LWORK >= 2 + 5*N + MAX( 12 * NN, NB * ( NP0 + 1 ) )
If eigenvectors are requested (JOBZ = 'V' ) then
the amount of workspace required is:
LWORK >= 2 + 5*N + MAX( 18*NN, NP0 * MQ0 + 2 * NB * NB ) +
(2 + ICEIL( NEIG, NPROW*NPCOL))*NN
Variable definitions:
NEIG = number of eigenvectors requested
NB = DESCA( MB_ ) = DESCA( NB_ ) =
DESCZ( MB_ ) = DESCZ( NB_ )
NN = MAX( N, NB, 2 )
DESCA( RSRC_ ) = DESCA( NB_ ) = DESCZ( RSRC_ ) =
DESCZ( CSRC_ ) = 0
NP0 = NUMROC( NN, NB, 0, 0, NPROW )
MQ0 = NUMROC( MAX( NEIG, NB, 2 ), NB, 0, 0, NPCOL )
ICEIL( X, Y ) is a ScaLAPACK function returning
ceiling(X/Y)
If LWORK = -1, then LWORK is global input and a workspace query
is assumed; the routine only calculates the size required for
optimal performance for all work arrays. Each of these values
is returned in the first entry of the corresponding work
arrays, and no error message is issued by PXERBLA.
Note that in a workspace query, for performance the optimal
workspace LWOPT is returned rather than the minimum necessary
WORKSPACE LWMIN. For very small matrices, LWOPT >> LWMIN.
IWORK (local workspace) INTEGER array
On return, IWORK(1) contains the amount of integer workspace
required.
LIWORK (local input) INTEGER
size of IWORK
Let NNP = MAX( N, NPROW*NPCOL + 1, 4 ). Then:
LIWORK >= 12*NNP + 2*N when the eigenvectors are desired
LIWORK >= 10*NNP + 2*N when only the eigenvalues have to be
computed
If LIWORK = -1, then LIWORK is global input and a workspace
query is assumed; the routine only calculates the minimum and
optimal size for all work arrays. Each of these values is
returned in the first entry of the corresponding work array,
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.
ALIGNMENT REQUIREMENTS
The distributed submatrices A(IA:*, JA:*) and Z(IZ:IZ+M-1,JZ:JZ+N-1)
must satisfy the following alignment properties:
1.Identical (quadratic) dimension:
DESCA(M_) = DESCZ(M_) = DESCA(N_) = DESCZ(N_)
2.Quadratic conformal blocking:
DESCA(MB_) = DESCA(NB_) = DESCZ(MB_) = DESCZ(NB_)
DESCA(RSRC_) = DESCZ(RSRC_)
3.MOD( IA-1, MB_A ) = MOD( IZ-1, MB_Z ) = 0
4.IAROW = IZROW
ScaLAPACK routine 31 October 2017 PSSYEVR(3)