naginterfaces.library.lapackeig.ztrevc

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

ztrevc computes selected left and/or right eigenvectors of a complex upper triangular matrix.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qxf.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.

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

The $n\times n$ upper triangular matrix $T$, as returned by zhseqr().

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 eigenvector corresponding to the eigenvalue ${\lambda }_j$, $select[j-1]$ must be set $True$.

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

vlNone or complex, 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 zhseqr()).

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

vrNone or complex, 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 zhseqr()).

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

Returns

tcomplex, ndarray, shape $(n,n)$

Is used as internal workspace prior to being restored and hence is unchanged.

vlNone or complex, 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.

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

vrNone or complex, 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.

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

mint

$\text{m}$, the number of selected 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

ztrevc computes left and/or right eigenvectors of a complex upper triangular matrix $T$. Such a matrix arises from the Schur factorization of a complex general matrix, as computed by zhseqr(), 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}^{H}y=\overline{\lambda }y)\text{.}$$

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 a unitary matrix from the Schur factorization of a matrix $A$ as $A=QT{Q}^H$; 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 $max\left(\left|Re\left(x_i\right)\right|+\left|Im\left(x_i\right)\right|\right)=1$.

References

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