IBM Books

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

STBSV, DTBSV, CTBSV, and ZTBSV--Triangular Band Equation Solve

STBSV and DTBSV solve one of the following triangular banded systems of equations with a single right-hand side, using the vector x and triangular band matrix A or its transpose:

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

CTBSV and ZTBSV solve one of the following triangular banded systems of equations with a single right-hand side, using the vector x and triangular band matrix A, its transpose, or its conjugate transpose:

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

Matrix A can be either upper or lower triangular and is stored in upper- or lower-triangular-band-packed storage mode, respectively.

Table 116. Data Types

A, x Subprogram
Short-precision real STBSV
Long-precision real DTBSV
Short-precision complex CTBSV
Long-precision complex ZTBSV

Syntax

Fortran CALL STBSV | DTBSV | CTBSV | ZTBSV (uplo, trans, diag, n, k, a, lda, x, incx)
C and C++ stbsv | dtbsv | ctbsv | ztbsv (uplo, trans, diag, n, k, a, lda, x, incx);
PL/I CALL STBSV | DTBSV | CTBSV | ZTBSV (uplo, trans, diag, n, k, a, lda, x, incx);

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

trans
indicates the form of matrix A used in the system of equations, where:

If trans = 'N', A is used, resulting in solution 1.

If trans = 'T', AT is used, resulting in solution 2.

If trans = 'C', AH is used, resulting in solution 3.

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. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 116.

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, containing the right-hand side of the triangular system to be solved. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 116.

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

On Return

x
is the solution 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 116.

Notes
  1. These subroutines accept lowercase letters for the uplo, trans, and diag arguments.
  2. For STBSV and DTBSV, if you specify 'C' for the trans 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. 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, and you do not need to set these values in the array.
  5. For both upper and lower triangular band matrices, if you specify k >= n, ESSL assumes, for purposes of the computation only, 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 a11 and all other elements in the array specified for A, as described in Triangular Band Matrix. For an illustration of this technique, see Example 3.
  6. 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.
  7. If you are using a lower triangular band matrix, it may save your program some time if you 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 solve a triangular banded system of equations with a single right-hand side. The solution, x, may be any of the following, where triangular band matrix A, its transpose, or its conjugate transpose is used, and where A can be either upper- or lower-triangular:

1. x<--A-1x
2. x<--A-Tx
3. x<--A-Hx (for CTBSV and ZTBSV 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. n < 0
  2. k < 0
  3. lda <= 0
  4. lda < k+1
  5. incx = 0
  6. uplo <> 'L' or 'U'
  7. trans <> 'T', 'N', or 'C'
  8. diag <> 'N' or 'U'

Example 1

This example shows the solution x<--A-1x. Matrix A is a real 9 by 9 upper triangular band matrix with an upper band width of 2 that is not unit triangular, stored in upper-triangular-band-packed storage mode. Vector x is a vector of length 9, where matrix A is: 

             *                                             *
             | 1.0  1.0  1.0  0.0  0.0  0.0  0.0  0.0  0.0 |
             | 0.0  4.0  2.0  3.0  0.0  0.0  0.0  0.0  0.0 |
             | 0.0  0.0  4.0  1.0  1.0  0.0  0.0  0.0  0.0 |
             | 0.0  0.0  0.0  4.0  2.0  2.0  0.0  0.0  0.0 |
             | 0.0  0.0  0.0  0.0  3.0  1.0  1.0  0.0  0.0 |
             | 0.0  0.0  0.0  0.0  0.0  3.0  2.0  2.0  0.0 |
             | 0.0  0.0  0.0  0.0  0.0  0.0  3.0  1.0  0.0 |
             | 0.0  0.0  0.0  0.0  0.0  0.0  0.0  2.0  2.0 |
             | 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  1.0 |
             *                                             *

Call Statement and Input
            UPLO TRANS  DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL STBSV( 'U' , 'N' , 'N' , 9 , 2 , A , 3 , X , 1  )

        *                                             *
        |  .    .   1.0  3.0  1.0  2.0  1.0  2.0  0.0 |
A    =  |  .   1.0  2.0  1.0  2.0  1.0  2.0  1.0  2.0 |
        | 1.0  4.0  4.0  4.0  3.0  3.0  3.0  2.0  1.0 |
        *                                             *
 
X        =  (2.0, 7.0, 1.0, 8.0, 2.0, 8.0, 1.0, 8.0, 3.0)

Output
X        =  (1.0, 1.0, 0.0, 1.0, 0.0, 2.0, 0.0, 1.0, 3.0)

Example 2

This example shows the solution x<--A-Tx, solving the same system as in Example 1. Matrix A is a real 9 by 9 lower triangular band matrix with a lower band width of 2 that is not unit triangular, stored in lower-triangular-band-packed storage mode. Vector x is a vector of length 9 where matrix A is: 

             *                                             *
             | 1.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0 |
             | 1.0  4.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0 |
             | 1.0  2.0  4.0  0.0  0.0  0.0  0.0  0.0  0.0 |
             | 0.0  3.0  1.0  4.0  0.0  0.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 |
             | 0.0  0.0  0.0  2.0  1.0  3.0  0.0  0.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  0.0  0.0  0.0  2.0  1.0  2.0  0.0 |
             | 0.0  0.0  0.0  0.0  0.0  0.0  0.0  2.0  1.0 |
             *                                             *

Call Statement and Input
            UPLO TRANS  DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL STBSV( 'L' , 'T' , 'N' , 9 , 2 , A , 3 , X , 1  )

        *                                             *
        | 1.0  4.0  4.0  4.0  3.0  3.0  3.0  2.0  1.0 |
A    =  | 1.0  2.0  1.0  2.0  1.0  2.0  1.0  2.0   .  |
        | 1.0  3.0  1.0  2.0  1.0  2.0  0.0   .    .  |
        *                                             *

X = (same as input X in Example 1)

Output

X = (same as output X in Example 1)

Example 3

This example shows the solution x<--A-Tx, where k > n. Matrix A is a real 4 by 4 upper triangular band matrix with an upper band width of 3, even though k is specified as 5. It is not unit triangular and is stored in upper-triangular-band-packed storage mode. Vector x is a vector of length 4 where matrix A is: 

                          *                    *
                          | 1.0  2.0  3.0  2.0 |
                          | 0.0  2.0  2.0  5.0 |
                          | 0.0  0.0  3.0  3.0 |
                          | 0.0  0.0  0.0  1.0 |
                          *                    *

Call Statement and Input
            UPLO TRANS  DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL STBSV( 'U' , 'T' , 'N' , 4 , 5 , A , 6 , X , 1  )

        *                    *
        |  .    .    .    .  |
        |  .    .    .    .  |
A    =  |  .    .    .   2.0 |
        |  .    .   3.0  5.0 |
        |  .   2.0  2.0  3.0 |
        | 1.0  2.0  3.0  1.0 |
        *                    *
 
X        =  (5.0, 18.0, 32.0, 41.0)

Output
X        =  (5.0, 4.0, 3.0, 2.0)

Example 4

This example shows the solution x<--A-Tx. Matrix A is a complex 7 by 7 lower triangular band matrix with a lower 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, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) |
      | (1.0, 2.0) (2.0, 1.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) |
      | (1.0, 3.0) (2.0, 2.0) (3.0, 1.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) |
      | (1.0, 4.0) (2.0, 3.0) (3.0, 3.0) (4.0, 1.0) (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) |
      | (0.0, 0.0) (2.0, 4.0) (3.0, 3.0) (4.0, 2.0) (2.0, 1.0) (0.0, 0.0) (0.0, 0.0) |
      | (0.0, 0.0) (0.0, 0.0) (3.0, 3.0) (4.0, 3.0) (5.0, 1.0) (3.0, 1.0) (0.0, 0.0) |
      | (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (4.0, 4.0) (5.0, 2.0) (6.0, 1.0) (2.0, 1.0) |
      *                                                                              *

Call Statement and Input
            UPLO TRANS  DIAG  N   K   A  LDA  X  INCX
             |     |     |    |   |   |   |   |   |
CALL CTBSV( 'L' , 'T' , 'N' , 7 , 3 , A , 4 , X , 1  )



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

X        =  ((2.0, 2.0), (7.0, 1.0), (1.0, 1.0), (8.0, 1.0),
             (2.0, 0.0), (8.0, 1.0), (1.0, 2.0))

Output
X        =  ((-12.048, -13.136), (6.304, -1.472), (-1.880, 1.040),
             (2.600, -1.800), (-2.160, 1.880), (0.800, -1.400),
             (0.800, 0.600))

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