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

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dgees (f08pa)

## Purpose

nag_lapack_dgees (f08pa) computes the eigenvalues, the real Schur form T$T$, and, optionally, the matrix of Schur vectors Z$Z$ for an n$n$ by n$n$ real nonsymmetric matrix A$A$.

## Syntax

[a, sdim, wr, wi, vs, info] = f08pa(jobvs, sort, select, a, 'n', n)
[a, sdim, wr, wi, vs, info] = nag_lapack_dgees(jobvs, sort, select, a, 'n', n)

## Description

The real Schur factorization of A$A$ is given by
 A = Z T ZT , $A = Z T ZT ,$
where Z$Z$, the matrix of Schur vectors, is orthogonal and T$T$ is the real Schur form. A matrix is in real Schur form if it is upper quasi-triangular with 1$1$ by 1$1$ and 2$2$ by 2$2$ blocks. 2$2$ by 2$2$ blocks will be standardized in the form
 [ a b c a ]
$[ a b c a ]$
where bc < 0$bc<0$. The eigenvalues of such a block are a ± sqrt(bc)$a±\sqrt{bc}$.
Optionally, nag_lapack_dgees (f08pa) also orders the eigenvalues on the diagonal of the real 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_dgees (f08pa) may be called with the string 'f08paz'.
An eigenvalue wr(j) + sqrt(1) × wi(j)${\mathbf{wr}}\left(j\right)+\sqrt{-1}×{\mathbf{wi}}\left(j\right)$ is selected if select(wr(j),wi(j))${\mathbf{select}}\left({\mathbf{wr}}\left(j\right),{\mathbf{wi}}\left(j\right)\right)$ is true. If either one of a complex conjugate pair of eigenvalues is selected, then both are. Note that a selected complex eigenvalue may no longer satisfy select(wr(j),wi(j)) = true${\mathbf{select}}\left({\mathbf{wr}}\left(j\right),{\mathbf{wi}}\left(j\right)\right)=\mathbf{true}$ after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case info is set to n + 2${\mathbf{n}}+2$ (see info below).
[result] = select(wr, wi)

Input Parameters

1:     wr – double scalar
2:     wi – double scalar
The real and imaginary parts of the eigenvalue.

Output Parameters

1:     result – logical scalar
The result of the function.
4:     a(lda, : $:$) – double 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 bwork

### Output Parameters

1:     a(lda, : $:$) – double 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 real 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 (after sorting) for which select is true. (Complex conjugate pairs for which select is true for either eigenvalue count as 2$2$.)
3:     wr( : $:$) – double array
Note: the dimension of the array wr must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
See the description of wi.
4:     wi( : $:$) – double array
Note: the dimension of the array wi must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
wr and wi contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form T$T$. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.
5:     vs(ldvs, : $:$) – double 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 orthogonal matrix Z$Z$ of Schur vectors.
If jobvs = 'N'${\mathbf{jobvs}}=\text{'N'}$, vs is not referenced.
6:     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: wr, 9: wi, 10: vs, 11: ldvs, 12: work, 13: lwork, 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 ZT , $A+E=ZT ZT ,$
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.

## Further Comments

The total number of floating point operations is proportional to n3${n}^{3}$.
The complex analogue of this function is nag_lapack_zgees (f08pn).

## Example

```function nag_lapack_dgees_example
jobvs = 'Vectors (Schur)';
sortp = 'Sort';
select = @(wr, wi) (wi == 0);
a = [0.35, 0.45, -0.14, -0.17;
0.09, 0.07, -0.54, 0.35;
-0.44, -0.33, -0.03, 0.17;
0.25, -0.32, -0.13, 0.11];
[aOut, sdim, wr, wi, vs, info] = nag_lapack_dgees(jobvs, sortp, select, a)
```
```

aOut =

0.7995   -0.0059   -0.0751   -0.0927
0   -0.1007    0.3937    0.3569
0         0   -0.0994   -0.5128
0         0    0.3132   -0.0994

sdim =

2

wr =

0.7995
-0.1007
-0.0994
-0.0994

wi =

0
0
0.4008
-0.4008

vs =

-0.6551   -0.1210   -0.5032    0.5504
-0.5236   -0.3286    0.7857    0.0229
0.5362   -0.5974    0.0904    0.5894
-0.0956   -0.7215   -0.3482   -0.5908

info =

0

```
```function f08pa_example
jobvs = 'Vectors (Schur)';
sortp = 'Sort';
select = @(wr, wi) (wi == 0);
a = [0.35, 0.45, -0.14, -0.17;
0.09, 0.07, -0.54, 0.35;
-0.44, -0.33, -0.03, 0.17;
0.25, -0.32, -0.13, 0.11];
[aOut, sdim, wr, wi, vs, info] = f08pa(jobvs, sortp, select, a)
```
```

aOut =

0.7995   -0.0059   -0.0751   -0.0927
0   -0.1007    0.3937    0.3569
0         0   -0.0994   -0.5128
0         0    0.3132   -0.0994

sdim =

2

wr =

0.7995
-0.1007
-0.0994
-0.0994

wi =

0
0
0.4008
-0.4008

vs =

-0.6551   -0.1210   -0.5032    0.5504
-0.5236   -0.3286    0.7857    0.0229
0.5362   -0.5974    0.0904    0.5894
-0.0956   -0.7215   -0.3482   -0.5908

info =

0

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013