Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

?gebal

Balances a general matrix to improve the accuracy of computed eigenvalues and eigenvectors.

Syntax

lapack_int LAPACKE_sgebal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
float*
a
,
lapack_int
lda
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
scale
);
lapack_int LAPACKE_dgebal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
double*
a
,
lapack_int
lda
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
scale
);
lapack_int LAPACKE_cgebal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
lapack_complex_float*
a
,
lapack_int
lda
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
scale
);
lapack_int LAPACKE_zgebal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
lapack_complex_double*
a
,
lapack_int
lda
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
scale
);
Include Files
  • mkl.h
Description
The routine
balances
a matrix
A
by performing either or both of the following two similarity transformations:
(1) The routine first attempts to permute
A
to block upper triangular form:
Equation
where
P
is a permutation matrix, and
A'
11
and
A'
33
are upper triangular. The diagonal elements of
A'
11
and
A'
33
are eigenvalues of
A
. The rest of the eigenvalues of
A
are the eigenvalues of the central diagonal block
A'
22
, in rows and columns
ilo
to
ihi
. Subsequent operations to compute the eigenvalues of
A
(or its Schur factorization) need only be applied to these rows and columns; this can save a significant amount of work if
ilo
> 1
and
ihi
<
n
.
If no suitable permutation exists (as is often the case), the routine sets
ilo
= 1
and
ihi
=
n
, and
A'
22
is the whole of
A
.
(2) The routine applies a diagonal similarity transformation to
A'
, to make the rows and columns of
A'
22
as close in norm as possible:
Equation
This scaling can reduce the norm of the matrix (that is,
||
A''
22
|| < ||
A'
22
||
), and hence reduce the effect of rounding errors on the accuracy of computed eigenvalues and eigenvectors.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
job
Must be
'N'
or
'P'
or
'S'
or
'B'
.
If
job
=
'N'
, then
A
is neither permuted nor scaled (but
ilo
,
ihi
, and
scale
get their values).
If
job
=
'P'
, then
A
is permuted but not scaled.
If
job
=
'S'
, then
A
is scaled but not permuted.
If
job
=
'B'
, then
A
is both scaled and permuted.
n
The order of the matrix
A
(
n
0
).
a
Array
a
(size max(1,
lda
*
n
))
contains the matrix
A
.
lda
The leading dimension of
a
; at least max(1,
n
).
Output Parameters
a
Overwritten by the balanced matrix (
a
is not referenced if
job
=
'N'
).
ilo
,
ihi
The values
ilo
and
ihi
such that on exit
a
(
i,j
) is zero if
i
>
j
and
1
j
<
ilo
or
ihi
<
j
n
.
If
job
=
'N'
or
'S'
, then
ilo
= 1
and
ihi
=
n
.
scale
Array, size at least max(1,
n
).
Contains details of the permutations and scaling factors.
More precisely, if
p
j
is the index of the row and column interchanged with row and column
j
, and
d
j
is the scaling factor used to balance row and column
j
, then
scale
[
j
- 1]
=
p
j
for
j
= 1, 2,...,
ilo
-1,
ihi
+1,...,
n
;
scale
[
j
- 1]
=
d
j
for
j
=
ilo
,
ilo
+ 1,...,
ihi
.
The order in which the interchanges are made is
n
to
ihi
+1, then 1 to
ilo
-1.
Return Values
This function returns a value
info
.
If
info
=0
, the execution is successful.
If
info
=
-i
, the
i
-th parameter had an illegal value.
Application Notes
The errors are negligible, compared with those in subsequent computations.
If the matrix
A
is balanced by this routine, then any eigenvectors computed subsequently are eigenvectors of the matrix
A''
and hence you must call gebak to transform them back to eigenvectors of
A
.
If the Schur vectors of
A
are required, do not call this routine with
job
=
'S'
or
'B'
, because then the balancing transformation is not orthogonal (not unitary for complex flavors).
If you call this routine with
job
=
'P'
, then any Schur vectors computed subsequently are Schur vectors of the matrix
A''
, and you need to call gebak (with
side
=
'R'
) to transform them back to Schur vectors of
A
.
The total number of floating-point operations is proportional to
n
2
.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804