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$, and, optionally, the matrix of Schur vectors $Z$ for an $n$ by $n$ real nonsymmetric matrix $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$ is given by
 $A = Z T ZT ,$
where $Z$, the matrix of Schur vectors, is orthogonal and $T$ is the real Schur form. A matrix is in real Schur form if it is upper quasi-triangular with $1$ by $1$ and $2$ by $2$ blocks. $2$ by $2$ blocks will be standardized in the form
 $a b c a$
where $bc<0$. The eigenvalues of such a block are $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$ 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:     $\mathrm{jobvs}$ – string (length ≥ 1)
If ${\mathbf{jobvs}}=\text{'N'}$, Schur vectors are not computed.
If ${\mathbf{jobvs}}=\text{'V'}$, Schur vectors are computed.
Constraint: ${\mathbf{jobvs}}=\text{'N'}$ or $\text{'V'}$.
2:     $\mathrm{sort}$ – string (length ≥ 1)
Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.
${\mathbf{sort}}=\text{'N'}$
Eigenvalues are not ordered.
${\mathbf{sort}}=\text{'S'}$
Eigenvalues are ordered (see select).
Constraint: ${\mathbf{sort}}=\text{'N'}$ or $\text{'S'}$.
3:     $\mathrm{select}$ – function handle or string containing name of m-file
If ${\mathbf{sort}}=\text{'S'}$, select is used to select eigenvalues to sort to the top left of the Schur form.
If ${\mathbf{sort}}=\text{'N'}$, select is not referenced and nag_lapack_dgees (f08pa) may be called with the string 'f08paz'.
An eigenvalue ${\mathbf{wr}}\left(j\right)+\sqrt{-1}×{\mathbf{wi}}\left(j\right)$ is selected if ${\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 ${\mathbf{select}}\left({\mathbf{wr}}\left(j\right),{\mathbf{wi}}\left(j\right)\right)=\mathit{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 ${\mathbf{n}}+2$ (see info below).
[result] = select(wr, wi)

Input Parameters

1:     $\mathrm{wr}$ – double scalar
2:     $\mathrm{wi}$ – double scalar
The real and imaginary parts of the eigenvalue.

Output Parameters

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

### Optional Input Parameters

1:     $\mathrm{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$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
a stores its real Schur form $T$.
2:     $\mathrm{sdim}$int64int32nag_int scalar
If ${\mathbf{sort}}=\text{'N'}$, ${\mathbf{sdim}}=0$.
If ${\mathbf{sort}}=\text{'S'}$, ${\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$.)
3:     $\mathrm{wr}\left(:\right)$ – double array
The dimension of the array wr will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
See the description of wi.
4:     $\mathrm{wi}\left(:\right)$ – double array
The dimension of the array wi will be $\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$. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.
5:     $\mathrm{vs}\left(\mathit{ldvs},:\right)$ – double array
The first dimension, $\mathit{ldvs}$, of the array vs will be
• if ${\mathbf{jobvs}}=\text{'V'}$, $\mathit{ldvs}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldvs}=1$.
The second dimension of the array vs will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{jobvs}}=\text{'V'}$ and $1$ otherwise.
If ${\mathbf{jobvs}}=\text{'V'}$, vs contains the orthogonal matrix $Z$ of Schur vectors.
If ${\mathbf{jobvs}}=\text{'N'}$, vs is not referenced.
6:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see 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.

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $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.
${\mathbf{info}}=1 \text{to} {\mathbf{n}}$
If ${\mathbf{info}}=i$ and $i\le {\mathbf{n}}$, the $QR$ algorithm failed to compute all the eigenvalues.
W  ${\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  ${\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 ${\mathbf{select}}=\mathit{true}$. This could also be caused by underflow due to scaling.

## Accuracy

The computed Schur factorization satisfies
 $A+E=ZT ZT ,$
where
 $E2 = Oε A2 ,$
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 ${n}^{3}$.
The complex analogue of this function is nag_lapack_zgees (f08pn).

## Example

This example finds the Schur factorization of the matrix
 $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 ,$
such that the real positive eigenvalues of $A$ are the top left diagonal elements of the Schur form, $T$.
Note that the block size (NB) of $64$ assumed in this example is not realistic for such a small problem, but should be suitable for large problems.
```function f08pa_example

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

% Matrix A
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];

% Schur vectors of A, selecting real positive eigenvalues
jobvs = 'Vectors (Schur)';
sortp = 'Sort';
select = @(wr, wi) (wr > 0 && wi == 0);
[~, sdim, wr, wi, vs, info] = ...
f08pa( ...
jobvs, sortp, select, a);

fprintf('Number of eigenvalues for which SELECT is true = %3d\n',sdim);
fprintf(' (dimension of invariant subspace)\n\n');
disp('Selected eigenvalues');
disp(wr(1:sdim) + i*wi(1:sdim));

```
```f08pa example results

Number of eigenvalues for which SELECT is true =   1
(dimension of invariant subspace)

Selected eigenvalues
0.7995

```

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–2015