# FreeBSD Manual Pages

```PSGGQRF(l)			       )			    PSGGQRF(l)

NAME
PSGGQRF	-  compute  a generalized QR factorization of an N-by-M	matrix
sub( A )	= A(IA:IA+N-1,JA:JA+M-1) and an	 N-by-P	 matrix	 sub(  B  )  =
B(IB:IB+N-1,JB:JB+P-1)

SYNOPSIS
SUBROUTINE PSGGQRF( N,  M, P, A,	IA, JA,	DESCA, TAUA, B,	IB, JB,	DESCB,
TAUB, WORK, LWORK, INFO )

INTEGER	   IA, IB, INFO, JA, JB, LWORK,	M, N, P

INTEGER	   DESCA( * ), DESCB( *	)

REAL		   A( *	), B( *	), TAUA( * ), TAUB( * ), WORK( * )

PURPOSE
PSGGQRF computes	a generalized QR factorization	of  an	N-by-M	matrix
sub(  A	)  =  A(IA:IA+N-1,JA:JA+M-1)  and  an N-by-P matrix sub( B ) =
B(IB:IB+N-1,JB:JB+P-1):
sub(	A ) = Q*R,	  sub( B ) = Q*T*Z,

where Q is an N-by-N orthogonal matrix, Z is a  P-by-P  orthogonal  ma-
trix, and R and T assume	one of the forms:

if N >= M,  R = ( R11 ) M  ,   or if N <	M,  R =	( R11  R12 ) N,
(  0  ) N-M			   N   M-N
M

where R11 is upper triangular, and

if N <= P,  T = ( 0  T12	) N,   or if N > P,  T = ( T11 ) N-P,
P-N  N				 ( T21 ) P
P

where T12 or T21	is upper triangular.

In  particular,	if sub(	B ) is square and nonsingular, the GQR factor-
ization of sub( A ) and sub( B )	implicitly gives the QR	 factorization
of inv( sub( B )	)* sub(	A ):

inv( sub( B	) )*sub( A )= Z'*(inv(T)*R)

where  inv(  sub( B ) ) denotes the inverse of the matrix sub( B	), and
Z' denotes the transpose	of matrix Z.

Notes
=====

Each global data	object is described by an associated description  vec-
tor.  This vector stores	the information	required to establish the map-
ping between an object element and its corresponding process and	memory
location.

Let  A  be  a generic term for any 2D block cyclicly distributed	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 distribu-
ted over.	The context itself is glo-
bal, 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 distributed matrix, and as-
sume that its process grid has dimension	p x q.
LOCr(  K	) denotes the number of	elements of K that a process would re-
ceive 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
N       (global input) INTEGER
The number of rows to be	operated on i.e	the number of rows  of
the distributed submatrices sub(	A ) and	sub( B ). N >= 0.

M       (global input) INTEGER
The  number of columns to be operated on	i.e the	number of col-
umns of the distributed submatrix sub( A	).  M >= 0.

P       (global input) INTEGER
The number of columns to	be operated on i.e the number of  col-
umns of the distributed submatrix sub( B	).  P >= 0.

A       (local input/local output) REAL pointer into the
local  memory  to  an array of dimension	(LLD_A,	LOCc(JA+M-1)).
On entry, the local pieces of  the  N-by-M  distributed	matrix
sub( A )	which is to be factored.  On exit, the elements	on and
above the diagonal of sub( A ) contain the min(N,M) by M	 upper
trapezoidal matrix R (R is upper	triangular if N	>= M); the el-
ements below the	diagonal, with the array TAUA,	represent  the
orthogonal matrix Q as a	product	of min(N,M) elementary reflec-
tors (see Further Details).  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	indicating  the	 first
column of sub( A	).

DESCA   (global and local input)	INTEGER	array of dimension DLEN_.
The array descriptor for	the distributed	matrix A.

TAUA    (local output) REAL, array, dimension
LOCc(JA+MIN(N,M)-1).  This  array  contains  the	scalar factors
TAUA of the elementary reflectors which represent the  orthogo-
nal  matrix  Q.	TAUA is	tied to	the distributed	matrix A. (see
Further Details).   B	    (local  input/local	 output)  REAL
pointer	into the local memory to an array of dimension (LLD_B,
LOCc(JB+P-1)).  On entry, the local pieces of the  N-by-P  dis-
tributed	matrix sub( B )	which is to be factored. On exit, if N
<= P, the upper triangle	of B(IB:IB+N-1,JB+P-N:JB+P-1) contains
the N by	N upper	triangular matrix T; if	N > P, the elements on
and above the (N-P)-th subdiagonal contain the  N  by  P	 upper
trapezoidal  matrix  T;	the remaining elements,	with the array
TAUB, represent the orthogonal matrix Z as a product of elemen-
tary  reflectors	(see Further Details).	IB	(global	input)
INTEGER The row index in	the  global  array  B  indicating  the
first row of sub( B ).

JB      (global input) INTEGER
The  column  index  in  the global array	B indicating the first
column of sub( B	).

DESCB   (global and local input)	INTEGER	array of dimension DLEN_.
The array descriptor for	the distributed	matrix B.

TAUB    (local output) REAL, array, dimension LOCr(IB+N-1)
This array contains the scalar factors of  the  elementary  re-
flectors	which represent	the orthogonal unitary matrix Z.  TAUB
is tied to the distributed matrix B (see	Further	Details).

WORK    (local workspace/local output) REAL array,
dimension (LWORK) On exit, WORK(1) returns the minimal and  op-
timal LWORK.

LWORK   (local or global	input) INTEGER
The dimension of	the array WORK.	 LWORK is local	input and must
be at least LWORK >= MAX( NB_A *	( NpA0 + MqA0 +	NB_A  ),  MAX(
(NB_A*(NB_A-1))/2, (PqB0	+ NpB0)*NB_A ) + NB_A *	NB_A, MB_B * (
NpB0 + PqB0 + MB_B ) ), where

IROFFA =	MOD( IA-1, MB_A	), ICOFFA = MOD( JA-1, NB_A  ),	 IAROW
=  INDXG2P( IA, MB_A, MYROW, RSRC_A, NPROW ), IACOL  = INDXG2P(
JA, NB_A, MYCOL,	CSRC_A,	NPCOL ), NpA0	 =  NUMROC(  N+IROFFA,
MB_A,  MYROW,  IAROW, NPROW ), MqA0   = NUMROC( M+ICOFFA, NB_A,
MYCOL, IACOL, NPCOL ),

IROFFB =	MOD( IB-1, MB_B	), ICOFFB = MOD( JB-1, NB_B  ),	 IBROW
=  INDXG2P( IB, MB_B, MYROW, RSRC_B, NPROW ), IBCOL  = INDXG2P(
JB, NB_B, MYCOL,	CSRC_B,	NPCOL ), NpB0	 =  NUMROC(  N+IROFFB,
MB_B,  MYROW,  IBROW, NPROW ), PqB0   = NUMROC( P+ICOFFB, NB_B,
MYCOL, IBCOL, NPCOL ),

and NUMROC, INDXG2P are ScaLAPACK tool functions; MYROW,	MYCOL,
NPROW  and  NPCOL  can  be determined by	calling	the subroutine
BLACS_GRIDINFO.

If LWORK	= -1, then LWORK is global input and a workspace query
is assumed; the routine only calculates the minimum 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.

FURTHER	DETAILS
The matrix Q is represented as a	product	of elementary reflectors

Q = H(ja) H(ja+1) . .	. H(ja+k-1), where k = min(n,m).

Each H(i) has the form

H(i) = I - taua * v *	v'

where taua is a real scalar, and	v is a real vector with
v(1:i-1)	= 0 and	v(i) = 1; v(i+1:n) is stored on	exit in
A(ia+i:ia+n-1,ja+i-1), and taua in TAUA(ja+i-1).
To form Q explicitly, use ScaLAPACK subroutine PSORGQR.
To use Q	to update another matrix, use ScaLAPACK	subroutine PSORMQR.

The matrix Z is represented as a	product	of elementary reflectors

Z = H(ib) H(ib+1) . .	. H(ib+k-1), where k = min(n,p).

Each H(i) has the form

H(i) = I - taub * v *	v'

where taub is a real scalar, and	v is a real vector with
v(p-k+i+1:p) = 0	and v(p-k+i) = 1; v(1:p-k+i-1) is stored  on  exit  in
B(ib+n-k+i-1,jb:jb+p-k+i-2),  and  taub in TAUB(ib+n-k+i-1).  To	form Z
explicitly, use ScaLAPACK subroutine PSORGRQ.
To use Z	to update another matrix, use ScaLAPACK	subroutine PSORMRQ.

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

The distributed submatrices sub(	A ) and	sub(  B	 )  must  verify  some
alignment properties, namely the	following expression should be true:

( MB_A.EQ.MB_B .AND. IROFFA.EQ.IROFFB .AND. IAROW.EQ.IBROW )

ScaLAPACK version 1.7		13 August 2001			    PSGGQRF(l)
```

NAME | SYNOPSIS | PURPOSE | ARGUMENTS | FURTHER DETAILS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=psggqrf&manpath=FreeBSD+12.1-RELEASE+and+Ports>