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

SGBF and DGBF--General Band Matrix Factorization

These subroutines factor general band matrix A, stored in general-band storage mode, using Gaussian elimination. 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 SGBS or DGBS, respectively.

Table 105. Data Types

A	Subroutine
Short-precision real	SGBF
Long-precision real	DGBF

Note:: The output from these factorization subroutines should be used only as input to the solve subroutines SGBS and DGBS, respectively.

Syntax

Fortran	CALL SGBF \| DGBF (`agb`, `lda`, `n`, `ml`, `mu`, `ipvt`)
C and C++	sgbf \| dgbf (`agb`, `lda`, `n`, `ml`, `mu`, `ipvt`);
PL/I	CALL SGBF \| DGBF (`agb`, `lda`, `n`, `ml`, `mu`, `ipvt`);

On Entry

agb: is the general band matrix A of order n, stored in general-band storage mode, to be factored. It has an upper band width mu and a lower band width ml. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 105, where lda >= 2ml+mu+16.
lda: is the leading dimension of the array specified for agb. Specified as: a fullword integer; lda > 0 and lda >= 2ml+mu+16.
n: is the order of the matrix A. Specified as: a fullword integer; n > ml and n > mu.
ml: is the lower band width ml of the matrix A. Specified as: a fullword integer; 0 <= ml < n.
mu: is the upper band width mu of the matrix A. Specified as: a fullword integer; 0 <= mu < n.
ipvt: See On Return.

On Return

agb: 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 105.
ipvt: is the integer vector ipvt of length n, containing the pivot information necessary to construct matrix L from the information contained in the output array agb. Returned as: a one-dimensional array of (at least) length n, containing fullword integers.

Notes

ipvt is not a permutation vector in the strict sense. It is used to record column interchanges in L due to partial pivoting and to improve performance.
The entire lda by n array specified for agb must remain unchanged between calls to the factorization and solve subroutines.
This subroutine can be used for tridiagonal matrices (ml = mu = 1); however, the tridiagonal subroutines SGTF/DGTF and SGTS/DGTS are faster.
For a description of how a general band matrix is stored in general-band storage mode in an array, see General Band Matrix.

Function

The general band matrix A, stored in general-band storage mode, is factored using Gaussian elimination with partial pivoting to compute the LU factorization of A, where:

ipvt is a vector containing the pivoting information.

L is a unit lower triangular band matrix.

U is an upper triangular band matrix.

The transformed matrix A contains U in packed format, along with the multipliers necessary to construct, with the help of ipvt, a matrix L, such that A = LU. This factorization can then be used by SGBS or DGBS, respectively, to solve the system of equations. See reference [38].

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

Matrix A is singular.

One or more columns of L and the corresponding diagonal of U contain all zeros (all columns of L are checked). The last column, i, of L with a corresponding U = 0 diagonal element 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 2103 in the ESSL error option table; otherwise, the default value causes your program to terminate when this error occurs. For details, see What Can You Do about ESSL Computational Errors?.

Input-Argument Errors

lda <= 0
ml < 0
ml >= n
mu < 0
mu >= n
lda < 2ml+mu+16

Example

This example shows a factorization of a general band matrix A of order 9, with a lower band width of 2 and an upper band width of 3. On input matrix A is:

            *                                                *
            | 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 |
            | 4.0  1.0  1.0  1.0  1.0  1.0   0.0   0.0   0.0 |
            | 0.0  5.0  1.0  1.0  1.0  1.0   1.0   0.0   0.0 |
            | 0.0  0.0  6.0  1.0  1.0  1.0   1.0   1.0   0.0 |
            | 0.0  0.0  0.0  7.0  1.0  1.0   1.0   1.0   1.0 |
            | 0.0  0.0  0.0  0.0  8.0  1.0   1.0   1.0   1.0 |
            | 0.0  0.0  0.0  0.0  0.0  9.0   1.0   1.0   1.0 |
            | 0.0  0.0  0.0  0.0  0.0  0.0  10.0  11.0  12.0 |
            *                                                *

Matrix A is stored in general-band storage mode in the two-dimensional array AGB of size LDA by N, where LDA = 2ml+mu+16 = 23. The array AGB is declared as AGB(1:23,1:9).

Note:: Matrix A is the same matrix used in the examples in subroutines SGEF and DGEF (see Example 1) and SGEFCD and DGEFCD (see Example).

Call Statement and Input

           AGB  LDA   N   ML  MU  IPVT )
            |    |    |   |   |    |
CALL SGBF( AGB , 23 , 9 , 2 , 3 , IPVT )

        *                                                                           *
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  1.0000  1.0000  1.0000   1.0000   1.0000   1.0000 |
        | 0.0000  0.0000  1.0000  1.0000  1.0000  1.0000   1.0000   1.0000   1.0000 |
        | 0.0000  1.0000  1.0000  1.0000  1.0000  1.0000   1.0000   1.0000   1.0000 |
        | 1.0000  1.0000  1.0000  1.0000  1.0000  1.0000   1.0000   1.0000  12.0000 |
        | 1.0000  1.0000  1.0000  1.0000  1.0000  1.0000   1.0000  11.0000   0.0000 |
        | 4.0000  5.0000  6.0000  7.0000  8.0000  9.0000  10.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
AGB  =  | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000 |
        *                                                                           *

Output

        *                                                                             *
        | 0.0000  0.0000  0.0000  0.0000   0.0000   1.0000   1.0000   1.0000   1.0000 |
        | 0.0000  0.0000  0.0000  0.0000   1.0000   1.0000   1.0000   1.0000   1.0000 |
        | 0.0000  0.0000  0.0000  1.0000   1.0000   1.0000   1.0000   1.0000   1.0000 |
        | 0.0000  0.0000  1.0000  1.0000   1.0000   1.0000   1.0000   1.0000  12.0000 |
        | 0.0000  1.0000  1.0000  1.0000   1.0000   1.0000   1.0000  11.0000   0.3111 |
        | 0.2500  0.2000  0.1600  0.1400   0.1250   0.1100   0.1000   5.5380  -325.00 |
        | 0.0000  0.1500  0.0000  0.0714   0.0000  -0.0556  -0.0306   0.9385   0.0000 |
        | 0.2500  0.1500  0.1000  0.0714  -0.0714  -0.0694  -0.0194   0.0000   0.0000 |
        | 0.2500  0.0000  0.1000  0.0000   0.0536   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
AGB  =  | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000   0.0000   0.0000   0.0000 |
        *                                                                             *

IPVT     =  (2, -65534, -131070, -196606, -262142, -327678, -327678,
             -327680, -327680)

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