Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/31/2023
Public

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

Document Table of 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 Ai, j = 0 and Bi, 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 Pj is the index of the row interchanged with row j, and Dj is the scaling factor applied to row j, then

lscale[j - 1] = Pj, for j = 1,..., ilo-1

= Dj, for j = ilo,...,ihi

= Pj, for j = ihi+1,..., n.

rscale contains details of the permutations and scaling factors applied to the right side of A and B.

If Pj is the index of the column interchanged with column j, and Dj is the scaling factor applied to column j, then

rscale[j - 1] = Pj, for j = 1,..., ilo-1

= Dj, for j = ilo,...,ihi

= Pj, 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.