IBM Books

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

SSBMV, DSBMV, CHBMV, and ZHBMV--Matrix-Vector Product for a Real Symmetric or Complex Hermitian Band Matrix

SSBMV and DSBMV compute the matrix-vector product for a real symmetric band matrix. CHBMV and ZHBMV compute the matrix-vector product for a complex Hermitian band matrix. The band matrix A is stored in either upper- or lower-band-packed storage mode. It uses the scalars alpha and beta, vectors x and y, and band matrix A:

y<--betay+alphaAx
y<--betay+alphaAx

Table 68. Data Types

alpha, beta, x, y, A Subprogram
Short-precision real SSBMV
Long-precision real DSBMV
Short-precision complex CHBMV
Long-precision complex ZHBMV

Syntax

Fortran CALL SSBMV | DSBMV | CHBMV | ZHBMV (uplo, n, k, alpha, a, lda, x, incx, beta, y, incy)
C and C++ ssbmv | dsbmv | chbmv | zhbmv (uplo, n, k, alpha, a, lda, x, incx, beta, y, incy);
PL/I CALL SSBMV | DSBMV | CHBMV | ZHBMV (uplo, n, k, alpha, a, lda, x, incx, beta, y, incy);

On Entry

uplo
indicates the storage mode used for matrix A, where either the upper or lower triangle can be stored:

If uplo = 'U', A is stored in upper-band-packed storage mode.

If uplo = 'L', A is stored in lower-band-packed storage mode.

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

n
is the order of matrix A and the number of elements in vectors x and y. Specified as: a fullword integer; n >= 0.

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

alpha
is the scaling constant alpha. Specified as: a number of the data type indicated in Table 68.

a
is the real symmetric or complex Hermitian band matrix A of order n, having a half band width of k, where:

If uplo = 'U', A is stored in upper-band-packed storage mode.

If uplo = 'L', A is stored in lower-band-packed storage mode.

Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 68, where lda >= k+1.

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

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

beta
is the scaling constant beta. Specified as: a number of the data type indicated in Table 68.

y
is the vector y of length n. Specified as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 68.

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

On Return

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

Notes
  1. All subroutines accept lowercase letters for the uplo argument.
  2. Vector y must have no common elements with matrix A or vector x; otherwise, results are unpredictable. See Concepts.
  3. To achieve optimal performance in these subroutines, use lda = k+1.
  4. The imaginary parts of the diagonal elements of the complex Hermitian matrix A are assumed to be zero, so you do not have to set these values.
  5. For real symmetric and complex Hermitian band matrices, if you specify k >= n, ESSL assumes, only for purposes of the computation, that the half band width of matrix A is n-1; that is, it processes matrix A, of order n, as though it is a (nonbanded) real symmetric or complex Hermitian matrix. However, ESSL uses the original value for k for the purposes of finding the locations of element a11 and all other elements in the array specified for A, as described in the storage modes referenced in the next note. For an illustration of this technique, see Example 3.
  6. For a description of how a real symmetric band matrix is stored, see Upper-Band-Packed Storage Mode or Lower-Band-Packed Storage Mode. For a description of how a complex Hermitian band matrix is stored, see Complex Hermitian Matrix.

Function

These subroutines perform the following matrix-vector product, using a real symmetric or complex Hermitian band matrix A, stored in either upper- or lower-band-packed storage mode:

y<--betay+alphaAx

where:

x and y are vectors of length n.
alpha and beta are scalars.
A is an real symmetric or complex Hermitian band matrix of order n, having a half band width of k.

For SSBMV and CHBMV, intermediate results are accumulated in long precision. Occasionally, for performance reasons, these intermediate results are truncated to short precision and stored.

See references [34], [38], [46], and [79]. No computation is performed if n is 0 or if alpha is zero and beta is one.

Error Conditions

Computational Errors

None

Input-Argument Errors
  1. uplo <> 'U' or 'L'
  2. n < 0
  3. k < 0
  4. lda <= 0
  5. lda < k+1
  6. incx = 0
  7. incy = 0

Example 1

This example shows how to use SSBMV to perform the matrix-vector product, where the real symmetric band matrix A of order 7 and half band width of 3 is stored in upper-band-packed storage mode. Matrix A is: 

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

Call Statement and Input
            UPLO  N   K  ALPHA  A  LDA  X  INCX  BETA   Y  INCY
             |    |   |    |    |   |   |   |     |     |   |
CALL SSBMV( 'U' , 7 , 3 , 2.0 , A , 5 , X , 1  , 10.0 , Y , 2  )
 
        *                                   *
        |  .    .    .   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)
Y        =  (1.0, . , 2.0, . , 3.0, . , 4.0, . , 5.0, . , 6.0, . , 7.0)

Output
Y        =  (30.0, . , 78.0, . , 148.0, . , 244.0, . , 288.0, . ,
             316.0, . , 322.0)

Example 2

This example shows how to use CHBMV to perform the matrix-vector product, where the complex Hermitian band matrix A of order 7 and half band width of 3 is stored in lower-band-packed storage mode. Matrix A is: 


        *                                                                                     *
        |  (1.0, 0.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) |
        | (1.0, -1.0)  (2.0, 0.0)  (2.0, 2.0)  (2.0, 2.0)  (2.0, 2.0)  (0.0, 0.0)  (0.0, 0.0) |
        | (1.0, -1.0) (2.0, -2.0)  (3.0, 0.0)  (3.0, 3.0)  (3.0, 3.0)  (3.0, 3.0)  (0.0, 0.0) |
        | (1.0, -1.0) (2.0, -2.0) (3.0, -3.0)  (4.0, 0.0)  (4.0, 4.0)  (4.0, 4.0)  (4.0, 4.0) |
        |  (0.0, 0.0) (2.0, -2.0) (3.0, -3.0) (4.0, -4.0)  (5.0, 0.0)  (5.0, 5.0)  (5.0, 5.0) |
        |  (0.0, 0.0)  (0.0, 0.0) (3.0, -3.0) (4.0, -4.0) (5.0, -5.0)  (6.0, 0.0)  (6.0, 6.0) |
        |  (0.0, 0.0)  (0.0, 0.0)  (0.0, 0.0) (4.0, -4.0) (5.0, -5.0) (6.0, -6.0)  (7.0, 0.0) |
        *                                                                                     *
Note:
The imaginary parts of the diagonal elements of a complex Hermitian matrix are assumed to be zero, so you do not need to set these values.

Call Statement and Input
            UPLO  N   K   ALPHA   A  LDA  X  INCX  BETA   Y  INCY
             |    |   |     |     |   |   |   |     |     |   |
CALL CHBMV( 'L' , 7 , 3 , ALPHA , A , 5 , X , 1  , BETA , Y , 2  )
 
ALPHA    =  (2.0, 0.0)
BETA     =  (10.0, 0.0)



        *                                                                             *
        |  (1.0, . )  (2.0, . )  (3.0, . )  (4.0, . )  (5.0, . )  (6.0, . ) (7.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)     .     |
A    =  | (1.0, 1.0) (2.0, 2.0) (3.0, 3.0) (4.0, 4.0) (5.0, 5.0)   .            .     |
        | (1.0, 1.0) (2.0, 2.0) (3.0, 3.0) (4.0, 4.0)   .          .            .     |
        |     .          .          .          .        .          .            .     |
        *                                                                             *

X        =  ((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))
Y        =  ((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))

Output
Y        =  ((48.0, 12.0), . , (124.0, 32.0), . , (228.0, 68.0), . ,
             (360.0, 128.0), . , (360.0, 216.0), . ,
             (300.0, 332.0), . , (168.0, 476.0))

Example 3

This example shows how to use SSBMV to perform the matrix-vector product, where n >= k. Matrix A is a real 5 by 5 symmetric band matrix with a half band width of 5, stored in upper-band-packed storage mode. Matrix A is: 

                       *                         *
                       | 1.0  1.0  1.0  1.0  1.0 |
                       | 1.0  2.0  2.0  2.0  2.0 |
                       | 1.0  2.0  3.0  3.0  3.0 |
                       | 1.0  2.0  3.0  4.0  4.0 |
                       | 1.0  2.0  3.0  4.0  5.0 |
                       *                         *

Call Statement and Input
            UPLO  N   K  ALPHA  A  LDA  X  INCX  BETA   Y  INCY
             |    |   |    |    |   |   |   |     |     |   |
CALL SSBMV( 'U' , 5 , 5 , 2.0 , A , 7 , X , 1  , 10.0 , Y , 2  )
 
        *                         *
        |  .    .    .    .    .  |
        |  .    .    .    .   1.0 |
        |  .    .    .   1.0  2.0 |
A    =  |  .    .   1.0  2.0  3.0 |
        |  .   1.0  2.0  3.0  4.0 |
        | 1.0  2.0  3.0  4.0  5.0 |
        |  .    .    .    .    .  |
        *                         *
 
X        =  (1.0, 2.0, 3.0, 4.0, 5.0)
Y        =  (1.0, . , 2.0, . , 3.0, . , 4.0, . , 5.0, . )

Output
Y        =  (40.0, . , 78.0, . , 112.0, . , 140.0, . , 160.0, . )

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