NAG Library Function Document

nag_dgees (f08pac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

nag_dgees (f08pac) computes the eigenvalues, the real Schur form

T

, and, optionally, the matrix of Schur vectors

Z

for an

n

n

real nonsymmetric matrix

A

2 Specification

#include <nag.h>

#include <nagf08.h>

void

nag_dgees (Nag_OrderType order, Nag_JobType jobvs, Nag_SortEigValsType sort,

Nag_Boolean

(*select)(double wr, double wi),

Integer n, double a[], Integer pda, Integer *sdim, double wr[], double wi[], double vs[], Integer pdvs, NagError *fail)

3 Description

The real Schur factorization of

A

is given by

A = Z T Z^{T},

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

1

and

2

2

blocks.

2

2

blocks will be standardized in the form

[\begin{array}{c} a & b \\ c & a \end{array}]

where

b c < 0

. The eigenvalues of such a block are

a \pm \sqrt{b c}

Optionally, nag_dgees (f08pac) 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.

4 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

5 Arguments

1: order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: jobvs – Nag_JobTypeInput

On entry: if

jobvs = Nag_DoNothing

, Schur vectors are not computed.

jobvs = Nag_Schur

, Schur vectors are computed.

Constraint:

jobvs = Nag_DoNothing

Nag_Schur

3: sort – Nag_SortEigValsTypeInput

On entry: specifies whether or not to order the eigenvalues on the diagonal of the Schur form.

$sort = Nag_NoSortEigVals$: Eigenvalues are not ordered.
$sort = Nag_SortEigVals$: Eigenvalues are ordered (see select).

Constraint:

sort = Nag_NoSortEigVals

Nag_SortEigVals

4: select – function, supplied by the userExternal Function

sort = Nag_SortEigVals

, select is used to select eigenvalues to sort to the top left of the Schur form.

sort = Nag_NoSortEigVals

, select is not referenced and nag_dgees (f08pac) may be specified as NULLFN.

An eigenvalue

wr [j - 1] + \sqrt{- 1} \times wi [j - 1]

is selected if

select (wr [j - 1], wi [j - 1])

is Nag_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 - 1], wi [j - 1]) = Nag_TRUE

after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case

fail . errnum

is set to

n + 2

The specification of select is:

Nag_Boolean

select (double wr, double wi)

1: wr – doubleInput
2: wi – doubleInput: On entry: the real and imaginary parts of the eigenvalue.

5: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

6: a[ $\dim$ ] – doubleInput/Output

Note: the dimension, dim, of the array a must be at least

\max (1, pda \times n)

The

(i, j)

th element of the matrix

A

is stored in

$a [(j - 1) \times pda + i - 1]$ when $order = Nag_ColMajor$ ;
$a [(i - 1) \times pda + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

n

matrix

A

On exit: a is overwritten by its real Schur form

T

7: pda – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array a.

Constraint:

pda \geq \max (1, n)

8: sdim – Integer *Output

On exit: if

sort = Nag_NoSortEigVals

sdim = 0

sort = Nag_SortEigVals

sdim =

number of eigenvalues (after sorting) for which select is Nag_TRUE. (Complex conjugate pairs for which select is Nag_TRUE for either eigenvalue count as

2

9: wr[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array wr must be at least

\max (1, n)

On exit: see the description of wi.

10: wi[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array wi must be at least

\max (1, n)

On exit: 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.

11: vs[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array vs must be at least

$\max (1, pdvs \times n)$ when $jobvs = Nag_Schur$ ;
$1$ otherwise.

The

i

th element of the

j

th vector is stored in

$vs [(j - 1) \times pdvs + i - 1]$ when $order = Nag_ColMajor$ ;
$vs [(i - 1) \times pdvs + j - 1]$ when $order = Nag_RowMajor$ .

On exit: if

jobvs = Nag_Schur

, vs contains the orthogonal matrix

Z

of Schur vectors.

jobvs = Nag_DoNothing

, vs is not referenced.

12: pdvs – IntegerInput

On entry: the stride used in the array vs.

Constraints:

if $jobvs = Nag_Schur$ , $pdvs \geq \max (1, n)$ ;
otherwise $pdvs \geq 1$ .

13: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_CONVERGENCE: The $Q R$ algorithm failed to compute all the eigenvalues.
NE_ENUM_INT_2: On entry, $jobvs = 〈value〉$ , $pdvs = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $jobvs = Nag_Schur$ , $pdvs \geq \max (1, n)$ ;
otherwise $pdvs \geq 1$ .
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $pda = 〈value〉$ .
Constraint: $pda > 0$ .; On entry, $pdvs = 〈value〉$ .
Constraint: $pdvs > 0$ .
NE_INT_2: On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq \max (1, n)$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_SCHUR_REORDER: The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).
NE_SCHUR_REORDER_SELECT: After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy $select = Nag_TRUE$ . This could also be caused by underflow due to scaling.

7 Accuracy

The computed Schur factorization satisfies

A + E = Z T Z^{T},

where

{‖E‖}_{2} = O (ε) {‖A‖}_{2},

and

ε

is the machine precision. See Section 4.8 of Anderson et al. (1999) for further details.

8 Further Comments

The total number of floating point operations is proportional to

n^{3}

The complex analogue of this function is nag_zgees (f08pnc).

9 Example

This example finds the Schur factorization of the matrix

A = (\begin{array}{r} 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 \end{array}),

such that the real eigenvalues of

A

are the top left diagonal elements of the Schur form,

T

NAG Library Function Documentnag_dgees (f08pac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_dgees (f08pac)