NAG Library Routine Document

F08QXF (ZTREVC)

1  Purpose

2  Specification

3  Description

4  References

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 $\max \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 $\max \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 \max \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 $\max \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 \max \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 $\max \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 \max \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\times \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

$\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

8  Further Comments

9  Example