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$. In other words, it can compute the spectral factorization of $T$ as
 $T=ZΛZT,$
where $\Lambda$ is a diagonal matrix whose diagonal elements are the eigenvalues ${\lambda }_{i}$, and $Z$ is the orthogonal matrix whose columns are the eigenvectors ${z}_{i}$. Thus
 $Tzi=λizi, i=1,2,…,n.$
The function stores the real orthogonal matrix $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$ which has been reduced to tridiagonal form $T$:
 $A =QTQH, where ​Q​ is unitary =QZΛQZH.$
In this case, the matrix $Q$ must be formed explicitly and passed to nag_lapack_zsteqr (f08js), which must be called with ${\mathbf{compz}}=\text{'V'}$. The functions which must be called to perform the reduction to tridiagonal form and form $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 ${\mathbf{vect}}=\text{'V'}$.
nag_lapack_zsteqr (f08js) uses the implicitly shifted $QR$ algorithm, switching between the $QR$ and $QL$ variants in order to handle graded matrices effectively (see Greenbaum and Dongarra (1980)). The eigenvectors are normalized so that ${‖{z}_{i}‖}_{2}=1$, but are determined only to within a complex factor of absolute value $1$.
If only the eigenvalues of $T$ are required, it is more efficient to call nag_lapack_dsterf (f08jf) instead. If $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 http://www.netlib.org/lapack/lawnspdf/lawn17.pdf
Parlett B N (1998) The Symmetric Eigenvalue Problem SIAM, Philadelphia

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{compz}$ – string (length ≥ 1)
Indicates whether the eigenvectors are to be computed.
${\mathbf{compz}}=\text{'N'}$
Only the eigenvalues are computed (and the array z is not referenced).
${\mathbf{compz}}=\text{'V'}$
The eigenvalues and eigenvectors of $A$ are computed (and the array z must contain the matrix $Q$ on entry).
${\mathbf{compz}}=\text{'I'}$
The eigenvalues and eigenvectors of $T$ are computed (and the array z is initialized by the function).
Constraint: ${\mathbf{compz}}=\text{'N'}$, $\text{'V'}$ or $\text{'I'}$.
2:     $\mathrm{d}\left(:\right)$ – double array
The dimension of the array d must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The diagonal elements of the tridiagonal matrix $T$.
3:     $\mathrm{e}\left(:\right)$ – double array
The dimension of the array e must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$
The off-diagonal elements of the tridiagonal matrix $T$.
4:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array
The first dimension, $\mathit{ldz}$, of the array z must satisfy
• if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$, $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compz}}=\text{'N'}$, $\mathit{ldz}\ge 1$.
The second dimension of the array z must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$ and at least $1$ if ${\mathbf{compz}}=\text{'N'}$.
If ${\mathbf{compz}}=\text{'V'}$, z must contain the unitary matrix $Q$ from the reduction to tridiagonal form.
If ${\mathbf{compz}}=\text{'I'}$, z need not be set.

### Optional Input Parameters

1:     $\mathrm{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$, the order of the matrix $T$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{d}\left(:\right)$ – double array
The dimension of the array d will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The $n$ eigenvalues in ascending order, unless ${\mathbf{info}}>{\mathbf{0}}$ (in which case see Error Indicators and Warnings).
2:     $\mathrm{e}\left(:\right)$ – double array
The dimension of the array e will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$
3:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array
The first dimension, $\mathit{ldz}$, of the array z will be
• if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$, $\mathit{ldz}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compz}}=\text{'N'}$, $\mathit{ldz}=1$.
The second dimension of the array z will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$ and at least $1$ if ${\mathbf{compz}}=\text{'N'}$.
If ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$, the $n$ required orthonormal eigenvectors stored as columns of $Z$; the $i$th column corresponds to the $i$th eigenvalue, where $i=1,2,\dots ,n$, unless ${\mathbf{info}}>{\mathbf{0}}$.
If ${\mathbf{compz}}=\text{'N'}$, z is not referenced.
4:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see 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.

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $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  ${\mathbf{info}}>0$
The algorithm has failed to find all the eigenvalues after a total of $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$. If ${\mathbf{info}}=i$, then $i$ off-diagonal elements have not converged to zero.

## Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix $\left(T+E\right)$, where
 $E2 = Oε T2 ,$
and $\epsilon$ is the machine precision.
If ${\lambda }_{i}$ is an exact eigenvalue and ${\stackrel{~}{\lambda }}_{i}$ is the corresponding computed value, then
 $λ~i - λi ≤ c n ε T2 ,$
where $c\left(n\right)$ is a modestly increasing function of $n$.
If ${z}_{i}$ is the corresponding exact eigenvector, and ${\stackrel{~}{z}}_{i}$ is the corresponding computed eigenvector, then the angle $\theta \left({\stackrel{~}{z}}_{i},{z}_{i}\right)$ between them is bounded as follows:
 $θ z~i,zi ≤ cnεT2 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 $24{n}^{2}$ if ${\mathbf{compz}}=\text{'N'}$ and about $14{n}^{3}$ if ${\mathbf{compz}}=\text{'V'}$ or $\text{'I'}$, but depends on how rapidly the algorithm converges. When ${\mathbf{compz}}=\text{'N'}$, the operations are all performed in scalar mode; the additional operations to compute the eigenvectors when ${\mathbf{compz}}=\text{'V'}$ or $\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

See Example in nag_lapack_zungtr (f08ft), nag_lapack_zupgtr (f08gt) or nag_lapack_zhbtrd (f08hs), which illustrate the use of this function to compute the eigenvalues and eigenvectors of a full or band Hermitian matrix.
```function f08js_example

fprintf('f08js example results\n\n');

% Hermitian matrix A (Lower triangular part stored)
uplo = 'L';
a = [-2.28 + 0.00i,  0.00 + 0i,     0    + 0i,     0    + 0i;
1.78 + 2.03i, -1.12 + 0i,     0    + 0i,     0    + 0i;
2.26 - 0.10i,  0.01 - 0.43i, -0.37 + 0i,     0    + 0i;
-0.12 - 2.53i, -1.07 - 0.86i,  2.31 + 0.92i, -0.73 + 0i];

% Reduce to tridiagonal form
[QT, d, e, tau, info] = f08fs( ...
uplo, a);

% Form Q
[Q, info] = f08ft( ...
uplo, QT, tau);

% Calculate eigenvalues/vectors of A from Q, d and e.
compz = 'V';
[w, ~, z, info] = f08js( ...
compz, d, e, Q);

% Normalize: largest elements are real
for i = 1:4
[~,k] = max(abs(real(z(:,i)))+abs(imag(z(:,i))));
z(:,i) = z(:,i)*conj(z(k,i))/abs(z(k,i));
end

disp(' Eigenvalues of A:');
disp(w');
disp(' Corresponding eigenvectors:');
disp(z);

```
```f08js example results

Eigenvalues of A:
-6.0002   -3.0030    0.5036    3.9996

Corresponding eigenvectors:
0.7299 + 0.0000i  -0.2120 + 0.1497i   0.1000 - 0.3570i   0.1991 + 0.4720i
-0.1663 - 0.2061i   0.7307 + 0.0000i   0.2863 - 0.3353i  -0.2467 + 0.3751i
-0.4165 - 0.1417i  -0.3291 + 0.0479i   0.6890 + 0.0000i   0.4468 + 0.1466i
0.1743 + 0.4162i   0.5200 + 0.1329i   0.0662 + 0.4347i   0.5612 + 0.0000i

```