IBM Books

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

PDTRSV and PZTRSV--Solution of Triangular System of Equations with a Single Right-Hand Side

PDTRSV performs one of the following solves for a triangular system of equations with a single right-hand side:

Solution Equation
1. x<--A-1x Ax = b
2. x<--A-Tx ATx = b

PZTRSV performs one of the following solves for a triangular system of equations with a single right-hand side:

Solution Equation
1. x<--A-1x Ax = b
2. x<--A-Tx ATx = b
3. x<--A-Hx AHx = b

where, in the formulas above:

A represents the global triangular submatrix Aia:ia+n-1, ja:ja+n-1.
x represents the global vector:

Notes:

  1. The term b used in the systems of equations listed above represents the right-hand side of the system. It is important to note that in these subroutines the right-hand side of the equation is actually provided in the input-output argument x.

  2. No data should be moved to form AT or AH; 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 43. Data Types

A, x Subprogram
Long-precision real PDTRSV
Long-precision complex PZTRSV

Syntax

Fortran CALL PDTRSV | PZTRSV (uplo, transa, diag, n, a, ia, ja, desc_a, x, ix, jx, desc_x, incx)
C and C++ pdtrsv | pztrsv (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 used in the system of equations, where:

If transa = 'N', A is used in the system of equations.

If transa = 'T', AT is used in the system of equations.

If transa = 'C', AH is used in the system of equations.

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, used in the system of equations. 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:

Note:
No data should be moved to form AT or AH; 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 43. 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, containing the right-hand side of the triangular system to be solved. 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:

Scope: local

Specified as: an LLD_X by (at least) LOCq(N_X) array, containing numbers of the data type indicated in Table 43. 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 solution vector.

Scope: local

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

Notes and Coding Rules
  1. These subroutines accept lowercase letters for the uplo, transa, and diag arguments.
  2. For PDTRSV, if you specify 'C' for transa, it is interpreted as though you specified 'T'.
  3. The matrix and vector must have no common elements; otherwise, results are unpredictable.
  4. PDTRSV and PZTRSV 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.
  5. 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.
  6. For suggested block sizes, see Coding Tips for Optimizing Parallel Performance.
  7. The following values must be equal: CTXT_A = CTXT_X.
  8. The global triangular matrix A must be distributed using a square block-cyclic distribution; that is, MB_A = NB_A.
  9. 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).
  10. If incx = M_X:
  11. If incx = 1( <> M_X):

Error Conditions

Computational Errors

None

Resource Errors

Unable to allocate work space

Input-Argument and Miscellaneous Errors

Stage 1:  

  1. DTYPE_A is invalid.
  2. DTYPE_X is invalid.

Stage 2:  

  1. CTXT_A is invalid.

Stage 3:  

  1. This subroutine was called from outside the process grid.

Stage 4:  

  1. uplo <> 'U' or 'L'
  2. transa <> 'N', 'T', or 'C'
  3. diag <> 'N' or 'U'
  4. n < 0
  5. M_A < 0 and n = 0; M_A < 1 otherwise
  6. N_A < 0 and n = 0; N_A < 1 otherwise
  7. MB_A < 1
  8. NB_A < 1
  9. RSRC_A < 0 or RSRC_A >= p
  10. CSRC_A < 0 or CSRC_A >= q
  11. CTXT_A <> CTXT_X
  12. M_X < 0 and n = 0; M_X < 1 otherwise
  13. N_X < 0 and n = 0; N_X < 1 otherwise
  14. MB_X < 1
  15. NB_X < 1
  16. RSRC_X < 0 or RSRC_X >= p
  17. CSRC_X < 0 or CSRC_X >= q

Stage 5:  

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

    If n <> 0:

  3. ix > M_X
  4. jx > N_X
  5. ia > M_A
  6. ja > N_A
  7. ia+n-1 > M_A
  8. ja+n-1 > N_A

    If incx = M_X:

  9. NB_A <> NB_X
  10. mod(jx-1, NB_X) <> mod(ja-1, NB_A)
  11. n <> 0 and jx+n-1 > N_X

    If incx = 1( <> M_X):

  12. MB_A <> MB_X
  13. mod(ix-1, MB_X) <> mod(ia-1, MB_A)
  14. n <> 0 and ix+n-1 > M_X

    Otherwise:

  15. incx <> 1 and incx <> M_X

Stage 6:  

  1. LLD_A < max(1, LOCp(M_A))
  2. LLD_X < max(1, LOCp(M_X))
  3. If incx = M_X and transa = 'T', 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)
  4. If incx = 1( <> M_X) and transa = 'N', 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 solves x<--A-1x using a 2 × 2 process grid, where A is a unit triangular matrix. 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 row-distributed vector within a row of global matrix X, by specifying incx = M_X = 1, ix = 1, and jx = 2.

Note:
Because matrix A is unit triangular, the diagonal elements are not referenced. This subroutine assumes a value of 1.0 for the diagonal elements.

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 PDTRSV( 'L' , 'N'  , 'U' , 12 , A , 2 , 2 , DESC_A , X , 1 , 2 ,
 
            DESC_X INCX
               |     |
            DESC_X , 1 )


Desc_A Desc_X
DTYPE_ 1 1
CTXT_ icontxt(IOBG15) icontxt(IOBG15)
M_ 13 1
N_ 13 13
MB_ 3 1
NB_ 3 3
RSRC_ 0 0
CSRC_ 0 0
LLD_ See below(EPSSL15) See below(EPSSL15)

Notes:

  1. icontxt is the output of the BLACS_GRIDINIT call.

  2. 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 P00 and P01, LLD_A = 6 on P10 and P11, and LLD_X = 1 on all processes.

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  |    .    .    .   |    .    .    .   |    .    .    .   |    .  |
     | ----------------|------------------|------------------|------------------|------ |
     |   .   3.0  2.0  |   1.0   .    .   |    .    .    .   |    .    .    .   |    .  |
 1   |   .   1.0  3.0  |   2.0  1.0   .   |    .    .    .   |    .    .    .   |    .  |
     |   .   2.0  1.0  |   3.0  2.0  1.0  |    .    .    .   |    .    .    .   |    .  |
     | ----------------|------------------|------------------|------------------|------ |
     |   .   3.0  2.0  |   1.0  3.0  2.0  |   1.0   .    .   |    .    .    .   |    .  |
 2   |   .   1.0  3.0  |   2.0  1.0  3.0  |   2.0  1.0   .   |    .    .    .   |    .  |
     |   .   2.0  1.0  |   3.0  2.0  1.0  |   3.0  2.0  1.0  |    .    .    .   |    .  |
     | ----------------|------------------|------------------|------------------|------ |
     |   .   3.0  2.0  |   1.0  3.0  2.0  |   1.0  3.0  2.0  |   1.0   .    .   |    .  |
 3   |   .   1.0  3.0  |   2.0  1.0  3.0  |   2.0  1.0  3.0  |   2.0  1.0   .   |    .  |
     |   .   2.0  1.0  |   3.0  2.0  1.0  |   3.0  2.0  1.0  |   3.0  2.0  1.0  |    .  |
     | ----------------|------------------|------------------|------------------|------ |
 4   |   .   3.0  2.0  |   1.0  3.0  2.0  |   1.0  3.0  2.0  |   1.0  3.0  2.0  |   1.0 |
     *                                                                                  *

The following is the 2 × 2 process grid: 

B,D  |  0 2 4  | 1 3 
-----| ------- |-----
0    |   P00   |  P01
2    |         |
4    |         |
-----| ------- |-----
1    |   P10   |  P11
3    |         |

Local arrays for A: 


p,q  |                 0                  |                1
-----|------------------------------------|--------------------------------
     |   .    .    .    .    .    .    .  |    .    .    .    .    .    .
     |   .    .    .    .    .    .    .  |    .    .    .    .    .    .
     |   .   2.0   .    .    .    .    .  |    .    .    .    .    .    .
 0   |   .   3.0  2.0   .    .    .    .  |   1.0  3.0  2.0   .    .    .
     |   .   1.0  3.0  2.0   .    .    .  |   2.0  1.0  3.0   .    .    .
     |   .   2.0  1.0  3.0  2.0   .    .  |   3.0  2.0  1.0   .    .    .
     |   .   3.0  2.0  1.0  3.0  2.0   .  |   1.0  3.0  2.0  1.0  3.0  2.0
-----|------------------------------------|--------------------------------
     |   .   3.0  2.0   .    .    .    .  |    .    .    .    .    .    .
     |   .   1.0  3.0   .    .    .    .  |   2.0   .    .    .    .    .
     |   .   2.0  1.0   .    .    .    .  |   3.0  2.0   .    .    .    .
 1   |   .   3.0  2.0  1.0  3.0  2.0   .  |   1.0  3.0  2.0   .    .    .
     |   .   1.0  3.0  2.0  1.0  3.0   .  |   2.0  1.0  3.0  2.0   .    .
     |   .   2.0  1.0  3.0  2.0  1.0   .  |   3.0  2.0  1.0  3.0  2.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 row-distributed vector. Following is the global vector x of size 1 × 12, starting at row 1 and column 2 in 1 × 13 global matrix X with block size 1 × 3: 


B,D          0                  1                  2                  3             4
     *                                                                                  *
 0   |   .   2.0  7.0  |  13.0 15.0 17.0  |  26.0 28.0 27.0  |  39.0 41.0 37.0  |  52.0 |
     *                                                                                  *

The following is the 2 × 2 process grid: 

B,D  |  0 2 4  | 1 3 
-----| ------- |-----
0    |   P00   |  P01
-----| ------- |-----
--   |   P10   |  P11

Local arrays for x: 


p,q  |                 0                   |                1
-----|-------------------------------------|--------------------------------
 0   |   .   2.0  7.0 26.0 28.0 27.0 52.0  |  13.0 15.0 17.0 39.0 41.0 37.0

Output:

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 row-distributed vector. Following is the global vector x of size 1 × 12, starting at row 1 and column 2 in 1 × 13 global matrix X with block size 1 × 3: 


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

The following is the 2 × 2 process grid: 

B,D  |  0 2 4  | 1 3 
-----| ------- |-----
0    |   P00   |  P01
-----| ------- |-----
--   |   P10   |  P11

Local arrays for x: 


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

Example 2

This example solves x<--A-1x using a 2 × 2 process grid, where A is a unit triangular matrix.

Note:
Because matrix A is unit triangular, the diagonal elements are not referenced. This subroutine assumes a value of (1.0,0.0) for the diagonal elements.

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 PZTRSV( '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(IOBG16) icontxt(IOBG16)
M_ 4 4
N_ 4 1
MB_ 2 2
NB_ 2 1
RSRC_ 0 0
CSRC_ 0 0
LLD_ See below(EPSSL16) See below(EPSSL16)

Notes:

  1. icontxt is the output of the BLACS_GRIDINIT call.

  2. 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 P00 and P01, LLD_A = 2 on P10 and P11, and LLD_X = 2 on P00 and P10.

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    |   P00   |  P01
-----| ------- |-----
1    |   P10   |  P11

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, 4.0) |
     | ----------- |
     | ( 3.0,17.0) |
 1   | ( 4.0,44.0) |
     *             *

The following is the 2 × 2 process grid: 

B,D  |    0    | --  
-----| ------- |-----
0    |   P00   |  P01
-----| ------- |-----
1    |   P10   |  P11

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)

Output:

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    |   P00   |  P01
-----| ------- |-----
1    |   P10   |  P11

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)

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