pctrevc.f

Go to the documentation of this file.

      SUBROUTINE pctrevc( SIDE, HOWMNY, SELECT, N, T, DESCT, VL, DESCVL,
     $                    VR, DESCVR, MM, M, WORK, RWORK, INFO )
*
*  -- ScaLAPACK routine (version 1.7) --
*     University of Tennessee, Knoxville, Oak Ridge National Laboratory,
*     and University of California, Berkeley.
*     July 31, 2001
*
*     .. Scalar Arguments ..
      CHARACTER          HOWMNY, SIDE
      INTEGER            INFO, M, MM, N
*     ..
*     .. Array Arguments ..
      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
*  vector.  This vector stores the information required to establish
*  the mapping 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 column.
*  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 backtransform 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
*          computed.
*          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)
*  substitution.  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
*
*  =====================================================================
*
*     .. Parameters ..
      REAL               ZERO, ONE
      parameter( zero = 0.0e+0, one = 1.0e+0 )
      COMPLEX            CZERO, CONE
      parameter( czero = ( 0.0e+0, 0.0e+0 ),
     $                   cone = ( 1.0e+0, 0.0e+0 ) )
      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 )
*     ..
*     .. Local Scalars ..
      LOGICAL            ALLV, BOTHV, LEFTV, OVER, RIGHTV, SOMEV
      INTEGER            CONTXT, CSRC, I, ICOL, II, IROW, IS, ITMP1,
     $                   itmp2, j, k, ki, ldt, ldvl, ldvr, ldw, mb,
     $                   mycol, myrow, nb, npcol, nprow, rsrc
      REAL               SELF
      REAL               OVFL, REMAXD, SCALE, SMLNUM, ULP, UNFL
      COMPLEX            CDUM, REMAXC, SHIFT
*     ..
*     .. Local Arrays ..
      INTEGER            DESCW( DLEN_ )
      REAL               SMIN( 1 )
*     ..
*     .. External Functions ..
      LOGICAL            LSAME
      REAL               PSLAMCH
      EXTERNAL           lsame, pslamch
*     ..
*     .. External Subroutines ..
      EXTERNAL           blacs_gridinfo, descinit, sgsum2d, igamn2d,
     $                   infog2l, pslabad, pscasum, pxerbla, pcamax,
     $                   pccopy, pcsscal, pcgemv, pclaset, pclattrs,
     $                   cgsum2d
*     ..
*     .. Intrinsic Functions ..
      INTRINSIC          abs, real, cmplx, conjg, aimag, max
*     ..
*     .. Statement Functions ..
      REAL               CABS1
*     ..
*     .. Statement Function definitions ..
      cabs1( cdum ) = abs( real( cdum ) ) + abs( aimag( cdum ) )
*     ..
*     .. Executable Statements ..
*
*       This is just to keep ftnchek happy
      IF( block_cyclic_2d*csrc_*ctxt_*dlen_*dtype_*lld_*mb_*m_*nb_*n_*
     $    rsrc_.LT.0 )RETURN
*
      contxt = desct( ctxt_ )
      rsrc = desct( rsrc_ )
      csrc = desct( csrc_ )
      mb = desct( mb_ )
      nb = desct( nb_ )
      ldt = desct( lld_ )
      ldw = ldt
      ldvr = descvr( lld_ )
      ldvl = descvl( lld_ )
*
      CALL blacs_gridinfo( contxt, nprow, npcol, myrow, mycol )
      self = myrow*npcol + mycol
*
*     Decode and test the input parameters
*
      bothv = lsame( side, 'B' )
      rightv = lsame( side, 'R' ) .OR. bothv
      leftv = lsame( side, 'L' ) .OR. bothv
*
      allv = lsame( howmny, 'A' )
      over = lsame( howmny, 'B' ) .OR. lsame( howmny, 'O' )
      somev = lsame( howmny, 'S' )
*
*     Set M to the number of columns required to store the selected
*     eigenvectors.
*
      IF( somev ) THEN
         m = 0
         DO 10 j = 1, n
            IF( SELECT( j ) )
     $         m = m + 1
   10    CONTINUE
      ELSE
         m = n
      END IF
*
      info = 0
      IF( .NOT.rightv .AND. .NOT.leftv ) THEN
         info = -1
      ELSE IF( .NOT.allv .AND. .NOT.over .AND. .NOT.somev ) THEN
         info = -2
      ELSE IF( n.LT.0 ) THEN
         info = -4
      ELSE IF( mm.LT.m ) THEN
         info = -11
      END IF
      CALL igamn2d( contxt, 'ALL', ' ', 1, 1, info, 1, itmp1, itmp2, -1,
     $              -1, -1 )
      IF( info.LT.0 ) THEN
         CALL pxerbla( contxt, 'PCTREVC', -info )
         RETURN
      END IF
*
*     Quick return if possible.
*
      IF( n.EQ.0 )
     $   RETURN
*
*     Set the constants to control overflow.
*
      unfl = pslamch( contxt, 'Safe minimum' )
      ovfl = one / unfl
      CALL pslabad( contxt, unfl, ovfl )
      ulp = pslamch( contxt, 'Precision' )
      smlnum = unfl*( n / ulp )
*
*     Store the diagonal elements of T in working array WORK( LDW+1 ).
*
      DO 20 i = 1, n
         CALL infog2l( i, i, desct, nprow, npcol, myrow, mycol, irow,
     $                 icol, itmp1, itmp2 )
         IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
            work( ldw+irow ) = t( ( icol-1 )*ldt+irow )
         END IF
   20 CONTINUE
*
*     Compute 1-norm of each column of strictly upper triangular
*     part of T to control overflow in triangular solver.  Computed,
*     but not used.  For use in PCLATTRS.
*
      rwork( 1 ) = zero
      DO 30 j = 2, n
         CALL pscasum( j-1, rwork( j ), t, 1, j, desct, 1 )
   30 CONTINUE
*     I replicate the norms in RWORK.  Should they be distributed
*     over the process rows?
      CALL sgsum2d( contxt, 'Row', ' ', n, 1, rwork, n, -1, -1 )
*
      IF( rightv ) THEN
*
*        Compute right eigenvectors.
*
*        Need to set the distribution pattern of WORK
*
         CALL descinit( descw, n, 1, nb, 1, rsrc, csrc, contxt, ldw,
     $                  info )
*
         is = m
         DO 70 ki = n, 1, -1
*
            IF( somev ) THEN
               IF( .NOT.SELECT( ki ) )
     $            GO TO 70
            END IF
*
            smin( 1 ) = zero
            shift = czero
            CALL infog2l( ki, ki, desct, nprow, npcol, myrow, mycol,
     $                    irow, icol, itmp1, itmp2 )
            IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
               shift = t( ( icol-1 )*ldt+irow )
               smin( 1 ) = max( ulp*( cabs1( shift ) ), smlnum )
            END IF
            CALL sgsum2d( contxt, 'ALL', ' ', 1, 1, smin, 1, -1, -1 )
            CALL cgsum2d( contxt, 'ALL', ' ', 1, 1, shift, 1, -1, -1 )
*
            CALL infog2l( 1, 1, descw, nprow, npcol, myrow, mycol, irow,
     $                    icol, itmp1, itmp2 )
            IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
               work( 1 ) = cone
            END IF
*
*           Form right-hand side.  Distribute rhs onto first column
*           of processor grid.
*
            IF( ki.GT.1 ) THEN
               CALL pccopy( ki-1, t, 1, ki, desct, 1, work, 1, 1, descw,
     $                      1 )
            END IF
            DO 40 k = 1, ki - 1
               CALL infog2l( k, 1, descw, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( myrow.EQ.itmp1 .AND. mycol.EQ.itmp2 ) THEN
                  work( irow ) = -work( irow )
               END IF
   40       CONTINUE
*
*           Solve the triangular system:
*              (T(1:KI-1,1:KI-1) - T(KI,KI))*X = SCALE*WORK.
*
            DO 50 k = 1, ki - 1
               CALL infog2l( k, k, desct, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
                  t( ( icol-1 )*ldt+irow ) = t( ( icol-1 )*ldt+irow ) -
     $               shift
                  IF( cabs1( t( ( icol-1 )*ldt+irow ) ).LT.smin( 1 ) )
     $            THEN
                     t( ( icol-1 )*ldt+irow ) = cmplx( smin( 1 ) )
                  END IF
               END IF
   50       CONTINUE
*
            IF( ki.GT.1 ) THEN
               CALL pclattrs( 'Upper', 'No transpose', 'Non-unit', 'Y',
     $                        ki-1, t, 1, 1, desct, work, 1, 1, descw,
     $                        scale, rwork, info )
               CALL infog2l( ki, 1, descw, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( myrow.EQ.itmp1 .AND. mycol.EQ.itmp2 ) THEN
                  work( irow ) = cmplx( scale )
               END IF
            END IF
*
*           Copy the vector x or Q*x to VR and normalize.
*
            IF( .NOT.over ) THEN
               CALL pccopy( ki, work, 1, 1, descw, 1, vr, 1, is, descvr,
     $                      1 )
*
               CALL pcamax( ki, remaxc, ii, vr, 1, is, descvr, 1 )
               remaxd = one / max( cabs1( remaxc ), unfl )
               CALL pcsscal( ki, remaxd, vr, 1, is, descvr, 1 )
*
               CALL pclaset( ' ', n-ki, 1, czero, czero, vr, ki+1, is,
     $                       descvr )
            ELSE
               IF( ki.GT.1 )
     $            CALL pcgemv( 'N', n, ki-1, cone, vr, 1, 1, descvr,
     $                         work, 1, 1, descw, 1, cmplx( scale ),
     $                         vr, 1, ki, descvr, 1 )
*
               CALL pcamax( n, remaxc, ii, vr, 1, ki, descvr, 1 )
               remaxd = one / max( cabs1( remaxc ), unfl )
               CALL pcsscal( n, remaxd, vr, 1, ki, descvr, 1 )
            END IF
*
*           Set back the original diagonal elements of T.
*
            DO 60 k = 1, ki - 1
               CALL infog2l( k, k, desct, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
                  t( ( icol-1 )*ldt+irow ) = work( ldw+irow )
               END IF
   60       CONTINUE
*
            is = is - 1
   70    CONTINUE
      END IF
*
      IF( leftv ) THEN
*
*        Compute left eigenvectors.
*
*        Need to set the distribution pattern of WORK
*
         CALL descinit( descw, n, 1, mb, 1, rsrc, csrc, contxt, ldw,
     $                  info )
*
         is = 1
         DO 110 ki = 1, n
*
            IF( somev ) THEN
               IF( .NOT.SELECT( ki ) )
     $            GO TO 110
            END IF
*
            smin( 1 ) = zero
            shift = czero
            CALL infog2l( ki, ki, desct, nprow, npcol, myrow, mycol,
     $                    irow, icol, itmp1, itmp2 )
            IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
               shift = t( ( icol-1 )*ldt+irow )
               smin( 1 ) = max( ulp*( cabs1( shift ) ), smlnum )
            END IF
            CALL sgsum2d( contxt, 'ALL', ' ', 1, 1, smin, 1, -1, -1 )
            CALL cgsum2d( contxt, 'ALL', ' ', 1, 1, shift, 1, -1, -1 )
*
            CALL infog2l( n, 1, descw, nprow, npcol, myrow, mycol, irow,
     $                    icol, itmp1, itmp2 )
            IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
               work( irow ) = cone
            END IF
*
*           Form right-hand side.
*
            IF( ki.LT.n ) THEN
               CALL pccopy( n-ki, t, ki, ki+1, desct, n, work, ki+1, 1,
     $                      descw, 1 )
            END IF
            DO 80 k = ki + 1, n
               CALL infog2l( k, 1, descw, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( myrow.EQ.itmp1 .AND. mycol.EQ.itmp2 ) THEN
                  work( irow ) = -conjg( work( irow ) )
               END IF
   80       CONTINUE
*
*           Solve the triangular system:
*              (T(KI+1:N,KI+1:N) - T(KI,KI))'*X = SCALE*WORK.
*
            DO 90 k = ki + 1, n
               CALL infog2l( k, k, desct, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
                  t( ( icol-1 )*ldt+irow ) = t( ( icol-1 )*ldt+irow ) -
     $               shift
                  IF( cabs1( t( ( icol-1 )*ldt+irow ) ).LT.smin( 1 ) )
     $               t( ( icol-1 )*ldt+irow ) = cmplx( smin( 1 ) )
               END IF
   90       CONTINUE
*
            IF( ki.LT.n ) THEN
               CALL pclattrs( 'Upper', 'Conjugate transpose', 'Nonunit',
     $                        'Y', n-ki, t, ki+1, ki+1, desct, work,
     $                        ki+1, 1, descw, scale, rwork, info )
               CALL infog2l( ki, 1, descw, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( myrow.EQ.itmp1 .AND. mycol.EQ.itmp2 ) THEN
                  work( irow ) = cmplx( scale )
               END IF
            END IF
*
*           Copy the vector x or Q*x to VL and normalize.
*
            IF( .NOT.over ) THEN
               CALL pccopy( n-ki+1, work, ki, 1, descw, 1, vl, ki, is,
     $                      descvl, 1 )
*
               CALL pcamax( n-ki+1, remaxc, ii, vl, ki, is, descvl, 1 )
               remaxd = one / max( cabs1( remaxc ), unfl )
               CALL pcsscal( n-ki+1, remaxd, vl, ki, is, descvl, 1 )
*
               CALL pclaset( ' ', ki-1, 1, czero, czero, vl, 1, is,
     $                       descvl )
            ELSE
               IF( ki.LT.n )
     $            CALL pcgemv( 'N', n, n-ki, cone, vl, 1, ki+1, descvl,
     $                         work, ki+1, 1, descw, 1, cmplx( scale ),
     $                         vl, 1, ki, descvl, 1 )
*
               CALL pcamax( n, remaxc, ii, vl, 1, ki, descvl, 1 )
               remaxd = one / max( cabs1( remaxc ), unfl )
               CALL pcsscal( n, remaxd, vl, 1, ki, descvl, 1 )
            END IF
*
*           Set back the original diagonal elements of T.
*
            DO 100 k = ki + 1, n
               CALL infog2l( k, k, desct, nprow, npcol, myrow, mycol,
     $                       irow, icol, itmp1, itmp2 )
               IF( ( myrow.EQ.itmp1 ) .AND. ( mycol.EQ.itmp2 ) ) THEN
                  t( ( icol-1 )*ldt+irow ) = work( ldw+irow )
               END IF
  100       CONTINUE
*
            is = is + 1
  110    CONTINUE
      END IF
*
      RETURN
*
*     End of PCTREVC
*
      END