ScaLAPACK  2.0.2
ScaLAPACK: Scalable Linear Algebra PACKage
pdormqr.f
Go to the documentation of this file.
00001       SUBROUTINE PDORMQR( 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       DOUBLE PRECISION   A( * ), C( * ), TAU( * ), WORK( * )
00016 *     ..
00017 *
00018 *  Purpose
00019 *  =======
00020 *
00021 *  PDORMQR overwrites the general real 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 = 'T':      Q**T * sub( C )       sub( C ) * Q**T
00027 *
00028 *  where Q is a real orthogonal 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 PDGEQRF. 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**T from the Left;
00095 *          = 'R': apply Q or Q**T from the Right.
00096 *
00097 *  TRANS   (global input) CHARACTER
00098 *          = 'N':  No transpose, apply Q;
00099 *          = 'T':  Transpose, apply Q**T.
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) DOUBLE PRECISION 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 *          PDGEQRF 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) DOUBLE PRECISION 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 PDGEQRF.
00138 *          TAU is tied to the distributed matrix A.
00139 *
00140 *  C       (local input/local output) DOUBLE PRECISION 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) DOUBLE PRECISION 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',
00165 *            LWORK >= MAX( (NB_A*(NB_A-1))/2, (NqC0 + MpC0)*NB_A ) +
00166 *                     NB_A * NB_A
00167 *          else if SIDE = 'R',
00168 *            LWORK >= MAX( (NB_A*(NB_A-1))/2, ( NqC0 + MAX( NpA0 +
00169 *                     NUMROC( NUMROC( N+ICOFFC, NB_A, 0, 0, NPCOL ),
00170 *                             NB_A, 0, 0, LCMQ ), MpC0 ) )*NB_A ) +
00171 *                     NB_A * NB_A
00172 *          end if
00173 *
00174 *          where LCMQ = LCM / NPCOL with LCM = ICLM( NPROW, NPCOL ),
00175 *
00176 *          IROFFA = MOD( IA-1, MB_A ), ICOFFA = MOD( JA-1, NB_A ),
00177 *          IAROW = INDXG2P( IA, MB_A, MYROW, RSRC_A, NPROW ),
00178 *          NpA0 = NUMROC( N+IROFFA, MB_A, MYROW, IAROW, NPROW ),
00179 *
00180 *          IROFFC = MOD( IC-1, MB_C ), ICOFFC = MOD( JC-1, NB_C ),
00181 *          ICROW = INDXG2P( IC, MB_C, MYROW, RSRC_C, NPROW ),
00182 *          ICCOL = INDXG2P( JC, NB_C, MYCOL, CSRC_C, NPCOL ),
00183 *          MpC0 = NUMROC( M+IROFFC, MB_C, MYROW, ICROW, NPROW ),
00184 *          NqC0 = NUMROC( N+ICOFFC, NB_C, MYCOL, ICCOL, NPCOL ),
00185 *
00186 *          ILCM, INDXG2P and NUMROC are ScaLAPACK tool functions;
00187 *          MYROW, MYCOL, NPROW and NPCOL can be determined by calling
00188 *          the subroutine BLACS_GRIDINFO.
00189 *
00190 *          If LWORK = -1, then LWORK is global input and a workspace
00191 *          query is assumed; the routine only calculates the minimum
00192 *          and optimal size for all work arrays. Each of these
00193 *          values is returned in the first entry of the corresponding
00194 *          work array, and no error message is issued by PXERBLA.
00195 *
00196 *
00197 *  INFO    (global output) INTEGER
00198 *          = 0:  successful exit
00199 *          < 0:  If the i-th argument is an array and the j-entry had
00200 *                an illegal value, then INFO = -(i*100+j), if the i-th
00201 *                argument is a scalar and had an illegal value, then
00202 *                INFO = -i.
00203 *
00204 *  Alignment requirements
00205 *  ======================
00206 *
00207 *  The distributed submatrices A(IA:*, JA:*) and C(IC:IC+M-1,JC:JC+N-1)
00208 *  must verify some alignment properties, namely the following
00209 *  expressions should be true:
00210 *
00211 *  If SIDE = 'L',
00212 *    ( MB_A.EQ.MB_C .AND. IROFFA.EQ.IROFFC .AND. IAROW.EQ.ICROW )
00213 *  If SIDE = 'R',
00214 *    ( MB_A.EQ.NB_C .AND. IROFFA.EQ.ICOFFC )
00215 *
00216 *  =====================================================================
00217 *
00218 *     .. Parameters ..
00219       INTEGER            BLOCK_CYCLIC_2D, CSRC_, CTXT_, DLEN_, DTYPE_,
00220      $                   LLD_, MB_, M_, NB_, N_, RSRC_
00221       PARAMETER          ( BLOCK_CYCLIC_2D = 1, DLEN_ = 9, DTYPE_ = 1,
00222      $                     CTXT_ = 2, M_ = 3, N_ = 4, MB_ = 5, NB_ = 6,
00223      $                     RSRC_ = 7, CSRC_ = 8, LLD_ = 9 )
00224 *     ..
00225 *     .. Local Scalars ..
00226       LOGICAL            LEFT, LQUERY, NOTRAN
00227       CHARACTER          COLBTOP, ROWBTOP
00228       INTEGER            IAROW, ICC, ICCOL, ICOFFC, ICROW, ICTXT, IINFO,
00229      $                   IPW, IROFFA, IROFFC, J, J1, J2, J3, JB, JCC,
00230      $                   LCM, LCMQ, LWMIN, MI, MPC0, MYCOL, MYROW, NI,
00231      $                   NPA0, NPCOL, NPROW, NQ, NQC0
00232 *     ..
00233 *     .. Local Arrays ..
00234       INTEGER            IDUM1( 4 ), IDUM2( 4 )
00235 *     ..
00236 *     .. External Subroutines ..
00237       EXTERNAL           BLACS_GRIDINFO, CHK1MAT, PCHK2MAT, PDLARFB,
00238      $                   PDLARFT, PDORM2R, PB_TOPGET, PB_TOPSET, PXERBLA
00239 *     ..
00240 *     .. External Functions ..
00241       LOGICAL            LSAME
00242       INTEGER            ICEIL, ILCM, INDXG2P, NUMROC
00243       EXTERNAL           ICEIL, ILCM, INDXG2P, LSAME, NUMROC
00244 *     ..
00245 *     .. Intrinsic Functions ..
00246       INTRINSIC          DBLE, ICHAR, MAX, MIN, MOD
00247 *     ..
00248 *     .. Executable Statements ..
00249 *
00250 *     Get grid parameters
00251 *
00252       ICTXT = DESCA( CTXT_ )
00253       CALL BLACS_GRIDINFO( ICTXT, NPROW, NPCOL, MYROW, MYCOL )
00254 *
00255 *     Test the input parameters
00256 *
00257       INFO = 0
00258       IF( NPROW.EQ.-1 ) THEN
00259          INFO = -(900+CTXT_)
00260       ELSE
00261          LEFT = LSAME( SIDE, 'L' )
00262          NOTRAN = LSAME( TRANS, 'N' )
00263 *
00264 *        NQ is the order of Q
00265 *
00266          IF( LEFT ) THEN
00267             NQ = M
00268             CALL CHK1MAT( M, 3, K, 5, IA, JA, DESCA, 9, INFO )
00269          ELSE
00270             NQ = N
00271             CALL CHK1MAT( N, 4, K, 5, IA, JA, DESCA, 9, INFO )
00272          END IF
00273          CALL CHK1MAT( M, 3, N, 4, IC, JC, DESCC, 14, INFO )
00274          IF( INFO.EQ.0 ) THEN
00275             IROFFA = MOD( IA-1, DESCA( MB_ ) )
00276             IROFFC = MOD( IC-1, DESCC( MB_ ) )
00277             ICOFFC = MOD( JC-1, DESCC( NB_ ) )
00278             IAROW = INDXG2P( IA, DESCA( MB_ ), MYROW, DESCA( RSRC_ ),
00279      $                       NPROW )
00280             ICROW = INDXG2P( IC, DESCC( MB_ ), MYROW, DESCC( RSRC_ ),
00281      $                       NPROW )
00282             ICCOL = INDXG2P( JC, DESCC( NB_ ), MYCOL, DESCC( CSRC_ ),
00283      $                       NPCOL )
00284             MPC0 = NUMROC( M+IROFFC, DESCC( MB_ ), MYROW, ICROW, NPROW )
00285             NQC0 = NUMROC( N+ICOFFC, DESCC( NB_ ), MYCOL, ICCOL, NPCOL )
00286 *
00287             IF( LEFT ) THEN
00288                LWMIN = MAX( ( DESCA( NB_ ) * ( DESCA( NB_ ) - 1 ) ) / 2,
00289      $                      ( MPC0 + NQC0 ) * DESCA( NB_ ) ) +
00290      $                 DESCA( NB_ ) * DESCA( NB_ )
00291             ELSE
00292                NPA0 = NUMROC( N+IROFFA, DESCA( MB_ ), MYROW, IAROW,
00293      $                        NPROW )
00294                LCM = ILCM( NPROW, NPCOL )
00295                LCMQ = LCM / NPCOL
00296                LWMIN =  MAX( ( DESCA( NB_ ) * ( DESCA( NB_ ) - 1 ) )
00297      $                  / 2, ( NQC0 + MAX( NPA0 + NUMROC( NUMROC(
00298      $                  N+ICOFFC, DESCA( NB_ ), 0, 0, NPCOL ),
00299      $                  DESCA( NB_ ), 0, 0, LCMQ ), MPC0 ) ) *
00300      $                  DESCA( NB_ ) ) + DESCA( NB_ ) * DESCA( NB_ )
00301             END IF
00302 *
00303             WORK( 1 ) = DBLE( LWMIN )
00304             LQUERY = ( LWORK.EQ.-1 )
00305             IF( .NOT.LEFT .AND. .NOT.LSAME( SIDE, 'R' ) ) THEN
00306                INFO = -1
00307             ELSE IF( .NOT.NOTRAN .AND. .NOT.LSAME( TRANS, 'T' ) ) THEN
00308                INFO = -2
00309             ELSE IF( K.LT.0 .OR. K.GT.NQ ) THEN
00310                INFO = -5
00311             ELSE IF( .NOT.LEFT .AND. DESCA( MB_ ).NE.DESCC( NB_ ) ) THEN
00312                INFO = -(900+NB_)
00313             ELSE IF( LEFT .AND. IROFFA.NE.IROFFC ) THEN
00314                INFO = -12
00315             ELSE IF( LEFT .AND. IAROW.NE.ICROW ) THEN
00316                INFO = -12
00317             ELSE IF( .NOT.LEFT .AND. IROFFA.NE.ICOFFC ) THEN
00318                INFO = -13
00319             ELSE IF( LEFT .AND. DESCA( MB_ ).NE.DESCC( MB_ ) ) THEN
00320                INFO = -(1400+MB_)
00321             ELSE IF( ICTXT.NE.DESCC( CTXT_ ) ) THEN
00322                INFO = -(1400+CTXT_)
00323             ELSE IF( LWORK.LT.LWMIN .AND. .NOT.LQUERY ) THEN
00324                INFO = -16
00325             END IF
00326          END IF
00327 *
00328          IF( LEFT ) THEN
00329             IDUM1( 1 ) = ICHAR( 'L' )
00330          ELSE
00331             IDUM1( 1 ) = ICHAR( 'R' )
00332          END IF
00333          IDUM2( 1 ) = 1
00334          IF( NOTRAN ) THEN
00335             IDUM1( 2 ) = ICHAR( 'N' )
00336          ELSE
00337             IDUM1( 2 ) = ICHAR( 'T' )
00338          END IF
00339          IDUM2( 2 ) = 2
00340          IDUM1( 3 ) = K
00341          IDUM2( 3 ) = 5
00342          IF( LWORK.EQ.-1 ) THEN
00343             IDUM1( 4 ) = -1
00344          ELSE
00345             IDUM1( 4 ) = 1
00346          END IF
00347          IDUM2( 4 ) = 16
00348          IF( LEFT ) THEN
00349             CALL PCHK2MAT( M, 3, K, 5, IA, JA, DESCA, 9, M, 3, N, 4, IC,
00350      $                     JC, DESCC, 14, 4, IDUM1, IDUM2, INFO )
00351          ELSE
00352             CALL PCHK2MAT( N, 4, K, 5, IA, JA, DESCA, 9, M, 3, N, 4, IC,
00353      $                     JC, DESCC, 14, 4, IDUM1, IDUM2, INFO )
00354          END IF
00355       END IF
00356 *
00357       IF( INFO.NE.0 ) THEN
00358          CALL PXERBLA( ICTXT, 'PDORMQR', -INFO )
00359          RETURN
00360       ELSE IF( LQUERY ) THEN
00361          RETURN
00362       END IF
00363 *
00364 *     Quick return if possible
00365 *
00366       IF( M.EQ.0 .OR. N.EQ.0 .OR. K.EQ.0 )
00367      $   RETURN
00368 *
00369       CALL PB_TOPGET( ICTXT, 'Broadcast', 'Rowwise', ROWBTOP )
00370       CALL PB_TOPGET( ICTXT, 'Broadcast', 'Columnwise', COLBTOP )
00371 *
00372       IF( ( LEFT .AND. .NOT.NOTRAN ) .OR.
00373      $    ( .NOT.LEFT .AND. NOTRAN ) ) THEN
00374          J1 = MIN( ICEIL( JA, DESCA( NB_ ) ) * DESCA( NB_ ), JA+K-1 )
00375      $                    + 1
00376          J2 = JA+K-1
00377          J3 = DESCA( NB_ )
00378       ELSE
00379          J1 = MAX( ( (JA+K-2) / DESCA( NB_ ) ) * DESCA( NB_ ) + 1, JA )
00380          J2 = MIN( ICEIL( JA, DESCA( NB_ ) ) * DESCA( NB_ ), JA+K-1 )
00381      $                    + 1
00382          J3 = -DESCA( NB_ )
00383       END IF
00384 *
00385       IF( LEFT ) THEN
00386          NI  = N
00387          JCC = JC
00388          IF( NOTRAN ) THEN
00389             CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', 'D-ring' )
00390          ELSE
00391             CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', 'I-ring' )
00392          END IF
00393          CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', ' ' )
00394       ELSE
00395          MI  = M
00396          ICC = IC
00397       END IF
00398 *
00399 *     Use unblocked code for the first block if necessary
00400 *
00401       IF( ( LEFT .AND. .NOT.NOTRAN ) .OR. ( .NOT.LEFT .AND. NOTRAN ) )
00402      $   CALL PDORM2R( SIDE, TRANS, M, N, J1-JA, A, IA, JA, DESCA, TAU,
00403      $                 C, IC, JC, DESCC, WORK, LWORK, IINFO )
00404 *
00405       IPW = DESCA( NB_ ) * DESCA( NB_ ) + 1
00406       DO 10 J = J1, J2, J3
00407          JB = MIN( DESCA( NB_ ), K-J+JA )
00408 *
00409 *        Form the triangular factor of the block reflector
00410 *        H = H(j) H(j+1) . . . H(j+jb-1)
00411 *
00412          CALL PDLARFT( 'Forward', 'Columnwise', NQ-J+JA, JB, A,
00413      $                 IA+J-JA, J, DESCA, TAU, WORK, WORK( IPW ) )
00414          IF( LEFT ) THEN
00415 *
00416 *           H or H' is applied to C(ic+j-ja:ic+m-1,jc:jc+n-1)
00417 *
00418             MI  = M - J + JA
00419             ICC = IC + J - JA
00420          ELSE
00421 *
00422 *           H or H' is applied to C(ic:ic+m-1,jc+j-ja:jc+n-1)
00423 *
00424             NI  = N - J + JA
00425             JCC = JC + J - JA
00426          END IF
00427 *
00428 *        Apply H or H'
00429 *
00430          CALL PDLARFB( SIDE, TRANS, 'Forward', 'Columnwise', MI, NI,
00431      $                JB, A, IA+J-JA, J, DESCA, WORK, C, ICC, JCC,
00432      $                DESCC, WORK( IPW ) )
00433    10 CONTINUE
00434 *
00435 *     Use unblocked code for the last block if necessary
00436 *
00437       IF( ( LEFT .AND. NOTRAN ) .OR. ( .NOT.LEFT .AND. .NOT.NOTRAN ) )
00438      $   CALL PDORM2R( SIDE, TRANS, M, N, J2-JA, A, IA, JA, DESCA, TAU,
00439      $                 C, IC, JC, DESCC, WORK, LWORK, IINFO )
00440 *
00441       CALL PB_TOPSET( ICTXT, 'Broadcast', 'Rowwise', ROWBTOP )
00442       CALL PB_TOPSET( ICTXT, 'Broadcast', 'Columnwise', COLBTOP )
00443 *
00444       WORK( 1 ) = DBLE( LWMIN )
00445 *
00446       RETURN
00447 *
00448 *     End of PDORMQR
00449 *
00450       END