nag_dtrevc (f08qkc) : NAG Library, Mark 23

2 Specification

#include <nag.h>

#include <nagf08.h>

void	nag_dtrevc (Nag_OrderType order, Nag_SideType side, Nag_HowManyType how_many, Nag_Boolean select[], Integer n, const double t[], Integer pdt, double vl[], Integer pdvl, double vr[], Integer pdvr, Integer mm, Integer m, NagError fail)

3 Description

nag_dtrevc (f08qkc) computes left and/or right eigenvectors of a real upper quasi-triangular matrix

T

in canonical Schur form. Such a matrix arises from the Schur factorization of a real general matrix, as computed by nag_dhseqr (f08pec), for example.

The right eigenvector

x

, and the left eigenvector

y

, corresponding to an eigenvalue

λ

, are defined by:

T x = λ x and y^{H} T = λ y^{H} (or ​ T^{T} y = \bar{λ} y) .

Note that even though

T

is real,

λ

x

and

y

may be complex. If

x

is an eigenvector corresponding to a complex eigenvalue

λ

, then the complex conjugate vector

\bar{x}

is the eigenvector corresponding to the complex conjugate eigenvalue

\bar{λ}

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 an orthogonal matrix from the Schur factorization of a matrix

A

A = Q T Q^{T}

; if

x

is a (left or right) eigenvector of

T

, then

Q x

is an eigenvector of

A

The eigenvectors are computed by forward or backward substitution. They are scaled so that, for a real eigenvector

x

\max (|x_{i}|) = 1

, and for a complex eigenvector,

\max (|Re (x_{i})| + |Im (x_{i})|) = 1

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: side – Nag_SideTypeInput

On entry: indicates whether left and/or right eigenvectors are to be computed.

$side = Nag_RightSide$: Only right eigenvectors are computed.
$side = Nag_LeftSide$: Only left eigenvectors are computed.
$side = Nag_BothSides$: Both left and right eigenvectors are computed.

Constraint:

side = Nag_RightSide

Nag_LeftSide

Nag_BothSides

3: how_many – Nag_HowManyTypeInput

On entry: indicates how many eigenvectors are to be computed.

$how_many = Nag_ComputeAll$: All eigenvectors (as specified by side) are computed.
$how_many = Nag_BackTransform$: All eigenvectors (as specified by side) are computed and then pre-multiplied by the matrix $Q$ (which is overwritten).
$how_many = Nag_ComputeSelected$: Selected eigenvectors (as specified by side and select) are computed.

Constraint:

how_many = Nag_ComputeAll

Nag_BackTransform

Nag_ComputeSelected

4: select[

\dim

] – Nag_BooleanInput/Output

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

$\max (1, n)$ when $how_many = Nag_ComputeSelected$ ;
$1$ otherwise.

On entry: specifies which eigenvectors are to be computed if

how_many = Nag_ComputeSelected

. To obtain the real eigenvector corresponding to the real eigenvalue

λ_{j}

select [j - 1]

must be set Nag_TRUE. To select the complex eigenvector corresponding to a complex conjugate pair of eigenvalues

λ_{j}

and

λ_{j + 1}

select [j - 1]

and/or

select [j]

must be set Nag_TRUE; the eigenvector corresponding to the first eigenvalue in the pair is computed.

On exit: if a complex eigenvector was selected as specified above, then

select [j - 1]

is set to Nag_TRUE and

select [j]

to Nag_FALSE.

how_many = Nag_ComputeAll

Nag_BackTransform

, select is not referenced.

5: n – IntegerInput

On entry:

n

, the order of the matrix

T

Constraint:

n \geq 0

6: t[

\dim

] – const doubleInput

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

\max (1, pdt \times n)

The

(i, j)

th element of the matrix

T

is stored in

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

On entry: the

n

n

upper quasi-triangular matrix

T

in canonical Schur form, as returned by nag_dhseqr (f08pec).

7: pdt – IntegerInput

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

Constraint:

pdt \geq \max (1, n)

8: vl[

\dim

] – doubleInput/Output

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

$\max (1, pdvl \times mm)$ when $side = Nag_LeftSide$ or $Nag_BothSides$ and $order = Nag_ColMajor$ ;
$\max (1, n \times pdvl)$ when $side = Nag_LeftSide$ or $Nag_BothSides$ and $order = Nag_RowMajor$ ;
$1$ when $side = Nag_RightSide$ .

The

(i, j)

th element of the matrix is stored in

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

On entry: if

how_many = Nag_BackTransform

and

side = Nag_LeftSide

Nag_BothSides

, vl must contain an

n

n

matrix

Q

(usually the matrix of Schur vectors returned by nag_dhseqr (f08pec)).

how_many = Nag_ComputeAll

Nag_ComputeSelected

, vl need not be set.

On exit: if

side = Nag_LeftSide

Nag_BothSides

, vl contains the computed left eigenvectors (as specified by how_many and select). The eigenvectors are stored consecutively in the rows or columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one row or column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two rows or columns; the first row or column holds the real part and the second row or column holds the imaginary part.

side = Nag_RightSide

, vl is not referenced.

9: pdvl – IntegerInput

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

Constraints:

if order=Nag_ColMajor,
- if $side = Nag_LeftSide$ or $Nag_BothSides$ , $pdvl \geq \max (1, n)$ ;
- if $side = Nag_RightSide$ , $pdvl \geq 1$ ;
if order=Nag_RowMajor,
- if $side = Nag_LeftSide$ or $Nag_BothSides$ , $pdvl \geq \max (1, mm)$ ;
- if $side = Nag_RightSide$ , $pdvl \geq 1$ .

10: vr[

\dim

] – doubleInput/Output

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

$\max (1, pdvr \times mm)$ when $side = Nag_RightSide$ or $Nag_BothSides$ and $order = Nag_ColMajor$ ;
$\max (1, n \times pdvr)$ when $side = Nag_RightSide$ or $Nag_BothSides$ and $order = Nag_RowMajor$ ;
$1$ when $side = Nag_LeftSide$ .

The

(i, j)

th element of the matrix is stored in

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

On entry: if

how_many = Nag_BackTransform

and

side = Nag_RightSide

Nag_BothSides

, vr must contain an

n

n

matrix

Q

(usually the matrix of Schur vectors returned by nag_dhseqr (f08pec)).

how_many = Nag_ComputeAll

Nag_ComputeSelected

, vr need not be set.

On exit: if

side = Nag_RightSide

Nag_BothSides

, vr contains the computed right eigenvectors (as specified by how_many and select). The eigenvectors are stored consecutively in the rows or columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one row or column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two rows or columns; the first row or column holds the real part and the second row or column holds the imaginary part.

side = Nag_LeftSide

, vr is not referenced.

11: pdvr – IntegerInput

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

Constraints:

if order=Nag_ColMajor,
- if $side = Nag_RightSide$ or $Nag_BothSides$ , $pdvr \geq \max (1, n)$ ;
- if $side = Nag_LeftSide$ , $pdvr \geq 1$ ;
if order=Nag_RowMajor,
- if $side = Nag_RightSide$ or $Nag_BothSides$ , $pdvr \geq \max (1, mm)$ ;
- if $side = Nag_LeftSide$ , $pdvr \geq 1$ .

12: mm – IntegerInput

On entry: the number of rows or columns in the arrays vl and/or vr. The precise number of rows or columns required (depending on the value of order),

required_rowcol

, is

n

how_many = Nag_ComputeAll

Nag_BackTransform

; if

how_many = Nag_ComputeSelected

required_rowcol

is obtained by counting

1

for each selected real eigenvector and

2

for each selected complex eigenvector (see select), in which case

0 \leq required_rowcol \leq n

Constraint:

mm \geq required_rowcol

13: m – Integer *Output

On exit:

required_rowcol

, the number of rows or columns of vl and/or vr actually used to store the computed eigenvectors. If

how_many = Nag_ComputeAll

Nag_BackTransform

, m is set to

n

14: 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_ENUM_INT_2

On entry,

side = 〈value〉

pdvl = 〈value〉

mm = 〈value〉

.
Constraint: if

side = Nag_LeftSide

Nag_BothSides

pdvl \geq \max (1, mm)

;
if

side = Nag_RightSide

pdvl \geq 1

On entry,

side = 〈value〉

pdvl = 〈value〉

and

n = 〈value〉

.
Constraint: if

side = Nag_LeftSide

Nag_BothSides

pdvl \geq \max (1, n)

;
if

side = Nag_RightSide

pdvl \geq 1

On entry,

side = 〈value〉

pdvr = 〈value〉

mm = 〈value〉

.
Constraint: if

side = Nag_RightSide

Nag_BothSides

pdvr \geq \max (1, mm)

;
if

side = Nag_LeftSide

pdvr \geq 1

On entry,

side = 〈value〉

pdvr = 〈value〉

and

n = 〈value〉

.
Constraint: if

side = Nag_RightSide

Nag_BothSides

pdvr \geq \max (1, n)

;
if

side = Nag_LeftSide

pdvr \geq 1

NE_INT

On entry,

mm = 〈value〉

.
Constraint:

mm \geq required_rowcol

, where

required_rowcol

is obtained by counting

1

for each selected real eigenvector and

2

for each selected complex eigenvector.

On entry,

n = 〈value〉

.
Constraint:

n \geq 0

On entry,

pdt = 〈value〉

.
Constraint:

pdt > 0

On entry,

pdvl = 〈value〉

.
Constraint:

pdvl > 0

On entry,

pdvr = 〈value〉

.
Constraint:

pdvr > 0

NE_INT_2

On entry,

pdt = 〈value〉

and

n = 〈value〉

.
Constraint:

pdt \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.

7 Accuracy

x_{i}

is an exact right eigenvector, and

{\tilde{x}}_{i}

is the corresponding computed eigenvector, then the angle

θ ({\tilde{x}}_{i}, x_{i})

between them is bounded as follows:

θ ({\tilde{x}}_{i}, x_{i}) \leq \frac{c (n) ε {‖T‖}_{2}}{{sep}_{i}}

where

{sep}_{i}

is the reciprocal condition number of

x_{i}

The condition number

{sep}_{i}

may be computed by calling nag_dtrsna (f08qlc).

NAG Library Function Document

nag_dtrevc (f08qkc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

NAG Library Function Documentnag_dtrevc (f08qkc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

NAG Library Function Document

nag_dtrevc (f08qkc)