naginterfaces.library.lapackeig.zggesx

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

zggesx 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)$.

Estimates of condition numbers for selected generalized eigenvalue clusters and Schur vectors are also computed.

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f08/f08xpf.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$).

sensestr, length 1

Determines which reciprocal condition numbers are computed.

$sense=\text{'N'}$

None are computed.

$sense=\text{'E'}$

Computed for average of selected eigenvalues only.

$sense=\text{'V'}$

Computed for selected deflating subspaces only.

$sense=\text{'B'}$

Computed for both.

If $sense=\text{'E'}$, $\text{'V'}$ or $\text{'B'}$, $sort=\text{'S'}$.

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[j-1]$ and $beta[j-1],j=1,2,\dots ,n$ are the diagonals of the complex Schur form $(S,T)$. $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$ in magnitude, and $beta$ will always be less than and usually comparable with $\parallel b\parallel$.

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.

rcondefloat, ndarray, shape $\left(2\right)$

If $sense=\text{'E'}$ or $\text{'B'}$, $rconde\left[0\right]$ and $rconde\left[1\right]$ contain the reciprocal condition numbers for the average of the selected eigenvalues.

If $sense=\text{'N'}$ or $\text{'V'}$, $rconde$ is not referenced.

rcondvfloat, ndarray, shape $\left(2\right)$

If $sense=\text{'V'}$ or $\text{'B'}$, $rcondv\left[0\right]$ and $rcondv\left[1\right]$ contain the reciprocal condition numbers for the selected deflating subspaces.

if $sense=\text{'N'}$ or $\text{'E'}$, $rcondv$ 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 $sense$.

Constraint: $sense=\text{'N'}$, $\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.

(errno $-6$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

(errno $n+1$)

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

Warns

NagAlgorithmicWarning

(errno $(i>0)\text{and}(i\le n)$)

The $QZ$ iteration failed. $(A,B)$ are not in Schur form, but $alpha\left[j\right]$ and $beta\left[j\right]$ should be correct from element $⟨value⟩$.

(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).

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, zggesx 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.

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

The reciprocals of the condition estimates, the reciprocal values of the left and right projection norms, are returned in $rconde\left[0\right]$ and $rconde\left[1\right]$ respectively, for the selected generalized eigenvalues, together with reciprocal condition estimates for the corresponding left and right deflating subspaces, in $rcondv\left[0\right]$ and $rcondv\left[1\right]$. See Section 4.11 of Anderson et al. (1999) for further information.

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, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore