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_zsteqr (f08js)

## Purpose

nag_lapack_zsteqr (f08js) computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix which has been reduced to tridiagonal form.

## Syntax

[d, e, z, info] = f08js(compz, d, e, z, 'n', n)
[d, e, z, info] = nag_lapack_zsteqr(compz, d, e, z, 'n', n)

## Description

nag_lapack_zsteqr (f08js) 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 stores the real orthogonal matrix Z$Z$ in a complex array, so that it may also be used to compute all the eigenvalues and eigenvectors of a complex Hermitian matrix A$A$ which has been reduced to tridiagonal form T$T$:
 A = QTQH, where ​Q​ is unitary = (QZ)Λ(QZ)H.
$A =QTQH, where ​Q​ is unitary =(QZ)Λ(QZ)H.$
In this case, the matrix Q$Q$ must be formed explicitly and passed to nag_lapack_zsteqr (f08js), 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_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'}$.
nag_lapack_zsteqr (f08js) 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 complex factor of absolute value 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_zpteqr (f08ju).

## 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$.
4:     z(ldz, : $:$) – complex 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 unitary matrix Q$Q$ from the reduction to tridiagonal form.
If compz = 'I'${\mathbf{compz}}=\text{'I'}$, z need not be set.

### 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$.

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, : $:$) – complex 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 unitarily 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 real floating point operations is typically about 24n2$24{n}^{2}$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$ and about 14n3$14{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 real analogue of this function is nag_lapack_dsteqr (f08je).

## Example

```function nag_lapack_zsteqr_example
compz = 'V';
d = [-2.28;
-0.1284569816493291;
-0.1665932537524081;
-1.924949764598263];
e = [-4.33845594653213;
-2.022594578622617;
-1.802322978338735];
z = [complex(1),  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  -0.4102842167667538 - 0.4679084045148932i, ...
0.06892965664061006 + 0.1779918861910115i,  0.6582921534701638 + 0.3780841414574355i;
0 + 0i,  -0.5209226572431817 + 0.02304967509925584i, ...
-0.2575502363844263 - 0.7356001925994043i,  -0.231282326855171 + 0.2591852914789428i;
0 + 0i,  0.027659610119107 + 0.5831567800111723i, ...
0.5955581080629656 - 0.0379257589519286i,  0.06573064825393153 + 0.5465480532428592i];
[dOut, eOut, zOut, info] = nag_lapack_zsteqr(compz, d, e, z)
```
```

dOut =

-6.0002
-3.0030
0.5036
3.9996

eOut =

0
0
0

zOut =

0.7299 + 0.0000i  -0.2595 + 0.0000i  -0.3707 + 0.0000i  -0.5123 + 0.0000i
-0.1663 - 0.2061i   0.5969 + 0.4214i  -0.4001 - 0.1853i  -0.2498 - 0.3731i
-0.4165 - 0.1417i  -0.2965 - 0.1507i  -0.1858 - 0.6635i  -0.3087 + 0.3547i
0.1743 + 0.4162i   0.3482 + 0.4085i   0.4008 - 0.1810i  -0.2181 + 0.5171i

info =

0

```
```function f08js_example
compz = 'V';
d = [-2.28;
-0.1284569816493291;
-0.1665932537524081;
-1.924949764598263];
e = [-4.33845594653213;
-2.022594578622617;
-1.802322978338735];
z = [complex(1),  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  -0.4102842167667538 - 0.4679084045148932i, ...
0.06892965664061006 + 0.1779918861910115i,  0.6582921534701638 + 0.3780841414574355i;
0 + 0i,  -0.5209226572431817 + 0.02304967509925584i, ...
-0.2575502363844263 - 0.7356001925994043i,  -0.231282326855171 + 0.2591852914789428i;
0 + 0i,  0.027659610119107 + 0.5831567800111723i, ...
0.5955581080629656 - 0.0379257589519286i,  0.06573064825393153 + 0.5465480532428592i];
[dOut, eOut, zOut, info] = f08js(compz, d, e, z)
```
```

dOut =

-6.0002
-3.0030
0.5036
3.9996

eOut =

0
0
0

zOut =

0.7299 + 0.0000i  -0.2595 + 0.0000i  -0.3707 + 0.0000i  -0.5123 + 0.0000i
-0.1663 - 0.2061i   0.5969 + 0.4214i  -0.4001 - 0.1853i  -0.2498 - 0.3731i
-0.4165 - 0.1417i  -0.2965 - 0.1507i  -0.1858 - 0.6635i  -0.3087 + 0.3547i
0.1743 + 0.4162i   0.3482 + 0.4085i   0.4008 - 0.1810i  -0.2181 + 0.5171i

info =

0

```