naginterfaces.library.lapackeig.zgges3

naginterfaces.library.lapackeig.zgges3(jobvsl, jobvsr, sort, n, a, b, selctg=None, data=None)

zgges3 computes the generalized eigenvalues, the generalized Schur form $(S,T)$ and, optionally, the left and/or right generalized Schur vectors for a pair of $n\times n$ complex nonsymmetric matrices $(A,B)$.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xqf.html

Parameters

jobvslstr, length 1

If $jobvsl=\text{'N'}$, do not compute the left Schur vectors.

If $jobvsl=\text{'V'}$, compute the left Schur vectors.

jobvsrstr, length 1

If $jobvsr=\text{'N'}$, do not compute the right Schur vectors.

If $jobvsr=\text{'V'}$, compute the right Schur vectors.

sortstr, length 1

Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

$sort=\text{'N'}$

Eigenvalues are not ordered.

$sort=\text{'S'}$

Eigenvalues are ordered (see $selctg$).

nint

$n$, the order of the matrices $A$ and $B$.

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

The first of the pair of matrices, $A$.

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

The second of the pair of matrices, $B$.

selctgNone or callable retval = selctg(a, b, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

If $sort=\text{'S'}$, $selctg$ is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

Parameters

acomplex

An eigenvalue $a[j-1]/b[j-1]$ is selected if $selctg\left(a\right[j-1],b[j-1\left]\right)$ is $True$.

Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy $selctg\left(a\right[j-1],b[j-1\left]\right)=True$ after ordering. $errno$ = $n$ + 2 in this case.

bcomplex

An eigenvalue $a[j-1]/b[j-1]$ is selected if $selctg\left(a\right[j-1],b[j-1\left]\right)$ is $True$.

Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy $selctg\left(a\right[j-1],b[j-1\left]\right)=True$ after ordering. $errno$ = $n$ + 2 in this case.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalbool

Must be $True$ if the eigenvalue is to be selected.

dataarbitrary, optional

User-communication data for callback functions.

Returns

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

$a$ has been overwritten by its generalized Schur form $S$.

bcomplex, ndarray, shape $(n,n)$

$b$ has been overwritten by its generalized Schur form $T$.

sdimint

If $sort=\text{'N'}$, $sdim=0$.

If $sort=\text{'S'}$, $sdim=$ number of eigenvalues (after sorting) for which $selctg$ is $True$.

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

See the description of $beta$.

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

$alpha[\text{j}-1]/beta[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$, will be the generalized eigenvalues. $alpha[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$ and $beta[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$, are the diagonals of the complex Schur form $(A,B)$ output by zgges3. The $beta[j-1]$ will be non-negative real.

Note: the quotients $alpha[j-1]/beta[j-1]$ may easily overflow or underflow, and $beta[j-1]$ may even be zero.

Thus, you should avoid naively computing the ratio $\alpha /\beta$.

However, $alpha$ will always be less than and usually comparable with ${\parallel A\parallel }_2$ in magnitude, and $beta$ will always be less than and usually comparable with ${\parallel B\parallel }_2$.

vslcomplex, ndarray, shape $(:,:)$

If $jobvsl=\text{'V'}$, $vsl$ will contain the left Schur vectors, $Q$.

If $jobvsl=\text{'N'}$, $vsl$ is not referenced.

vsrcomplex, ndarray, shape $(:,:)$

If $jobvsr=\text{'V'}$, $vsr$ will contain the right Schur vectors, $Z$.

If $jobvsr=\text{'N'}$, $vsr$ is not referenced.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobvsl$.

Constraint: $jobvsl=\text{'N'}$ or $\text{'V'}$.

(errno $-2$)

On entry, error in parameter $jobvsr$.

Constraint: $jobvsr=\text{'N'}$ or $\text{'V'}$.

(errno $-3$)

On entry, error in parameter $sort$.

Constraint: $sort=\text{'N'}$ or $\text{'S'}$.

(errno $-5$)

On entry, error in parameter $n$.

Constraint: $n\ge 0$.

(errno $n+1$)

The $QZ$ iteration failed with an unexpected error, please contact NAG.

Warns

NagAlgorithmicWarning

(errno $n+2$)

After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy $selctg=True$. This could also be caused by underflow due to scaling.

(errno $n+3$)

The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

(errno $i<n$)

The $QZ$ iteration did not converge and the matrix pair $(A,B)$ is not in the generalized Schur form. The computed ${\alpha }_i$ and ${\beta }_i$ should be correct for $i=⟨value⟩,\dots ,⟨value⟩$.

Notes

The generalized Schur factorization for a pair of complex matrices $(A,B)$ is given by

$$A=QS{Z}^H\text{,}B=QT{Z}^H\text{,}$$

where $Q$ and $Z$ are unitary, $T$ and $S$ are upper triangular. The generalized eigenvalues, $\lambda$, of $(A,B)$ are computed from the diagonals of $T$ and $S$ and satisfy

$$Az=\lambda Bz\text{,}$$

where $z$ is the corresponding generalized eigenvector. $\lambda$ is actually returned as the pair $(\alpha ,\beta )$ such that

$$\lambda =\alpha /\beta$$

since $\beta$, or even both $\alpha$ and $\beta$ can be zero. The columns of $Q$ and $Z$ are the left and right generalized Schur vectors of $(A,B)$.

Optionally, zgges3 can order the generalized eigenvalues on the diagonals of $(S,T)$ so that selected eigenvalues are at the top left. The leading columns of $Q$ and $Z$ then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

zgges3 computes $T$ to have real non-negative diagonal entries. The generalized Schur factorization, before reordering, is computed by the $QZ$ algorithm.

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore