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_dsteqr (f08je)

## Purpose

nag_lapack_dsteqr (f08je) computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix, or of a real symmetric matrix which has been reduced to tridiagonal form.

## Syntax

[d, e, z, info] = f08je(compz, d, e, 'n', n, 'z', z)
[d, e, z, info] = nag_lapack_dsteqr(compz, d, e, 'n', n, 'z', z)

## Description

nag_lapack_dsteqr (f08je) 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.$
The function may also be used to compute all the eigenvalues and eigenvectors of a real symmetric matrix A$A$ which has been reduced to tridiagonal form T$T$:
 A = QTQT, where ​Q​ is orthogonal = (QZ)Λ(QZ)T.
$A =QTQT, where ​Q​ is orthogonal =(QZ)Λ(QZ)T.$
In this case, the matrix Q$Q$ must be formed explicitly and passed to nag_lapack_dsteqr (f08je), which must be called with compz = 'V'${\mathbf{compz}}=\text{'V'}$. The functions which must be called to perform the reduction to tridiagonal form and form Q$Q$ are:
 full matrix nag_lapack_dsytrd (f08fe) and nag_lapack_dorgtr (f08ff) full matrix, packed storage nag_lapack_dsptrd (f08ge) and nag_lapack_dopgtr (f08gf) band matrix nag_lapack_dsbtrd (f08he) with vect = 'V'${\mathbf{vect}}=\text{'V'}$.
nag_lapack_dsteqr (f08je) uses the implicitly shifted QR$QR$ algorithm, switching between the QR$QR$ and QL$QL$ variants in order to handle graded matrices effectively (see Greenbaum and Dongarra (1980)). The eigenvectors are normalized so that zi2 = 1${‖{z}_{i}‖}_{2}=1$, but are determined only to within a factor ± 1$±1$.
If only the eigenvalues of T$T$ are required, it is more efficient to call nag_lapack_dsterf (f08jf) instead. If T$T$ is positive definite, small eigenvalues can be computed more accurately by nag_lapack_dpteqr (f08jg).

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Greenbaum A and Dongarra J J (1980) Experiments with QR/QL methods for the symmetric triangular eigenproblem LAPACK Working Note No. 17 (Technical Report CS-89-92) University of Tennessee, Knoxville
Parlett B N (1998) The Symmetric Eigenvalue Problem SIAM, Philadelphia

## Parameters

### Compulsory Input Parameters

1:     compz – string (length ≥ 1)
Indicates whether the eigenvectors are to be computed.
compz = 'N'${\mathbf{compz}}=\text{'N'}$
Only the eigenvalues are computed (and the array z is not referenced).
compz = 'I'${\mathbf{compz}}=\text{'I'}$
The eigenvalues and eigenvectors of T$T$ are computed (and the array z is initialized by the function).
compz = 'V'${\mathbf{compz}}=\text{'V'}$
The eigenvalues and eigenvectors of A$A$ are computed (and the array z must contain the matrix Q$Q$ on entry).
Constraint: compz = 'N'${\mathbf{compz}}=\text{'N'}$, 'V'$\text{'V'}$ or 'I'$\text{'I'}$.
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 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,n1)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$.
The off-diagonal elements of the tridiagonal matrix T$T$.

### 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$.
2:     z(ldz, : $:$) – double array
The first dimension, ldz, of the array z must satisfy
• if compz = 'I'${\mathbf{compz}}=\text{'I'}$ or 'V'$\text{'V'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if compz = 'N'${\mathbf{compz}}=\text{'N'}$, ldz1$\mathit{ldz}\ge 1$.
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, z must contain the orthogonal matrix Q$Q$ from the reduction to tridiagonal form.
If compz = 'I'${\mathbf{compz}}=\text{'I'}$, z need not be set.

ldz work

### 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 n$n$ eigenvalues in ascending order, unless ${\mathbf{INFO}}>{\mathbf{0}}$ (in which case see Section [Error Indicators and Warnings]).
2:     e( : $:$) – double array
Note: the dimension of the array e must be at least max (1,n1)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$.
3:     z(ldz, : $:$) – double array
The first dimension, ldz, of the array z will be
• if compz = 'I'${\mathbf{compz}}=\text{'I'}$ or 'V'$\text{'V'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if compz = 'N'${\mathbf{compz}}=\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 compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$
If compz = 'I'${\mathbf{compz}}=\text{'I'}$ or 'V'$\text{'V'}$, the n$n$ required orthonormal eigenvectors stored as columns of Z$Z$; the i$i$th column corresponds to the i$i$th eigenvalue, where i = 1,2,,n$i=1,2,\dots ,n$, unless ${\mathbf{INFO}}>{\mathbf{0}}$.
If compz = 'N'${\mathbf{compz}}=\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

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_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: compz, 2: n, 3: d, 4: e, 5: z, 6: ldz, 7: work, 8: 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.
W INFO > 0${\mathbf{INFO}}>0$
The algorithm has failed to find all the eigenvalues after a total of 30 × n$30×{\mathbf{n}}$ iterations. In this case, d and e contain on exit the diagonal and off-diagonal elements, respectively, of a tridiagonal matrix orthogonally similar to T$T$. If info = i${\mathbf{info}}=i$, then i$i$ off-diagonal elements have not converged to zero.

## 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 mini≠j|λi-λj| .$
Thus the accuracy of a computed eigenvector depends on the gap between its eigenvalue and all the other eigenvalues.

The total number of floating point operations is typically about 24n2$24{n}^{2}$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$ and about 7n3$7{n}^{3}$ if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, but depends on how rapidly the algorithm converges. When compz = 'N'${\mathbf{compz}}=\text{'N'}$, the operations are all performed in scalar mode; the additional operations to compute the eigenvectors when compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ can be vectorized and on some machines may be performed much faster.
The complex analogue of this function is nag_lapack_zsteqr (f08js).

## Example

```function nag_lapack_dsteqr_example
compz = 'I';
d = [-6.99;
7.92;
2.34;
0.32];
e = [-0.44;
-2.63;
-1.18];
z = zeros(4, 4);
[dOut, eOut, z, info] = nag_lapack_dsteqr(compz, d, e, 'z', z)
```
```

dOut =

-7.0037
-0.4059
2.0028
8.9968

eOut =

0
0
0

z =

-0.9995   -0.0109   -0.0167   -0.0255
-0.0310    0.1627    0.3408    0.9254
-0.0089    0.5170    0.7696   -0.3746
-0.0014    0.8403   -0.5397    0.0509

info =

0

```
```function f08je_example
compz = 'I';
d = [-6.99;
7.92;
2.34;
0.32];
e = [-0.44;
-2.63;
-1.18];
z = zeros(4, 4);
[dOut, eOut, z, info] = f08je(compz, d, e, 'z', z)
```
```

dOut =

-7.0037
-0.4059
2.0028
8.9968

eOut =

0
0
0

z =

-0.9995   -0.0109   -0.0167   -0.0255
-0.0310    0.1627    0.3408    0.9254
-0.0089    0.5170    0.7696   -0.3746
-0.0014    0.8403   -0.5397    0.0509

info =

0

```