ScaLAPACK  2.0.2
ScaLAPACK: Scalable Linear Algebra PACKage
pzunm2r.f
Go to the documentation of this file.
00001       SUBROUTINE PZUNM2R( SIDE, TRANS, M, N, K, A, IA, JA, DESCA, TAU,
00002      $                    C, IC, JC, DESCC, WORK, LWORK, INFO )
00003 *
00004 *  -- ScaLAPACK routine (version 1.7) --
00005 *     University of Tennessee, Knoxville, Oak Ridge National Laboratory,
00006 *     and University of California, Berkeley.
00007 *     May 25, 2001
00008 *
00009 *     .. Scalar Arguments ..
00010       CHARACTER          SIDE, TRANS
00011       INTEGER            IA, IC, INFO, JA, JC, K, LWORK, M, N
00012 *     ..
00013 *     .. Array Arguments ..
00014       INTEGER            DESCA( * ), DESCC( * )
00015       COMPLEX*16         A( * ), C( * ), TAU( * ), WORK( * )
00016 *     ..
00017 *
00018 *  Purpose
00019 *  =======
00020 *
00021 *  PZUNM2R overwrites the general complex M-by-N distributed matrix
00022 *  sub( C ) = C(IC:IC+M-1,JC:JC+N-1) with
00023 *
00024 *                      SIDE = 'L'            SIDE = 'R'
00025 *  TRANS = 'N':      Q * sub( C )          sub( C ) * Q
00026 *  TRANS = 'C':      Q**H * sub( C )       sub( C ) * Q**H
00027 *
00028 *  where Q is a complex unitary distributed matrix defined as the
00029 *  product of k elementary reflectors
00030 *
00031 *        Q = H(1) H(2) . . . H(k)
00032 *
00033 *  as returned by PZGEQRF. Q is of order M if SIDE = 'L' and of order N
00034 *  if SIDE = 'R'.
00035 *
00036 *  Notes
00037 *  =====
00038 *
00039 *  Each global data object is described by an associated description
00040 *  vector.  This vector stores the information required to establish
00041 *  the mapping between an object element and its corresponding process
00042 *  and memory location.
00043 *
00044 *  Let A be a generic term for any 2D block cyclicly distributed array.
00045 *  Such a global array has an associated description vector DESCA.
00046 *  In the following comments, the character _ should be read as
00047 *  "of the global array".
00048 *
00049 *  NOTATION        STORED IN      EXPLANATION
00050 *  --------------- -------------- --------------------------------------
00051 *  DTYPE_A(global) DESCA( DTYPE_ )The descriptor type.  In this case,
00052 *                                 DTYPE_A = 1.
00053 *  CTXT_A (global) DESCA( CTXT_ ) The BLACS context handle, indicating
00054 *                                 the BLACS process grid A is distribu-
00055 *                                 ted over. The context itself is glo-
00056 *                                 bal, but the handle (the integer
00057 *                                 value) may vary.
00058 *  M_A    (global) DESCA( M_ )    The number of rows in the global
00059 *                                 array A.
00060 *  N_A    (global) DESCA( N_ )    The number of columns in the global
00061 *                                 array A.
00062 *  MB_A   (global) DESCA( MB_ )   The blocking factor used to distribute
00063 *                                 the rows of the array.
00064 *  NB_A   (global) DESCA( NB_ )   The blocking factor used to distribute
00065 *                                 the columns of the array.
00066 *  RSRC_A (global) DESCA( RSRC_ ) The process row over which the first
00067 *                                 row of the array A is distributed.
00068 *  CSRC_A (global) DESCA( CSRC_ ) The process column over which the
00069 *                                 first column of the array A is
00070 *                                 distributed.
00071 *  LLD_A  (local)  DESCA( LLD_ )  The leading dimension of the local
00072 *                                 array.  LLD_A >= MAX(1,LOCr(M_A)).
00073 *
00074 *  Let K be the number of rows or columns of a distributed matrix,
00075 *  and assume that its process grid has dimension p x q.
00076 *  LOCr( K ) denotes the number of elements of K that a process
00077 *  would receive if K were distributed over the p processes of its
00078 *  process column.
00079 *  Similarly, LOCc( K ) denotes the number of elements of K that a
00080 *  process would receive if K were distributed over the q processes of
00081 *  its process row.
00082 *  The values of LOCr() and LOCc() may be determined via a call to the
00083 *  ScaLAPACK tool function, NUMROC:
00084 *          LOCr( M ) = NUMROC( M, MB_A, MYROW, RSRC_A, NPROW ),
00085 *          LOCc( N ) = NUMROC( N, NB_A, MYCOL, CSRC_A, NPCOL ).
00086 *  An upper bound for these quantities may be computed by:
00087 *          LOCr( M ) <= ceil( ceil(M/MB_A)/NPROW )*MB_A
00088 *          LOCc( N ) <= ceil( ceil(N/NB_A)/NPCOL )*NB_A
00089 *
00090 *  Arguments
00091 *  =========
00092 *
00093 *  SIDE    (global input) CHARACTER
00094 *          = 'L': apply Q or Q**H from the Left;
00095 *          = 'R': apply Q or Q**H from the Right.
00096 *
00097 *  TRANS   (global input) CHARACTER
00098 *          = 'N':  No transpose, apply Q;
00099 *          = 'C':  Conjugate transpose, apply Q**H.
00100 *
00101 *  M       (global input) INTEGER
00102 *          The number of rows to be operated on i.e the number of rows
00103 *          of the distributed submatrix sub( C ). M >= 0.
00104 *
00105 *  N       (global input) INTEGER
00106 *          The number of columns to be operated on i.e the number of
00107 *          columns of the distributed submatrix sub( C ). N >= 0.
00108 *
00109 *  K       (global input) INTEGER
00110 *          The number of elementary reflectors whose product defines the
00111 *          matrix Q.  If SIDE = 'L', M >= K >= 0, if SIDE = 'R',
00112 *          N >= K >= 0.
00113 *
00114 *  A       (local input) COMPLEX*16 pointer into the local memory
00115 *          to an array of dimension (LLD_A,LOCc(JA+K-1)). On entry, the
00116 *          j-th column must contain the vector which defines the elemen-
00117 *          tary reflector H(j), JA <= j <= JA+K-1, as returned by
00118 *          PZGEQRF in the K columns of its distributed matrix
00119 *          argument A(IA:*,JA:JA+K-1). A(IA:*,JA:JA+K-1) is modified by
00120 *          the routine but restored on exit.
00121 *          If SIDE = 'L', LLD_A >= MAX( 1, LOCr(IA+M-1) );
00122 *          if SIDE = 'R', LLD_A >= MAX( 1, LOCr(IA+N-1) ).
00123 *
00124 *  IA      (global input) INTEGER
00125 *          The row index in the global array A indicating the first
00126 *          row of sub( A ).
00127 *
00128 *  JA      (global input) INTEGER
00129 *          The column index in the global array A indicating the
00130 *          first column of sub( A ).
00131 *
00132 *  DESCA   (global and local input) INTEGER array of dimension DLEN_.
00133 *          The array descriptor for the distributed matrix A.
00134 *
00135 *  TAU     (local input) COMPLEX*16, array, dimension LOCc(JA+K-1).
00136 *          This array contains the scalar factors TAU(j) of the
00137 *          elementary reflectors H(j) as returned by PZGEQRF.
00138 *          TAU is tied to the distributed matrix A.
00139 *
00140 *  C       (local input/local output) COMPLEX*16 pointer into the
00141 *          local memory to an array of dimension (LLD_C,LOCc(JC+N-1)).
00142 *          On entry, the local pieces of the distributed matrix sub(C).
00143 *          On exit, sub( C ) is overwritten by Q*sub( C ) or Q'*sub( C )
00144 *          or sub( C )*Q' or sub( C )*Q.
00145 *
00146 *  IC      (global input) INTEGER
00147 *          The row index in the global array C indicating the first
00148 *          row of sub( C ).
00149 *
00150 *  JC      (global input) INTEGER
00151 *          The column index in the global array C indicating the
00152 *          first column of sub( C ).
00153 *
00154 *  DESCC   (global and local input) INTEGER array of dimension DLEN_.
00155 *          The array descriptor for the distributed matrix C.
00156 *
00157 *  WORK    (local workspace/local output) COMPLEX*16 array,
00158 *                                                     dimension (LWORK)
00159 *          On exit, WORK(1) returns the minimal and optimal LWORK.
00160 *
00161 *  LWORK   (local or global input) INTEGER
00162 *          The dimension of the array WORK.
00163 *          LWORK is local input and must be at least
00164 *          If SIDE = 'L', LWORK >= MpC0 + MAX( 1, NqC0 );
00165 *          if SIDE = 'R', LWORK >= NqC0 + MAX( MAX( 1, MpC0 ), NUMROC(
00166 *                   NUMROC( N+ICOFFC,NB_A,0,0,NPCOL ),NB_A,0,0,LCMQ ) );
00167 *
00168 *          where LCMQ = LCM / NPCOL with LCM = ICLM( NPROW, NPCOL ),
00169 *
00170 *          IROFFC = MOD( IC-1, MB_C ), ICOFFC = MOD( JC-1, NB_C ),
00171 *          ICROW = INDXG2P( IC, MB_C, MYROW, RSRC_C, NPROW ),
00172 *          ICCOL = INDXG2P( JC, NB_C, MYCOL, CSRC_C, NPCOL ),
00173 *          MpC0 = NUMROC( M+IROFFC, MB_C, MYROW, ICROW, NPROW ),
00174 *          NqC0 = NUMROC( N+ICOFFC, NB_C, MYCOL, ICCOL, NPCOL ),
00175 *
00176 *          ILCM, INDXG2P and NUMROC are ScaLAPACK tool functions;
00177 *          MYROW, MYCOL, NPROW and NPCOL can be determined by calling
00178 *          the subroutine BLACS_GRIDINFO.
00179 *
00180 *          If LWORK = -1, then LWORK is global input and a workspace
00181 *          query is assumed; the routine only calculates the minimum
00182 *          and optimal size for all work arrays. Each of these
00183 *          values is returned in the first entry of the corresponding
00184 *          work array, and no error message is issued by PXERBLA.
00185 *
00186 *
00187 *  INFO    (local output) INTEGER
00188 *          = 0:  successful exit
00189 *          < 0:  If the i-th argument is an array and the j-entry had
00190 *                an illegal value, then INFO = -(i*100+j), if the i-th
00191 *                argument is a scalar and had an illegal value, then
00192 *                INFO = -i.
00193 *
00194 *  Alignment requirements
00195 *  ======================
00196 *
00197 *  The distributed submatrices A(IA:*, JA:*) and C(IC:IC+M-1,JC:JC+N-1)
00198 *  must verify some alignment properties, namely the following
00199 *  expressions should be true:
00200 *
00201 *  If SIDE = 'L',
00202 *    ( MB_A.EQ.MB_C .AND. IROFFA.EQ.IROFFC .AND. IAROW.EQ.ICROW )
00203 *  If SIDE = 'R',
00204 *    ( MB_A.EQ.NB_C .AND. IROFFA.EQ.ICOFFC )
00205 *
00206 *  =====================================================================
00207 *
00208 *     .. Parameters ..
00209       INTEGER            BLOCK_CYCLIC_2D, CSRC_, CTXT_, DLEN_, DTYPE_,
00210      $                   LLD_, MB_, M_, NB_, N_, RSRC_
00211       PARAMETER          ( BLOCK_CYCLIC_2D = 1, DLEN_ = 9, DTYPE_ = 1,
00212      $                     CTXT_ = 2, M_ = 3, N_ = 4, MB_ = 5, NB_ = 6,
00213      $                     RSRC_ = 7, CSRC_ = 8, LLD_ = 9 )
00214       COMPLEX*16         ONE
00215       PARAMETER          ( ONE  = ( 1.0D+0, 0.0D+0 ) )
00216 *     ..
00217 *     .. Local Scalars ..
00218       LOGICAL            LEFT, LQUERY, NOTRAN
00219       CHARACTER          COLBTOP, ROWBTOP
00220       INTEGER            IACOL, IAROW, ICCOL, ICOFFC, ICROW, ICTXT, ICC,
00221      $                   II, IROFFA, IROFFC, J, J1, J2, J3, JCC, JJ,
00222      $                   LCM, LCMQ, LWMIN, MI, MP, MPC0, MYCOL, MYROW,
00223      $                   NI, NPCOL, NPROW, NQ, NQC0
00224       COMPLEX*16         AJJ
00225 *     ..
00226 *     .. External Subroutines ..
00227       EXTERNAL           BLACS_ABORT, BLACS_GRIDINFO, CHK1MAT, INFOG2L,
00228      $                   PB_TOPGET, PB_TOPSET, PXERBLA, PZELSET,
00229      $                   PZELSET2, PZLARF, PZLARFC, ZGEBR2D, ZGEBS2D,
00230      $                   ZGERV2D, ZGESD2D, ZSCAL
00231 *     ..
00232 *     .. External Functions ..
00233       LOGICAL            LSAME
00234       INTEGER            ILCM, INDXG2P, NUMROC
00235       EXTERNAL           ILCM, INDXG2P, LSAME, NUMROC
00236 *     ..
00237 *     .. Intrinsic Functions ..
00238       INTRINSIC          DBLE, DCMPLX, DCONJG, MAX, MOD
00239 *     ..
00240 *     .. Executable Statements ..
00241 *
00242 *     Get grid parameters
00243 *
00244       ICTXT = DESCA( CTXT_ )
00245       CALL BLACS_GRIDINFO( ICTXT, NPROW, NPCOL, MYROW, MYCOL )
00246 *
00247 *     Test the input parameters
00248 *
00249       INFO = 0
00250       IF( NPROW.EQ.-1 ) THEN
00251          INFO = -(900+CTXT_)
00252       ELSE
00253          LEFT = LSAME( SIDE, 'L' )
00254          NOTRAN = LSAME( TRANS, 'N' )
00255 *
00256 *        NQ is the order of Q
00257 *
00258          IF( LEFT ) THEN
00259             NQ = M
00260             CALL CHK1MAT( M, 3, K, 5, IA, JA, DESCA, 9, INFO )
00261          ELSE
00262             NQ = N
00263             CALL CHK1MAT( N, 4, K, 5, IA, JA, DESCA, 9, INFO )
00264          END IF
00265          CALL CHK1MAT( M, 3, N, 4, IC, JC, DESCC, 14, INFO )
00266          IF( INFO.EQ.0 ) THEN
00267             IROFFA = MOD( IA-1, DESCA( MB_ ) )
00268             IROFFC = MOD( IC-1, DESCC( MB_ ) )
00269             ICOFFC = MOD( JC-1, DESCC( NB_ ) )
00270             IAROW = INDXG2P( IA, DESCA( MB_ ), MYROW, DESCA( RSRC_ ),
00271      $                       NPROW )
00272             ICROW = INDXG2P( IC, DESCC( MB_ ), MYROW, DESCC( RSRC_ ),
00273      $                       NPROW )
00274             ICCOL = INDXG2P( JC, DESCC( NB_ ), MYCOL, DESCC( CSRC_ ),
00275      $                       NPCOL )
00276             MPC0 = NUMROC( M+IROFFC, DESCC( MB_ ), MYROW, ICROW, NPROW )
00277             NQC0 = NUMROC( N+ICOFFC, DESCC( NB_ ), MYCOL, ICCOL, NPCOL )
00278 *
00279             IF( LEFT ) THEN
00280                LWMIN = MPC0 + MAX( 1, NQC0 )
00281             ELSE
00282                LCM = ILCM( NPROW, NPCOL )
00283                LCMQ = LCM / NPCOL
00284                LWMIN = NQC0 + MAX( MAX( 1, MPC0 ), NUMROC( NUMROC(
00285      $                 N+ICOFFC, DESCA( NB_ ), 0, 0, NPCOL ),
00286      $                 DESCA( NB_ ), 0, 0, LCMQ ) )
00287             END IF
00288 *
00289             WORK( 1 ) = DCMPLX( DBLE( LWMIN ) )
00290             LQUERY = ( LWORK.EQ.-1 )
00291             IF( .NOT.LEFT .AND. .NOT.LSAME( SIDE, 'R' ) ) THEN
00292                INFO = -1
00293             ELSE IF( .NOT.NOTRAN .AND. .NOT.LSAME( TRANS, 'C' ) ) THEN
00294                INFO = -2
00295             ELSE IF( K.LT.0 .OR. K.GT.NQ ) THEN
00296                INFO = -5
00297             ELSE IF( .NOT.LEFT .AND. DESCA( MB_ ).NE.DESCC( NB_ ) ) THEN
00298                INFO = -(900+NB_)
00299             ELSE IF( LEFT .AND. IROFFA.NE.IROFFC ) THEN
00300                INFO = -12
00301             ELSE IF( LEFT .AND. IAROW.NE.ICROW ) THEN
00302                INFO = -12
00303             ELSE IF( .NOT.LEFT .AND. IROFFA.NE.ICOFFC ) THEN
00304                INFO = -13
00305             ELSE IF( LEFT .AND. DESCA( MB_ ).NE.DESCC( MB_ ) ) THEN
00306                INFO = -(1400+MB_)
00307             ELSE IF( ICTXT.NE.DESCC( CTXT_ ) ) THEN
00308                INFO = -(1400+CTXT_)
00309             ELSE IF( LWORK.LT.LWMIN .AND. .NOT.LQUERY ) THEN
00310                INFO = -16
00311             END IF
00312          END IF
00313       END IF
00314 *
00315       IF( INFO.NE.0 ) THEN
00316          CALL PXERBLA( ICTXT, 'PZUNM2R', -INFO )
00317          CALL BLACS_ABORT( ICTXT, 1 )
00318          RETURN
00319       ELSE IF( LQUERY ) THEN
00320          RETURN
00321       END IF
00322 *
00323 *     Quick return if possible
00324 *
00325       IF( M.EQ.0 .OR. N.EQ.0 .OR. K.EQ.0 )
00326      $   RETURN
00327 *
00328       IF( DESCA( M_ ).EQ.1 ) THEN
00329          CALL INFOG2L( IA, JA, DESCA, NPROW, NPCOL, MYROW, MYCOL, II,
00330      $                 JJ, IAROW, IACOL )
00331          CALL INFOG2L( IC, JC, DESCC, NPROW, NPCOL, MYROW, MYCOL, ICC,
00332      $                 JCC, ICROW, ICCOL )
00333          IF( LEFT ) THEN
00334             IF( MYROW.EQ.IAROW ) THEN
00335                NQ = NUMROC( JC+N-1, DESCC( NB_ ), MYCOL, DESCC( CSRC_ ),
00336      $                      NPCOL )
00337                IF( MYCOL.EQ.IACOL ) THEN
00338                   IF( NOTRAN ) THEN
00339                      AJJ = ONE - TAU( JJ )
00340                   ELSE
00341                      AJJ = ONE - DCONJG( TAU( JJ ) )
00342                   END IF
00343                   CALL ZGEBS2D( ICTXT, 'Rowwise', ' ', 1, 1, AJJ, 1 )
00344                   CALL ZSCAL( NQ-JCC+1, AJJ,
00345      $                        C( ICC+(JCC-1)*DESCC( LLD_ ) ),
00346      $                        DESCC( LLD_ ) )
00347                ELSE
00348                   CALL ZGEBR2D( ICTXT, 'Rowwise', ' ', 1, 1, AJJ, 1,
00349      $                          IAROW, IACOL )
00350                   CALL ZSCAL( NQ-JCC+1, AJJ,
00351      $                        C( ICC+(JCC-1)*DESCC( LLD_ ) ),
00352      $                        DESCC( LLD_ ) )
00353                END IF
00354             END IF
00355          ELSE
00356             IF( MYCOL.EQ.IACOL ) THEN
00357                IF( NOTRAN ) THEN
00358                   AJJ = ONE - TAU( JJ )
00359                ELSE
00360                   AJJ = ONE - DCONJG( TAU( JJ ) )
00361                END IF
00362             END IF
00363 *
00364             IF( IACOL.NE.ICCOL ) THEN
00365                IF( MYCOL.EQ.IACOL )
00366      $            CALL ZGESD2D( ICTXT, 1, 1, AJJ, 1, MYROW, ICCOL )
00367                IF( MYCOL.EQ.ICCOL )
00368      $            CALL ZGERV2D( ICTXT, 1, 1, AJJ, 1, MYROW, IACOL )
00369             END IF
00370 *
00371             IF( MYCOL.EQ.ICCOL ) THEN
00372                MP = NUMROC( IC+M-1, DESCC( MB_ ), MYROW, DESCC( RSRC_ ),
00373      $                      NPROW )
00374                CALL ZSCAL( MP-ICC+1, AJJ, C( ICC+(JCC-1)*
00375      $                     DESCC( LLD_ ) ), 1 )
00376             END IF
00377 *
00378          END IF
00379 *
00380       ELSE
00381 *
00382          CALL PB_TOPGET( ICTXT, 'Broadcast', 'Rowwise', ROWBTOP )
00383          CALL PB_TOPGET( ICTXT, 'Broadcast', 'Columnwise', COLBTOP )
00384 *
00385          IF( LEFT .AND. .NOT.NOTRAN .OR. .NOT.LEFT .AND. NOTRAN ) THEN
00386             J1 = JA
00387             J2 = JA+K-1
00388             J3 = 1
00389          ELSE
00390             J1 = JA+K-1
00391             J2 = JA
00392             J3 = -1
00393          END IF
00394 *
00395          IF( LEFT ) THEN
00396             NI  = N
00397             JCC = JC
00398             IF( NOTRAN ) THEN
00399                CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', 'D-ring' )
00400             ELSE
00401                CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', 'I-ring' )
00402             END IF
00403             CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', ' ' )
00404          ELSE
00405             MI  = M
00406             ICC = IC
00407          END IF
00408 *
00409          DO 10 J = J1, J2, J3
00410             IF( LEFT ) THEN
00411 *
00412 *              H(j) or H(j)' is applied to C(ic+j-ja:ic+m-1,jc:jc+n-1)
00413 *
00414                MI  = M - J + JA
00415                ICC = IC + J - JA
00416             ELSE
00417 *
00418 *              H(j) or H(j)' is applied to C(ic:ic+m-1,jc+j-ja:jc+n-1)
00419 *
00420                NI  = N - J + JA
00421                JCC = JC + J - JA
00422             END IF
00423 *
00424 *           Apply H(j) or H(j)'
00425 *
00426             CALL PZELSET2( AJJ, A, IA+J-JA, J, DESCA, ONE )
00427             IF( NOTRAN ) THEN
00428                CALL PZLARF( SIDE, MI, NI, A, IA+J-JA, J, DESCA, 1, TAU,
00429      $                      C, ICC, JCC, DESCC, WORK )
00430             ELSE
00431                CALL PZLARFC( SIDE, MI, NI, A, IA+J-JA, J, DESCA, 1, TAU,
00432      $                    C, ICC, JCC, DESCC, WORK )
00433             END IF
00434             CALL PZELSET( A, IA+J-JA, J, DESCA, AJJ )
00435 *
00436    10    CONTINUE
00437 *
00438          CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', ROWBTOP )
00439          CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', COLBTOP )
00440 *
00441       END IF
00442 *
00443       WORK( 1 ) = DCMPLX( DBLE( LWMIN ) )
00444 *
00445       RETURN
00446 *
00447 *     End of PZUNM2R
00448 *
00449       END