Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_ztrevc (f08qx)

## Purpose

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

## Syntax

[t, vl, vr, m, info] = f08qx(job, howmny, select, t, vl, vr, mm, 'n', n)
[t, vl, vr, m, info] = nag_lapack_ztrevc(job, howmny, select, t, vl, vr, mm, 'n', n)

## Description

nag_lapack_ztrevc (f08qx) 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 nag_lapack_zhseqr (f08ps), 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 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}^{\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$.

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{job}$ – string (length ≥ 1)
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:     $\mathrm{howmny}$ – string (length ≥ 1)
Indicates how many eigenvectors are to be computed.
${\mathbf{howmny}}=\text{'A'}$
All eigenvectors (as specified by job) are computed.
${\mathbf{howmny}}=\text{'B'}$
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'}$ or $\text{'S'}$.
3:     $\mathrm{select}\left(:\right)$ – logical array
The dimension of the array select must be at least ${\mathbf{n}}$ if ${\mathbf{howmny}}=\text{'S'}$, and at least $1$ otherwise
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'}$ or $\text{'B'}$, select is not referenced.
4:     $\mathrm{t}\left(\mathit{ldt},:\right)$ – complex array
The first dimension of the array t must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array t must be at least ${\mathbf{n}}$.
The $n$ by $n$ upper triangular matrix $T$, as returned by nag_lapack_zhseqr (f08ps).
5:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – complex array
The first dimension, $\mathit{ldvl}$, of the array vl must satisfy
• if ${\mathbf{job}}=\text{'L'}$ or $\text{'B'}$, $\mathit{ldvl}\ge {\mathbf{n}}$;
• if ${\mathbf{job}}=\text{'R'}$, $\mathit{ldvl}\ge 1$.
The second dimension of the array vl must be at least ${\mathbf{mm}}$ if ${\mathbf{job}}=\text{'L'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{job}}=\text{'R'}$.
If ${\mathbf{howmny}}=\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 nag_lapack_zhseqr (f08ps)).
If ${\mathbf{howmny}}=\text{'A'}$ or $\text{'S'}$, vl need not be set.
6:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – complex array
The first dimension, $\mathit{ldvr}$, of the array vr must satisfy
• if ${\mathbf{job}}=\text{'R'}$ or $\text{'B'}$, $\mathit{ldvr}\ge {\mathbf{n}}$;
• if ${\mathbf{job}}=\text{'L'}$, $\mathit{ldvr}\ge 1$.
The second dimension of the array vr must be at least ${\mathbf{mm}}$ if ${\mathbf{job}}=\text{'R'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{job}}=\text{'L'}$.
If ${\mathbf{howmny}}=\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 nag_lapack_zhseqr (f08ps)).
If ${\mathbf{howmny}}=\text{'A'}$ or $\text{'S'}$, vr need not be set.
7:     $\mathrm{mm}$int64int32nag_int scalar
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'}$ 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$.
Constraints:
• if ${\mathbf{howmny}}=\text{'A'}$ or $\text{'B'}$, ${\mathbf{mm}}\ge {\mathbf{n}}$;
• otherwise ${\mathbf{mm}}\ge \mathit{m}$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array t and the second dimension of the array t. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrix $T$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{t}\left(\mathit{ldt},:\right)$ – complex array
The first dimension of the array t will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array t will be ${\mathbf{n}}$.
Is used as internal workspace prior to being restored and hence is unchanged.
2:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – complex array
The first dimension, $\mathit{ldvl}$, of the array vl will be
• if ${\mathbf{job}}=\text{'L'}$ or $\text{'B'}$, $\mathit{ldvl}={\mathbf{n}}$;
• if ${\mathbf{job}}=\text{'R'}$, $\mathit{ldvl}=1$.
The second dimension of the array vl will be ${\mathbf{mm}}$ if ${\mathbf{job}}=\text{'L'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{job}}=\text{'R'}$.
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.
3:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – complex array
The first dimension, $\mathit{ldvr}$, of the array vr will be
• if ${\mathbf{job}}=\text{'R'}$ or $\text{'B'}$, $\mathit{ldvr}={\mathbf{n}}$;
• if ${\mathbf{job}}=\text{'L'}$, $\mathit{ldvr}=1$.
The second dimension of the array vr will be ${\mathbf{mm}}$ if ${\mathbf{job}}=\text{'R'}$ or $\text{'B'}$ and at least $1$ if ${\mathbf{job}}=\text{'L'}$.
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.
4:     $\mathrm{m}$int64int32nag_int scalar
$\mathit{m}$, the number of selected eigenvectors. If ${\mathbf{howmny}}=\text{'A'}$ or $\text{'B'}$, m is set to $n$.
5:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: job, 2: howmny, 3: select, 4: n, 5: t, 6: ldt, 7: vl, 8: ldvl, 9: vr, 10: ldvr, 11: mm, 12: m, 13: work, 14: rwork, 15: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.

## 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 nag_lapack_ztrsna (f08qy).

The real analogue of this function is nag_lapack_dtrevc (f08qk).

## Example

See Example in nag_lapack_zgebal (f08nv).
```function f08qx_example

fprintf('f08qx example results\n\n');

n = int64(4);
a = [ 1.50 - 2.75i,  0    + 0i,     0    + 0i,     0    + 0i;
-8.06 - 1.24i, -2.50 - 0.50i,  0    + 0i,    -0.75 + 0.50i;
-2.09 + 7.56i,  1.39 + 3.97i, -1.25 + 0.75i, -4.82 - 5.67i;
6.18 + 9.79i, -0.92 - 0.62i,  0    + 0i,    -2.50 - 0.50i];

% Balance a
[a, ilo, ihi, scale, info] = f08nv( ...
'Both', a);

% Reduce a to upper Hessenberg form
[H, tau, info] = f08ns( ...
ilo, ihi, a);

% Form Q explicitly, storing result in vr
[Q, info] = f08nt( ...
ilo, ihi, H, tau);

% Calculate the eigenvalues and Schur factorisation of A
[S, w, VR, info] = f08ps( ...
'Schur Form', 'Vectors', ilo, ihi, H, Q);

disp('Eigenvalues of A:');
disp(w);

% Calculate the eigenvectors of A
select = [false];
vl = [complex(0)];

[T, ~, Z, m, info] = ...
f08qx( ...
'Right', 'Backtransform', select, H, vl, VR, n);

% Scale
[V, info] = f08nw( ...
'Both', 'Right', ilo, ihi, scale, Z);

% Normalize eigenvectors: largest element is real
for i = 1:m
[~,k] = max(abs(real(V(:,i)))+abs(imag(V(:,i))));
V(:,i) = V(:,i)*conj(V(k,i))/abs(V(k,i));
end

disp('Right eigenvectors of A:');
disp(V);

```
```f08qx example results

Eigenvalues of A:
-1.2500 + 0.7500i
-1.5000 - 0.4975i
-3.5000 - 0.5025i
1.5000 - 2.7500i

Right eigenvectors of A:
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.1778 - 0.0372i
0.0000 + 0.0000i   0.1902 - 0.0910i   0.1898 - 0.0908i   0.4382 - 0.1021i
1.0000 + 0.0000i   0.7492 + 0.0000i   0.7479 + 0.0000i   0.8449 + 0.0000i
0.0000 + 0.0000i  -0.2314 - 0.0337i  -0.2310 - 0.0336i   0.1950 - 0.3509i

```