Developer Reference for Intel® oneAPI Math Kernel Library for C
?geequ
Computes row and column scaling factors intended to equilibrate a general matrix and reduce its condition number.
Syntax
lapack_int LAPACKE_sgeequ ( intmatrix_layout , lapack_intm , lapack_intn , const float*a , lapack_intlda , float*r , float*c , float*rowcnd , float*colcnd , float*amax );
lapack_int LAPACKE_dgeequ ( intmatrix_layout , lapack_intm , lapack_intn , const double*a , lapack_intlda , double*r , double*c , double*rowcnd , double*colcnd , double*amax );
lapack_int LAPACKE_cgeequ ( intmatrix_layout , lapack_intm , lapack_intn , const lapack_complex_float*a , lapack_intlda , float*r , float*c , float*rowcnd , float*colcnd , float*amax );
lapack_int LAPACKE_zgeequ ( intmatrix_layout , lapack_intm , lapack_intn , const lapack_complex_double*a , lapack_intlda , double*r , double*c , double*rowcnd , double*colcnd , double*amax );
Include Files
mkl.h
Description
sgeequ dgeequ cgeequ zgeequ geequ
The routine computes row and column scalings intended to equilibrate an m -by- n 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 ?laqge (Scales a general rectangular matrix, using row and column scaling factors computed by ?geequ.) auxiliary function that uses scaling factors computed by ?geequ .
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 .
a
Array: size max(1, lda * n ) for column major layout and max(1, lda * m ) for row major layout .
Contains the m -by- n matrix A whose equilibration factors are to be computed.
lda
The leading dimension of a ; lda≥ max(1, m) .
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 , i > 0 , 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.