Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_zhbtrd (f08hs)

## Purpose

nag_lapack_zhbtrd (f08hs) reduces a complex Hermitian band matrix to tridiagonal form.

## Syntax

[ab, d, e, q, info] = f08hs(vect, uplo, kd, ab, q, 'n', n)
[ab, d, e, q, info] = nag_lapack_zhbtrd(vect, uplo, kd, ab, q, 'n', n)

## Description

nag_lapack_zhbtrd (f08hs) reduces a Hermitian band matrix $A$ to real symmetric tridiagonal form $T$ by a unitary similarity transformation:
 $T = QH A Q .$
The unitary matrix $Q$ is determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required.
The function uses a vectorizable form of the reduction, due to Kaufman (1984).

## References

Kaufman L (1984) Banded eigenvalue solvers on vector machines ACM Trans. Math. Software 10 73–86
Parlett B N (1998) The Symmetric Eigenvalue Problem SIAM, Philadelphia

## 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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{kd}}+1\right)$.
The second dimension of the array ab must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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 ​}\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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 \mathrm{min}\phantom{\rule{0.125em}{0ex}}\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 \mathrm{max}\phantom{\rule{0.125em}{0ex}}\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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{kd}}+1\right)$.
The second dimension of the array ab will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{vect}}=\text{'N'}$, $\mathit{ldq}=1$.
The second dimension of the array q will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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

The computed tridiagonal matrix $T$ is exactly similar to a nearby matrix $\left(A+E\right)$, where
 $E2≤ c n ε A2 ,$
$c\left(n\right)$ is a modestly increasing function of $n$, and $\epsilon$ is the machine precision.
The elements of $T$ themselves may be sensitive to small perturbations in $A$ or to rounding errors in the computation, but this does not affect the stability of the eigenvalues and eigenvectors.
The computed matrix $Q$ differs from an exactly unitary matrix by a matrix $E$ such that
 $E2 = Oε ,$
where $\epsilon$ is the machine precision.

The total number of real floating-point operations is approximately $20{n}^{2}k$ if ${\mathbf{vect}}=\text{'N'}$ with $10{n}^{3}\left(k-1\right)/k$ additional operations if ${\mathbf{vect}}=\text{'V'}$.
The real analogue of this function is nag_lapack_dsbtrd (f08he).

## Example

This example computes all the eigenvalues and eigenvectors of the matrix $A$, where
 $A = -3.13+0.00i 1.94-2.10i -3.40+0.25i 0.00+0.00i 1.94+2.10i -1.91+0.00i -0.82-0.89i -0.67+0.34i -3.40-0.25i -0.82+0.89i -2.87+0.00i -2.10-0.16i 0.00+0.00i -0.67-0.34i -2.10+0.16i 0.50+0.00i .$
Here $A$ is Hermitian and is treated as a band matrix. The program first calls nag_lapack_zhbtrd (f08hs) to reduce $A$ to tridiagonal form $T$, and to form the unitary matrix $Q$; the results are then passed to nag_lapack_zsteqr (f08js) which computes the eigenvalues and eigenvectors of $A$.
```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
```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015