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_dstedc (f08jh)

Purpose

nag_lapack_dstedc (f08jh) computes all the eigenvalues and, optionally, all the eigenvectors of a real n$n$ by n$n$ symmetric tridiagonal matrix, or of a real full or banded symmetric matrix which has been reduced to tridiagonal form.

Syntax

[d, e, z, info] = f08jh(compz, d, e, z, 'n', n)
[d, e, z, info] = nag_lapack_dstedc(compz, d, e, z, 'n', n)

Description

nag_lapack_dstedc (f08jh) computes all the eigenvalues and, optionally, the eigenvectors of a real symmetric tridiagonal matrix T$T$. That is, the function computes the spectral factorization of T$T$ given by
 T = Z Λ ZT , $T = Z Λ ZT ,$
where Λ$\Lambda$ is a diagonal matrix whose diagonal elements are the eigenvalues, λi${\lambda }_{i}$, of T$T$ and Z$Z$ is an orthogonal matrix whose columns are the eigenvectors, zi${z}_{i}$, of T$T$. Thus
 Tzi = λi zi ,   i = 1,2, … ,n . $Tzi = λi zi , i = 1,2,…,n .$
The function may also be used to compute all the eigenvalues and vectors of a real full, or banded, symmetric matrix A$A$ which has been reduced to tridiagonal form T$T$ as
 A = QTQT , $A = QTQT ,$
where Q$Q$ is orthogonal. The spectral factorization of A$A$ is then given by
 A = (QZ) Λ (QZ)T . $A = (QZ) Λ (QZ)T .$
In this case Q$Q$ must be formed explicitly and passed to nag_lapack_dstedc (f08jh) in the array z, and the function called with compz = 'V'${\mathbf{compz}}=\text{'V'}$. Functions which may be called to form T$T$ and 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'}$
When only eigenvalues are required then this function calls nag_lapack_dsterf (f08jf) to compute the eigenvalues of the tridiagonal matrix T$T$, but when eigenvectors of T$T$ are also required and the matrix is not too small, then a divide and conquer method is used, which can be much faster than nag_lapack_dsteqr (f08je), although more storage is required.

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
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

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.
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 subdiagonal elements of the tridiagonal matrix.
4:     z(ldz, : $:$) – double array
The first dimension, ldz, of the array z must satisfy
• if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise 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$ otherwise
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, z must contain the orthogonal matrix Q$Q$ used in the reduction to tridiagonal form.

Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array d.
n$n$, the order of the symmetric tridiagonal 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)$.
If ${\mathbf{INFO}}={\mathbf{0}}$, the eigenvalues in ascending order.
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 = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise 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$ otherwise
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, z contains the orthonormal eigenvectors of the original symmetric matrix A$A$, and if compz = 'I'${\mathbf{compz}}=\text{'I'}$, z contains the orthonormal eigenvectors of the symmetric tridiagonal matrix T$T$.
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: 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.
W INFO > 0${\mathbf{INFO}}>0$
The algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns info / (n + 1)${\mathbf{info}}/\left({\mathbf{n}}+1\right)$ through info  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 mini≠j|λi-λj| .$
Thus the accuracy of a computed eigenvector depends on the gap between its eigenvalue and all the other eigenvalues.
See Section 4.7 of Anderson et al. (1999) for further details. See also nag_lapack_ddisna (f08fl).

If only eigenvalues are required, the total number of floating point operations is approximately proportional to n2${n}^{2}$. When eigenvectors are required the number of operations is bounded above by approximately the same number of operations as nag_lapack_dsteqr (f08je), but for large matrices nag_lapack_dstedc (f08jh) is usually much faster.
The complex analogue of this function is nag_lapack_zstedc (f08jv).

Example

```function nag_lapack_dstedc_example
compz = 'V';
d = [4.99;
-2.48056;
-0.06611383795565984;
0.8566738379556601];
e = [0.223606797749979;
1.102975469536834;
1.430096362031785];
z = [1, 0, 0, 0;
0, 0.1788854381999832, -0.1320894800577693, -0.9749627527542107;
0, 0.9838699100999075, 0.02401626910141259, 0.1772659550462201;
0, 0, -0.9909468139494252, 0.1342550256917159];
[dOut, eOut, zOut, info] = nag_lapack_dstedc(compz, d, e, z)
```
```

dOut =

-2.9943
-0.7000
1.9974
4.9969

eOut =

0
0
0

zOut =

0.0251   -0.0162   -0.0113   -0.9995
-0.0656    0.5859   -0.8077   -0.0020
-0.9002    0.3135    0.3006   -0.0311
-0.4298   -0.7471   -0.5070    0.0071

info =

0

```
```function f08jh_example
compz = 'V';
d = [4.99;
-2.48056;
-0.06611383795565984;
0.8566738379556601];
e = [0.223606797749979;
1.102975469536834;
1.430096362031785];
z = [1, 0, 0, 0;
0, 0.1788854381999832, -0.1320894800577693, -0.9749627527542107;
0, 0.9838699100999075, 0.02401626910141259, 0.1772659550462201;
0, 0, -0.9909468139494252, 0.1342550256917159];
[dOut, eOut, zOut, info] = f08jh(compz, d, e, z)
```
```

dOut =

-2.9943
-0.7000
1.9974
4.9969

eOut =

0
0
0

zOut =

0.0251   -0.0162   -0.0113   -0.9995
-0.0656    0.5859   -0.8077   -0.0020
-0.9002    0.3135    0.3006   -0.0311
-0.4298   -0.7471   -0.5070    0.0071

info =

0

```