ScaLAPACK  2.0.2
ScaLAPACK: Scalable Linear Algebra PACKage
pcunmr3.f
Go to the documentation of this file.
00001       SUBROUTINE PCUNMR3( SIDE, TRANS, M, N, K, L, A, IA, JA, DESCA,
00002      $                    TAU, 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, L, LWORK, M, N
00012 *     ..
00013 *     .. Array Arguments ..
00014       INTEGER            DESCA( * ), DESCC( * )
00015       COMPLEX            A( * ), C( * ), TAU( * ), WORK( * )
00016 *     ..
00017 *
00018 *  Purpose
00019 *  =======
00020 *
00021 *  PCUNMR3 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 PCTZRZF. 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 *  L       (global input) INTEGER
00115 *          The columns of the distributed submatrix sub( A ) containing
00116 *          the meaningful part of the Householder reflectors.
00117 *          If SIDE = 'L', M >= L >= 0, if SIDE = 'R', N >= L >= 0.
00118 *
00119 *  A       (local input) COMPLEX pointer into the local memory
00120 *          to an array of dimension (LLD_A,LOCc(JA+M-1)) if SIDE='L',
00121 *          and (LLD_A,LOCc(JA+N-1)) if SIDE='R', where
00122 *          LLD_A >= MAX(1,LOCr(IA+K-1)); On entry, the i-th row must
00123 *          contain the vector which defines the elementary reflector
00124 *          H(i), IA <= i <= IA+K-1, as returned by PCTZRZF in the
00125 *          K rows of its distributed matrix argument A(IA:IA+K-1,JA:*).
00126 *          A(IA:IA+K-1,JA:*) is modified by the routine but restored on
00127 *          exit.
00128 *
00129 *  IA      (global input) INTEGER
00130 *          The row index in the global array A indicating the first
00131 *          row of sub( A ).
00132 *
00133 *  JA      (global input) INTEGER
00134 *          The column index in the global array A indicating the
00135 *          first column of sub( A ).
00136 *
00137 *  DESCA   (global and local input) INTEGER array of dimension DLEN_.
00138 *          The array descriptor for the distributed matrix A.
00139 *
00140 *  TAU     (local input) COMPLEX, array, dimension LOCc(IA+K-1).
00141 *          This array contains the scalar factors TAU(i) of the
00142 *          elementary reflectors H(i) as returned by PCTZRZF.
00143 *          TAU is tied to the distributed matrix A.
00144 *
00145 *  C       (local input/local output) COMPLEX pointer into the
00146 *          local memory to an array of dimension (LLD_C,LOCc(JC+N-1)).
00147 *          On entry, the local pieces of the distributed matrix sub(C).
00148 *          On exit, sub( C ) is overwritten by Q*sub( C ) or Q'*sub( C )
00149 *          or sub( C )*Q' or sub( C )*Q.
00150 *
00151 *  IC      (global input) INTEGER
00152 *          The row index in the global array C indicating the first
00153 *          row of sub( C ).
00154 *
00155 *  JC      (global input) INTEGER
00156 *          The column index in the global array C indicating the
00157 *          first column of sub( C ).
00158 *
00159 *  DESCC   (global and local input) INTEGER array of dimension DLEN_.
00160 *          The array descriptor for the distributed matrix C.
00161 *
00162 *  WORK    (local workspace/local output) COMPLEX array,
00163 *                                                   dimension (LWORK)
00164 *          On exit, WORK(1) returns the minimal and optimal LWORK.
00165 *
00166 *  LWORK   (local or global input) INTEGER
00167 *          The dimension of the array WORK.
00168 *          LWORK is local input and must be at least
00169 *          If SIDE = 'L', LWORK >= MpC0 + MAX( MAX( 1, NqC0 ), NUMROC(
00170 *                  NUMROC( M+IROFFC,MB_A,0,0,NPROW ),MB_A,0,0,LCMP ) );
00171 *          if SIDE = 'R', LWORK >= NqC0 + MAX( 1, MpC0 );
00172 *
00173 *          where LCMP = LCM / NPROW with LCM = ICLM( NPROW, NPCOL ),
00174 *
00175 *          IROFFC = MOD( IC-1, MB_C ), ICOFFC = MOD( JC-1, NB_C ),
00176 *          ICROW = INDXG2P( IC, MB_C, MYROW, RSRC_C, NPROW ),
00177 *          ICCOL = INDXG2P( JC, NB_C, MYCOL, CSRC_C, NPCOL ),
00178 *          MpC0 = NUMROC( M+IROFFC, MB_C, MYROW, ICROW, NPROW ),
00179 *          NqC0 = NUMROC( N+ICOFFC, NB_C, MYCOL, ICCOL, NPCOL ),
00180 *
00181 *          ILCM, INDXG2P and NUMROC are ScaLAPACK tool functions;
00182 *          MYROW, MYCOL, NPROW and NPCOL can be determined by calling
00183 *          the subroutine BLACS_GRIDINFO.
00184 *
00185 *          If LWORK = -1, then LWORK is global input and a workspace
00186 *          query is assumed; the routine only calculates the minimum
00187 *          and optimal size for all work arrays. Each of these
00188 *          values is returned in the first entry of the corresponding
00189 *          work array, and no error message is issued by PXERBLA.
00190 *
00191 *
00192 *  INFO    (local output) INTEGER
00193 *          = 0:  successful exit
00194 *          < 0:  If the i-th argument is an array and the j-entry had
00195 *                an illegal value, then INFO = -(i*100+j), if the i-th
00196 *                argument is a scalar and had an illegal value, then
00197 *                INFO = -i.
00198 *
00199 *  Alignment requirements
00200 *  ======================
00201 *
00202 *  The distributed submatrices A(IA:*, JA:*) and C(IC:IC+M-1,JC:JC+N-1)
00203 *  must verify some alignment properties, namely the following
00204 *  expressions should be true:
00205 *
00206 *  If SIDE = 'L',
00207 *    ( NB_A.EQ.MB_C .AND. ICOFFA.EQ.IROFFC )
00208 *  If SIDE = 'R',
00209 *    ( NB_A.EQ.NB_C .AND. ICOFFA.EQ.ICOFFC .AND. IACOL.EQ.ICCOL )
00210 *
00211 *  =====================================================================
00212 *
00213 *     .. Parameters ..
00214       INTEGER            BLOCK_CYCLIC_2D, CSRC_, CTXT_, DLEN_, DTYPE_,
00215      $                   LLD_, MB_, M_, NB_, N_, RSRC_
00216       PARAMETER          ( BLOCK_CYCLIC_2D = 1, DLEN_ = 9, DTYPE_ = 1,
00217      $                     CTXT_ = 2, M_ = 3, N_ = 4, MB_ = 5, NB_ = 6,
00218      $                     RSRC_ = 7, CSRC_ = 8, LLD_ = 9 )
00219 *     ..
00220 *     .. Local Scalars ..
00221       LOGICAL            LEFT, LQUERY, NOTRAN
00222       CHARACTER          COLBTOP, ROWBTOP
00223       INTEGER            I, I1, I2, I3, IACOL, ICC, ICCOL, ICOFFA,
00224      $                   ICOFFC, ICROW, ICTXT, IROFFC, JAA, JCC, LCM,
00225      $                   LCMP, LWMIN, MI, MPC0, MYCOL, MYROW, NI, NPCOL,
00226      $                   NPROW, NQ, NQC0
00227 *     ..
00228 *     .. External Subroutines ..
00229       EXTERNAL           BLACS_ABORT, BLACS_GRIDINFO, CHK1MAT, PCLARZ,
00230      $                   PCLARZC, PB_TOPGET, PB_TOPSET, PXERBLA
00231 *     ..
00232 *     .. External Functions ..
00233       LOGICAL            LSAME
00234       INTEGER            ILCM, INDXG2P, NUMROC
00235       EXTERNAL           ILCM, INDXG2P, LSAME, NUMROC
00236 *     ..
00237 *     .. Intrinsic Functions ..
00238       INTRINSIC          CMPLX, MAX, MOD, REAL
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( K, 5, M, 3, IA, JA, DESCA, 10, INFO )
00261          ELSE
00262             NQ = N
00263             CALL CHK1MAT( K, 5, N, 4, IA, JA, DESCA, 10, INFO )
00264          END IF
00265          CALL CHK1MAT( M, 3, N, 4, IC, JC, DESCC, 15, INFO )
00266          IF( INFO.EQ.0 ) THEN
00267             ICOFFA = MOD( JA-1, DESCA( NB_ ) )
00268             IROFFC = MOD( IC-1, DESCC( MB_ ) )
00269             ICOFFC = MOD( JC-1, DESCC( NB_ ) )
00270             IACOL = INDXG2P( JA, DESCA( NB_ ), MYCOL, DESCA( CSRC_ ),
00271      $                       NPCOL )
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                LCM = ILCM( NPROW, NPCOL )
00281                LCMP = LCM / NPROW
00282                LWMIN = MPC0 + MAX( MAX( 1, NQC0 ), NUMROC( NUMROC(
00283      $                 M+IROFFC, DESCA( MB_ ), 0, 0, NPROW ),
00284      $                 DESCA( MB_ ), 0, 0, LCMP ) )
00285             ELSE
00286                LWMIN = NQC0 + MAX( 1, MPC0 )
00287             END IF
00288 *
00289             WORK( 1 ) = CMPLX( REAL( 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( L.LT.0 .OR. L.GT.NQ ) THEN
00298                INFO = -6
00299             ELSE IF( LEFT .AND. DESCA( NB_ ).NE.DESCC( MB_ ) ) THEN
00300                INFO = -(1000+NB_)
00301             ELSE IF( LEFT .AND. ICOFFA.NE.IROFFC ) THEN
00302                INFO = -13
00303             ELSE IF( .NOT.LEFT .AND. ICOFFA.NE.ICOFFC ) THEN
00304                INFO = -14
00305             ELSE IF( .NOT.LEFT .AND. IACOL.NE.ICCOL ) THEN
00306                INFO = -14
00307             ELSE IF( .NOT.LEFT .AND. DESCA( NB_ ).NE.DESCC( NB_ ) ) THEN
00308                INFO = -(1500+NB_)
00309             ELSE IF( ICTXT.NE.DESCC( CTXT_ ) ) THEN
00310                INFO = -(1500+CTXT_)
00311             ELSE IF( LWORK.LT.LWMIN .AND. .NOT.LQUERY ) THEN
00312                INFO = -17
00313             END IF
00314          END IF
00315       END IF
00316 *
00317       IF( INFO.NE.0 ) THEN
00318          CALL PXERBLA( ICTXT, 'PCUNMR3', -INFO )
00319          CALL BLACS_ABORT( ICTXT, 1 )
00320          RETURN
00321       ELSE IF( LQUERY ) THEN
00322          RETURN
00323       END IF
00324 *
00325 *     Quick return if possible
00326 *
00327       IF( M.EQ.0 .OR. N.EQ.0 .OR. K.EQ.0 )
00328      $   RETURN
00329 *
00330       CALL PB_TOPGET( ICTXT, 'Broadcast', 'Rowwise', ROWBTOP )
00331       CALL PB_TOPGET( ICTXT, 'Broadcast', 'Columnwise', COLBTOP )
00332 *
00333       IF( ( LEFT .AND. .NOT.NOTRAN .OR. .NOT.LEFT .AND. NOTRAN ) ) THEN
00334          I1 = IA
00335          I2 = IA + K - 1
00336          I3 = 1
00337       ELSE
00338          I1 = IA + K - 1
00339          I2 = IA
00340          I3 = -1
00341       END IF
00342 *
00343       IF( LEFT ) THEN
00344          NI = N
00345          JCC = JC
00346          JAA = JA + M - L
00347       ELSE
00348          MI = M
00349          ICC = IC
00350          JAA = JA + N - L
00351          CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', ' ' )
00352          IF( NOTRAN ) THEN
00353             CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', 'I-ring' )
00354          ELSE
00355             CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', 'D-ring' )
00356          END IF
00357       END IF
00358 *
00359       DO 10 I = I1, I2, I3
00360          IF( LEFT ) THEN
00361 *
00362 *           H(i) or H(i)' is applied to C(ic+i-ia:icc+m-1,jc:jc+n-1)
00363 *
00364             MI = M - I + IA
00365             ICC = IC + I - IA
00366          ELSE
00367 *
00368 *           H(i) or H(i)' is applied to C(ic:ic+m-1,jc+i-ia:jc+n-1)
00369 *
00370             NI = N - I + IA
00371             JCC = JC + I - IA
00372          END IF
00373 *
00374 *        Apply H(i) or H(i)'
00375 *
00376          IF( NOTRAN ) THEN
00377             CALL PCLARZ( SIDE, MI, NI, L, A, I, JAA, DESCA, DESCA( M_ ),
00378      $                   TAU, C, ICC, JCC, DESCC, WORK )
00379          ELSE
00380             CALL PCLARZC( SIDE, MI, NI, L, A, I, JAA, DESCA,
00381      $                    DESCA( M_ ), TAU, C, ICC, JCC, DESCC, WORK )
00382          END IF
00383 *
00384    10 CONTINUE
00385 *
00386       CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', ROWBTOP )
00387       CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', COLBTOP )
00388 *
00389       WORK( 1 ) = CMPLX( REAL( LWMIN ) )
00390 *
00391       RETURN
00392 *
00393 *     End of PCUNMR3
00394 *
00395       END