pdormql(3)

NAME

PDORMQL - overwrite the general real M-by-N distributed

matrix sub( C )
= C(IC:IC+M-1,JC:JC+N-1) with SIDE = 'L' SIDE = 'R'

TRANS = 'N'

SYNOPSIS

SUBROUTINE PDORMQL( SIDE, TRANS,  M,  N,  K,  A,  IA,  JA,
DESCA, TAU, C, IC,
                    JC, DESCC, WORK, LWORK, INFO )
    CHARACTER       SIDE, TRANS
    INTEGER         IA, IC, INFO, JA, JC, K, LWORK, M, N
    INTEGER         DESCA( * ), DESCC( * )
    DOUBLE           PRECISION  A(  * ), C( * ), TAU( * ),
WORK( * )

PURPOSE

PDORMQL overwrites the general real M-by-N distributed

matrix sub( C )
= C(IC:IC+M-1,JC:JC+N-1) with TRANS = 'T': Q**T

* sub( C )
sub( C ) * Q**T

where Q is a real orthogonal distributed matrix defined

as the product
of K elementary reflectors

Q = H(k) . . . H(2) H(1)

as returned by PDGEQLF. Q is of order M if SIDE = 'L' and

of order N if
SIDE = 'R'.

Notes
=====

Each global data object is described by an associated de

scription vector. This vector stores the information required to es

tablish the mapping between an object element and its corresponding pro

cess and memory
location.

Let A be a generic term for any 2D block cyclicly dis

tributed 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

distributed over. The context it

self is global, 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 distribut

ed matrix, and
assume that its process grid has dimension p x q.
LOCr( K ) denotes the number of elements of K that a

process would
receive if K were distributed over the p 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 q 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

= 'L': apply Q or Q**T from the Left;
= 'R': apply Q or Q**T from the Right.

TRANS (global input) CHARACTER

= 'N': No transpose, apply Q;
= 'T': Transpose, apply Q**T.

M (global input) INTEGER

The number of rows to be operated on i.e the num

ber of rows of
the distributed submatrix sub( C ). M >= 0.

N (global input) INTEGER

The number of columns to be operated on i.e

the number of
columns of the distributed submatrix sub( C ). N

>= 0.

K (global input) INTEGER

The number of elementary reflectors whose product

defines the
matrix Q. If SIDE = 'L', M >= K >= 0, if SIDE =

'R', N >= K >=
0.

A (local input) DOUBLE PRECISION pointer into the

local memory

to an array of dimension (LLD_A,LOCc(JA+K-1)). On

entry, the jth column must contain the vector which de

fines the elementary reflector H(j), JA <= j <= JA+K-1, as re

turned by PDGEQLF
in the K columns of its distributed ma

trix argument
A(IA:*,JA:JA+K-1). A(IA:*,JA:JA+K-1) is modified

by the routine
but restored on exit. If SIDE = 'L',

LLD_A >= MAX( 1,
LOCr(IA+M-1) ), if SIDE = 'R', LLD_A >= MAX( 1,

LOCr(IA+N-1) ).

IA (global input) INTEGER

The row index in the global array A indicating the

first row of
sub( A ).

JA (global input) INTEGER

The column index in the global array A indicat

ing the first
column of sub( A ).

DESCA (global and local input) INTEGER array of dimen

sion DLEN_.

The array descriptor for the distributed matrix A.

TAU (local input) DOUBLE PRECISION, array, dimension

LOCc(JA+N-1)

This array contains the scalar factors TAU(j) of

the elementary
reflectors H(j) as returned by PDGEQLF. TAU is

tied to the
distributed matrix A.

C (local input/local output) DOUBLE PRECISION point

er into the

local memory to an array of dimension

(LLD_C,LOCc(JC+N-1)). On
entry, the local pieces of the distributed matrix

sub(C). On
exit, sub( C ) is overwritten by Q*sub( C ) or

Q'*sub( C ) or
sub( C )*Q' or sub( C )*Q.

IC (global input) INTEGER

The row index in the global array C indicating the

first row of
sub( C ).

JC (global input) INTEGER

The column index in the global array C indi

cating the first
column of sub( C ).

DESCC (global and local input) INTEGER array of dimen

sion DLEN_.

The array descriptor for the distributed matrix C.

WORK (local workspace/local output) DOUBLE PRECISION

array,

dimension (LWORK) On exit, WORK(1) returns the

minimal and
optimal LWORK.

LWORK (local or global input) INTEGER

The dimension of the array WORK. LWORK is local

input and must
be at least If SIDE = 'L', LWORK >= MAX(

(NB_A*(NB_A-1))/2,
(NqC0 + MpC0)*NB_A ) + NB_A * NB_A else if SIDE =

'R', LWORK >=
MAX( (NB_A*(NB_A-1))/2, ( NqC0 + MAX( NpA0 +

NUMROC( NUMROC(
N+ICOFFC, NB_A, 0, 0, NPCOL ), NB_A, 0, 0,

LCMQ ), MpC0 )
)*NB_A ) + NB_A * NB_A end if

where LCMQ = LCM / NPCOL with LCM = ICLM( NPROW,

NPCOL ),

IROFFA = MOD( IA-1, MB_A ), ICOFFA = MOD( JA-1,

NB_A ), IAROW =
INDXG2P( IA, MB_A, MYROW, RSRC_A, NPROW ),

NpA0 = NUMROC(
N+IROFFA, MB_A, MYROW, IAROW, NPROW ),

IROFFC = MOD( IC-1, MB_C ), ICOFFC = MOD( JC-1,

NB_C ), ICROW =
INDXG2P( IC, MB_C, MYROW, RSRC_C, NPROW ), ICCOL =

INDXG2P( JC,
NB_C, MYCOL, CSRC_C, NPCOL ), MpC0 = NUMROC(

M+IROFFC, MB_C,
MYROW, ICROW, NPROW ), NqC0 = NUMROC( N+ICOFFC,

NB_C, MYCOL,
ICCOL, NPCOL ),

ILCM, INDXG2P and NUMROC are ScaLAPACK tool func

tions; MYROW,
MYCOL, NPROW and NPCOL can be determined by call

ing the subroutine BLACS_GRIDINFO.

If LWORK = -1, then LWORK is global input and a

workspace query
is assumed; the routine only calculates the mini

mum and optimal
size for all work arrays. Each of these values is

returned in
the first entry of the corresponding work array,

and no error
message is issued by PXERBLA.

INFO (global output) INTEGER

= 0: successful exit
< 0: If the i-th argument is an array and the j

entry had an
illegal value, then INFO = -(i*100+j), if the i

th argument is
a scalar and had an illegal value, then INFO = -i.

Alignment requirements ======================

The distributed submatrices A(IA:*,

JA:*) and
C(IC:IC+M-1,JC:JC+N-1) must verify some align

ment properties,
namely the following expressions should be true:

If SIDE = 'L', ( MB_A.EQ.MB_C .AND. IROF

FA.EQ.IROFFC .AND.
IAROW.EQ.ICROW ) If SIDE = 'R', (

MB_A.EQ.NB_C .AND.
IROFFA.EQ.ICOFFC )

LAPACK version 1.5 12 May 1997

PDORMQL(l)