Developer Reference for Intel® oneAPI Math Kernel Library for C
?gbtrf
Computes the LU factorization of a general m -by- n band matrix.
Syntax
lapack_intLAPACKE_sgbtrf ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , float*ab , lapack_intldab , lapack_int*ipiv );
lapack_intLAPACKE_dgbtrf ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , double*ab , lapack_intldab , lapack_int*ipiv );
lapack_intLAPACKE_cgbtrf ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , lapack_complex_float*ab , lapack_intldab , lapack_int*ipiv );
lapack_intLAPACKE_zgbtrf ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , lapack_complex_double*ab , lapack_intldab , lapack_int*ipiv );
Include Files
mkl.h
Description
sgbtrf dgbtrf cgbtrf zgbtrf gbtrf
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 ).
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 , \(U_{ii}\) is 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.
LAPACK 95 Interface Notes
There exist FORTRAN 77 and FORTRAN 95 interfaces for this routine. See the Intel® oneMKL Fortran Developer Reference for details.
Application Notes
The computed \(L\) and \(U\) are the exact factors of a perturbed matrix \(A\) + \(E\) , where
\[|E| \leq c(kl+ku+1) \varepsilon P|L||U|\]
c(k) is a modest linear function of k , and \(\varepsilon\) 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:
\[AB = \begin{pmatrix} * & * & * & + & + & + \\ * & * & + & + & + & + \\ * & a_{1,2} & a_{2,3} & a_{3,4} & a_{4,5} & a_{5,6} \\ a_{1,1} & a_{2,2} & a_{3,3} & a_{4,4} & a_{5,5} & a_{6,6} \\ a_{2,1} & a_{3,2} & a_{4,3} & a_{5,4} & a_{6,5} & * \\ a_{3,1} & a_{4,2} & a_{5,3} & a_{6,4} & * & * \end{pmatrix}\]
\[AB = \begin{pmatrix} * & * & * & u_{1,4} & u_{2,5} & u_{3,6} \\ * & * & u_{1,3} & u_{2,4} & u_{3,5} & u_{4,6} \\ * & u_{1,2} & u_{2,3} & u_{3,4} & u_{4,5} & u_{5,6} \\ u_{1,1} & u_{2,2} & u_{3,3} & u_{4,4} & u_{5,5} & u_{6,6} \\ l_{2,1} & l_{3,2} & l_{4,3} & l_{5,4} & l_{6,5} & * \\ l_{3,1} & l_{4,2} & l_{5,3} & l_{6,4} & * & * \end{pmatrix}\]
matrix_layout = LAPACK_ROW_MAJOR
On entry:
On exit:
\[AB = \begin{pmatrix} * & * & a_{1,1} & a_{1,2} & + & + \\ * & a_{2,1} & a_{2,2} & a_{2,3} & + & + \\ a_{3,1} & a_{3,2} & a_{3,3} & a_{3,4} & + & + \\ a_{4,2} & a_{4,3} & a_{4,4} & a_{4,5} & * & * \\ a_{5,3} & a_{5,4} & a_{5,5} & a_{5,6} & * & * \\ a_{6,4} & a_{6,5} & a_{6,6} & * & * & * \end{pmatrix}\]
\[AB = \begin{pmatrix} * & * & u_{1,1} & u_{1,2} & u_{1,3} & u_{1,4} \\ * & l_{2,1} & u_{2,2} & u_{2,3} & u_{2,4} & u_{2,5} \\ l_{3,1} & l_{3,2} & u_{3,3} & u_{3,4} & u_{3,5} & u_{3,6} \\ l_{4,2} & l_{4,3} & u_{4,4} & u_{4,5} & u_{4,6} & * \\ l_{5,3} & l_{5,4} & u_{5,5} & u_{5,6} & * & * \\ l_{6,4} & l_{6,5} & u_{6,6} & * & * & * \end{pmatrix}\]
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 (Solves a system of linear equations with an LU-factored band coefficient matrix, with multiple right-hand sides.)
to solve \(A X = B\) or \(A^{T}X = B\) or \(A^{H}X = B\)
gbcon (Estimates the reciprocal of the condition number of a band matrix in the 1-norm or the infinity-norm.)
to estimate the condition number of \(A\) .