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_dspevd (f08gc)

## Purpose

nag_lapack_dspevd (f08gc) computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric matrix held in packed storage. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors. However, if only eigenvalues are required, then it uses the Pal–Walker–Kahan variant of the $QL$ or $QR$ algorithm.

## Syntax

[ap, w, z, info] = f08gc(job, uplo, n, ap)
[ap, w, z, info] = nag_lapack_dspevd(job, uplo, n, ap)

## Description

nag_lapack_dspevd (f08gc) computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric matrix $A$ (held in packed storage). In other words, it can compute the spectral factorization of $A$ as
 $A=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
 $Azi=λizi, i=1,2,…,n.$

## 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:     $\mathrm{job}$ – string (length ≥ 1)
Indicates whether eigenvectors are computed.
${\mathbf{job}}=\text{'N'}$
Only eigenvalues are computed.
${\mathbf{job}}=\text{'V'}$
Eigenvalues and eigenvectors are computed.
Constraint: ${\mathbf{job}}=\text{'N'}$ or $\text{'V'}$.
2:     $\mathrm{uplo}$ – string (length ≥ 1)
Indicates whether the upper or lower triangular part of $A$ is stored.
${\mathbf{uplo}}=\text{'U'}$
The upper triangular part of $A$ is stored.
${\mathbf{uplo}}=\text{'L'}$
The lower triangular part of $A$ is stored.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
3:     $\mathrm{n}$int64int32nag_int scalar
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
4:     $\mathrm{ap}\left(:\right)$ – double array
The dimension of the array ap must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×\left({\mathbf{n}}+1\right)/2\right)$
The upper or lower triangle of the $n$ by $n$ symmetric matrix $A$, packed by columns.
More precisely,
• if ${\mathbf{uplo}}=\text{'U'}$, the upper triangle of $A$ must be stored with element ${A}_{ij}$ in ${\mathbf{ap}}\left(i+j\left(j-1\right)/2\right)$ for $i\le j$;
• if ${\mathbf{uplo}}=\text{'L'}$, the lower triangle of $A$ must be stored with element ${A}_{ij}$ in ${\mathbf{ap}}\left(i+\left(2n-j\right)\left(j-1\right)/2\right)$ for $i\ge j$.

None.

### Output Parameters

1:     $\mathrm{ap}\left(:\right)$ – double array
The dimension of the array ap will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×\left({\mathbf{n}}+1\right)/2\right)$
ap stores the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of $A$.
2:     $\mathrm{w}\left(:\right)$ – double array
The dimension of the array w will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The eigenvalues of the matrix $A$ in ascending order.
3:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – double array
The first dimension, $\mathit{ldz}$, of the array z will be
• if ${\mathbf{job}}=\text{'V'}$, $\mathit{ldz}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{job}}=\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{job}}=\text{'V'}$ and at least $1$ if ${\mathbf{job}}=\text{'N'}$.
If ${\mathbf{job}}=\text{'V'}$, z stores the orthogonal matrix $Z$ which contains the eigenvectors of $A$.
If ${\mathbf{job}}=\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

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: job, 2: uplo, 3: n, 4: ap, 5: w, 6: z, 7: ldz, 8: work, 9: lwork, 10: iwork, 11: liwork, 12: 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.
${\mathbf{info}}>0$
if ${\mathbf{info}}=i$ and ${\mathbf{job}}=\text{'N'}$, the algorithm failed to converge; $i$ elements of an intermediate tridiagonal form did not converge to zero; if ${\mathbf{info}}=i$ and ${\mathbf{job}}=\text{'V'}$, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column $i/\left({\mathbf{n}}+1\right)$ through .

## Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix $\left(A+E\right)$, where
 $E2 = Oε A2 ,$
and $\epsilon$ is the machine precision. See Section 4.7 of Anderson et al. (1999) for further details.

The complex analogue of this function is nag_lapack_zhpevd (f08gq).

## Example

This example computes all the eigenvalues and eigenvectors of the symmetric matrix $A$, where
 $A = 1.0 2.0 3.0 4.0 2.0 2.0 3.0 4.0 3.0 3.0 3.0 4.0 4.0 4.0 4.0 4.0 .$
```function f08gc_example

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

% A is symmetric matrix stored in symmetric (Lower) packed format
uplo = 'L';
n = int64(4);
ap = [1;     2;     3;     4;
2;     3;     4;
3;     4;
4];

% Eigenvalues and vectors of A
job = 'Vectors';
[apf, w, z, info] = f08gc( ...
job, uplo, n, ap);

disp('Eigenvalues');
disp(w');

% 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('Eigenvectors');
disp(z);

```
```f08gc example results

Eigenvalues
-2.0531   -0.5146   -0.2943   12.8621

Eigenvectors
0.7003   -0.5144   -0.2767    0.4103
0.3592    0.4851    0.6634    0.4422
-0.1569    0.5420   -0.6504    0.5085
-0.5965   -0.4543    0.2457    0.6144

```