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

STBMV, DTBMV, CTBMV, and ZTBMV--Matrix-Vector Product for a Triangular Band Matrix, Its Transpose, or Its Conjugate Transpose

STBMV and DTBMV compute one of the following matrix-vector products, using the vector x and triangular band matrix A or its transpose:

x<--Ax

x<--A^Tx

CTBMV and ZTBMV compute one of the following matrix-vector products, using the vector x and triangular band 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 and is stored in upper- or lower-triangular-band-packed storage mode, respectively.

Table 70. Data Types

Syntax

On Entry

uplo

indicates whether matrix A is an upper or lower triangular band 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 band matrix A. Specified as: a fullword integer; n >= 0.

k

is the upper or lower band width k of the matrix A. Specified as: a fullword integer; k >= 0.

a

is the upper or lower triangular band matrix A of order n, stored in upper- or lower-triangular-band-packed 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 70.

lda

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

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 70.

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 70.

Notes

1. These subroutines accept lowercase letters for the uplo, transa, and diag arguments.
2. For STBMV and DTBMV, 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. To achieve optimal performance in these subroutines, use lda = k+1.
5. 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. As a result, you do not have to set these values.
6. For both upper and lower triangular band matrices, if you specify k >= n, ESSL assumes, only for purposes of the computation, that the upper or lower band width of matrix A is n-1; that is, it processes matrix A, of order n, as though it is a (nonbanded) triangular matrix. However, ESSL uses the original value for k for the purposes of finding the locations of element a₁₁ and all other elements in the array specified for A, as described in Triangular Band Matrix. For an illustration of this technique, see Example 4.
7. For a description of triangular band matrices and how they are stored in upper- and lower-triangular-band-packed storage mode, see Triangular Band Matrix.
8. If you are using a lower triangular band matrix, you may want to use this alternate approach instead of using lower-triangular-band-packed storage mode. Leave matrix A in full-matrix storage mode when you pass it to ESSL and specify the lda argument to be lda+1, which is the leading dimension of matrix A plus 1. ESSL then processes the matrix elements in the same way as though you had set them up in lower-triangular-band-packed storage mode.

Function

These subroutines can perform the following matrix-vector product computations, using the triangular band 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 CTBMV and ZTBMV only)

where:

x is a vector of length n.

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

See references [34], [46], 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. k < 0
6. lda <= 0
7. lda < k+1
8. incx = 0

Example 1

This example shows the computation x<--Ax. Matrix A is a real 7 by 7 upper triangular band matrix with a half band width of 3 that is not unit triangular, stored in upper-triangular-band-packed storage mode. Vector x is a vector of length 7. Matrix A is:

                  *                                   *
                  | 1.0  1.0  1.0  1.0  0.0  0.0  0.0 |
                  | 0.0  2.0  2.0  2.0  2.0  0.0  0.0 |
                  | 0.0  0.0  3.0  3.0  3.0  3.0  0.0 |
                  | 0.0  0.0  0.0  4.0  4.0  4.0  4.0 |
                  | 0.0  0.0  0.0  0.0  5.0  5.0  5.0 |
                  | 0.0  0.0  0.0  0.0  0.0  6.0  6.0 |
                  | 0.0  0.0  0.0  0.0  0.0  0.0  7.0 |
                  *                                   *

Call Statement and Input

            UPLO TRANSA DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL STBMV( 'U' , 'N' , 'N' , 7 , 3 , A , 5 , X , 1  )
 
        *                                   *
        |  .    .    .   1.0  2.0  3.0  4.0 |
        |  .    .   1.0  2.0  3.0  4.0  5.0 |
A    =  |  .   1.0  2.0  3.0  4.0  5.0  6.0 |
        | 1.0  2.0  3.0  4.0  5.0  6.0  7.0 |
        |  .    .    .    .    .    .    .  |
        *                                   *
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0)

Output

X        =  (10.0, 28.0, 54.0, 88.0, 90.0, 78.0, 49.0)

Example 2

This example shows the computation x<--A^Tx. Matrix A is a real 7 by 7 lower triangular band matrix with a half band width of 3 that is not unit triangular, stored in lower-triangular-band-packed storage mode. Vector x is a vector of length 7. Matrix A is:

                  *                                   *
                  | 1.0  0.0  0.0  0.0  0.0  0.0  0.0 |
                  | 1.0  2.0  0.0  0.0  0.0  0.0  0.0 |
                  | 1.0  2.0  3.0  0.0  0.0  0.0  0.0 |
                  | 1.0  2.0  3.0  4.0  0.0  0.0  0.0 |
                  | 0.0  2.0  3.0  4.0  5.0  0.0  0.0 |
                  | 0.0  0.0  3.0  4.0  5.0  6.0  0.0 |
                  | 0.0  0.0  0.0  4.0  5.0  6.0  7.0 |
                  *                                   *

Call Statement and Input

            UPLO TRANSA DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL STBMV( 'L' , 'T' , 'N' , 7 , 3 , A , 5 , X , 1  )
 
        *                                   *
        | 1.0  2.0  3.0  4.0  5.0  6.0  7.0 |
        | 1.0  2.0  3.0  4.0  5.0  6.0   .  |
A    =  | 1.0  2.0  3.0  4.0  5.0   .    .  |
        | 1.0  2.0  3.0  4.0   .    .    .  |
        |  .    .    .    .    .    .    .  |
        *                                   *
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0)

Output

X        =  (10.0, 28.0, 54.0, 88.0, 90.0, 78.0, 49.0)

Example 3

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

        *                                                                              *
        | (1.0, 1.0) (1.0, 1.0) (1.0, 1.0) (1.0, 1.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) |
        | (0.0, 0.0) (2.0, 2.0) (2.0, 2.0) (2.0, 2.0) (2.0, 2.0) (0.0, 0.0) (0.0, 0.0) |
        | (0.0, 0.0) (0.0, 0.0) (3.0, 3.0) (3.0, 3.0) (3.0, 3.0) (3.0, 3.0) (0.0, 0.0) |
        | (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (4.0, 4.0) (4.0, 4.0) (4.0, 4.0) (4.0, 4.0) |
        | (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (5.0, 5.0) (5.0, 5.0) (5.0, 5.0) |
        | (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (6.0, 6.0) (6.0, 6.0) |
        | (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (7.0, 7.0) |
        *                                                                              *

Call Statement and Input

            UPLO TRANSA DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL CTBMV( 'U' , 'C' , 'N' , 7 , 3 , A , 5 , X , 1  )

        *                                                                                    *
        |     .           .           .       (1.0, 1.0)  (2.0, 2.0)  (3.0, 3.0)  (4.0, 4.0) |
        |     .           .       (1.0, 1.0)  (2.0, 2.0)  (3.0, 3.0)  (4.0, 4.0)  (5.0, 5.0) |
A    =  |     .       (1.0, 1.0)  (2.0, 2.0)  (3.0, 3.0)  (4.0, 4.0)  (5.0, 5.0)  (6.0, 6.0) |
        | (1.0, 1.0)  (2.0, 2.0)  (3.0, 3.0)  (4.0, 4.0)  (5.0, 5.0)  (6.0, 6.0)  (7.0, 7.0) |
        |     .           .           .           .           .           .           .      |
        *                                                                                    *

X        =  ((1.0, 2.0), (2.0, 4.0), (3.0, 6.0), (4.0, 8.0),
             (5.0, 10.0), (6.0, 12.0), (7.0, 14.0))

Output

X        =  ((1.0, 2.0), (7.0, 9.0), (24.0, 23.0), (58.0, 46.0),
             (112.0, 79.0), (186.0, 122.0), (280.0, 175.0))

Example 4

This example shows the computation x<--A^Tx, where k > n. Matrix A is a real 4 by 4 upper triangular band matrix with a half band width of 5 that is not unit triangular, stored in upper-triangular-band-packed storage mode. Vector x is a vector of length 4. Matrix A is:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL STBMV( 'U' , 'T' , 'N' , 4 , 5 , A , 6 , X , 1  )
 
        *                     *
        |  .    .    .    .   |
A    =  |  .    .    .    .   |
        |  .    .    .   1.0  |
        |  .    .   1.0  2.0  |
        |  .   1.0  2.0  3.0  |
        | 1.0  2.0  3.0  4.0  |
        *                     *
 
X        =  (1.0, 2.0, 3.0, 4.0)

Output

X        =  (1.0, 5.0, 14.0, 30.0)