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

SPBF, DPBF, SPBCHF, and DPBCHF--Positive Definite Symmetric Band Matrix Factorization

These subroutines factor positive definite symmetric band matrix A, stored in lower-band-packed storage mode, using:

• Gaussian elimination for SPBF and DPBF
• Cholesky factorization for SPBCHF and DPBCHF

To solve the system of equations with one or more right-hand sides, follow the call to these subroutines with one or more calls to SPBS, DPBS, SPBCHS, or DPBCHS, respectively.

Table 107. Data Types

Notes:

1. The output from these factorization subroutines should be used only as input to the solve subroutines SPBS, DPBS, SPBCHS, and DPBCHS, respectively.

2. For optimal performance:
   • For wide band widths, use _PBCHF.
   • For narrow band widths, use either _PBF or _PBCHF.
   • For very narrow band widths:
     • Use either SPBF or SPBCHF.
     • Use DPBF.

Syntax

On Entry

apb

is the positive definite symmetric band matrix A of order n, stored in lower-band-packed storage mode, to be factored. It has a half band width of m. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 107. See Notes.

lda

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

n

is the order n of matrix A. Specified as: a fullword integer; n > m.

m

is the half band width of the matrix A. Specified as: a fullword integer; 0 <= m < n.

On Return

apb

is the transformed matrix A of order n, containing the results of the factorization. See Function. Returned as: an lda by (at least) n array, containing numbers of the data type indicated in Table 107. For further details, see Notes.

Notes

1. These subroutines can be used for tridiagonal matrices (m = 1); however, the tridiagonal subroutines, SPTF/DPTF and SPTS/DPTS, are faster.
2. For SPBF and DPBF when m > 0, location APB(2,n) is sometimes set to 0.
3. For a description of how a positive definite symmetric band matrix is stored in lower-band-packed storage mode in an array, see Positive Definite Symmetric Band Matrix.

Function

The positive definite symmetric band matrix A, stored in lower-band-packed storage mode, is factored using Gaussian elimination in SPBF and DPBF and Cholesky factorization in SPBCHF and DPBCHF. The transformed matrix A contains the results of the factorization in packed format. This factorization can then be used by SPBS, DPBS, SPBCHS, and DPBCHS, respectively, to solve the system of equations.

For performance reasons, divides are done in a way that reduces the effective exponent range for which DPBF works properly, when processing narrow band widths; therefore, you may want to scale your problem.

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

1. Matrix A is not positive definite (for SPBF and DPBF).
   • One or more elements of D contain values less than or equal to 0; all elements of D are checked. The index i of the last nonpositive element encountered is identified in the computational error message.
   • The return code is set to 1.
   • i can be determined at run time by use of the ESSL error-handling facilities. To obtain this information, you must use ERRSET to change the number of allowable errors for error code 2104 in the ESSL error option table; otherwise, the default value causes your program to terminate when this error occurs. For details, see Chapter 4, Coding Your Program.
2. Matrix A is not positive definite (for SPBCHF and DPBCHF).
   • The leading minor of order i has a nonpositive determinant. The order i is identified in the computational error message.
   • The return code is set to 1.
   • i can be determined at run time by using the ESSL error-handling facilities. To obtain this information, you must use ERRSET to change the number of allowable errors for error code 2115 in the ESSL error option table; otherwise, the default value causes your program to be terminate when this error occurs. For details, see Chapter 4, Coding Your Program.

Input-Argument Errors

1. lda <= 0
2. m < 0
3. m >= n
4. m >= lda

Example 1

This example shows a factorization of a real positive definite symmetric band matrix A of order 9, using Gaussian elimination, where on input, matrix A is:

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

and on output, matrix A is:

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

where array location APB(2,9) is set to 0.0.

Call Statement and Input

           APB  LDA  N   M
            |    |   |   |
CALL SPBF( APB , 3 , 9 , 2 )
 
        *                                             *
        | 1.0  2.0  3.0  3.0  3.0  3.0  3.0  3.0  3.0 |
APB  =  | 1.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0   .  |
        | 1.0  1.0  1.0  1.0  1.0  1.0  1.0   .    .  |
        *                                             *

Output

        *                                             *
        | 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0 |
APB  =  | 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  0.0 |
        | 1.0  1.0  1.0  1.0  1.0  1.0  1.0   .    .  |
        *                                             *

Example 2

This example shows a Cholesky factorization of the same matrix used in Example 1.

Call Statement and Input

             APB  LDA  N   M
              |    |   |   |
CALL SPBCHF( APB , 3 , 9 , 2 )

Output

        *                                             *
        | 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0 |
APB  =  | 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0   .  |
        | 1.0  1.0  1.0  1.0  1.0  1.0  1.0   .    .  |
        *                                             *