NAG Library Function Document

nag_ztrevc (f08qxc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

1 Purpose

nag_ztrevc (f08qxc) computes selected left and/or right eigenvectors of a complex upper triangular matrix.

2 Specification

#include <nag.h>

#include <nagf08.h>

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

3 Description

nag_ztrevc (f08qxc) computes left and/or right eigenvectors of a complex upper triangular matrix

T

. Such a matrix arises from the Schur factorization of a complex general matrix, as computed by nag_zhseqr (f08psc), 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^{H} y = \bar{λ} y) .

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

A

A = Q T Q^{H}

; 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

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

4 References

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: 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$ ] – const Nag_BooleanInput

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 eigenvector corresponding to the eigenvalue

λ_{j}

select [j - 1]

must be set Nag_TRUE.

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$ ] – ComplexInput/Output

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 triangular matrix

T

, as returned by nag_zhseqr (f08psc).

On exit: is used as internal workspace prior to being restored and hence is unchanged.

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$ ] – ComplexInput/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_zhseqr (f08psc)).

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 (depending on the value of order) of the array, in the same order as their eigenvalues.

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$ ] – ComplexInput/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_zhseqr (f08psc)).

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 (depending on the value of order) of the array, in the same order as their eigenvalues.

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 (depending on the value of order) in the arrays vl and/or vr. The precise number of rows or columns required,

required_rowcol

, is

n

how_many = Nag_ComputeAll

Nag_BackTransform

; if

how_many = Nag_ComputeSelected

required_rowcol

is the number of selected eigenvectors (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 selected 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$ or $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$ or $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$ or $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$ or $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 the number of selected eigenvectors.; 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_ztrsna (f08qyc).

8 Further Comments

The real analogue of this function is nag_dtrevc (f08qkc).

9 Example

See Section 9 in nag_zgebal (f08nvc).

nag_ztrevc (f08qxc) (PDF version)

f08 Chapter Contents

f08 Chapter Introduction

NAG C Library Manual

NAG Library Function Documentnag_ztrevc (f08qxc)

+− 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_ztrevc (f08qxc)