?gbtrf

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 3/22/2024

Version

Public

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

Visible to Intel only — GUID: GUID-03E2AA41-0886-485D-B0D7-1C2186119220

View Details

?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, ldabn) for column-major layout or max(1, ldabm) 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

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_iiis 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 `AX = B` or `A^TX = B` or `A^H*X = B`
gbcon	to estimate the condition number of `A`.

Parent topic: Matrix Factorization: LAPACK Computational Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?gbtrf

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values

Application Notes

See Also

On entry:	On exit:

On entry:	On exit: