001        SUBROUTINE PZLARZ( SIDE , M , N , L , V , IV , JV , DESCV , INCV , TAU , C ,
002       $IC , JC , DESCC , WORK )
003  
004  *     -- ScaLAPACK auxiliary routine(version 1.7) --
005  *     University of Tennessee , Knoxville , Oak Ridge National Laboratory ,
006  *     and University of California , Berkeley.
007  *     May 25 , 2001
008  
009  *     .. Scalar Arguments ..
010        CHARACTER SIDE
011        INTEGER IC , INCV , IV , JC , JV , L , M , N
012  *     ..
013  *     .. Array Arguments ..
014        INTEGER DESCC( * ) , DESCV( * )
015        COMPLEX*16 C( * ) , TAU( * ) , V( * ) , WORK( * )
016  *     ..
017  
018  *     Purpose
019  *     === ====
020  
021  *     PZLARZ applies a complex elementary reflector Q to a complex M - by - N
022  *     distributed matrix sub( C ) = C(IC : IC + M - 1 , JC : JC + N - 1) , from either the
023  *     left or the right. Q is represented in the form
024  
025  *     Q = I - tau * v * v'
026  
027  *     where tau is a complex scalar and v is a complex vector.
028  
029  *     If tau = 0 , then Q is taken to be the unit matrix.
030  
031  *     Q is a product of k elementary reflectors as returned by PZTZRZF.
032  
033  *     Notes
034  *     === ==
035  
036  *     Each global data object is described by an associated description
037  *     vector. This vector stores the information required to establish
038  *     the mapping between an object element and its corresponding process
039  *     and memory location.
040  
041  *     Let A be a generic term for any 2D block cyclicly distributed array.
042  *     Such a global array has an associated description vector DESCA.
043  *     In the following comments , the character _ should be read as
044  *     "of the global array".
045  
046  *     NOTATION STORED IN EXPLANATION
047  *     --- ------------ -------------- --------------------------------------
048  *     DTYPE_A(global) DESCA( DTYPE_ )The descriptor type. In this case ,
049  *     DTYPE_A = 1.
050  *     CTXT_A(global) DESCA( CTXT_ ) The BLACS context handle , indicating
051  *     the BLACS process grid A is distribu -
052  *     ted over. The context itself is glo -
053  *     bal , but the handle(the integer
054  *     value) may vary.
055  *     M_A(global) DESCA( M_ ) The number of rows in the global
056  *     array A.
057  *     N_A(global) DESCA( N_ ) The number of columns in the global
058  *     array A.
059  *     MB_A(global) DESCA( MB_ ) The blocking factor used to distribute
060  *     the rows of the array.
061  *     NB_A(global) DESCA( NB_ ) The blocking factor used to distribute
062  *     the columns of the array.
063  *     RSRC_A(global) DESCA( RSRC_ ) The process row over which the first
064  *     row of the array A is distributed.
065  *     CSRC_A(global) DESCA( CSRC_ ) The process column over which the
066  *     first column of the array A is
067  *     distributed.
068  *     LLD_A(local) DESCA( LLD_ ) The leading dimension of the local
069  *     array. LLD_A >= MAX(1 , LOCr(M_A)).
070  
071  *     Let K be the number of rows or columns of a distributed matrix ,
072  *     and assume that its process grid has dimension p x q.
073  *     LOCr( K ) denotes the number of elements of K that a process
074  *     would receive if K were distributed over the p processes of its
075  *     process column.
076  *     Similarly , LOCc( K ) denotes the number of elements of K that a
077  *     process would receive if K were distributed over the q processes of
078  *     its process row.
079  *     The values of LOCr() and LOCc() may be determined via a call to the
080  *     ScaLAPACK tool function , NUMROC :
081  *     LOCr( M ) = NUMROC( M , MB_A , MYROW , RSRC_A , NPROW ) ,
082  *     LOCc( N ) = NUMROC( N , NB_A , MYCOL , CSRC_A , NPCOL ).
083  *     An upper bound for these quantities may be computed by :
084  *     LOCr( M ) <= ceil( ceil(M / MB_A) / NPROW )*MB_A
085  *     LOCc( N ) <= ceil( ceil(N / NB_A) / NPCOL )*NB_A
086  
087  *     Because vectors may be viewed as a subclass of matrices , a
088  *     distributed vector is considered to be a distributed matrix.
089  
090  *     Restrictions
091  *     === =========
092  
093  *     If SIDE = 'Left' and INCV = 1 , then the row process having the first
094  *     entry V(IV , JV) must also own C(IC + M - L , JC : JC + N - 1). Moreover ,
095  *     MOD(IV - 1 , MB_V) must be equal to MOD(IC + N - L - 1 , MB_C) , if INCV = M_V , only
096  *     the last equality must be satisfied.
097  
098  *     If SIDE = 'Right' and INCV = M_V then the column process having the
099  *     first entry V(IV , JV) must also own C(IC : IC + M - 1 , JC + N - L) and
100  *     MOD(JV - 1 , NB_V) must be equal to MOD(JC + N - L - 1 , NB_C) , if INCV = 1 only
101  *     the last equality must be satisfied.
102  
103  *     Arguments
104  *     === ======
105  
106  *     SIDE(global input) CHARACTER
107  *     = 'L' : form Q * sub( C ) ,
108  *     = 'R' : form sub( C ) * Q.
109  
110  *     M(global input) INTEGER
111  *     The number of rows to be operated on i.e the number of rows
112  *     of the distributed submatrix sub( C ). M >= 0.
113  
114  *     N(global input) INTEGER
115  *     The number of columns to be operated on i.e the number of
116  *     columns of the distributed submatrix sub( C ). N >= 0.
117  
118  *     L(global input) INTEGER
119  *     The columns of the distributed submatrix sub( A ) containing
120  *     the meaningful part of the Householder reflectors.
121  *     If SIDE = 'L' , M >= L >= 0 , if SIDE = 'R' , N >= L >= 0.
122  
123  *     V(local input) COMPLEX*16 pointer into the local memory
124  *     to an array of dimension(LLD_V ,*) containing the local
125  *     pieces of the distributed vectors V representing the
126  *     Householder transformation Q ,
127  *     V(IV : IV + L - 1 , JV) if SIDE = 'L' and INCV = 1 ,
128  *     V(IV , JV : JV + L - 1) if SIDE = 'L' and INCV = M_V ,
129  *     V(IV : IV + L - 1 , JV) if SIDE = 'R' and INCV = 1 ,
130  *     V(IV , JV : JV + L - 1) if SIDE = 'R' and INCV = M_V ,
131  
132  *     The vector v in the representation of Q. V is not used if
133  *     TAU = 0.
134  
135  *     IV(global input) INTEGER
136  *     The row index in the global array V indicating the first
137  *     row of sub( V ).
138  
139  *     JV(global input) INTEGER
140  *     The column index in the global array V indicating the
141  *     first column of sub( V ).
142  
143  *     DESCV(global and local input) INTEGER array of dimension DLEN_.
144  *     The array descriptor for the distributed matrix V.
145  
146  *     INCV(global input) INTEGER
147  *     The global increment for the elements of V. Only two values
148  *     of INCV are supported in this version , namely 1 and M_V.
149  *     INCV must not be zero.
150  
151  *     TAU(local input) COMPLEX*16 , array , dimension LOCc(JV) if
152  *     INCV = 1 , and LOCr(IV) otherwise. This array contains the
153  *     Householder scalars related to the Householder vectors.
154  *     TAU is tied to the distributed matrix V.
155  
156  *     C(local input / local output) COMPLEX*16 pointer into the
157  *     local memory to an array of dimension(LLD_C , LOCc(JC + N - 1) ) ,
158  *     containing the local pieces of sub( C ). On exit , sub( C )
159  *     is overwritten by the Q * sub( C ) if SIDE = 'L' , or
160  *     sub( C ) * Q if SIDE = 'R'.
161  
162  *     IC(global input) INTEGER
163  *     The row index in the global array C indicating the first
164  *     row of sub( C ).
165  
166  *     JC(global input) INTEGER
167  *     The column index in the global array C indicating the
168  *     first column of sub( C ).
169  
170  *     DESCC(global and local input) INTEGER array of dimension DLEN_.
171  *     The array descriptor for the distributed matrix C.
172  
173  *     WORK(local workspace) COMPLEX*16 array , dimension(LWORK)
174  *     If INCV = 1 ,
175  *     if SIDE = 'L' ,
176  *     if IVCOL = ICCOL ,
177  *     LWORK >= NqC0
178  *     else
179  *     LWORK >= MpC0 + MAX( 1 , NqC0 )
180  *     end if
181  *     else if SIDE = 'R' ,
182  *     LWORK >= NqC0 + MAX( MAX( 1 , MpC0 ) , NUMROC( NUMROC(
183  *     N + ICOFFC , NB_V , 0 , 0 , NPCOL ) , NB_V , 0 , 0 , LCMQ ) )
184  *     end if
185  *     else if INCV = M_V ,
186  *     if SIDE = 'L' ,
187  *     LWORK >= MpC0 + MAX( MAX( 1 , NqC0 ) , NUMROC( NUMROC(
188  *     M + IROFFC , MB_V , 0 , 0 , NPROW ) , MB_V , 0 , 0 , LCMP ) )
189  *     else if SIDE = 'R' ,
190  *     if IVROW = ICROW ,
191  *     LWORK >= MpC0
192  *     else
193  *     LWORK >= NqC0 + MAX( 1 , MpC0 )
194  *     end if
195  *     end if
196  *     end if
197  
198  *     where LCM is the least common multiple of NPROW and NPCOL and
199  *     LCM = ILCM( NPROW , NPCOL ) , LCMP = LCM / NPROW ,
200  *     LCMQ = LCM / NPCOL ,
201  
202  *     IROFFC = MOD( IC - 1 , MB_C ) , ICOFFC = MOD( JC - 1 , NB_C ) ,
203  *     ICROW = INDXG2P( IC , MB_C , MYROW , RSRC_C , NPROW ) ,
204  *     ICCOL = INDXG2P( JC , NB_C , MYCOL , CSRC_C , NPCOL ) ,
205  *     MpC0 = NUMROC( M + IROFFC , MB_C , MYROW , ICROW , NPROW ) ,
206  *     NqC0 = NUMROC( N + ICOFFC , NB_C , MYCOL , ICCOL , NPCOL ) ,
207  
208  *     ILCM , INDXG2P and NUMROC are ScaLAPACK tool functions ;
209  *     MYROW , MYCOL , NPROW and NPCOL can be determined by calling
210  *     the subroutine BLACS_GRIDINFO.
211  
212  *     Alignment requirements
213  *     === ===================
214  
215  *     The distributed submatrices V(IV : * , JV :*) and C(IC : IC + M - 1 , JC : JC + N - 1)
216  *     must verify some alignment properties , namely the following
217  *     expressions should be true :
218  
219  *     MB_V = NB_V ,
220  
221  *     If INCV = 1 ,
222  *     If SIDE = 'Left' ,
223  *     ( MB_V.EQ.MB_C .AND. IROFFV.EQ.IROFFC .AND. IVROW.EQ.ICROW )
224  *     If SIDE = 'Right' ,
225  *     ( MB_V.EQ.NB_A .AND. MB_V.EQ.NB_C .AND. IROFFV.EQ.ICOFFC )
226  *     else if INCV = M_V ,
227  *     If SIDE = 'Left' ,
228  *     ( MB_V.EQ.NB_V .AND. MB_V.EQ.MB_C .AND. ICOFFV.EQ.IROFFC )
229  *     If SIDE = 'Right' ,
230  *     ( NB_V.EQ.NB_C .AND. ICOFFV.EQ.ICOFFC .AND. IVCOL.EQ.ICCOL )
231  *     end if
232  
233  *     === ==================================================================
234  
235  *     .. Parameters ..
236        INTEGER BLOCK_CYCLIC_2D , CSRC_ , CTXT_ , DLEN_ , DTYPE_ ,
237       $LLD_ , MB_ , M_ , NB_ , N_ , RSRC_
238        PARAMETER( BLOCK_CYCLIC_2D = 1 , DLEN_ = 9 , DTYPE_ = 1 ,
239       $CTXT_ = 2 , M_ = 3 , N_ = 4 , MB_ = 5 , NB_ = 6 ,
240       $RSRC_ = 7 , CSRC_ = 8 , LLD_ = 9 )
241        COMPLEX*16 ONE , ZERO
242        PARAMETER( ONE =( 1.0D + 0 , 0.0D + 0 ) ,
243       $ZERO =( 0.0D + 0 , 0.0D + 0 ) )
244        CALL ZGERC( MPC2 , NQV , - TAULOC , WORK( IPW ) , 1 , WORK ,
245       $1 , C( IOFFC2 ) , LDC )
246        END IF
247  
248        END IF
249  
250        END IF
251  
252        END IF
253  
254        RETURN
255  
256  *     End of PZLARZ
257  
258        END18749