naginterfaces.library.lapackeig.dgeesx

naginterfaces.library.lapackeig.dgeesx(jobvs, sort, sense, a, select=None, data=None)

dgeesx computes the eigenvalues, the real Schur form $T$, and, optionally, the matrix of Schur vectors $Z$ for an $n\times n$ real nonsymmetric matrix $A$.

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

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

Parameters

jobvsstr, length 1

If $jobvs=\text{'N'}$, Schur vectors are not computed.

If $jobvs=\text{'V'}$, Schur vectors are computed.

sortstr, length 1

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

$sort=\text{'N'}$

Eigenvalues are not ordered.

$sort=\text{'S'}$

Eigenvalues are ordered (see $select$).

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 right invariant subspace only.

$sense=\text{'B'}$

Computed for both.

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

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

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

selectNone or callable retval = select(wr, wi, data=None), optional

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

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

An eigenvalue $wr[j-1]+\sqrt{-1}\times wi[j-1]$ is selected if $select\left(wr\right[j-1],wi[j-1\left]\right)$ is $True$.

If either one of a complex conjugate pair of eigenvalues is selected, then both are.

Note that a selected complex eigenvalue may no longer satisfy $select\left(wr\right[j-1],wi[j-1\left]\right)=True$ after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case $\text{errno}$ is set to $n+2$.

Parameters

wrfloat

The real and imaginary parts of the eigenvalue.

wifloat

The real and imaginary parts of the eigenvalue.

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$ is overwritten by its real Schur form $T$.

sdimint

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

If $sort=\text{'S'}$, $sdim=$ number of eigenvalues (after sorting) for which $select$ is $True$. (Complex conjugate pairs for which $select$ is $True$ for either eigenvalue count as $2$.)

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

See the description of $wi$.

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

$wr$ and $wi$ contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form $T$. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.

vsfloat, ndarray, shape $(:,:)$

If $jobvs=\text{'V'}$, $vs$ contains the orthogonal matrix $Z$ of Schur vectors.

If $jobvs=\text{'N'}$, $vs$ is not referenced.

rcondefloat

If $sense=\text{'E'}$ or $\text{'B'}$, contains the reciprocal condition number for the average of the selected eigenvalues.

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

rcondvfloat

If $sense=\text{'V'}$ or $\text{'B'}$, $rcondv$ contains the reciprocal condition number for the selected right invariant subspace.

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

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobvs$.

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

(errno $-2$)

On entry, error in parameter $sort$.

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

(errno $-4$)

On entry, error in parameter $sense$.

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

(errno $-5$)

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

Constraint: $n\ge 0$.

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

The $QR$ algorithm failed to compute all the eigenvalues.

Warns

NagAlgorithmicWarning

(errno $n+1$)

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

(errno $n+2$)

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

Notes

The real Schur factorization of $A$ is given by

$$A=ZT{Z}^T\text{,}$$

where $Z$, the matrix of Schur vectors, is orthogonal and $T$ is the real Schur form. A matrix is in real Schur form if it is upper quasi-triangular with $1\times 1$ and $2\times 2$ blocks. $2\times 2$ blocks will be standardized in the form

$$\begin{array}{c}\left[\begin{array}{cc}a& b\\ c& a\end{array}\right]\end{array}$$

where $bc<0$. The eigenvalues of such a block are $a\pm \sqrt{bc}$.

Optionally, dgeesx also orders the eigenvalues on the diagonal of the real Schur form so that selected eigenvalues are at the top left; computes a reciprocal condition number for the average of the selected eigenvalues ($rconde$); and computes a reciprocal condition number for the right invariant subspace corresponding to the selected eigenvalues ($rcondv$). The leading columns of $Z$ form an orthonormal basis for this invariant subspace.

For further explanation of the reciprocal condition numbers $rconde$ and $rcondv$, see Section 4.8 of Anderson et al. (1999) (where these quantities are called $s$ and $\text{sep}$ respectively).

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