Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

?gbtrf

Computes the LU factorization of a general m-by-n band matrix.

Syntax

lapack_int LAPACKE_sgbtrf (int matrix_layout , lapack_int m , lapack_int n , lapack_int kl , lapack_int ku , float * ab , lapack_int ldab , lapack_int * ipiv );

lapack_int LAPACKE_dgbtrf (int matrix_layout , lapack_int m , lapack_int n , lapack_int kl , lapack_int ku , double * ab , lapack_int ldab , lapack_int * ipiv );

lapack_int LAPACKE_cgbtrf (int matrix_layout , lapack_int m , lapack_int n , lapack_int kl , lapack_int ku , lapack_complex_float * ab , lapack_int ldab , lapack_int * ipiv );

lapack_int LAPACKE_zgbtrf (int matrix_layout , lapack_int m , lapack_int n , lapack_int kl , lapack_int ku , lapack_complex_double * ab , lapack_int ldab , lapack_int * ipiv );

Include Files

  • mkl.h

Description

The routine forms the LU factorization of a general m-by-n band matrix A with kl non-zero subdiagonals and ku non-zero superdiagonals, that is,

A = P*L*U,

where P is a permutation matrix; L is lower triangular with unit diagonal elements and at most kl non-zero elements in each column; U is an upper triangular band matrix with kl + ku superdiagonals. The routine uses partial pivoting, with row interchanges (which creates the additional kl superdiagonals in U).

NOTE:

This routine supports the Progress Routine feature. See Progress Function for details.

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

m

The number of rows in matrix A; m 0.

n

The number of columns in matrix A; n 0.

kl

The number of subdiagonals within the band of A; kl 0.

ku

The number of superdiagonals within the band of A; ku 0.

ab

Array, size at least max(1, ldab*n) for column-major layout or max(1, ldab*m) for row-major layout.

The array ab contains the matrix A in band storage as described in Band Storage.

ldab

The leading dimension of the array ab. (ldab 2*kl + ku + 1)

Output Parameters

ab

Overwritten with elements of L and U. U is stored as an upper triangular band matrix with kl + ku superdiagonals, and L is stored as a lower triangular band matrix with kl subdiagonals (diagonal unit values are not stored). Since the output array has more nonzero elements than the initial matrix A, there are limitations on the value of ldab and the placement of elements of A in array ab.

See Application Notes below for further details.

ipiv

Array, size at least max(1,min(m, n)). The pivot indices; for 1 i min(m, n) , row i was interchanged with row ipiv(i).

Return Values

This function returns a value info.

If info = 0, the execution is successful.

If info = -i, parameter i had an illegal value.

If info = i, uiiis 0. The factorization has been completed, but U is exactly singular. Division by 0 will occur if you use the factor U for solving a system of linear equations.

Application Notes

The computed L and U are the exact factors of a perturbed matrix A + E, where

|E|  c(kl+ku+1) ε P|L||U|

c(k) is a modest linear function of k, and ε is the machine precision.

The total number of floating-point operations for real flavors varies between approximately 2n(ku+1)kl and 2n(kl+ku+1)kl. The number of operations for complex flavors is four times greater. All these estimates assume that kl and ku are much less than min(m,n).

As described in Band Storage, storage of a band matrix can be considered in two steps: packing band matrix elements into a matrix AB, then storing the elements in a linear array ab using a full storage scheme. The effect of the ?gbtrf routine on matrix AB is illustrated by this example, for m = n = 6, kl = 2, ku = 1.

  • matrix_layout = LAPACK_COL_MAJOR

    On entry:

    On exit:

  • matrix_layout = LAPACK_ROW_MAJOR

    On entry:

    On exit:

Elements marked * are not used; elements marked + need not be set on entry, but are required by the routine to store elements of U because of fill-in resulting from the row interchanges.

After calling this routine with m = n, you can call the following routines:

gbtrs

to solve A*X = B or AT*X = B or AH*X = B

gbcon

to estimate the condition number of A.