Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dstevd (f08jc)

## Purpose

nag_lapack_dstevd (f08jc) computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors. However, if only eigenvalues are required, then it uses the Pal–Walker–Kahan variant of the QL$QL$ or QR$QR$ algorithm.

## Syntax

[d, e, z, info] = f08jc(job, d, e, 'n', n)
[d, e, z, info] = nag_lapack_dstevd(job, d, e, 'n', n)

## Description

nag_lapack_dstevd (f08jc) computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix T$T$. In other words, it can compute the spectral factorization of T$T$ as
 T = ZΛZT, $T=ZΛZT,$
where Λ$\Lambda$ is a diagonal matrix whose diagonal elements are the eigenvalues λi${\lambda }_{i}$, and Z$Z$ is the orthogonal matrix whose columns are the eigenvectors zi${z}_{i}$. Thus
 Tzi = λizi,  i = 1,2, … ,n. $Tzi=λizi, i=1,2,…,n.$

## References

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

## Parameters

### Compulsory Input Parameters

1:     job – string (length ≥ 1)
Indicates whether eigenvectors are computed.
job = 'N'${\mathbf{job}}=\text{'N'}$
Only eigenvalues are computed.
job = 'V'${\mathbf{job}}=\text{'V'}$
Eigenvalues and eigenvectors are computed.
Constraint: job = 'N'${\mathbf{job}}=\text{'N'}$ or 'V'$\text{'V'}$.
2:     d( : $:$) – double array
Note: the dimension of the array d must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The n$n$ diagonal elements of the tridiagonal matrix T$T$.
3:     e( : $:$) – double array
Note: the dimension of the array e must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The n1$n-1$ off-diagonal elements of the tridiagonal matrix T$T$. The n$n$th element of this array is used as workspace.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array d and the second dimension of the array d. (An error is raised if these dimensions are not equal.)
n$n$, the order of the matrix T$T$.
Constraint: n0${\mathbf{n}}\ge 0$.

### Input Parameters Omitted from the MATLAB Interface

ldz work lwork iwork liwork

### Output Parameters

1:     d( : $:$) – double array
Note: the dimension of the array d must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The eigenvalues of the matrix T$T$ in ascending order.
2:     e( : $:$) – double array
Note: the dimension of the array e must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
e is overwritten with intermediate results.
3:     z(ldz, : $:$) – double array
The first dimension, ldz, of the array z will be
• if job = 'V'${\mathbf{job}}=\text{'V'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if job = 'N'${\mathbf{job}}=\text{'N'}$, ldz1$\mathit{ldz}\ge 1$.
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if job = 'V'${\mathbf{job}}=\text{'V'}$ and at least 1$1$ if job = 'N'${\mathbf{job}}=\text{'N'}$
If job = 'V'${\mathbf{job}}=\text{'V'}$, z stores the orthogonal matrix Z$Z$ which contains the eigenvectors of T$T$.
If job = 'N'${\mathbf{job}}=\text{'N'}$, z is not referenced.
4:     info – int64int32nag_int scalar
info = 0${\mathbf{info}}=0$ unless the function detects an error (see Section [Error Indicators and Warnings]).

## Error Indicators and Warnings

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$i$ had an illegal value on entry. The parameters are numbered as follows:
1: job, 2: n, 3: d, 4: e, 5: z, 6: ldz, 7: work, 8: lwork, 9: iwork, 10: liwork, 11: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
INFO > 0${\mathbf{INFO}}>0$
if info = i${\mathbf{info}}=i$ and job = 'N'${\mathbf{job}}=\text{'N'}$, the algorithm failed to converge; i$i$ elements of an intermediate tridiagonal form did not converge to zero; if info = i${\mathbf{info}}=i$ and job = 'V'${\mathbf{job}}=\text{'V'}$, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column i / (n + 1)$i/\left({\mathbf{n}}+1\right)$ through i  mod  (n + 1).

## Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix (T + E)$\left(T+E\right)$, where
 ‖E‖2 = O(ε) ‖T‖2 , $‖E‖2 = O(ε) ‖T‖2 ,$
and ε$\epsilon$ is the machine precision.
If λi${\lambda }_{i}$ is an exact eigenvalue and λ̃i${\stackrel{~}{\lambda }}_{i}$ is the corresponding computed value, then
 |λ̃i − λi| ≤ c (n) ε ‖T‖2 , $| λ~i - λi | ≤ c (n) ε ‖T‖2 ,$
where c(n)$c\left(n\right)$ is a modestly increasing function of n$n$.
If zi${z}_{i}$ is the corresponding exact eigenvector, and i${\stackrel{~}{z}}_{i}$ is the corresponding computed eigenvector, then the angle θ(i,zi)$\theta \left({\stackrel{~}{z}}_{i},{z}_{i}\right)$ between them is bounded as follows:
 θ (z̃i,zi) ≤ ( c (n) ε ‖T‖2 )/( mini ≠ j  |λi − λj| ) . $θ (z~i,zi) ≤ c (n) ε ‖T‖2 min i≠j | λi - λj | .$
Thus the accuracy of a computed eigenvector depends on the gap between its eigenvalue and all the other eigenvalues.

There is no complex analogue of this function.

## Example

```function nag_lapack_dstevd_example
job = 'V';
d = [1;
4;
9;
16];
e = [1;
2;
3;
0];
[dOut, eOut, z, info] = nag_lapack_dstevd(job, d, e)
```
```

dOut =

0.6476
3.5470
8.6578
17.1477

eOut =

0
0
0
0

z =

0.9396    0.3388   -0.0494    0.0034
-0.3311    0.8628   -0.3781    0.0545
0.0853   -0.3648   -0.8558    0.3568
-0.0167    0.0879    0.3497    0.9326

info =

0

```
```function f08jc_example
job = 'V';
d = [1;
4;
9;
16];
e = [1;
2;
3;
0];
[dOut, eOut, z, info] = f08jc(job, d, e)
```
```

dOut =

0.6476
3.5470
8.6578
17.1477

eOut =

0
0
0
0

z =

0.9396    0.3388   -0.0494    0.0034
-0.3311    0.8628   -0.3781    0.0545
0.0853   -0.3648   -0.8558    0.3568
-0.0167    0.0879    0.3497    0.9326

info =

0

```