F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentF08QXF (ZTREVC)

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

F08QXF (ZTREVC) computes selected left and/or right eigenvectors of a complex upper triangular matrix.

## 2  Specification

 SUBROUTINE F08QXF ( JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, RWORK, INFO)
 INTEGER N, LDT, LDVL, LDVR, MM, M, INFO REAL (KIND=nag_wp) RWORK(N) COMPLEX (KIND=nag_wp) T(LDT,*), VL(LDVL,*), VR(LDVR,*), WORK(2*N) LOGICAL SELECT(*) CHARACTER(1) JOB, HOWMNY
The routine may be called by its LAPACK name ztrevc.

## 3  Description

F08QXF (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 F08PSF (ZHSEQR), for example.
The right eigenvector $x$, and the left eigenvector $y$, corresponding to an eigenvalue $\lambda$, are defined by:
 $Tx = λx and yHT = λyH or ​ THy = λ-y .$
The routine 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}^{\mathrm{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 $\mathrm{max}\phantom{\rule{0.25em}{0ex}}\left|\mathrm{Re}\left({x}_{i}\right)\right|+\left|\mathrm{Im}{x}_{i}\right|=1$.
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## 5  Parameters

1:     JOB – CHARACTER(1)Input
On entry: indicates whether left and/or right eigenvectors are to be computed.
${\mathbf{JOB}}=\text{'R'}$
Only right eigenvectors are computed.
${\mathbf{JOB}}=\text{'L'}$
Only left eigenvectors are computed.
${\mathbf{JOB}}=\text{'B'}$
Both left and right eigenvectors are computed.
Constraint: ${\mathbf{JOB}}=\text{'R'}$, $\text{'L'}$ or $\text{'B'}$.
2:     HOWMNY – CHARACTER(1)Input
On entry: indicates how many eigenvectors are to be computed.
${\mathbf{HOWMNY}}=\text{'A'}$
All eigenvectors (as specified by JOB) are computed.
${\mathbf{HOWMNY}}=\text{'B'}$ or $\text{'O'}$
All eigenvectors (as specified by JOB) are computed and then pre-multiplied by the matrix $Q$ (which is overwritten).
${\mathbf{HOWMNY}}=\text{'S'}$
Selected eigenvectors (as specified by JOB and SELECT) are computed.
Constraint: ${\mathbf{HOWMNY}}=\text{'A'}$, $\text{'B'}$, $\text{'O'}$ or $\text{'S'}$.
3:     SELECT($*$) – LOGICAL arrayInput
Note: the dimension of the array SELECT must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$ if ${\mathbf{HOWMNY}}=\text{'S'}$, and at least $1$ otherwise.
On entry: specifies which eigenvectors are to be computed if ${\mathbf{HOWMNY}}=\text{'S'}$. To obtain the eigenvector corresponding to the eigenvalue ${\lambda }_{j}$, ${\mathbf{SELECT}}\left(j\right)$ must be set .TRUE..
If ${\mathbf{HOWMNY}}=\text{'A'}$, $\text{'O'}$ or $\text{'B'}$, SELECT is not referenced.
4:     N – INTEGERInput
On entry: $n$, the order of the matrix $T$.
Constraint: ${\mathbf{N}}\ge 0$.
5:     T(LDT,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array T must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
On entry: the $n$ by $n$ upper triangular matrix $T$, as returned by F08PSF (ZHSEQR).
On exit: is used as internal workspace prior to being restored and hence is unchanged.
6:     LDT – INTEGERInput
On entry: the first dimension of the array T as declared in the (sub)program from which F08QXF (ZTREVC) is called.
Constraint: ${\mathbf{LDT}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$.
7:     VL(LDVL,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array VL must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{MM}}\right)$ if ${\mathbf{JOB}}=\text{'L'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'R'}$.
On entry: if ${\mathbf{HOWMNY}}=\text{'O'}$ or $\text{'B'}$ and ${\mathbf{JOB}}=\text{'L'}$ or $\text{'B'}$, VL must contain an $n$ by $n$ matrix $Q$ (usually the matrix of Schur vectors returned by F08PSF (ZHSEQR)).
If ${\mathbf{HOWMNY}}=\text{'A'}$ or $\text{'S'}$, VL need not be set.
On exit: if ${\mathbf{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 ${\mathbf{JOB}}=\text{'R'}$, VL is not referenced.
8:     LDVL – INTEGERInput
On entry: the first dimension of the array VL as declared in the (sub)program from which F08QXF (ZTREVC) is called.
Constraints:
• if ${\mathbf{JOB}}=\text{'L'}$ or $\text{'B'}$, ${\mathbf{LDVL}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{JOB}}=\text{'R'}$, ${\mathbf{LDVL}}\ge 1$.
9:     VR(LDVR,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array VR must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{MM}}\right)$ if ${\mathbf{JOB}}=\text{'R'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{JOB}}=\text{'L'}$.
On entry: if ${\mathbf{HOWMNY}}=\text{'O'}$ or $\text{'B'}$ and ${\mathbf{JOB}}=\text{'R'}$ or $\text{'B'}$, VR must contain an $n$ by $n$ matrix $Q$ (usually the matrix of Schur vectors returned by F08PSF (ZHSEQR)).
If ${\mathbf{HOWMNY}}=\text{'A'}$ or $\text{'S'}$, VR need not be set.
On exit: if ${\mathbf{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 ${\mathbf{JOB}}=\text{'L'}$, VR is not referenced.
10:   LDVR – INTEGERInput
On entry: the first dimension of the array VR as declared in the (sub)program from which F08QXF (ZTREVC) is called.
Constraints:
• if ${\mathbf{JOB}}=\text{'R'}$ or $\text{'B'}$, ${\mathbf{LDVR}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{N}}\right)$;
• if ${\mathbf{JOB}}=\text{'L'}$, ${\mathbf{LDVR}}\ge 1$.
11:   MM – INTEGERInput
On entry: the number of columns in the arrays VL and/or VR. The precise number of columns required, $\mathit{m}$, is $n$ if ${\mathbf{HOWMNY}}=\text{'A'}$, $\text{'O'}$ or $\text{'B'}$; if ${\mathbf{HOWMNY}}=\text{'S'}$, $\mathit{m}$ is the number of selected eigenvectors (see SELECT), in which case $0\le \mathit{m}\le n$.
Constraint: ${\mathbf{MM}}\ge \mathit{m}$.
12:   M – INTEGEROutput
On exit: $\mathit{m}$, the number of selected eigenvectors. If ${\mathbf{HOWMNY}}=\text{'A'}$, $\text{'O'}$ or $\text{'B'}$, M is set to $n$.
13:   WORK($2×{\mathbf{N}}$) – COMPLEX (KIND=nag_wp) arrayWorkspace
14:   RWORK(N) – REAL (KIND=nag_wp) arrayWorkspace
15:   INFO – INTEGEROutput
On exit: ${\mathbf{INFO}}=0$ unless the routine detects an error (see Section 6).

## 6  Error Indicators and Warnings

Errors or warnings detected by the routine:
${\mathbf{INFO}}<0$
If ${\mathbf{INFO}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

## 7  Accuracy

If ${x}_{i}$ is an exact right eigenvector, and ${\stackrel{~}{x}}_{i}$ is the corresponding computed eigenvector, then the angle $\theta \left({\stackrel{~}{x}}_{i},{x}_{i}\right)$ between them is bounded as follows:
 $θ x~i,xi ≤ c n ε T2 sepi$
where ${\mathit{sep}}_{i}$ is the reciprocal condition number of ${x}_{i}$.
The condition number ${\mathit{sep}}_{i}$ may be computed by calling F08QYF (ZTRSNA).