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$. 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 may also be used to compute all the eigenvalues and eigenvectors of a real symmetric matrix $A$ which has been reduced to tridiagonal form $T$:
 $A =QTQT, where ​Q​ is orthogonal =QZΛQZT.$
In this case, the matrix $Q$ must be formed explicitly and passed to nag_lapack_dsteqr (f08je), 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_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 ${\mathbf{vect}}=\text{'V'}$.
nag_lapack_dsteqr (f08je) 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 factor $±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_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 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$.

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$.
2:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – double 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 orthogonal matrix $Q$ from the reduction to tridiagonal form.
If ${\mathbf{compz}}=\text{'I'}$, z need not be set.

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)$ – double 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 orthogonally 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 floating-point operations is typically about $24{n}^{2}$ if ${\mathbf{compz}}=\text{'N'}$ and about $7{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 complex analogue of this function is nag_lapack_zsteqr (f08js).

Example

This example computes all the eigenvalues and eigenvectors of the symmetric tridiagonal matrix $T$, where
 $T = -6.99 -0.44 0.00 0.00 -0.44 7.92 -2.63 0.00 0.00 -2.63 2.34 -1.18 0.00 0.00 -1.18 0.32 .$
See also the examples for nag_lapack_dorgtr (f08ff), nag_lapack_dopgtr (f08gf) or nag_lapack_dsbtrd (f08he), which illustrate the use of this function to compute the eigenvalues and eigenvectors of a full or band symmetric matrix.
function f08je_example

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

% Symmetric tridiagonal A stored as diagonal and off-diagonal
n = 4;
d = [-6.99;     7.92;     2.34;     0.32];
e = [-0.44;    -2.63;    -1.18];

% All eigenvalues and eigenvectors of A
compz = 'I';
z = zeros(n, n);
[w, ~, z, info] = f08je( ...
compz, d, e, 'z', z);

% Normalize eigenvectors: largest element positive
for j = 1:n
[~,k] = max(abs(z(:,j)));
if z(k,j) < 0;
z(:,j) = -z(:,j);
end
end

disp('Eigenvalues');
disp(w');
disp('Eigenvectors');
disp(z);

f08je example results

Eigenvalues
-7.0037   -0.4059    2.0028    8.9968

Eigenvectors
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