naginterfaces.library.lapackeig.zgebal

naginterfaces.library.lapackeig.zgebal(job, n, a)

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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08nvf.html

Parameters

jobstr, length 1

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

$job=\text{'N'}$

$A$ is neither permuted nor scaled (but values are assigned to $ilo$, $ihi$ and $scale$).

$job=\text{'P'}$

$A$ is permuted but not scaled.

$job=\text{'S'}$

$A$ is scaled but not permuted.

$job=\text{'B'}$

$A$ is both permuted and scaled.

nint

$n$, the order of the matrix $A$.

acomplex, array-like, shape $(n,n)$

The $n\times n$ matrix $A$.

Returns

acomplex, ndarray, shape $(n,n)$

$a$ is overwritten by the balanced matrix. If $job=\text{'N'}$, $a$ is not referenced.

iloint

The values $i_{lo}$ and $i_{hi}$ such that on exit $a[i-1,j-1]$ is zero if $i>j$ and $1\le j<i_{lo}$ or $i_{hi}<i\le n$.

If $job=\text{'N'}$ or $\text{'S'}$, $i_{lo}=1$ and $i_{hi}=n$.

ihiint

The values $i_{lo}$ and $i_{hi}$ such that on exit $a[i-1,j-1]$ is zero if $i>j$ and $1\le j<i_{lo}$ or $i_{hi}<i\le n$.

If $job=\text{'N'}$ or $\text{'S'}$, $i_{lo}=1$ and $i_{hi}=n$.

scalefloat, ndarray, shape $\left(n\right)$

Details of the permutations and scaling factors applied to $A$. 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

$$\begin{array}{c}scale[j-1]=\{\begin{array}{cc}{p}_j\text{,}& j=1,2,\dots ,i_{lo}-1\\ d_j\text{,}& j=i_{lo},i_{lo}+1,\dots ,i_{hi}\text{and}\\ p_j\text{,}& j=i_{hi}+1,i_{hi}+2,\dots ,n\text{.}\end{array}\end{array}$$

The order in which the interchanges are made is $n$ to $i_{hi}+1$ then $1$ to $i_{lo}-1$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $job$.

Constraint: $job=\text{'N'}$, $\text{'P'}$, $\text{'S'}$ or $\text{'B'}$.

(errno $-2$)

On entry, error in parameter $n$.

Constraint: $n\ge 0$.

Notes

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

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

   $$\begin{array}{c}PA{P}^T=A^{\prime }=\left(\begin{array}{ccc}{A}_{11}^{\prime }& A_{12}^{\prime }& A_{13}^{\prime }\\ 0& A_{22}^{\prime }& A_{23}^{\prime }\\ 0& 0& A_{33}^{\prime }\end{array}\right)\end{array}$$

   where $P$ is a permutation matrix, and $A_{11}^{\prime }$ and $A_{33}^{\prime }$ are upper triangular. Then the diagonal elements of $A_{11}^{\prime }$ and $A_{33}^{\prime }$ are eigenvalues of $A$. The rest of the eigenvalues of $A$ are the eigenvalues of the central diagonal block $A_{22}^{\prime }$, in rows and columns $i_{lo}$ to $i_{hi}$. 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 $i_{lo}>1$ and $i_{hi}<n$. If no suitable permutation exists (as is often the case), the function sets $i_{lo}=1$ and $i_{hi}=n$, and $A_{22}^{\prime }$ is the whole of $A$.

2. The function applies a diagonal similarity transformation to $A^{\prime }$, to make the rows and columns of $A_{22}^{\prime }$ as close in norm as possible:

   $$\begin{array}{c}{A}^{\prime \prime }=D{A}^{\prime }{D}^{-1}=\left(\begin{array}{ccc}I& 0& 0\\ 0& D_{22}& 0\\ 0& 0& I\end{array}\right)\left(\begin{array}{ccc}{A}_{11}^{\prime }& A_{12}^{\prime }& A_{13}^{\prime }\\ 0& A_{22}^{\prime }& A_{23}^{\prime }\\ 0& 0& A_{33}^{\prime }\end{array}\right)\left(\begin{array}{ccc}I& 0& 0\\ 0& D_{22}^{-1}& 0\\ 0& 0& I\end{array}\right)\text{.}\end{array}$$

   This scaling can reduce the norm of the matrix (i.e., $\Vert A_{22}^{\prime \prime }\Vert <\Vert A_{22}^{\prime }\Vert$) 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