NAG Toolbox: nag_lapack_zhbtrd (f08hs)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Indicates whether $Q$ is to be returned.

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

$Q$ is returned.

$\mathbf{vect}=\text{'U'}$

$Q$ is updated (and the array q must contain a matrix on entry).

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

$Q$ is not required.

Constraint: $\mathbf{vect}=\text{'V'}$, $\text{'U'}$ or $\text{'N'}$.

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{kd}$ – int64int32nag_int scalar

If $\mathbf{uplo}=\text{'U'}$, the number of superdiagonals, $k_d$, of the matrix $A$.

If $\mathbf{uplo}=\text{'L'}$, the number of subdiagonals, $k_d$, of the matrix $A$.

Constraint: $\mathbf{kd}\ge 0$.

4:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – complex array

The first dimension of the array ab must be at least $\max \left(1,\mathbf{kd}+1\right)$.

The second dimension of the array ab must be at least $\max \left(1,\mathbf{n}\right)$.

The upper or lower triangle of the $n$ by $n$ Hermitian band matrix $A$.

The matrix is stored in rows $1$ to $k_d+1$, more precisely,

• if $\mathbf{uplo}=\text{'U'}$, the elements of the upper triangle of $A$ within the band must be stored with element $A_{ij}$ in $\mathbf{ab}\left(k_d+1+i-j,j\right)\text{ for }\max \left(1,j-k_d\right)\le i\le j$;
• if $\mathbf{uplo}=\text{'L'}$, the elements of the lower triangle of $A$ within the band must be stored with element $A_{ij}$ in $\mathbf{ab}\left(1+i-j,j\right)\text{ for }j\le i\le \min \left(n,j+k_d\right)\text{.}$

5:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array

The first dimension, $\mathit{ldq}$, of the array q must satisfy

• if $\mathbf{vect}=\text{'V'}$ or $\text{'U'}$, $\mathit{ldq}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{vect}=\text{'N'}$, $\mathit{ldq}\ge 1$.

The second dimension of the array q must be at least $\max \left(1,\mathbf{n}\right)$ if $\mathbf{vect}=\text{'V'}$ or $\text{'U'}$ and at least $1$ if $\mathbf{vect}=\text{'N'}$.

If $\mathbf{vect}=\text{'U'}$, q must contain the matrix formed in a previous stage of the reduction (for example, the reduction of a banded Hermitian-definite generalized eigenproblem); otherwise q need not be set.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the first dimension of the array ab and the second dimension of the array ab. (An error is raised if these dimensions are not equal.)

$n$, the order of the matrix $A$.

Constraint: $\mathbf{n}\ge 0$.

Output Parameters

1:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – complex array

The first dimension of the array ab will be $\max \left(1,\mathbf{kd}+1\right)$.

The second dimension of the array ab will be $\max \left(1,\mathbf{n}\right)$.

ab stores values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix $T$ are returned in ab using the same storage format as described above.

2:     $\mathrm{d}\left(\mathbf{n}\right)$ – double array

The diagonal elements of the tridiagonal matrix $T$.

3:     $\mathrm{e}\left(\mathbf{n}-1\right)$ – double array

The off-diagonal elements of the tridiagonal matrix $T$.

4:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array

The first dimension, $\mathit{ldq}$, of the array q will be

• if $\mathbf{vect}=\text{'V'}$ or $\text{'U'}$, $\mathit{ldq}=\max \left(1,\mathbf{n}\right)$;
• if $\mathbf{vect}=\text{'N'}$, $\mathit{ldq}=1$.

The second dimension of the array q will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{vect}=\text{'V'}$ or $\text{'U'}$ and at least $1$ if $\mathbf{vect}=\text{'N'}$.

If $\mathbf{vect}=\text{'V'}$ or $\text{'U'}$, the $n$ by $n$ matrix $Q$.

If $\mathbf{vect}=\text{'N'}$, q is not referenced.

5:     $\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: vect, 2: uplo, 3: n, 4: kd, 5: ab, 6: ldab, 7: d, 8: e, 9: q, 10: ldq, 11: work, 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.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08hs_example

function f08hs_example


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

% Hermitian band matrix A, stored on symmetric banded format
uplo = 'L';
kd = int64(2);
n  = 4;
ab = [-3.13 + 0i,     -1.91 + 0i,    -2.87 + 0i,     0.5 + 0i;
       1.94 + 2.10i,  -0.82 + 0.89i, -2.10 + 0.16i,  0   + 0i;
      -3.40 - 0.25i,  -0.67 - 0.34i,  0    + 0i,     0   + 0i];


% Reduce A to tridiagonal form and compute Q
vect = 'V';
q = complex(zeros(n, n));
[abf, d, e, q, info] = f08hs( ...
                              vect, uplo, kd, ab, q);

% 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:n
  [~,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');
disp(w');
[ifail] = x04da( ...
                 'General', ' ', z, 'Eigenvectors');

f08hs example results

Eigenvalues
   -7.0042   -4.0038    0.5968    3.0012

 Eigenvectors
          1       2       3       4
 1   0.7293 -0.2128 -0.3354  0.4732
     0.0000  0.1511 -0.1604  0.1947

 2  -0.1654  0.7316 -0.2804  0.0891
    -0.2046  0.0000 -0.3413  0.4387

 3   0.6081  0.3910 -0.0144 -0.5172
     0.0301 -0.3843  0.1532 -0.1938

 4   0.1653  0.2775  0.8019  0.4824
    -0.0303 -0.1378  0.0000  0.0000