naginterfaces.library.lapackeig.dgges3

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

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

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

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

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

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

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

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

selctgNone or callable retval = selctg(ar, ai, 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

arfloat

An eigenvalue $\left(ar\right[j-1]+\sqrt{-1}\times ai[j-1\left]\right)/b[j-1]$ is selected if $selctg\left(ar\right[j-1],ai[j-1],b[j-1\left]\right)=True$. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

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

aifloat

An eigenvalue $\left(ar\right[j-1]+\sqrt{-1}\times ai[j-1\left]\right)/b[j-1]$ is selected if $selctg\left(ar\right[j-1],ai[j-1],b[j-1\left]\right)=True$. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

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

bfloat

An eigenvalue $\left(ar\right[j-1]+\sqrt{-1}\times ai[j-1\left]\right)/b[j-1]$ is selected if $selctg\left(ar\right[j-1],ai[j-1],b[j-1\left]\right)=True$. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy $selctg\left(ar\right[j-1],ai[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

afloat, ndarray, shape $(n,n)$

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

bfloat, 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$. (Complex conjugate pairs for which $selctg$ is $True$ for either eigenvalue count as $2$.)

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

See the description of $beta$.

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

See the description of $beta$.

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

$\left(alphar\right[\text{j}-1]+alphai[\text{j}-1]\times i)/beta[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$, will be the generalized eigenvalues. $alphar[\text{j}-1]+alphai[\text{j}-1]\times i$, and $beta[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$, are the diagonals of the complex Schur form $(S,T)$ that would result if the $2\times 2$ diagonal blocks of the real Schur form of $(A,B)$ were further reduced to triangular form using $2\times 2$ complex unitary transformations.

If $alphai[j-1]$ is zero, then the $j$th eigenvalue is real; if positive, then the $j$th and $(j+1)$st eigenvalues are a complex conjugate pair, with $alphai\left[j\right]$ negative.

Note: the quotients $alphar[j-1]/beta[j-1]$ and $alphai[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, $alphar$ and $alphai$ 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$.

vslfloat, ndarray, shape $(:,:)$

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

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

vsrfloat, 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 $\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. No eigenvectors have been calculated but $alphar\left[j\right]$, $alphai\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 real matrices $(A,B)$ is given by

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

where $Q$ and $Z$ are orthogonal, $T$ is upper triangular and $S$ is upper quasi-triangular with $1\times 1$ and $2\times 2$ diagonal blocks. The generalized eigenvalues, $\lambda$, of $(A,B)$ are computed from the diagonals of $S$ and $T$ 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, dgges3 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.

dgges3 computes $T$ to have non-negative diagonal elements, and the $2\times 2$ blocks of $S$ correspond to complex conjugate pairs of generalized eigenvalues. 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