SGBTRF, DGBTRF, CGBTRF and ZGBTRF (General Band Matrix Factorization)

Purpose

These subroutines factor general band matrix A, stored in BLAS-general-band storage mode, using Gaussian elimination with partial pivoting.

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 SGBTRS, DGBTRS, CGBTRS, and ZGBTRS respectively.

Table 1. Data Types
A Subroutine
Short-precision real SGBTRFΔ
Long-precision real DGBTRFΔ
Short-precision complex CGBTRFΔ
Long-precision complex ZGBTRFΔ
ΔLAPACK
Note: The output from these factorization subroutines should be used only as input to the solve subroutines SGBTRS, DGBTRS, CGBTRS, and ZGBTRS respectively.

Syntax

Table 2. Syntax for supported computing languages
Language Syntax
Fortran CALL SGBTRF | DGBTRF | CGBTRF | ZGBTRF (m, n, kl, ku, a, lda, ipiv, info)
C and C++ sgbtrf | dgbtrf | cgbtrf | zgbtrf (m, n, kl, ku, a, lda, ipiv, info);
LAPACKE info = LAPACKE_sgbtrf | LAPACKE_dgbtrf | LAPACKE_cgbtrf | LAPACKE_zgbtrf (matrix_layout, m, n, kl, ku, a, lda, ipiv);
On Entry
matrix_layout
indicates whether the input and output matrices are stored in row major order or column major order, where:
  • If matrix_layout = LAPACK_ROW_MAJOR, the matrices are stored in row major order.
  • If matrix_layout = LAPACK_COL_MAJOR, the matrices are stored in column major order.
Specified as: an integer. The value of the matrix_layout argument must be LAPACK_ROW_MAJOR or LAPACK_COL_MAJOR.
m
is the number of rows in matrix A.

Specified as: an integer; m ≥ 0.

n
is the number of columns in matrix A.

Specified as: an integer; n ≥ 0.

kl
is the lower band width kl of the matrix A.
Specified as: an integer; kl ≥ 0.
ku
is the upper band width ku of the matrix A.
Specified as: an integer; ku ≥ 0.
a
is the m by n general band matrix A to be factored.
Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 1.
lda
is the leading dimension of the array specified for A.
Specified as: an integer; lda > 0 and lda ≥ 2kl+ku+1.
ipiv
See "On Return".
info
See "On Return".
On Return
a
is the transformed matrix A containing the results of the factorization. See Function.
Returned as: an lda by (at least) n array, containing integers.
ipiv
is the integer vector of length min(m,n), containing the pivot indices.
Returned as: a one-dimensional integer array of (at least) length min(m,n), containing integers; 1 ≤ ipivj ≤ m for all j.
info
has the following meaning:

If info = 0, the subroutine completed successfully.

If info > 0, info is set to the first i, where Uii is zero. The factorization has been completed.

Returned as:
  • For SGBTRF, DGBTRF, CGBTRF and ZGBTRF, returned as: an integer; info ≥ 0.
  • For LAPACKE_sgbtrf, LAPACKE_dgbtrf, LAPACKE_cgbtrf and LAPACKE_zgbtrf, returned as an integer function value; info ≥ 0.
Note:
  1. In your C program, argument info must be passed by reference.
  2. a and ipiv must have no common elements; otherwise, results are unpredictable.
  3. For a description of how a general band matrix is stored in BLAS-general-band storage mode in an array, see General Band Matrix.
  4. The way these subroutines handle singularity differs from LAPACK. Like LAPACK, these subroutines use the info argument to provide information about the singularity of A, but they also provide an error message.

Function

These subroutines factor general band matrix A, stored in BLAS-general-band storage mode, using Gaussian elimination with partial pivoting to compute the LU factorization of A:

A = PLU

In the formula above:
  • P is the permutation matrix
  • L is a unit lower triangular band matrix
  • U is a upper triangular band matrix

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 SGBTRS, DGBTRS, CGBTRS, and ZGBTRS respectively.

If m or n is 0, no computation is performed and the subroutine returns after doing some parameter checking.

See references [9] and [48].

Error conditions

Resource Errors
None
Computational Errors
Matrix A is singular or nearly singular.
  • The first column, i, of L with a corresponding Uii = 0 diagonal element is identified in the computational error message.
  • The computational error message may occur multiple times with processing continuing after each error, because the default for the number of allowable errors for error code 2146 is set to be unlimited in the ESSL error option table.
Input-Argument Errors
  1. m < 0
  2. n < 0
  3. kl < 0
  4. ku < 0
  5. lda ≤ 0
  6. 2kl + ku + 1 > lda

Examples

Example 1
This example shows a factorization of the following real general band matrix of order 9. Matrix A is:
                                            
     |  1.0 2.0 3.0 4.0 0.0 0.0 0.0 0.0 0.0 |
     |  2.0 1.0 2.0 3.0 4.0 0.0 0.0 0.0 0.0 |
     |  3.0 2.0 1.0 2.0 3.0 4.0 0.0 0.0 0.0 |
     |  0.0 3.0 2.0 1.0 2.0 3.0 4.0 0.0 0.0 |
     |  0.0 0.0 3.0 2.0 1.0 2.0 3.0 4.0 0.0 |
     |  0.0 0.0 0.0 3.0 2.0 1.0 2.0 3.0 4.0 |
     |  0.0 0.0 0.0 0.0 3.0 2.0 1.0 2.0 3.0 |
     |  0.0 0.0 0.0 0.0 0.0 3.0 2.0 1.0 2.0 | 
     |  0.0 0.0 0.0 0.0 0.0 0.0 3.0 2.0 1.0 |
Call Statement and Input: 
             M   N  KL  KU   A  LDA  IPIV   INFO)
             |   |   |   |   |   |     |      |
CALL DGBTRF( 9 , 9 , 2 , 3 , A , 8 , IPIV , INFO)
                                           
     |  .   .   .   .   .   .   .   .   .  |
     |  .   .   .   .   .   .   .   .   .  |
     |  .   .   .  4.0 4.0 4.0 4.0 4.0 4.0 | 
     |  .   .  3.0 3.0 3.0 3.0 3.0 3.0 3.0 | 
 A = |  .  2.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 1.0 1.0 | 
     | 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0  .  |
     | 3.0 3.0 3.0 3.0 3.0 3.0 3.0  .   .  |
Output: 
                                                                   
     |  .      .     .     .      .     4.000  4.000  4.000  4.000 | 
     |  .      .     .     .     3.000  3.000  3.000  3.000 -2.271 | 
     |  .      .     .    2.000  2.000  2.000  2.000 -4.074 -1.747 | 
     |  .      .    1.000 1.000  1.000  1.000 -4.691 -4.177  1.000 | 
 A = |  .     2.000 2.000 2.000  2.000 -4.419 -3.174  2.000  0.927 | 
     | 3.000  3.000 3.000 3.000 -3.617 -5.095  3.000 -1.546  3.037 | 
     | 0.666  0.444 0.518 0.567 -0.334  0.326  0.043 -0.790   .    | 
     | 0.333 -0.111 0.592 0.246 -0.829 -0.588 -0.617   .      .    |
                                                                   

IPIV     =  ( 3, 4, 5, 6, 5, 6, 9, 8, 9 )

INFO = 0
Example 2
This example shows a factorization of the following complex general band matrix of order 5. Matrix A is:
                                                                                       
     |( 0.100, 0.100) ( 1.000, 2.000) ( 1.000, 3.000) ( 0.000, 0.000) ( 0.000, 0.000)  |
     |( 2.000, 1.000) ( 0.200, 0.200) ( 2.000, 3.000) ( 2.000, 4.000) ( 0.000, 0.000)  |
     |( 0.000, 0.000) ( 3.000, 2.000) ( 0.300, 0.300) ( 3.000, 4.000) ( 3.000, 5.000)  | 
     |( 0.000, 0.000) ( 0.000, 0.000) ( 4.000, 3.000) ( 0.400, 0.400) ( 4.000, 5.000)  |
     |( 0.000, 0.000) ( 0.000, 0.000) ( 0.000, 0.000) ( 5.000, 4.000) ( 0.500, 0.500)  |
Call Statement and Input: 
             M   N  KL  KU   A  LDA  IPIV   INFO)
             |   |   |   |   |   |     |      |
CALL ZGBTRF( 5 , 5 , 1 , 2 , A , 5 , IPIV , INFO)
                                                                                        
      |       .               .               .               .               .         |
      |       .               .        ( 1.000, 3.000) ( 2.000, 4.000) ( 3.000, 5.000)  | 
  A = |       .        ( 1.000, 2.000) ( 2.000, 3.000) ( 3.000, 4.000) ( 4.000, 5.000)  | 
      |( 0.100, 0.100) ( 0.200, 0.200) ( 0.300, 0.300) ( 0.400, 0.400) ( 0.500, 0.500)  |
      |( 2.000, 1.000) ( 3.000, 2.000) ( 4.000, 3.000) ( 5.000, 4.000)        .         |
Output: 
                                                                                       
     |       .               .               .        ( 2.000, 4.000) ( 3.000, 5.000)  | 
     |       .               .        ( 2.000, 3.000) ( 3.000, 4.000) ( 4.000, 5.000)  | 
A =  |       .        ( 0.200, 0.200) ( 0.300, 0.300) ( 0.400, 0.400) ( 0.500, 0.500)  | 
     |( 2.000, 1.000) ( 3.000, 2.000) ( 4.000, 3.000) ( 5.000, 4.000) (-0.339,-6.596)  |
     |( 0.060, 0.020) ( 0.534, 0.305) ( 0.443, 0.300) (-0.412,-0.396)        .         |
                                                                                       

IPIV     =  ( 2, 3, 4, 5, 5 )

INFO = 0