naginterfaces.library.lapackeig.dtrevc

naginterfaces.library.lapackeig.dtrevc(job, howmny, t, select=None, vl=None, vr=None)

dtrevc computes selected left and/or right eigenvectors of a real upper quasi-triangular matrix.

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

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

Parameters

jobstr, length 1

Indicates whether left and/or right eigenvectors are to be computed.

$job=\text{'R'}$

Only right eigenvectors are computed.

$job=\text{'L'}$

Only left eigenvectors are computed.

$job=\text{'B'}$

Both left and right eigenvectors are computed.

howmnystr, length 1

Indicates how many eigenvectors are to be computed.

$howmny=\text{'A'}$

All eigenvectors (as specified by $job$) are computed.

$howmny=\text{'B'}$

All eigenvectors (as specified by $job$) are computed and then pre-multiplied by the matrix $Q$ (which is overwritten).

$howmny=\text{'S'}$

Selected eigenvectors (as specified by $job$ and $select$) are computed.

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

The $n\times n$ upper quasi-triangular matrix $T$ in canonical Schur form, as returned by dhseqr().

selectNone or bool, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $howmny=\text{'S'}$: $n$; otherwise: $1$.

Specifies which eigenvectors are to be computed if $howmny=\text{'S'}$. To obtain the real eigenvector corresponding to the real eigenvalue ${\lambda }_j$, $select[j-1]$ must be set $True$. To select the complex eigenvector corresponding to a complex conjugate pair of eigenvalues ${\lambda }_j$ and ${\lambda }_{j+1}$, $select[j-1]$ and/or $select\left[j\right]$ must be set $True$; the eigenvector corresponding to the first eigenvalue in the pair is computed.

vlNone or float, array-like, shape $(:,:)$, optional

Note: the required extent for this argument in dimension 1 is determined as follows: if $job\text{in}(\text{'L'},\text{'B'})$: $n$; if $job=\text{'R'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $job\text{in}(\text{'L'},\text{'B'})$: $\text{mm}$; otherwise: $0$.

If $howmny=\text{'B'}$ and $job=\text{'L'}$ or $\text{'B'}$, $vl$ must contain an $n\times n$ matrix $Q$ (usually the matrix of Schur vectors returned by dhseqr()).

If $howmny=\text{'A'}$ or $\text{'S'}$, $vl$ need not be set.

vrNone or float, array-like, shape $(:,:)$, optional

Note: the required extent for this argument in dimension 1 is determined as follows: if $job\text{in}(\text{'R'},\text{'B'})$: $n$; if $job=\text{'L'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $job\text{in}(\text{'R'},\text{'B'})$: $\text{mm}$; otherwise: $0$.

If $howmny=\text{'B'}$ and $job=\text{'R'}$ or $\text{'B'}$, $vr$ must contain an $n\times n$ matrix $Q$ (usually the matrix of Schur vectors returned by dhseqr()).

If $howmny=\text{'A'}$ or $\text{'S'}$, $vr$ need not be set.

Returns

selectNone or bool, ndarray, shape $(:)$

If a complex eigenvector was selected as specified above, $select[j-1]$ is set to $True$ and $select\left[j\right]$ to $False$.

If $howmny=\text{'A'}$ or $\text{'B'}$, $select$ is not referenced.

vlNone or float, ndarray, shape $(:,:)$

If $job=\text{'L'}$ or $\text{'B'}$, $vl$ contains the computed left eigenvectors (as specified by $howmny$ and $select$). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two columns; the first column holds the real part and the second column holds the imaginary part.

If $job=\text{'R'}$, $vl$ is not referenced.

vrNone or float, ndarray, shape $(:,:)$

If $job=\text{'R'}$ or $\text{'B'}$, $vr$ contains the computed right eigenvectors (as specified by $howmny$ and $select$). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two columns; the first column holds the real part and the second column holds the imaginary part.

If $job=\text{'L'}$, $vr$ is not referenced.

mint

$\text{m}$, the number of columns of $vl$ and/or $vr$ actually used to store the computed eigenvectors. If $howmny=\text{'A'}$ or $\text{'B'}$, $m$ is set to $n$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $job$.

Constraint: $job=\text{'R'}$, $\text{'L'}$ or $\text{'B'}$.

(errno $-2$)

On entry, error in parameter $howmny$.

Constraint: $howmny=\text{'A'}$, $\text{'B'}$, $\text{'O'}$ or $\text{'S'}$.

(errno $-4$)

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

Constraint: $n\ge 0$.

(errno $-11$)

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

Constraint: $\text{mm}\ge n$.

(errno $-11$)

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

Constraint: $\text{mm}\ge \text{m}$.

Notes

dtrevc computes left and/or right eigenvectors of a real upper quasi-triangular matrix $T$ in canonical Schur form. Such a matrix arises from the Schur factorization of a real general matrix, as computed by dhseqr(), for example.

The right eigenvector $x$, and the left eigenvector $y$, corresponding to an eigenvalue $\lambda$, are defined by:

$$Tx=\lambda x\text{and}{y}^{H}T=\lambda y^H(\text{or}{T}^{T}y=\overline{\lambda }y)\text{.}$$

Note that even though $T$ is real, $\lambda$, $x$ and $y$ may be complex. If $x$ is an eigenvector corresponding to a complex eigenvalue $\lambda$, then the complex conjugate vector $\overline{x}$ is the eigenvector corresponding to the complex conjugate eigenvalue $\overline{\lambda }$.

The function can compute the eigenvectors corresponding to selected eigenvalues, or it can compute all the eigenvectors. In the latter case the eigenvectors may optionally be pre-multiplied by an input matrix $Q$. Normally $Q$ is an orthogonal matrix from the Schur factorization of a matrix $A$ as $A=QT{Q}^T$; if $x$ is a (left or right) eigenvector of $T$, then $Qx$ is an eigenvector of $A$.

The eigenvectors are computed by forward or backward substitution. They are scaled so that, for a real eigenvector $x$, $max\left(\left|x_i\right|\right)=1$, and for a complex eigenvector, $max(\left|Re\left(x_i\right)\right|+\left|Im\left(x_i\right)\right|)=1$.

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore