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

STRMV, DTRMV, CTRMV, ZTRMV, STPMV, DTPMV, CTPMV, and ZTPMV--Matrix-Vector Product for a Triangular Matrix, Its Transpose, or Its Conjugate Transpose

STRMV, DTRMV, STPMV, and DTPMV compute one of the following matrix-vector products, using the vector x and triangular matrix A or its transpose:

x<--Ax

x<--A^Tx

CTRMV, ZTRMV, CTPMV, and ZTPMV compute one of the following matrix-vector products, using the vector x and triangular matrix A, its transpose, or its conjugate transpose:

x<--Ax

x<--A^Tx

x<--A^Hx

Matrix A can be either upper or lower triangular, where:

• For the _TRMV subroutines, it is stored in upper- or lower-triangular storage mode, respectively.
• For the _TPMV subroutines, it is stored in upper- or lower-triangular-packed storage mode, respectively.

Table 69. Data Types

Syntax

On Entry

uplo

indicates whether matrix A is an upper or lower triangular matrix, where:

If uplo = 'U', A is an upper triangular matrix.

If uplo = 'L', A is a lower triangular matrix.

Specified as: a single character. It must be '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.

Specified as: a single character. It must be '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.

Specified as: a single character. It must be 'U' or 'N'.

n

is the order of triangular matrix A. Specified as: a fullword integer; 0 <= n <= lda.

a

is the upper or lower triangular matrix A of order n, stored in upper- or lower-triangular storage mode, respectively.

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.

Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 69.

lda

is the leading dimension of the array specified for a. Specified as: a fullword integer; lda > 0 and lda >= n.

ap

is the upper or lower triangular matrix A of order n, stored in upper- or lower-triangular-packed storage mode, respectively. Specified as: a one-dimensional array of (at least) length n(n+1)/2, containing numbers of the data type indicated in Table 69.

x

is the vector x of length n. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 69.

incx

is the stride for vector x. Specified as: a fullword integer; incx > 0 or incx < 0.

On Return

x

is the vector x of length n, containing the results of the computation. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 69.

Notes

1. These subroutines accept lowercase letters for the uplo, transa, and diag arguments.
2. For STRMV, DTRMV, STPMV, and DTPMV if you specify 'C' for the transa argument, it is interpreted as though you specified 'T'.
3. Matrix A and vector x must have no common elements; otherwise, results are unpredictable.
4. ESSL assumes certain values in your array for parts of a triangular matrix. As a result, you do not have to set these values. For unit triangular matrices, the elements of the diagonal are assumed to be 1.0 for real matrices and (1.0, 0.0) for complex matrices. When using upper- or lower-triangular storage, the unreferenced elements in the lower and upper triangular part, respectively, are assumed to be zero.
5. For a description of triangular matrices and how they are stored in upper- and lower-triangular storage mode and in upper- and lower-triangular-packed storage mode, see Triangular Matrix.

Function

These subroutines can perform the following matrix-vector product computations, using the triangular matrix A, its transpose, or its conjugate transpose, where A can be either upper or lower triangular:

x<--Ax

x<--A^Tx

x<--A^Hx (for CTRMV, ZTRMV, CTPMV, and ZTPMV only)

where:

x is a vector of length n.

A is an upper or lower triangular matrix of order n. For _TRMV, it is stored in upper- or lower-triangular storage mode, respectively. For _TPMV, it is stored in upper- or lower-triangular-packed storage mode, respectively.

See references [32] and [38]. If n is 0, no computation is performed.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. uplo <>  'L' or 'U'
2. transa <>  'T', 'N', or 'C'
3. diag <>  'N' or 'U'
4. n < 0
5. lda <= 0
6. lda < n
7. incx = 0

Example 1

This example shows the computation x<--Ax. Matrix A is a real 4 by 4 lower triangular matrix that is unit triangular, stored in lower-triangular storage mode. Vector x is a vector of length 4. Matrix A is:

                            *                    *
                            | 1.0   .    .    .  |
                            | 1.0  1.0   .    .  |
                            | 2.0  3.0  1.0   .  |
                            | 3.0  4.0  3.0  1.0 |
                            *                    *

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   A  LDA  X  INCX
             |     |     |    |   |   |   |   |
CALL STRMV( 'L' , 'N' , 'U' , 4 , A , 4 , X , 1  )
 
        *                   *
        |  .    .    .    . |
A    =  | 1.0   .    .    . |
        | 2.0  3.0   .    . |
        | 3.0  4.0  3.0   . |
        *                   *
 
X        =  (1.0, 2.0, 3.0, 4.0)

Output

X        =  (1.0, 3.0, 11.0, 24.0)

Example 2

This example shows the computation x<--A^Tx. Matrix A is a real 4 by 4 upper triangular matrix that is unit triangular, stored in upper-triangular storage mode. Vector x is a vector of length 4. Matrix A is:

                        *                    *
                        | 1.0  2.0  3.0  2.0 |
                        |  .   1.0  2.0  5.0 |
                        |  .    .   1.0  3.0 |
                        |  .    .    .   1.0 |
                        *                    *

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   A  LDA  X  INCX
             |     |     |    |   |   |   |   |
CALL STRMV( 'U' , 'T' , 'U' , 4 , A , 4 , X , 1  )
 
        *                    *
        |  .   2.0  3.0  2.0 |
A    =  |  .    .   2.0  5.0 |
        |  .    .    .   3.0 |
        |  .    .    .    .  |
        *                    *
 
X        =  (5.0, 4.0, 3.0, 2.0)

Output

X        =  (5.0, 14.0, 26.0, 41.0)

Example 3

This example shows the computation x<--A^Hx. Matrix A is a complex 4 by 4 upper triangular matrix that is unit triangular, stored in upper-triangular storage mode. Vector x is a vector of length 4. Matrix A is:

               *                                                *
               | (1.0, 0.0)  (2.0, 2.0)  (3.0, 3.0)  (2.0, 2.0) |
               |     .       (1.0, 0.0)  (2.0, 2.0)  (5.0, 5.0) |
               |     .           .       (1.0, 0.0)  (3.0, 3.0) |
               |     .           .           .       (1.0, 0.0) |
               *                                                *

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   A  LDA  X  INCX
             |     |     |    |   |   |   |   |
CALL CTRMV( 'U' , 'C' , 'U' , 4 , A , 4 , X , 1  )
 
        *                                       *
        | .  (2.0, 2.0)  (3.0, 3.0)  (2.0, 2.0) |
A    =  | .      .       (2.0, 2.0)  (5.0, 5.0) |
        | .      .           .       (3.0, 3.0) |
        | .      .           .           .      |
        *                                       *
 
X        =  ((5.0, 5.0), (4.0, 4.0), (3.0, 3.0), (2.0, 2.0))

Output

X        =  ((5.0, 5.0), (24.0, 4.0), (49.0, 3.0), (80.0, 2.0))

Example 4

This example shows the computation x<--Ax. Matrix A is a real 4 by 4 lower triangular matrix that is unit triangular, stored in lower-triangular-packed storage mode. Vector x is a vector of length 4. Matrix A is:

                          *                    *
                          | 1.0   .    .    .  |
                          | 1.0  1.0   .    .  |
                          | 2.0  3.0  1.0   .  |
                          | 3.0  4.0  3.0  1.0 |
                          *                    *

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   AP   X  INCX
             |     |     |    |   |    |   |
CALL STPMV( 'L' , 'N' , 'U' , 4 , AP , X , 1  )
 
AP       =  ( . , 1.0, 2.0, 3.0, . , 3.0, 4.0, . , 3.0, . )
X        =  (1.0, 2.0, 3.0, 4.0)

Output

X        =  (1.0, 3.0, 11.0, 24.0)

Example 5

This example shows the computation x<--A^Tx. Matrix A is a real 4 by 4 upper triangular matrix that is not unit triangular, stored in upper-triangular-packed storage mode. Vector x is a vector of length 4. Matrix A is:

                          *                    *
                          | 1.0  2.0  3.0  2.0 |
                          |  .   2.0  2.0  5.0 |
                          |  .    .   3.0  3.0 |
                          |  .    .    .   1.0 |
                          *                    *

Call Statement and Input

            UPLO TRANSA DIAG  N   AP   X  INCX
             |     |     |    |   |    |   |
CALL STPMV( 'U' , 'T' , 'N' , 4 , AP , X , 1  )
 
AP       =  (1.0, 2.0, 2.0, 3.0, 2.0, 3.0, 2.0, 5.0, 3.0, 1.0)
X        =  (5.0, 4.0, 3.0, 2.0)

Output

X        =  (5.0, 18.0, 32.0, 41.0)

Example 6

This example shows the computation x<--A^Hx. Matrix A is a complex 4 by 4 upper triangular matrix that is unit triangular, stored in upper-triangular-packed storage mode. Vector x is a vector of length 4. Matrix A is:

          *                                             *
          | (1.0, 0.0) (2.0, 2.0) (3.0, 3.0) (2.0, 2.0) |
          |     .      (1.0, 0.0) (2.0, 2.0) (5.0, 5.0) |
          |     .          .      (1.0, 0.0) (3.0, 3.0) |
          |     .          .          .      (1.0, 0.0) |
          *                                             *

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   AP   X  INCX
             |     |     |    |   |    |   |
CALL CTPMV( 'U' , 'C' , 'U' , 4 , AP , X , 1  )
 
AP       =  ( . , (2.0, 2.0), . , (3.0, 3.0), (2.0, 2.0), . ,
             (2.0, 2.0), (5.0, 5.0), (3.0, 3.0), . )
X        =  ((5.0, 5.0), (4.0, 4.0), (3.0, 3.0), (2.0, 2.0))

Output

X        =  ((5.0, 5.0), (24.0, 4.0), (49.0, 3.0), (80.0, 2.0))