PCTREVC(3) ScaLAPACK routine of NEC Numeric Library Collection PCTREVC(3)
NAME
PCTREVC - compute some or all of the right and/or left eigenvectors of
a complex upper triangular matrix T in parallel
SYNOPSIS
SUBROUTINE PCTREVC( SIDE, HOWMNY, SELECT, N, T, DESCT, VL, DESCVL, VR,
DESCVR, MM, M, WORK, RWORK, INFO )
CHARACTER HOWMNY, SIDE
INTEGER INFO, M, MM, N
LOGICAL SELECT( * )
INTEGER DESCT( * ), DESCVL( * ), DESCVR( * )
REAL RWORK( * )
COMPLEX T( * ), VL( * ), VR( * ), WORK( * )
PURPOSE
PCTREVC computes some or all of the right and/or left eigenvectors of a
complex upper triangular matrix T in parallel. The right eigenvector x
and the left eigenvector y of T corresponding to an eigenvalue w are
defined by:
T*x = w*x, y'*T = w*y'
where y' denotes the conjugate transpose of the vector y.
If all eigenvectors are requested, the routine may either return the
matrices X and/or Y of right or left eigenvectors of T, or the products
Q*X and/or Q*Y, where Q is an input unitary
matrix. If T was obtained from the Schur factorization of an original
matrix A = Q*T*Q', then Q*X and Q*Y are the matrices of right or left
eigenvectors of A.
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 r x c.
LOCr( K ) denotes the number of elements of K that a process would
receive if K were distributed over the r 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 c 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
SIDE (global input) CHARACTER*1
= 'R': compute right eigenvectors only;
= 'L': compute left eigenvectors only;
= 'B': compute both right and left eigenvectors.
HOWMNY (global input) CHARACTER*1
= 'A': compute all right and/or left eigenvectors;
= 'B': compute all right and/or left eigenvectors, and back-
transform them using the input matrices supplied in VR and/or
VL; = 'S': compute selected right and/or left eigenvectors,
specified by the logical array SELECT.
SELECT (global input) LOGICAL array, dimension (N)
If HOWMNY = 'S', SELECT specifies the eigenvectors to be com-
puted. If HOWMNY = 'A' or 'B', SELECT is not referenced. To
select the eigenvector corresponding to the j-th eigenvalue,
SELECT(j) must be set to .TRUE..
N (global input) INTEGER
The order of the matrix T. N >= 0.
T (global input/output) COMPLEX array, dimension
(DESCT(LLD_),*) The upper triangular matrix T. T is modified,
but restored on exit.
DESCT (global and local input) INTEGER array of dimension DLEN_.
The array descriptor for the distributed matrix T.
VL (global input/output) COMPLEX array, dimension
(DESCVL(LLD_),MM) On entry, if SIDE = 'L' or 'B' and HOWMNY =
'B', VL must contain an N-by-N matrix Q (usually the unitary
matrix Q of Schur vectors returned by CHSEQR). On exit, if
SIDE = 'L' or 'B', VL contains: if HOWMNY = 'A', the matrix Y
of left eigenvectors of T; if HOWMNY = 'B', the matrix Q*Y; if
HOWMNY = 'S', the left eigenvectors of T specified by SELECT,
stored consecutively in the columns of VL, in the same order as
their eigenvalues. If SIDE = 'R', VL is not referenced.
DESCVL (global and local input) INTEGER array of dimension DLEN_.
The array descriptor for the distributed matrix VL.
VR (global input/output) COMPLEX array, dimension
(DESCVR(LLD_),MM) On entry, if SIDE = 'R' or 'B' and HOWMNY =
'B', VR must contain an N-by-N matrix Q (usually the unitary
matrix Q of Schur vectors returned by CHSEQR). On exit, if
SIDE = 'R' or 'B', VR contains: if HOWMNY = 'A', the matrix X
of right eigenvectors of T; if HOWMNY = 'B', the matrix Q*X; if
HOWMNY = 'S', the right eigenvectors of T specified by SELECT,
stored consecutively in the columns of VR, in the same order as
their eigenvalues. If SIDE = 'L', VR is not referenced.
DESCVR (global and local input) INTEGER array of dimension DLEN_.
The array descriptor for the distributed matrix VR.
MM (global input) INTEGER
The number of columns in the arrays VL and/or VR. MM >= M.
M (global output) INTEGER
The number of columns in the arrays VL and/or VR actually used
to store the eigenvectors. If HOWMNY = 'A' or 'B', M is set to
N. Each selected eigenvector occupies one column.
WORK (local workspace) COMPLEX array,
dimension ( 2*DESCT(LLD_) ) Additional workspace may be
required if PCLATTRS is updated to use WORK.
RWORK (local workspace) REAL array,
dimension ( DESCT(LLD_) )
INFO (global output) INTEGER
= 0: successful exit
< 0: if INFO = -i, the i-th argument had an illegal value
FURTHER DETAILS
The algorithm used in this program is basically backward (forward) sub-
stitution. It is the hope that scaling would be used to make the the
code robust against possible overflow. But scaling has not yet been
implemented in PCLATTRS which is called by this routine to solve the
triangular systems. PCLATTRS just calls PCTRSV.
Each eigenvector is normalized so that the element of largest magnitude
has magnitude 1; here the magnitude of a complex number (x,y) is taken
to be |x| + |y|.
FURTHER DETAILS
Implemented by Mark R. Fahey, June, 2000
ScaLAPACK routine 31 October 2017 PCTREVC(3)