Developer Reference for Intel® oneAPI Math Kernel Library for C
?gbequ
Computes row and column scaling factors intended to equilibrate a banded matrix and reduce its condition number.
Syntax
lapack_int LAPACKE_sgbequ ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , const float*ab , lapack_intldab , float*r , float*c , float*rowcnd , float*colcnd , float*amax );
lapack_int LAPACKE_dgbequ ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , const double*ab , lapack_intldab , double*r , double*c , double*rowcnd , double*colcnd , double*amax );
lapack_int LAPACKE_cgbequ ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , const lapack_complex_float*ab , lapack_intldab , float*r , float*c , float*rowcnd , float*colcnd , float*amax );
lapack_int LAPACKE_zgbequ ( intmatrix_layout , lapack_intm , lapack_intn , lapack_intkl , lapack_intku , const lapack_complex_double*ab , lapack_intldab , double*r , double*c , double*rowcnd , double*colcnd , double*amax );
Include Files
mkl.h
Description
sgbequ dgbequ cgbequ zgbequ gbequ
The routine computes row and column scalings intended to equilibrate an m -by- n band matrix A and reduce its condition number. The output array r returns the row scale factors and the array c the column scale factors. These factors are chosen to try to make the largest element in each row and column of the matrix B with elements b_{ij}=r(i)*a_{ij}*c(j)b_{ij}=r[i - 1]*a_{ij}*c[j - 1] have absolute value 1.
See ?laqgb (Scales a general band matrix, using row and column scaling factors computed by ?gbequ.) auxiliary function that uses scaling factors computed by ?gbequ .
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 of the matrix A ; m≥ 0 .
n
The number of columns of the 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 max(1, ldab * n ) for column major layout and max(1, ldab * m ) for row major layout . Contains the original band matrix A .
ldab
The leading dimension of ab ; ldab ≥ kl + ku +1.
Output Parameters
r , c
Arrays: r (size m ), c (size n ).
If info = 0 , or info>m , the array r contains the row scale factors of the matrix A .
If info = 0 , the array c contains the column scale factors of the matrix A .
rowcnd
If info = 0 or info>m , rowcnd contains the ratio of the smallest r(i)r[i] to the largest r(i)r[i] .
colcnd
If info = 0 , colcnd contains the ratio of the smallest c(i)c[i] to the largest c(i)c[i] .
amax
Absolute value of the largest element of the matrix A .
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 and
i≤m , the i -th row of A is exactly zero;
i>m , the ( i - m )th column of A is exactly zero.
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
All the components of r and c are restricted to be between SMLNUM = smallest safe number and BIGNUM = largest safe number. Use of these scaling factors is not guaranteed to reduce the condition number of \(A\) but works well in practice.
?lamch (Determines machine parameters for floating-point arithmetic.)
SMLNUM = slamch ('s')
BIGNUM = 1 / SMLNUMIf rowcnd≥ 0.1 and amax is neither too large nor too small, it is not worth scaling by r .
If colcnd≥ 0.1 , it is not worth scaling by c .
If amax is very close to SMLNUM or very close to BIGNUM , the matrix \(A\) should be scaled.