naginterfaces.library.lapackeig.zgebal

naginterfaces.library.lapackeig.zgebal(job, n, a)[source]

zgebal balances a complex general matrix in order to improve the accuracy of computed eigenvalues and/or eigenvectors.

For full information please refer to the NAG Library document for f08nv

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f08/f08nvf.html

Parameters
jobstr, length 1

Indicates whether is to be permuted and/or scaled (or neither).

is neither permuted nor scaled (but values are assigned to , and ).

is permuted but not scaled.

is scaled but not permuted.

is both permuted and scaled.

nint

, the order of the matrix .

acomplex, array-like, shape

The matrix .

Returns
acomplex, ndarray, shape

is overwritten by the balanced matrix. If , is not referenced.

iloint

The values and such that on exit is zero if and or .

If or , and .

ihiint

The values and such that on exit is zero if and or .

If or , and .

scalefloat, ndarray, shape

Details of the permutations and scaling factors applied to . More precisely, if is the index of the row and column interchanged with row and column and is the scaling factor used to balance row and column then

The order in which the interchanges are made is to then to .

Raises
NagValueError
(errno )

On entry, error in parameter .

Constraint: , , or .

(errno )

On entry, error in parameter .

Constraint: .

Notes

zgebal balances a complex general matrix . The term ‘balancing’ covers two steps, each of which involves a similarity transformation of . The function can perform either or both of these steps.

  1. The function first attempts to permute to block upper triangular form by a similarity transformation:

    where is a permutation matrix, and and are upper triangular. Then the diagonal elements of and are eigenvalues of . The rest of the eigenvalues of are the eigenvalues of the central diagonal block , in rows and columns to . Subsequent operations to compute the eigenvalues of (or its Schur factorization) need only be applied to these rows and columns; this can save a significant amount of work if and . If no suitable permutation exists (as is often the case), the function sets and , and is the whole of .

  2. The function applies a diagonal similarity transformation to , to make the rows and columns of as close in norm as possible:

    This scaling can reduce the norm of the matrix (i.e., ) and hence reduce the effect of rounding errors on the accuracy of computed eigenvalues and eigenvectors.

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore