NAG Toolbox: nag_lapack_zhpev (f08gn)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{jobz}$ – string (length ≥ 1)

Indicates whether eigenvectors are computed.

$\mathbf{jobz}=\text{'N'}$

Only eigenvalues are computed.

$\mathbf{jobz}=\text{'V'}$

Eigenvalues and eigenvectors are computed.

Constraint: $\mathbf{jobz}=\text{'N'}$ or $\text{'V'}$.

2:     $\mathrm{uplo}$ – string (length ≥ 1)

If $\mathbf{uplo}=\text{'U'}$, the upper triangular part of $A$ is stored.

If $\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)$ – complex array

The dimension of the array ap must be at least $\max \left(1,\mathbf{n}\times \left(\mathbf{n}+1\right)/2\right)$

The upper or lower triangle of the $n$ by $n$ Hermitian 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$.

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{ap}\left(:\right)$ – complex array

The dimension of the array ap will be $\max \left(1,\mathbf{n}\times \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(\mathbf{n}\right)$ – double array

The eigenvalues in ascending order.

3:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array

The first dimension, $\mathit{ldz}$, of the array z will be

• if $\mathbf{jobz}=\text{'V'}$, $\mathit{ldz}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldz}=1$.

The second dimension of the array z will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{jobz}=\text{'V'}$ and $1$ otherwise.

If $\mathbf{jobz}=\text{'V'}$, z contains the orthonormal eigenvectors of the matrix $A$, with the $i$th column of $Z$ holding the eigenvector associated with $\mathbf{w}\left(i\right)$.

If $\mathbf{jobz}=\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: jobz, 2: uplo, 3: n, 4: ap, 5: w, 6: z, 7: ldz, 8: work, 9: rwork, 10: 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$, the algorithm failed to converge; $i$ off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08gn_example

function f08gn_example


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

% A is Hermitian matrix stored in symmetric (Upper) packed format
uplo = 'U';
n = int64(4);
ap = [1 + 0i;
      2 - 1i;      2 + 0i;
      3 - 1i;      3 - 2i;      3 + 0i;
      4 - 1i;      4 - 2i;      4 - 3i;      4 + 0i];

% Eigenvalues of A only
jobz = 'No vectors';
[apf, w, ~, info] = f08gn( ...
                           jobz, uplo, n, ap);


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

% Eigenvalue error bound
errbnd = x02aj*max(abs(w(1)),abs(w(end)));
disp('Error estimate for the eigenvalues');
fprintf('%11.1e\n',errbnd);

f08gn example results

Eigenvalues
   -4.2443   -0.6886    1.1412   13.7916

Error estimate for the eigenvalues
    1.5e-15