NAG Library Function Document

nag_dstevr (f08jdc)

void	nag_dstevr (Nag_OrderType order, Nag_JobType job, Nag_RangeType range, Integer n, double d[], double e[], double vl, double vu, Integer il, Integer iu, double abstol, Integer m, double w[], double z[], Integer pdz, Integer isuppz[], NagError fail)

3 Description

Whenever possible nag_dstevr (f08jdc) computes the eigenspectrum using Relatively Robust Representations. nag_dstevr (f08jdc) computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various ‘good’

L D L^{T}

representations (also known as Relatively Robust Representations). Gram–Schmidt orthogonalisation is avoided as far as possible. More specifically, the various steps of the algorithm are as follows. For the

i

th unreduced block of

T

(a)	compute $T - σ_{i} I = L_{i} D_{i} L_{i}^{T}$ , such that $L_{i} D_{i} L_{i}^{T}$ is a relatively robust representation,
(b)	compute the eigenvalues, $λ_{j}$ , of $L_{i} D_{i} L_{i}^{T}$ to high relative accuracy by the dqds algorithm,
(c)	if there is a cluster of close eigenvalues, ‘choose’ $σ_{i}$ close to the cluster, and go to (a),
(d)	given the approximate eigenvalue $λ_{j}$ of $L_{i} D_{i} L_{i}^{T}$ , compute the corresponding eigenvector by forming a rank-revealing twisted factorization.

The desired accuracy of the output can be specified by the argument abstol. For more details, see Dhillon (1997) and Parlett and Dhillon (2000).

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

Barlow J and Demmel J W (1990) Computing accurate eigensystems of scaled diagonally dominant matrices SIAM J. Numer. Anal. 27 762–791

Demmel J W and Kahan W (1990) Accurate singular values of bidiagonal matrices SIAM J. Sci. Statist. Comput. 11 873–912

Dhillon I (1997) A new

O (n^{2})

algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem Computer Science Division Technical Report No. UCB//CSD-97-971 UC Berkeley

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Parlett B N and Dhillon I S (2000) Relatively robust representations of symmetric tridiagonals Linear Algebra Appl. 309 121–151

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 eigenvectors are computed.

$job = Nag_EigVals$: Only eigenvalues are computed.
$job = Nag_DoBoth$: Eigenvalues and eigenvectors are computed.

Constraint:

job = Nag_EigVals

Nag_DoBoth

3: range – Nag_RangeTypeInput

On entry: if

range = Nag_AllValues

, all eigenvalues will be found.

range = Nag_Interval

, all eigenvalues in the half-open interval

(vl, vu]

will be found.

range = Nag_Indices

, the ilth to iuth eigenvalues will be found.

Constraint:

range = Nag_AllValues

Nag_Interval

Nag_Indices

4: n – IntegerInput

On entry:

n

, the order of the matrix.

Constraint:

n \geq 0

5: d[ $\dim$ ] – doubleInput/Output

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

\max (1, n)

On entry: the

n

diagonal elements of the tridiagonal matrix

T

On exit: may be multiplied by a constant factor chosen to avoid over/underflow in computing the eigenvalues.

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

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

\max (1, n - 1)

On entry: the

(n - 1)

subdiagonal elements of the tridiagonal matrix

T

On exit: may be multiplied by a constant factor chosen to avoid over/underflow in computing the eigenvalues.

7: vl – doubleInput

8: vu – doubleInput

On entry: if

range = Nag_Interval

, the lower and upper bounds of the interval to be searched for eigenvalues.

range = Nag_AllValues

Nag_Indices

, vl and vu are not referenced.

Constraint: if

range = Nag_Interval

vl < vu

9: il – IntegerInput

10: iu – IntegerInput

On entry: if

range = Nag_Indices

, the indices (in ascending order) of the smallest and largest eigenvalues to be returned.

range = Nag_AllValues

Nag_Interval

, il and iu are not referenced.

Constraints:

if $range = Nag_Indices$ and $n = 0$ , $il = 1$ and $iu = 0$ ;
if $range = Nag_Indices$ and $n > 0$ , $1 \leq il \leq iu \leq n$ .

11: abstol – doubleInput

On entry: the absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval

[a, b]

of width less than or equal to

abstol + ε \max (|a|, |b|),

where

ε

is the machine precision. If abstol is less than or equal to zero, then

ε {‖T‖}_{1}

will be used in its place. See Demmel and Kahan (1990).

If high relative accuracy is important, set abstol to

nag_real_safe_small_number ()

, although doing so does not currently guarantee that eigenvalues are computed to high relative accuracy. See Barlow and Demmel (1990) for a discussion of which matrices can define their eigenvalues to high relative accuracy.

12: m – Integer *Output

On exit: the total number of eigenvalues found.

0 \leq m \leq n

range = Nag_AllValues

m = n

range = Nag_Indices

m = iu - il + 1

13: w[ $\dim$ ] – doubleOutput

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

\max (1, n)

On exit: the first m elements contain the selected eigenvalues in ascending order.

14: z[ $\dim$ ] – doubleOutput

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

$\max (1, pdz \times n)$ when $job = Nag_DoBoth$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix

Z

is stored in

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

On exit: if

job = Nag_DoBoth

, the first m columns of

Z

contain the orthonormal eigenvectors of the matrix

A

corresponding to the selected eigenvalues, with the

i

th column of

Z

holding the eigenvector associated with

w [i - 1]

job = Nag_EigVals

, z is not referenced.

15: pdz – IntegerInput

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

Constraints:

if $job = Nag_DoBoth$ , $pdz \geq \max (1, n)$ ;
otherwise $pdz \geq 1$ .

16: isuppz[ $\dim$ ] – IntegerOutput

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

\max (1, 2 \times m)

On exit: the support of the eigenvectors in z, i.e., the indices indicating the nonzero elements in z. The

i

th eigenvector is nonzero only in elements

isuppz [2 \times i - 2]

through

isuppz [2 \times i - 1]

. Implemented only for

range = Nag_AllValues

Nag_Indices

and

iu - il = n - 1

17: 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〉$ , $pdz = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $job = Nag_DoBoth$ , $pdz \geq \max (1, n)$ ;
otherwise $pdz \geq 1$ .
NE_ENUM_INT_3: On entry, $range = 〈value〉$ , $il = 〈value〉$ , $iu = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $range = Nag_Indices$ and $n = 0$ , $il = 1$ and $iu = 0$ ;
if $range = Nag_Indices$ and $n > 0$ , $1 \leq il \leq iu \leq n$ .
NE_ENUM_REAL_2: On entry, $range = 〈value〉$ , $vl = 〈value〉$ and $vu = 〈value〉$ .
Constraint: if $range = Nag_Interval$ , $vl < vu$ .
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $pdz = 〈value〉$ .
Constraint: $pdz > 0$ .
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.; An internal error has occurred in this function. Please refer to fail in nag_dstebz (f08jjc).

7 Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix

(A + E)

, where

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

and

ε

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

8 Further Comments

The total number of floating point operations is proportional to

n^{2}

job = Nag_EigVals

and is proportional to

n^{3}

job = Nag_DoBoth

and

range = Nag_AllValues

, otherwise the number of floating point operations will depend upon the number of computed eigenvectors.

9 Example

This example finds the eigenvalues with indices in the range

[2, 3]

, and the corresponding eigenvectors, of the symmetric tridiagonal matrix

T = (\begin{array}{r} 1 & 1 & 0 & 0 \\ 1 & 4 & 2 & 0 \\ 0 & 2 & 9 & 3 \\ 0 & 0 & 3 & 16 \end{array}) .

NAG Library Function Documentnag_dstevr (f08jdc)

+− 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_dstevr (f08jdc)