NAG Library Function Document

nag_dtrsna (f08qlc)

+− 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_dtrsna (f08qlc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix.

2 Specification

#include <nag.h>

#include <nagf08.h>

void	nag_dtrsna (Nag_OrderType order, Nag_JobType job, Nag_HowManyType how_many, const Nag_Boolean select[], Integer n, const double t[], Integer pdt, const double vl[], Integer pdvl, const double vr[], Integer pdvr, double s[], double sep[], Integer mm, Integer m, NagError fail)

3 Description

nag_dtrsna (f08qlc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix

T

in canonical Schur form. These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix

A = Z T Z^{T}

(with orthogonal

Z

), from which

T

may have been derived.

nag_dtrsna (f08qlc) computes the reciprocal of the condition number of an eigenvalue

λ_{i}

s_{i} = \frac{|v^{H} u|}{{‖u‖}_{E} {‖v‖}_{E}},

where

u

and

v

are the right and left eigenvectors of

T

, respectively, corresponding to

λ_{i}

. This reciprocal condition number always lies between zero (i.e., ill-conditioned) and one (i.e., well-conditioned).

An approximate error estimate for a computed eigenvalue

λ_{i}

is then given by

\frac{ε ‖T‖}{s_{i}},

where

ε

is the machine precision.

To estimate the reciprocal of the condition number of the right eigenvector corresponding to

λ_{i}

, the function first calls nag_dtrexc (f08qfc) to reorder the eigenvalues so that

λ_{i}

is in the leading position:

T = Q (\begin{matrix} λ_{i} & c^{T} \\ 0 & T_{22} \end{matrix}) Q^{T} .

The reciprocal condition number of the eigenvector is then estimated as

{sep}_{i}

, the smallest singular value of the matrix

(T_{22} - λ_{i} I)

. This number ranges from zero (i.e., ill-conditioned) to very large (i.e., well-conditioned).

An approximate error estimate for a computed right eigenvector

u

corresponding to

λ_{i}

is then given by

\frac{ε ‖T‖}{{sep}_{i}} .

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: job – Nag_JobTypeInput

On entry: indicates whether condition numbers are required for eigenvalues and/or eigenvectors.

$job = Nag_EigVals$: Condition numbers for eigenvalues only are computed.
$job = Nag_EigVecs$: Condition numbers for eigenvectors only are computed.
$job = Nag_DoBoth$: Condition numbers for both eigenvalues and eigenvectors are computed.

Constraint:

job = Nag_EigVals

Nag_EigVecs

Nag_DoBoth

3: how_many – Nag_HowManyTypeInput

On entry: indicates how many condition numbers are to be computed.

$how_many = Nag_ComputeAll$: Condition numbers for all eigenpairs are computed.
$how_many = Nag_ComputeSelected$: Condition numbers for selected eigenpairs (as specified by select) are computed.

Constraint:

how_many = Nag_ComputeAll

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 the eigenpairs for which condition numbers are to be computed if

how_many = Nag_ComputeSelected

. To select condition numbers for the eigenpair corresponding to the real eigenvalue

λ_{j}

select [j - 1]

must be set Nag_TRUE. To select condition numbers corresponding to a complex conjugate pair of eigenvalues

λ_{j}

and

λ_{j + 1}

select [j - 1]

and/or

select [j]

must be set to Nag_TRUE.

how_many = Nag_ComputeAll

, 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$ ] – const doubleInput

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

$\max (1, pdvl \times mm)$ when $job = Nag_EigVals$ or $Nag_DoBoth$ and $order = Nag_ColMajor$ ;
$\max (1, n \times pdvl)$ when $job = Nag_EigVals$ or $Nag_DoBoth$ and $order = Nag_RowMajor$ ;
$1$ when $job = Nag_EigVecs$ .

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

job = Nag_EigVals

Nag_DoBoth

, vl must contain the left eigenvectors of

T

(or of any matrix

Q T Q^{T}

with

Q

orthogonal) corresponding to the eigenpairs specified by how_many and select. The eigenvectors must be stored in consecutive rows or columns of vl, as returned by nag_dhsein (f08pkc) or nag_dtrevc (f08qkc).

job = Nag_EigVecs

, 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 $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvl \geq \max (1, n)$ ;
- if $job = Nag_EigVecs$ , $pdvl \geq 1$ ;
if order=Nag_RowMajor,
- if $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvl \geq \max (1, mm)$ ;
- if $job = Nag_EigVecs$ , $pdvl \geq 1$ .

10: vr[ $\dim$ ] – const doubleInput

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

$\max (1, pdvr \times mm)$ when $job = Nag_EigVals$ or $Nag_DoBoth$ and $order = Nag_ColMajor$ ;
$\max (1, n \times pdvr)$ when $job = Nag_EigVals$ or $Nag_DoBoth$ and $order = Nag_RowMajor$ ;
$1$ when $job = Nag_EigVecs$ .

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

job = Nag_EigVals

Nag_DoBoth

, vr must contain the right eigenvectors of

T

(or of any matrix

Q T Q^{T}

with

Q

orthogonal) corresponding to the eigenpairs specified by how_many and select. The eigenvectors must be stored in consecutive rows or columns of vr, as returned by nag_dhsein (f08pkc) or nag_dtrevc (f08qkc).

job = Nag_EigVecs

, 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 $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvr \geq \max (1, n)$ ;
- if $job = Nag_EigVecs$ , $pdvr \geq 1$ ;
if order=Nag_RowMajor,
- if $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvr \geq \max (1, mm)$ ;
- if $job = Nag_EigVecs$ , $pdvr \geq 1$ .

12: s[ $\dim$ ] – doubleOutput

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

$\max (1, mm)$ when $job = Nag_EigVals$ or $Nag_DoBoth$ ;
$1$ when $job = Nag_EigVecs$ .

On exit: the reciprocal condition numbers of the selected eigenvalues if

job = Nag_EigVals

Nag_DoBoth

, stored in consecutive elements of the array. Thus

s [j - 1]

sep [j - 1]

and the

j

th rows or columns of vl and vr all correspond to the same eigenpair (but not in general the

j

th eigenpair unless all eigenpairs have been selected). For a complex conjugate pair of eigenvalues, two consecutive elements of s are set to the same value.

s is not referenced if

job = Nag_EigVecs

13: sep[ $\dim$ ] – doubleOutput

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

$\max (1, mm)$ when $job = Nag_EigVecs$ or $Nag_DoBoth$ ;
$1$ when $job = Nag_EigVals$ .

On exit: the estimated reciprocal condition numbers of the selected right eigenvectors if

job = Nag_EigVecs

Nag_DoBoth

, stored in consecutive elements of the array. For a complex eigenvector, two consecutive elements of sep are set to the same value. If the eigenvalues cannot be reordered to compute

sep [j - 1]

, then

sep [j - 1]

is set to zero; this can only occur when the true value would be very small anyway.

job = Nag_EigVals

, sep is not referenced.

14: mm – IntegerInput

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

m

, is

n

how_many = Nag_ComputeAll

; if

how_many = Nag_ComputeSelected

m

is obtained by counting

1

for each selected real eigenvalue, and

2

for each selected complex conjugate pair of eigenvalues (see select), in which case

0 \leq m \leq n

Constraint:

mm \geq m

15: m – Integer *Output

On exit:

m

, the number of elements of s and/or sep actually used to store the estimated condition numbers. If

how_many = Nag_ComputeAll

, m is set to

n

16: 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, $job = 〈value〉$ , $pdvl = 〈value〉$ , $mm = 〈value〉$ .
Constraint: if $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvl \geq \max (1, mm)$ ;
if $job = Nag_EigVecs$ , $pdvl \geq 1$ .; On entry, $job = 〈value〉$ , $pdvl = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvl \geq \max (1, n)$ ;
if $job = Nag_EigVecs$ , $pdvl \geq 1$ .; On entry, $job = 〈value〉$ , $pdvr = 〈value〉$ , $mm = 〈value〉$ .
Constraint: if $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvr \geq \max (1, mm)$ ;
if $job = Nag_EigVecs$ , $pdvr \geq 1$ .; On entry, $job = 〈value〉$ , $pdvr = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $job = Nag_EigVals$ or $Nag_DoBoth$ , $pdvr \geq \max (1, n)$ ;
if $job = Nag_EigVecs$ , $pdvr \geq 1$ .
NE_INT: 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, $mm = 〈value〉$ and $m = 〈value〉$ .
Constraint: $mm \geq m$ .; 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

The computed values

{sep}_{i}

may over estimate the true value, but seldom by a factor of more than

3

8 Further Comments

For a description of canonical Schur form, see the document for nag_dhseqr (f08pec).

The complex analogue of this function is nag_ztrsna (f08qyc).

9 Example

This example computes approximate error estimates for all the eigenvalues and right eigenvectors of the matrix

T

, where

T = (\begin{array}{r} 0.7995 & - 0.1144 & 0.0060 & 0.0336 \\ 0.0000 & - 0.0994 & 0.2478 & 0.3474 \\ 0.0000 & - 0.6483 & - 0.0994 & 0.2026 \\ 0.0000 & 0.0000 & 0.0000 & - 0.1007 \end{array}) .

NAG Library Function Documentnag_dtrsna (f08qlc)

+− 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_dtrsna (f08qlc)