Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

?ggbal

Balances a pair of general real or complex matrices.

Syntax

lapack_int LAPACKE_sggbal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
float*
a
,
lapack_int
lda
,
float*
b
,
lapack_int
ldb
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
lscale
,
float*
rscale
);
lapack_int LAPACKE_dggbal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
double*
a
,
lapack_int
lda
,
double*
b
,
lapack_int
ldb
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
lscale
,
double*
rscale
);
lapack_int LAPACKE_cggbal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
lapack_complex_float*
a
,
lapack_int
lda
,
lapack_complex_float*
b
,
lapack_int
ldb
,
lapack_int*
ilo
,
lapack_int*
ihi
,
float*
lscale
,
float*
rscale
);
lapack_int LAPACKE_zggbal
(
int
matrix_layout
,
char
job
,
lapack_int
n
,
lapack_complex_double*
a
,
lapack_int
lda
,
lapack_complex_double*
b
,
lapack_int
ldb
,
lapack_int*
ilo
,
lapack_int*
ihi
,
double*
lscale
,
double*
rscale
);
Include Files
  • mkl.h
Description
The routine balances a pair of general real/complex matrices (
A
,
B
). This involves, first, permuting
A
 and
B
 by similarity transformations to isolate eigenvalues in the first 1 to
ilo
-1 and last
ihi
+1 to
n
 elements on the diagonal;and second, applying a diagonal similarity transformation to rows and columns
ilo
 to
ihi
 to make the rows and columns as close in norm as possible. Both steps are optional. Balancing may reduce the 1-norm of the matrices, and improve the accuracy of the computed eigenvalues and/or eigenvectors in the generalized eigenvalue problem
A
*
x
 =
λ
*
B
*
x
.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
job
Specifies the operations to be performed on
A
 and
B
. Must be
'N'
 or
'P'
 or
'S'
 or
'B'
.
If
job
 =
'N '
, then no operations are done; simply set
ilo
 =1
,
ihi
=
n
,
lscale
[
i
]
 =1.0
 and
rscale
[
i
]
=1.0
 for
i
 = 0,...,
n
 - 1
.
If
job
 =
'P'
, then permute only.
If
job
 =
'S'
, then scale only.
If
job
 =
'B'
, then both permute and scale.
n
The order of the matrices
A
 and
B
 (
n
≥
 0).
a
,
b
Arrays:
a
(size max(1,
lda
*
n
))
 contains the matrix
A
.
b
(size max(1,
ldb
*
n
))
 contains the matrix
B
.
If
job
 =
'N'
,
a
 and
b
 are not referenced.
lda
The leading dimension of
a
; at least max(1,
n
).
ldb
The leading dimension of
b
; at least max(1,
n
).
Output Parameters
a
,
b
Overwritten by the balanced matrices
A
 and
B
, respectively.
ilo
,
ihi
ilo
 and
ihi
 are set to integers such that on exit
A
i
,
j
 = 0 and
B
i
,
j
 = 0 if
i
>
j
 and
j
=1,...,
ilo
-1
 or
i
=
ihi
+1,...,
n
.
If
job
 =
'N'
or
'S'
, then
ilo
 = 1
 and
ihi
 =
n
.
lscale
,
rscale
Arrays, size at least max(1,
n
).
lscale
 contains details of the permutations and scaling factors applied to the left side of
A
 and
B
.
If
P
j
 is the index of the row interchanged with row
j
, and
D
j
 is the scaling factor applied to row
j
, then
lscale
[
j
 - 1]
 =
P
j
, for
j
 = 1,...,
ilo
-1
=
D
j
, for
j
 =
ilo
,...,
ihi
=
P
j
, for
j
 =
ihi
+1,...,
n
.
rscale
 contains details of the permutations and scaling factors applied to the right side of
A
 and
B
.
If
P
j
 is the index of the column interchanged with column
j
, and
D
j
 is the scaling factor applied to column
j
, then
rscale
[
j
 - 1]
 =
P
j
, for
j
 = 1,...,
ilo
-1
=
D
j
, for
j
 =
ilo
,...,
ihi
=
P
j
, for
j
 =
ihi
+1,...,
n
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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.