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_zstedc (f08jv)

## Purpose

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

## Syntax

[d, e, z, info] = f08jv(compz, d, e, z, 'n', n)
[d, e, z, info] = nag_lapack_zstedc(compz, d, e, z, 'n', n)

## Description

nag_lapack_zstedc (f08jv) 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 eigenvectors of a complex full, or banded, Hermitian matrix A$A$ which has been reduced to real tridiagonal form T$T$ as
 A = QTQH , $A = QTQH ,$
where Q$Q$ is unitary. The spectral factorization of A$A$ is then given by
 A = (QZ) Λ (QZ)H . $A = (QZ) Λ (QZ)H .$
In this case Q$Q$ must be formed explicitly and passed to nag_lapack_zstedc (f08jv) 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_zhetrd (f08fs) and nag_lapack_zungtr (f08ft) full matrix, packed storage nag_lapack_zhptrd (f08gs) and nag_lapack_zupgtr (f08gt) band matrix nag_lapack_zhbtrd (f08hs), 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_zsteqr (f08js), 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, : $:$) – complex 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 unitary 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 rwork lrwork 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, : $:$) – complex 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 Hermitian 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

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: rwork, 10: lrwork, 11: iwork, 12: liwork, 13: 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$
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_zsteqr (f08js), but for large matrices nag_lapack_zstedc (f08jv) is usually much faster.
The real analogue of this function is nag_lapack_dstedc (f08jh).

## Example

```function nag_lapack_zstedc_example
compz = 'V';
d = [-3.13;
-1.28529412359;
-0.9961823111303629;
-1.998523565279637];
e = [4.449280840765168;
1.700240893426197;
2.514369223733909];
z = [complex(1),  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  0.4360255217484467 + 0.4719863895215144i, ...
0.178928959228093 + 0.2536888179436562i,  -0.6192449219137889 - 0.3275251599103912i;
0 + 0i,  -0.76416844017769 - 0.05618885589541835i, ...
0.2548894129557567 + 0.05297877813842256i,  -0.5669454100367172 + 0.1539056392010643i;
0 + 0i,  0 + 0i,  0.8716895470004201 - 0.2756961753092227i, ...
0.2890720654179352 - 0.2838772508762855i];
[dOut, eOut, zOut, info] = nag_lapack_zstedc(compz, d, e, z)
```
```

dOut =

-7.0042
-4.0038
0.5968
3.0012

eOut =

0
0
0

zOut =

-0.7293 + 0.0000i   0.2610 + 0.0000i  -0.3718 + 0.0000i  -0.5117 + 0.0000i
0.1654 + 0.2046i  -0.5966 - 0.4235i  -0.4002 - 0.1869i  -0.2493 - 0.3718i
-0.6081 - 0.0301i  -0.5413 + 0.0870i   0.0531 + 0.1444i   0.5521 - 0.0176i
-0.1653 + 0.0303i  -0.3061 - 0.0482i   0.7234 - 0.3459i  -0.4461 + 0.1836i

info =

0

```
```function f08jv_example
compz = 'V';
d = [-3.13;
-1.28529412359;
-0.9961823111303629;
-1.998523565279637];
e = [4.449280840765168;
1.700240893426197;
2.514369223733909];
z = [complex(1),  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  0.4360255217484467 + 0.4719863895215144i, ...
0.178928959228093 + 0.2536888179436562i,  -0.6192449219137889 - 0.3275251599103912i;
0 + 0i,  -0.76416844017769 - 0.05618885589541835i, ...
0.2548894129557567 + 0.05297877813842256i,  -0.5669454100367172 + 0.1539056392010643i;
0 + 0i,  0 + 0i,  0.8716895470004201 - 0.2756961753092227i, ...
0.2890720654179352 - 0.2838772508762855i];
[dOut, eOut, zOut, info] = f08jv(compz, d, e, z)
```
```

dOut =

-7.0042
-4.0038
0.5968
3.0012

eOut =

0
0
0

zOut =

-0.7293 + 0.0000i   0.2610 + 0.0000i  -0.3718 + 0.0000i  -0.5117 + 0.0000i
0.1654 + 0.2046i  -0.5966 - 0.4235i  -0.4002 - 0.1869i  -0.2493 - 0.3718i
-0.6081 - 0.0301i  -0.5413 + 0.0870i   0.0531 + 0.1444i   0.5521 - 0.0176i
-0.1653 + 0.0303i  -0.3061 - 0.0482i   0.7234 - 0.3459i  -0.4461 + 0.1836i

info =

0

```