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_zgees (f08pn)

## Purpose

nag_lapack_zgees (f08pn) computes the eigenvalues, the Schur form T$T$, and, optionally, the matrix of Schur vectors Z$Z$ for an n$n$ by n$n$ complex nonsymmetric matrix A$A$.

## Syntax

[a, sdim, w, vs, info] = f08pn(jobvs, sort, select, a, 'n', n)
[a, sdim, w, vs, info] = nag_lapack_zgees(jobvs, sort, select, a, 'n', n)

## Description

The Schur factorization of A$A$ is given by
 A = Z T ZH , $A = Z T ZH ,$
where Z$Z$, the matrix of Schur vectors, is unitary and T$T$ is the Schur form. A complex matrix is in Schur form if it is upper triangular.
Optionally, nag_lapack_zgees (f08pn) also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left. The leading columns of Z$Z$ form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues.

## References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     jobvs – string (length ≥ 1)
If jobvs = 'N'${\mathbf{jobvs}}=\text{'N'}$, Schur vectors are not computed.
If jobvs = 'V'${\mathbf{jobvs}}=\text{'V'}$, Schur vectors are computed.
Constraint: jobvs = 'N'${\mathbf{jobvs}}=\text{'N'}$ or 'V'$\text{'V'}$.
2:     sort – string (length ≥ 1)
Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.
sort = 'N'${\mathbf{sort}}=\text{'N'}$
Eigenvalues are not ordered.
sort = 'S'${\mathbf{sort}}=\text{'S'}$
Eigenvalues are ordered (see select).
Constraint: sort = 'N'${\mathbf{sort}}=\text{'N'}$ or 'S'$\text{'S'}$.
3:     select – function handle or string containing name of m-file
If sort = 'S'${\mathbf{sort}}=\text{'S'}$, select is used to select eigenvalues to sort to the top left of the Schur form.
If sort = 'N'${\mathbf{sort}}=\text{'N'}$, select is not referenced and nag_lapack_zgees (f08pn) may be called with the string 'f08pnz'.
An eigenvalue w(j)${\mathbf{w}}\left(j\right)$ is selected if select(w(j))${\mathbf{select}}\left({\mathbf{w}}\left(j\right)\right)$ is true.
[result] = select(w)

Input Parameters

1:     w – complex scalar
The real and imaginary parts of the eigenvalue.

Output Parameters

1:     result – logical scalar
The result of the function.
4:     a(lda, : $:$) – complex array
The first dimension of the array a must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The n$n$ by n$n$ matrix A$A$.

### Optional Input Parameters

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

### Input Parameters Omitted from the MATLAB Interface

lda ldvs work lwork rwork bwork

### Output Parameters

1:     a(lda, : $:$) – complex array
The first dimension of the array a will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldamax (1,n)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
a stores its Schur form T$T$.
2:     sdim – int64int32nag_int scalar
If sort = 'N'${\mathbf{sort}}=\text{'N'}$, sdim = 0${\mathbf{sdim}}=0$.
If sort = 'S'${\mathbf{sort}}=\text{'S'}$, sdim = ${\mathbf{sdim}}=\text{}$ number of eigenvalues for which select is true.
3:     w( : $:$) – complex array
Note: the dimension of the array w must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
Contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form T$T$.
4:     vs(ldvs, : $:$) – complex array
The first dimension, ldvs, of the array vs will be
• if jobvs = 'V'${\mathbf{jobvs}}=\text{'V'}$, ldvs max (1,n) $\mathit{ldvs}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ldvs1$\mathit{ldvs}\ge 1$.
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if jobvs = 'V'${\mathbf{jobvs}}=\text{'V'}$, and at least 1$1$ otherwise
If jobvs = 'V'${\mathbf{jobvs}}=\text{'V'}$, vs contains the unitary matrix Z$Z$ of Schur vectors.
If jobvs = 'N'${\mathbf{jobvs}}=\text{'N'}$, vs is not referenced.
5:     info – int64int32nag_int scalar
info = 0${\mathbf{info}}=0$ unless the function detects an error (see Section [Error Indicators and Warnings]).

## Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$i$ had an illegal value on entry. The parameters are numbered as follows:
1: jobvs, 2: sort, 3: select, 4: n, 5: a, 6: lda, 7: sdim, 8: w, 9: vs, 10: ldvs, 11: work, 12: lwork, 13: rwork, 14: bwork, 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.
INFO = 1ton${\mathbf{INFO}}=1 \text{to} {\mathbf{n}}$
If info = i${\mathbf{info}}=i$ and in$i\le {\mathbf{n}}$, the QR$QR$ algorithm failed to compute all the eigenvalues.
W INFO = N + 1${\mathbf{INFO}}={\mathbf{N}}+1$
The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).
W INFO = N + 2${\mathbf{INFO}}={\mathbf{N}}+2$
After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy select = true${\mathbf{select}}=\mathbf{true}$. This could also be caused by underflow due to scaling.

## Accuracy

The computed Schur factorization satisfies
 A + E = ZT ZH , $A+E=ZT ZH ,$
where
 ‖E‖2 = O(ε) ‖A‖2 , $‖E‖2 = O(ε) ‖A‖2 ,$
and ε$\epsilon$ is the machine precision. See Section 4.8 of Anderson et al. (1999) for further details.

The total number of floating point operations is proportional to n3${n}^{3}$.
The real analogue of this function is nag_lapack_dgees (f08pa).

## Example

```function nag_lapack_zgees_example
jobvs = 'Vectors (Schur)';
sortp = 'No sort';
a = [ -3.97 - 5.04i,  -4.11 + 3.7i,  -0.34 + 1.01i,  1.29 - 0.86i;
0.34 - 1.5i,  1.52 - 0.43i,  1.88 - 5.38i,  3.36 + 0.65i;
3.31 - 3.85i,  2.5 + 3.45i,  0.88 - 1.08i,  0.64 - 1.48i;
-1.1 + 0.82i,  1.81 - 1.59i,  3.25 + 1.33i,  1.57 - 3.44i];
[aOut, sdim, w, vs, info] = nag_lapack_zgees(jobvs, sortp, @select, a)
```
```

aOut =

-6.0004 - 6.9998i  -0.3656 + 0.3637i   0.4761 - 0.1946i  -0.7237 + 0.5589i
0.0000 + 0.0000i  -5.0000 + 2.0060i   0.4981 - 0.5232i  -0.1637 + 0.2071i
0.0000 + 0.0000i   0.0000 + 0.0000i   7.9982 - 0.9964i   0.8487 - 0.6651i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   3.0023 - 3.9998i

sdim =

0

w =

-6.0004 - 6.9998i
-5.0000 + 2.0060i
7.9982 - 0.9964i
3.0023 - 3.9998i

vs =

-0.5312 - 0.6581i   0.3018 - 0.2402i  -0.0935 - 0.2736i  -0.1355 + 0.1844i
0.2474 - 0.1769i   0.1759 - 0.5473i  -0.4015 + 0.6010i  -0.0027 - 0.2337i
0.1874 - 0.2637i  -0.6002 + 0.1953i  -0.5752 - 0.0389i  -0.1458 + 0.3787i
-0.1909 + 0.2262i   0.2027 + 0.2852i  -0.1537 + 0.1951i  -0.8459 - 0.1130i

info =

0

```
```function f08pn_example
jobvs = 'Vectors (Schur)';
sortp = 'No sort';
a = [ -3.97 - 5.04i,  -4.11 + 3.7i,  -0.34 + 1.01i,  1.29 - 0.86i;
0.34 - 1.5i,  1.52 - 0.43i,  1.88 - 5.38i,  3.36 + 0.65i;
3.31 - 3.85i,  2.5 + 3.45i,  0.88 - 1.08i,  0.64 - 1.48i;
-1.1 + 0.82i,  1.81 - 1.59i,  3.25 + 1.33i,  1.57 - 3.44i];
[aOut, sdim, w, vs, info] = f08pn(jobvs, sortp, @select, a)
```
```

aOut =

-6.0004 - 6.9998i  -0.3656 + 0.3637i   0.4761 - 0.1946i  -0.7237 + 0.5589i
0.0000 + 0.0000i  -5.0000 + 2.0060i   0.4981 - 0.5232i  -0.1637 + 0.2071i
0.0000 + 0.0000i   0.0000 + 0.0000i   7.9982 - 0.9964i   0.8487 - 0.6651i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   3.0023 - 3.9998i

sdim =

0

w =

-6.0004 - 6.9998i
-5.0000 + 2.0060i
7.9982 - 0.9964i
3.0023 - 3.9998i

vs =

-0.5312 - 0.6581i   0.3018 - 0.2402i  -0.0935 - 0.2736i  -0.1355 + 0.1844i
0.2474 - 0.1769i   0.1759 - 0.5473i  -0.4015 + 0.6010i  -0.0027 - 0.2337i
0.1874 - 0.2637i  -0.6002 + 0.1953i  -0.5752 - 0.0389i  -0.1458 + 0.3787i
-0.1909 + 0.2262i   0.2027 + 0.2852i  -0.1537 + 0.1951i  -0.8459 - 0.1130i

info =

0

```