Arguments

A

(input/output) REAL or COMPLEX square array, shape $(:,:)$.
On entry, the matrix $A$.
On exit, A has been overwritten. If the left, the right or both generalized eigenvectors are computed, then A contains the first part of the real/complex Schur form of the "balanced" versions of the matrix pair ($A,B$).

B

(input/output) REAL or COMPLEX square array, shape $(:,:)$ with $size({\bf B},1) = size({\bf A},1)$.
On entry, the matrix $B$.
On exit, B has been overwritten. If the left, the right or both generalized eigenvectors are computed, then B contains the second part of the real/complex Schur form of the "balanced" versions of the matrix pair ($A,B$).

alpha

(output) REAL or COMPLEX array, shape $(:)$ with $size({\it alpha}) = size({\bf A},1)$.
The values of $\alpha$.
${\it alpha}(:)$ ::= ALPHAR(:), ALPHAI(:) $\mid$ ALPHA(:),
where
ALPHAR(:), ALPHAI(:) are of REAL type (for the real and imaginary parts) and ALPHA(:) is of COMPLEX type.

BETA

(output) REAL or COMPLEX array, shape $(:)$ with $size$(BETA) $= size$(A,1).
The values of $\beta$.
Note: The generalized eigenvalues of the pair $( A, B )$ are the scalars $\lambda_j = \alpha_j/\beta_j$. These quotients may easily over- or underflow, and $\beta_j$ may even be zero. Thus, the user should avoid computing them naively.
Note: If A and B are real then complex eigenvalues occur in complex conjugate pairs. Each pair is stored consecutively. Thus a complex conjugate pair is given by

$$\begin{array}{l} \lambda_j = ( {\bf ALPHAR}_j\,+\, i\, {\bf ... ...+1}\,+\, i\, {\bf ALPHAI}_{j+1})/{\bf BETA}_{j+1} \end{array}$$

where

$$\frac{{\bf ALPHAI}_j}{{\bf BETA}_j} = - \frac{{\bf ALPHAI}_{j+1}}{{\bf BETA}_{j+1}}$$

VL

Optional (output) REAL or COMPLEX square array, shape $(:,:)$ with $size$(VL, 1) $=$ $size$(A, 1).
The left generalized eigenvectors $u_j$ are stored in the columns of VL in the order of their eigenvalues. Each eigenvector is scaled so the largest component has $\mid real part\mid + \mid imag. part\mid = 1$, except that for eigenvalues with $\alpha = \beta = 0$, a zero vector is returned as the corresponding eigenvector.
Note: If $A$ and $B$ are real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VL$_{:,j}$ and VL$_{:,j+1}$. Thus a complex conjugate pair is given by

$$u_j = {\bf VL}_{:,j}\,+\,i\, {\bf VL}_{:,j+1}\,,\;\;\; u_{j+1} = {\bf VL}_{:,j}\,-\,i\, {\bf VL}_{:,j+1}$$

VR

Optional (output) REAL or COMPLEX square array, shape $(:,:)$ with $size$(VR, 1) $=$ $size$(A, 1).
The right generalized eigenvectors $v_j$ are stored in the columns of VR in the order of their eigenvalues. Each eigenvector is scaled so the largest component has $\mid real part\mid + \mid imag. part\mid = 1$, except that for eigenvalues with $\alpha = \beta = 0$, a zero vector is returned as the corresponding eigenvector.
Note: If $A$ and $B$ are real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VR$_{:,j}$ and VR$_{:,j+1}$. Thus a complex conjugate pair is given by

$$v_j = {\bf VR}_{:,j}\,+\,i\, {\bf VR}_{:,j+1}\,,\;\;\; v_{j+1} = {\bf VR}_{:,j}\,-\,i\, {\bf VR}_{:,j+1}$$

BALANC

Optional (input) CHARACTER(LEN=1).
Specifies the balance option to be performed.


Default value: 'N'.
Note: Computed reciprocal condition numbers will be for the matrices after balancing. Permuting does not change condition numbers (in exact arithmetic), but scaling does.

ILO,IHI

Optional (output) INTEGER.
ILO and IHI are integer values such that on exit ${\bf A}_{i,j} = 0$ and ${\bf B}_{i,j} = 0$ if $i > j$ and $j = 1, \dots, {\bf ILO}-1$ or $i = {\bf IHI}+1,\dots ,n$.
If BALANC = 'N' or 'S', then ${\bf ILO} = 1$ and ${\bf IHI} = n$.

LSCALE

Optional (output) REAL array, shape $(:)$ with $size({\bf LSCALE}) = size({\bf A},1)$.
Details of the permutations and scaling factors applied to the left side of $A$ and $B$. If $PL_j$ is the index of the row interchanged with row $j$, and $DL_j$ is the scaling factor applied to row $j$, then

$$PL_j = {\bf LSCALE}_j, \;\;\; j = 1, \dots ,{\bf ILO}-1 \; \mbox{ and } \; {\bf IHI}+1,\dots ,n$$

and

$$DL_j = {\bf LSCALE}_j, \;\;\; j = {\bf ILO}, \dots ,{\bf IHI}$$

.

RSCALE

Optional (output) REAL array, shape $(:)$, $size({\bf RSCALE}) = size({\bf A},1)$.
Details of the permutations and scaling factors applied to the right side of $A$ and $B$. If $PR_j$ is the index of the column interchanged with column $j$, and $DR_j$ is the scaling factor applied to column $j$, then

$$PR_j = {\bf RSCALE}_j, \;\;\; j = 1, \dots ,{\bf ILO}-1 \; \mbox{ and } \; {\bf IHI}+1,\dots ,n$$

and

$$DR_j = {\bf RSCALE}_j, \;\;\; j = {\bf ILO}, \dots ,{\bf IHI}$$

.

ABNRM

Optional (output) REAL.
The $l_1$ norm of $A$ after balancing.

BBNRM

Optional (output) REAL.
The $l_1$ norm of $B$ after balancing.

RCONDE

Optional (output) REAL array, shape $(:)$ with $size({\bf RCONDE}) = size({\bf A},1)$.
The reciprocal condition numbers of the eigenvalues.

RCONDV

Optional (output) REAL array, shape $(:)$ with $size({\bf RCONDE}) = size({\bf A},1)$.
The estimated reciprocal condition numbers of the right eigenvectors. If the eigenvalues cannot be reordered to compute RCONDV$_j$ then RCONDV$_j$ is set to $0$. This can only occur when the true value would be very small.

INFO

Optional (output) INTEGER.


If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17,9,20,21].