Parallel Engineering and Scientific Subroutine Library for AIX Version 2 Release 3: Guide and Reference

PDTRMV and PZTRMV--Matrix-Vector Product for a Triangular Matrix or Its Transpose

PDTRMV computes one of the following matrix-vector products:

1. x<--Ax

2. x<--A^Tx

PZTRMV computes one of the following matrix-vector products:

1. x<--Ax

2. x<--A^Tx

3. x<--A^Hx

where, in the formulas above:

A represents the global triangular submatrix A_{ia:ia+n-1,
ja:ja+n-1}.

x represents the global vector:

For incx = M_X, it is X_{ix:ix,
jx:jx+n-1}.
For incx = 1 and incx <> M_X, it is X_{ix:ix+n-1,
jx:jx}.

Note:: No data should be moved to form A^T or A^H; that is, the matrix A should always be stored in its untransposed form.

If n = 0, no computation is performed and the subroutine returns after doing some parameter checking. See references [14] and [15].

Table 42. Data Types

A, x	Subprogram
Long-precision real	PDTRMV
Long-precision complex	PZTRMV

Syntax

Fortran	CALL PDTRMV \| PZTRMV (`uplo`, `transa`, `diag`, `n`, `a`, `ia`, `ja`, `desc_a`, `x`, `ix`, `jx`, `desc_x`, `incx`)
C and C++	pdtrmv \| pztrmv (`uplo`, `transa`, `diag`, `n`, `a`, `ia`, `ja`, `desc_a`, `x`, `ix`, `jx`, `desc_x`, `incx`);

On Entry

uplo

indicates whether the upper or lower triangular part of the global triangular submatrix A is referenced, where:

If uplo = 'U', the upper triangular part is referenced.

If uplo = 'L', the lower triangular part is referenced.

Scope: global

Specified as: a single character; uplo = 'U' or 'L'.

transa

indicates the form of matrix A to use in the computation, where:

If transa = 'N', A is used in the computation.

If transa = 'T', A^T is used in the computation.

If transa = 'C', A^H is used in the computation.

Scope: global

Specified as: a single character; transa = 'N', 'T', or 'C'.

diag

indicates the characteristics of the diagonal of matrix A, where:

If diag = 'U', A is a unit triangular matrix.

If diag = 'N', A is not a unit triangular matrix.

Scope: global

Specified as: a single character; diag = 'U' or 'N'.

n

is the order of global triangular submatrix A and the length of global vector x.

Scope: global

Specified as: a fullword integer; n >= 0.

a

is the local part of the global triangular matrix A. This identifies the first element of the local array A. This subroutine computes the location of the first element of the local subarray used, based on ia, ja, desc_a, p, q, myrow, and mycol; therefore, the leading LOCp(ia+n-1) by LOCq(ja+n-1) part of the local array A must contain the local pieces of the leading ia+n-1 by ja+n-1 part of the global matrix, and:

If uplo = 'U', the leading n × n upper triangular part of the global triangular submatrix A_{ia:ia+n-1,
ja:ja+n-1} must contain the upper triangular part of the submatrix, and the strictly lower triangular part is not referenced.
If uplo = 'L', the leading lower triangular part of the global triangular submatrix A_{ia:ia+n-1,
ja:ja+n-1} must contain the lower triangular part of the submatrix, and the strictly upper triangular part is not referenced.

Note:: No data should be moved to form A^T or A^H; that is, the matrix A should always be stored in its untransposed form.

Scope: local

Specified as: an LLD_A by (at least) LOCq(N_A) array, containing numbers of the data type indicated in Table 42. Details about the block-cyclic data distribution of global matrix A are stored in desc_a.

ia

is the row index of the global matrix A, identifying the first row of the submatrix A.

Scope: global

Specified as: a fullword integer; 1 <= ia and ia+n-1 <= M_A.

ja

is the column index of the global matrix A, identifying the first column of the submatrix A.

Scope: global

Specified as: a fullword integer; 1 <= ja and ja+n-1 <= N_A.

desc_a

is the array descriptor for global matrix A, described in the following table:

`desc_a`	Name	Description	Limits	Scope
1	DTYPE_A	Descriptor type	DTYPE_A=1	Global
2	CTXT_A	BLACS context	Valid value, as returned by BLACS_GRIDINIT or BLACS_GRIDMAP	Global
3	M_A	Number of rows in the global matrix	If `n` = 0: M_A >= 0 Otherwise: M_A >= 1	Global
4	N_A	Number of columns in the global matrix	If `n` = 0: N_A >= 0 Otherwise: M_A >= 1	Global
5	MB_A	Row block size	MB_A >= 1	Global
6	NB_A	Column block size	NB_A >= 1	Global
7	RSRC_A	The process row of the `p` × `q` grid over which the first row of the global matrix is distributed	0 <= RSRC_A < `p`	Global
8	CSRC_A	The process column of the `p` × `q` grid over which the first column of the global matrix is distributed	0 <= CSRC_A < `q`	Global
9	LLD_A	The leading dimension of the local array	LLD_A >= max(1,LOCp(M_A))	Local

Specified as: an array of (at least) length 9, containing fullword integers.

x

is the local part of the global matrix X. This identifies the first element of the local array X. This subroutine computes the location of the first element of the local subarray used, based on ix, jx, desc_x, p, q, myrow, and mycol; therefore:

If incx = M_X, the leading LOCp(ix) by LOCq(jx+n-1) part of the local array X must contain the local pieces of the leading ix by jx+n-1 part of the global matrix.
If incx = 1 and incx <> M_X, the leading LOCp(ix+n-1) by LOCq(jx) part of the local array X must contain the local pieces of the leading ix+n-1 by jx part of the global matrix.

Scope: local

Specified as: an LLD_X by (at least) LOCq(N_X) array, containing numbers of the data type indicated in Table 42. Details about the block-cyclic data distribution of the global matrix X are stored in desc_x.

ix

has the following meaning:

If incx = M_X, it indicates which row of global matrix X is used for vector x.

If incx = 1 and incx <> M_X, it is the row index of global matrix X, identifying the first element of vector x.

Scope: global

Specified as: a fullword integer; 1 <= ix <= M_X and:

If incx = 1 and incx <> M_X, then ix+n-1 <= M_X.

jx

has the following meaning:

If incx = M_X, it is the column index of global matrix X, identifying the first element of vector x.

If incx = 1 and incx <> M_X, it indicates which column of global matrix X is used for vector x.

Scope: global

Specified as: a fullword integer; 1 <= jx <= N_X and:

If incx = M_X, then jx+n-1 <= N_X.

desc_x

is the array descriptor for global matrix X, described in the following table:

`desc_x`	Name	Description	Limits	Scope
1	DTYPE_X	Descriptor type	DTYPE_X=1	Global
2	CTXT_X	BLACS context	Valid value, as returned by BLACS_GRIDINIT or BLACS_GRIDMAP	Global
3	M_X	Number of rows in the global matrix	If `n` = 0: M_X >= 0 Otherwise: M_X >= 1	Global
4	N_X	Number of columns in the global matrix	If `n` = 0: N_X >= 0 Otherwise: M_X >= 1	Global
5	MB_X	Row block size	MB_X >= 1	Global
6	NB_X	Column block size	NB_X >= 1	Global
7	RSRC_X	The process row of the `p` × `q` grid over which the first row of the global matrix is distributed	0 <= RSRC_X < `p`	Global
8	CSRC_X	The process column of the `p` × `q` grid over which the first column of the global matrix is distributed	0 <= CSRC_X < `q`	Global
9	LLD_X	The leading dimension of the local array	LLD_X >= max(1,LOCp(M_X))	Local

Specified as: an array of (at least) length 9, containing fullword integers.

incx

is the stride for global vector x.

Scope: global

Specified as: a fullword integer; incx = 1 or incx = M_X, where:

If incx = M_X, then x is a row-distributed vector.

If incx = 1 and incx <> M_X, then x is a column-distributed vector.

On Return

x

is the updated local part of the global matrix X, containing the results of the computation.

Scope: local

Returned as: an LLD_X by (at least) LOCq(N_X) array, containing numbers of the data type indicated in Table 42.

Notes and Coding Rules

These subroutines accept lowercase letters for the uplo, transa, and diag arguments.
For PDTRMV, if you specify 'C' for transa, it is interpreted as though you specified 'T'.
The matrix and vector must have no common elements; otherwise, results are unpredictable.
PDTRMV and PZTRMV assume certain values in your array for parts of a triangular matrix. For unit triangular matrices, the elements of the diagonal are assumed to be one. When using an upper or lower triangular matrix, the unreferenced elements in the strictly lower or upper triangular part, respectively, are assumed to be zero. As a result, you do not have to set these values.
The NUMROC utility subroutine can be used to determine the values of LOCp(M_) and LOCq(N_) used in the argument descriptions above. For details, see Determining the Number of Rows and Columns in Your Local Arrays and NUMROC--Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process.
For suggested block sizes, see Coding Tips for Optimizing Parallel Performance.
The following values must be equal: CTXT_A = CTXT_X.
The global triangular matrix A must be distributed using a square block-cyclic distribution; that is, MB_A = NB_A.
The block row and block column offsets of the global triangular matrix A must be equal; that is, mod(ia-1, MB_A) = mod(ja-1, NB_A).
If incx = M_X:
- The following block sizes must be equal: NB_X = MB_A = NB_A
- In the process grid, the process column containing the first column of the submatrix A must also contain the first column of the submatrix X; that is, iacol = ixcol, where:
  
  iacol = mod((((ja-1)/NB_A)+CSRC_A), q)
  ixcol = mod((((jx-1)/NB_X)+CSRC_X), q)
- The block column offset of x must be equal to the block row and block column offsets of A; that is, mod(jx-1, NB_X) = mod(ja-1, NB_A) = mod(ia-1, MB_A).
If incx = 1( <> M_X):
- The following block sizes must be equal: MB_X = MB_A = NB_A
- In the process grid, the process row containing the first row of the submatrix A must also contain the first row of the submatrix X; that is, iarow = ixrow, where:
  
  iarow = mod((((ia-1)/MB_A)+RSRC_A), p)
  ixrow = mod((((ix-1)/MB_X)+RSRC_X), p)
- The block row offset of x must be equal to the block row and block column offsets of A; that is, mod(ix-1, MB_X) = mod(ia-1, MB_A) = mod(ja-1, NB_A).

Error Conditions

Computational Errors

None

Resource Errors

Unable to allocate work space

Input-Argument and Miscellaneous Errors

Stage 1:

DTYPE_A is invalid.
DTYPE_X is invalid.

Stage 2:

CTXT_A is invalid.

Stage 3:

This subroutine was called from outside the process grid.

Stage 4:

uplo <> 'U' or 'L'
transa <> 'N', 'T', or 'C'
diag <> 'N' or 'U'
n < 0
M_A < 0 and n = 0; M_A < 1 otherwise
N_A < 0 and n = 0; N_A < 1 otherwise
MB_A < 1
NB_A < 1
RSRC_A < 0 or RSRC_A >= p
CSRC_A < 0 or CSRC_A >= q
CTXT_A <> CTXT_X
M_X < 0 and n = 0; M_X < 1 otherwise
N_X < 0 and n = 0; N_X < 1 otherwise
MB_X < 1
NB_X < 1
RSRC_X < 0 or RSRC_X >= p
CSRC_X < 0 or CSRC_X >= q

Stage 5:

MB_A = NB_A
mod(ia-1, MB_A) <> mod(ja-1, NB_A)

If n <> 0:
ix > M_X
jx > N_X
ia > M_A
ja > N_A
ia+n-1 > M_A
ja+n-1 > N_A

If incx = M_X:
NB_A <> NB_X
mod(jx-1, NB_X) <> mod(ja-1, NB_A)
n <> 0 and jx+n-1 > N_X

If incx = 1( <> M_X):
MB_A <> MB_X
mod(ix-1, MB_X) <> mod(ia-1, MB_A)
n <> 0 and ix+n-1 > M_X

Otherwise:
incx <> 1 and incx <> M_X

Stage 6:

LLD_A < max(1, LOCp(M_A))
LLD_X < max(1, LOCp(M_X))
If incx = M_X, then (in the process grid) the process column containing the first column of the submatrix A does not contain the first column of the submatrix X; that is, iacol <> ixcol, where:

iacol = mod((((ja-1)/NB_A)+CSRC_A), q)
ixcol = mod((((jx-1)/NB_X)+CSRC_X), q)
If incx = 1( <> M_X), then (in the process grid) the process row containing the first row of the submatrix A does not contain the first row of the submatrix X; that is, iarow <> ixrow, where:

iarow = mod((((ia-1)/MB_A)+RSRC_A), p)
ixrow = mod((((ix-1)/MB_X)+RSRC_X), p)

Example 1

This example computes x = Ax using a 2 × 2 process grid. It uses a global submatrix A within a global matrix A by specifying ia = 2 and ja = 2. It uses vector x, which is a column-distributed vector within a column of X, by specifying incx = 1, ix = 2, and jx = 1.

Call Statements and Input

ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET (0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)
 
            UPLO  TRANSA DIAG  N    A  IA  JA   DESC_A   X  IX  JX
              |     |     |    |    |   |   |     |      |   |   |
CALL PDTRMV( 'U' , 'N' , 'N' , 12 , A , 2 , 2 , DESC_A , X , 2 , 1 ,
 
              DESC_X INCX
                |      |
              DESC_X , 1 )

	Desc_A	Desc_X
DTYPE_	1	1
CTXT_	`icontxt`^(IOBG13)	`icontxt`^(IOBG13)
M_	13	13
N_	13	1
MB_	3	3
NB_	3	1
RSRC_	0	0
CSRC_	0	0
LLD_	See below^(EPSSL13)	See below^(EPSSL13)
Notes: `icontxt` is the output of the BLACS_GRIDINIT call. Each process should set the LLD_ as follows: LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW)) LLD_X = MAX(1,NUMROC(M_X, MB_X, MYROW, RSRC_X, NPROW)) In this example, LLD_A = 7 on P₀₀ and P₀₁, LLD_A = 6 on P₁₀ and P₁₁, LLD_X = 7 on P₀₀, and LLD_X = 6 on P₁₀.

After the global matrix A is distributed over the process grid, only a portion of the global data structure is used--that is, global submatrix A. Following is the global submatrix A of order 12, starting at row 2 and column 2 in global triangular matrix A of order 13 with block size 3 × 3:

B,D          0                  1                  2                  3             4
     *                                                                                  *
     |   .    .    .   |    .    .    .   |    .    .    .   |    .    .    .   |    .  |
 0   |   .   1.0  2.0  |   1.0  2.0  1.0  |   1.0  3.0  1.0  |   1.0  2.0  3.0  |   2.0 |
     |   .    .   3.0  |   2.0  3.0  1.0  |   2.0  3.0  1.0  |   1.0  2.0  3.0  |   3.0 |
     | ----------------|------------------|------------------|------------------|------ |
     |   .    .    .   |   3.0  1.0  3.0  |   2.0  1.0  2.0  |   1.0  2.0  3.0  |   1.0 |
 1   |   .    .    .   |    .   1.0  2.0  |   2.0  1.0  1.0  |   1.0  2.0  3.0  |   2.0 |
     |   .    .    .   |    .    .   2.0  |   1.0  2.0  2.0  |   1.0  2.0  3.0  |   3.0 |
     | ----------------|------------------|------------------|------------------|------ |
     |   .    .    .   |    .    .    .   |   1.0  2.0  1.0  |   1.0  2.0  3.0  |   1.0 |
 2   |   .    .    .   |    .    .    .   |    .   2.0  1.0  |   1.0  2.0  3.0  |   2.0 |
     |   .    .    .   |    .    .    .   |    .    .   2.0  |   1.0  2.0  3.0  |   3.0 |
     | ----------------|------------------|------------------|------------------|------ |
     |   .    .    .   |    .    .    .   |    .    .    .   |   3.0  1.0  3.0  |   1.0 |
 3   |   .    .    .   |    .    .    .   |    .    .    .   |    .   2.0  2.0  |   2.0 |
     |   .    .    .   |    .    .    .   |    .    .    .   |    .    .   1.0  |   3.0 |
     | ----------------|------------------|------------------|------------------|------ |
 4   |   .    .    .   |    .    .    .   |    .    .    .   |    .    .    .   |   1.0 |
     *                                                                                  *

The following is the 2 × 2 process grid:

B,D  | 0 2 4 |1 3
-----|-------|-----
0    |   P₀₀   |  P₀₁
2    |       |
4    |       |
-----|-------|-----
1    |   P₁₀   |  P₁₁
3    |       |

Local arrays for A:

p,q  |                 0                   |                1
-----|-------------------------------------|--------------------------------
     |   .    .    .    .    .    .    .   |    .    .    .    .    .    .
     |   .   1.0  2.0  1.0  3.0  1.0  2.0  |   1.0  2.0  1.0  1.0  2.0  3.0
     |   .    .   3.0  2.0  3.0  1.0  3.0  |   2.0  3.0  1.0  1.0  2.0  3.0
 0   |   .    .    .   1.0  2.0  1.0  1.0  |    .    .    .   1.0  2.0  3.0
     |   .    .    .    .   2.0  1.0  2.0  |    .    .    .   1.0  2.0  3.0
     |   .    .    .    .    .   2.0  3.0  |    .    .    .   1.0  2.0  3.0
     |   .    .    .    .    .    .   1.0  |    .    .    .    .    .    .
-----|-------------------------------------|--------------------------------
     |   .    .    .   2.0  1.0  2.0  1.0  |   3.0  1.0  3.0  1.0  2.0  3.0
     |   .    .    .   2.0  1.0  1.0  2.0  |    .   1.0  2.0  1.0  2.0  3.0
     |   .    .    .   1.0  2.0  2.0  3.0  |    .    .   2.0  1.0  2.0  3.0
 1   |   .    .    .    .    .    .   1.0  |    .    .    .   3.0  1.0  3.0
     |   .    .    .    .    .    .   2.0  |    .    .    .    .   2.0  2.0
     |   .    .    .    .    .    .   3.0  |    .    .    .    .    .   1.0

After the global matrix X is distributed over the process grid, only a portion of the global data structure is used--that is, global vector x, which is a column-distributed vector. Following is the global vector x of size 12 × 1, starting at row 2 in 13 × 1 global matrix X with block size 3 × 1:

B,D     0
     *      *
     |   .  |
 0   |  2.0 |
     |  3.0 |
     | ---- |
     |  1.0 |
 1   |  2.0 |
     |  3.0 |
     | ---- |
     |  1.0 |
 2   |  2.0 |
     |  3.0 |
     | ---- |
     |  1.0 |
 3   |  2.0 |
     |  3.0 |
     | ---- |
 4   |  1.0 |
     *      *

The following is the 2 × 2 process grid:

B,D  |   0   |-- 
-----|-------|-----
0    |   P₀₀   |  P₀₁
2    |       |
4    |       |
-----|-------|-----
1    |   P₁₀   |  P₁₁
3    |       |

Local arrays for x:

p,q  |  0
-----|------
     |   .
     |  2.0
     |  3.0
 0   |  1.0
     |  2.0
     |  3.0
     |  1.0
-----|------
     |  1.0
     |  2.0
     |  3.0
 1   |  1.0
     |  2.0
     |  3.0

Output:

B,D      0
     *       *
     |    .  |
 0   |  42.0 |
     |  48.0 |
     | ----- |
     |  39.0 |
 1   |  31.0 |
     |  34.0 |
     | ----- |
     |  23.0 |
 2   |  23.0 |
     |  23.0 |
     | ----- |
     |  15.0 |
 3   |  12.0 |
     |   6.0 |
     | ----- |
 4   |   1.0 |
     *       *

The following is the 2 × 2 process grid:

B,D  |   0   |-- 
-----|-------|-----
0    |   P₀₀   |  P₀₁
2    |       |
4    |       |
-----|-------|-----
1    |   P₁₀   |  P₁₁
3    |       |

Local arrays for x:

p,q  |   0
-----|-------
     |    .
     |  42.0
     |  48.0
 0   |  23.0
     |  23.0
     |  23.0
     |   1.0
-----|-------
     |  39.0
     |  31.0
     |  34.0
 1   |  15.0
     |  12.0
     |   6.0

Example 2

This example computes x = Ax using a 2 × 2 process grid.

Note:: For unit triangular matrices, the elements of the diagonal are assumed to be one, so you do not have to set these values.

Call Statements and Input

ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET (0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)
 
            UPLO  TRANSA DIAG  N   A  IA  JA   DESC_A   X  IX  JX
              |     |     |    |   |   |   |     |      |   |   |
CALL PZTRMV( 'L' , 'N' , 'U' , 4 , A , 1 , 1 , DESC_A , X , 1 , 1 ,
 
              DESC_X INCX
                |      |
              DESC_X , 1 )

	Desc_A	Desc_X
DTYPE_	1	1
CTXT_	`icontxt`^(IOBG14)	`icontxt`^(IOBG14)
M_	4	4
N_	4	1
MB_	2	2
NB_	2	1
RSRC_	0	0
CSRC_	0	0
LLD_	See below^(EPSSL14)	See below^(EPSSL14)
Notes: `icontxt` is the output of the BLACS_GRIDINIT call. Each process should set the LLD_ as follows: LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW)) LLD_X = MAX(1,NUMROC(M_X, MB_X, MYROW, RSRC_X, NPROW)) In this example, LLD_A = 2 on P₀₀ and P₀₁, LLD_A = 2 on P₁₀ and P₁₁, LLD_X = 2 on P₀₀, and LLD_X = 2 on P₁₀.

Global triangular matrix A of order 4 with block size 2 × 2:

B,D             0                     1           
     *                                           *
     | (1.0,0.0)     .     |     .         .     |
 0   | (1.0,1.0) (1.0,0.0) |     .         .     |
     | --------------------|-------------------- |
     | (1.0,1.0) (3.0,3.0) | (1.0,0.0)     .     |
 1   | (3.0,3.0) (4.0,4.0) | (3.0,3.0) (1.0,0.0) |
     *                                           *

The following is the 2 × 2 process grid:

B,D  |   0   | 1 
-----|-------|-----
0    |   P₀₀   |  P₀₁
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for A:

p,q  |          0          |          1
-----|---------------------|--------------------
     |     .         .     |     .         .      
 0   | (1.0,1.0)     .     |     .         .      
-----|---------------------|--------------------- 
     | (1.0,1.0) (3.0,3.0) |     .         .      
 1   | (3.0,3.0) (4.0,4.0) | (3.0,3.0)     .

Global vector x of size 4 × 1 with block size 2:

B,D        0
     *           *
     | (1.0,1.0) |
 0   | (2.0,2.0) |
     | --------- |
     | (3.0,3.0) |
 1   | (4.0,4.0) |
     *           *

The following is the 2 × 2 process grid:

B,D  |   0   |-- 
-----|-------|-----
0    |   P₀₀   |  P₀₁
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for x:

p,q  |     0
-----|-----------
     | (1.0,1.0) 
 0   | (2.0,2.0) 
-----|-----------
     | (3.0,3.0) 
 1   | (4.0,4.0)

Output:

Global vector x of size 4 × 1 with block size 2:

B,D         0
     *             *
     | ( 1.0, 1.0) |
 0   | ( 2.0, 4.0) |
     | ----------- |
     | ( 3.0,17.0) |
 1   | ( 4.0,44.0) |
     *             *

The following is the 2 × 2 process grid:

B,D  |   0   |-- 
-----|-------|-----
0    |   P₀₀   |  P₀₁
-----|-------|-----
1    |   P₁₀   |  P₁₁

Local arrays for x:

p,q  |      0
-----|-------------
     | ( 1.0, 1.0) 
 0   | ( 2.0, 4.0) 
-----|-------------
     | ( 3.0,17.0) 
 1   | ( 4.0,44.0)

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]