Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PZLAPIV(l)			       )			    PZLAPIV(l)

NAME
       PZLAPIV	-  applie  either  P (permutation matrix indicated by IPIV) or
       inv(  P	)  to  a  general  M-by-N  distributed	matrix	sub(  A	 )   =
       A(IA:IA+M-1,JA:JA+N-1), resulting in row	or column pivoting

SYNOPSIS
       SUBROUTINE PZLAPIV( DIREC,  ROWCOL,  PIVROC,  M,	 N,  A,	IA, JA,	DESCA,
			   IPIV, IP, JP, DESCIP, IWORK )

	   CHARACTER*1	   DIREC, PIVROC, ROWCOL

	   INTEGER	   IA, IP, JA, JP, M, N

	   INTEGER	   DESCA( * ), DESCIP( * ), IPIV( * ), IWORK( *	)

	   COMPLEX*16	   A( *	)

PURPOSE
       PZLAPIV applies either P	(permutation matrix indicated by IPIV) or inv(
       P   )   to   a	general	  M-by-N   distributed	 matrix	 sub(  A  )  =
       A(IA:IA+M-1,JA:JA+N-1), resulting in row	or column pivoting. The	 pivot
       vector  may  be distributed across a process row	or a column. The pivot
       vector should be	aligned	with the distributed matrix  A.	 This  routine
       will  transpose	the pivot vector if necessary.	For example if the row
       pivots should be	applied	to the columns of sub( A  ),  pass  ROWCOL='C'
       and PIVROC='C'.

       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

       Restrictions
       ============

       IPIV  must  always  be  a distributed vector (not a matrix).  Thus: IF(
       ROWPIV .EQ. 'C' ) THEN
	  JP must be 1
       ELSE
	  IP must be 1
       END IF

       The following restrictions apply	when IPIV must be transposed: IF( ROW-
       PIV.EQ.'C' .AND.	PIVROC.EQ.'C') THEN
	   DESCIP(MB_) must equal DESCA(NB_)
       ELSE IF(	ROWPIV.EQ.'R" .AND. PIVROC.EQ.'R') THEN
	   DESCIP(NB_) must equal DESCA(MB_)
       END IF

ARGUMENTS
       DIREC   (global input) CHARACTER*1
	       Specifies  in  which  order  the	 permutation is	applied: = 'F'
	       (Forward) Applies pivots	Forward	from top of matrix.   Computes
	       P*sub( A	).  = 'B' (Backward) Applies pivots Backward from bot-
	       tom of matrix. Computes inv( P )*sub( A ).

       ROWCOL  (global input) CHARACTER*1
	       Specifies if the	rows or	columns	are to be permuted: = 'R' Rows
	       will be permuted, = 'C' Columns will be permuted.

       PIVROC  (global input) CHARACTER*1
	       Specifies  whether  IPIV	 is  distributed over a	process	row or
	       column: = 'R' IPIV distributed over a process row  =  'C'  IPIV
	       distributed over	a process column

       M       (global input) INTEGER
	       The  number  of rows to be operated on, i.e. the	number of rows
	       of the distributed submatrix sub( A ). 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( A ). N	>= 0.

       A       (local input/local output) COMPLEX*16 pointer into the
	       local  memory  to  an array of dimension	(LLD_A,	LOCc(JA+N-1)).
	       On entry, this array contains the local pieces of the  distrib-
	       uted submatrix sub( A ) to which	the row	or column interchanges
	       will be applied.	On exit, the local pieces of the permuted dis-
	       tributed	submatrix.

       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.

       IPIV    (local input) INTEGER array, dimension (LIPIV) where LIPIV is
	       when  ROWCOL='R'	 or  'r':  >=  LOCr(  IA+M-1  )	+ MB_A	    if
	       PIVROC='C' or 'c', >= LOCc( M + MOD(JP-1,NB_P) )	if  PIVROC='R'
	       or   'r',   and,	  when	 ROWCOL='C'  or	 'c':  >=  LOCr(  N  +
	       MOD(IP-1,MB_P) )	if PIVROC='C' or 'c', >= LOCc( JA+N-1 )	+ NB_A
	       if  PIVROC='R' or 'r'.  This array contains the pivoting	infor-
	       mation. IPIV(i) is the global row (column), local row  (column)
	       i  was  swapped with.  When ROWCOL='R' or 'r' and PIVROC='C' or
	       'c', or ROWCOL='C' or 'c' and PIVROC='R'	or 'r',	the last piece
	       of  this	 array of size MB_A (resp. NB_A) is used as workspace.
	       In those	cases, this array is tied to the distributed matrix A.

       IP      (global input) INTEGER
	       The row index in	the global array P indicating the first	row of
	       sub( P ).

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

       DESCIP  (global and local input)	INTEGER	array of dimension DLEN_.
	       The array descriptor for	the distributed	vector IPIV.

       IWORK   (local workspace) INTEGER array,	dimension (LDW)
	       where LDW is equal to the workspace  necessary  for  transposi-
	       tion, and the storage of	the tranposed IPIV:

	       Let  LCM	 be the	least common multiple of NPROW and NPCOL.  IF(
	       ROWCOL.EQ.'R' .AND. PIVROC.EQ.'R' ) THEN	IF(  NPROW.EQ.NPCOL  )
	       THEN  LDW  =  LOCr(  N_P	 + MOD(JP-1, NB_P) ) + NB_P ELSE LDW =
	       LOCr(   N_P   +	 MOD(JP-1,   NB_P)   )	 +   NB_P   *	 CEIL(
	       CEIL(LOCc(N_P)/NB_P)  /	(LCM/NPCOL)  )	END  IF	 ELSE IF( ROW-
	       COL.EQ.'C' .AND.	PIVROC.EQ.'C' )	THEN IF( NPROW.EQ.NPCOL	) THEN
	       LDW = LOCc( M_P + MOD(IP-1, MB_P) ) + MB_P ELSE LDW = LOCc( M_P
	       + MOD(IP-1, MB_P) )  +  MB_P  *	CEIL(  CEIL(LOCr(M_P)/MB_P)  /
	       (LCM/NPROW) ) END IF ELSE IWORK is not referenced.  END IF

ScaLAPACK version 1.7		13 August 2001			    PZLAPIV(l)

NAME | SYNOPSIS | PURPOSE | ARGUMENTS

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

home | help