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_zpbstf (f08ut)

## Purpose

nag_lapack_zpbstf (f08ut) computes a split Cholesky factorization of a complex Hermitian positive definite band matrix.

## Syntax

[bb, info] = f08ut(uplo, kb, bb, 'n', n)
[bb, info] = nag_lapack_zpbstf(uplo, kb, bb, 'n', n)

## Description

nag_lapack_zpbstf (f08ut) computes a split Cholesky factorization of a complex Hermitian positive definite band matrix $B$. It is designed to be used in conjunction with nag_lapack_zhbgst (f08us).
The factorization has the form $B={S}^{\mathrm{H}}S$, where $S$ is a band matrix of the same bandwidth as $B$ and the following structure: $S$ is upper triangular in the first $\left(n+k\right)/2$ rows, and transposed — hence, lower triangular — in the remaining rows. For example, if $n=9$ and $k=2$, then
 $S = s11 s12 s13 s22 s23 s24 s33 s34 s35 s44 s45 s55 s64 s65 s66 s75 s76 s77 s86 s87 s88 s97 s98 s99 .$

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{uplo}$ – string (length ≥ 1)
Indicates whether the upper or lower triangular part of $B$ is stored.
${\mathbf{uplo}}=\text{'U'}$
The upper triangular part of $B$ is stored.
${\mathbf{uplo}}=\text{'L'}$
The lower triangular part of $B$ is stored.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
2:     $\mathrm{kb}$int64int32nag_int scalar
If ${\mathbf{uplo}}=\text{'U'}$, the number of superdiagonals, ${k}_{b}$, of the matrix $B$.
If ${\mathbf{uplo}}=\text{'L'}$, the number of subdiagonals, ${k}_{b}$, of the matrix $B$.
Constraint: ${\mathbf{kb}}\ge 0$.
3:     $\mathrm{bb}\left(\mathit{ldbb},:\right)$ – complex array
The first dimension of the array bb must be at least ${\mathbf{kb}}+1$.
The second dimension of the array bb must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $n$ by $n$ Hermitian positive definite band matrix $B$.
The matrix is stored in rows $1$ to ${k}_{b}+1$, more precisely,
• if ${\mathbf{uplo}}=\text{'U'}$, the elements of the upper triangle of $B$ within the band must be stored with element ${B}_{ij}$ in ${\mathbf{bb}}\left({k}_{b}+1+i-j,j\right)\text{​ for ​}\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,j-{k}_{b}\right)\le i\le j$;
• if ${\mathbf{uplo}}=\text{'L'}$, the elements of the lower triangle of $B$ within the band must be stored with element ${B}_{ij}$ in ${\mathbf{bb}}\left(1+i-j,j\right)\text{​ for ​}j\le i\le \mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,j+{k}_{b}\right)\text{.}$

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array bb and the second dimension of the array bb. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrix $B$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{bb}\left(\mathit{ldbb},:\right)$ – complex array
The first dimension of the array bb will be ${\mathbf{kb}}+1$.
The second dimension of the array bb will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
$B$ stores the elements of its split Cholesky factor $S$.
2:     $\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: uplo, 2: n, 3: kb, 4: bb, 5: ldbb, 6: 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 factorization could not be completed, because the updated element $b\left(i,i\right)$ would be the square root of a negative number. Hence $B$ is not positive definite. This may indicate an error in forming the matrix $B$.

## Accuracy

The computed factor $S$ is the exact factor of a perturbed matrix $\left(B+E\right)$, where
 $E≤ck+1εSHS,$
$c\left(k+1\right)$ is a modest linear function of $k+1$, and $\epsilon$ is the machine precision. It follows that $\left|{e}_{ij}\right|\le c\left(k+1\right)\epsilon \sqrt{\left({b}_{ii}{b}_{jj}\right)}$.

The total number of floating-point operations is approximately $4n{\left(k+1\right)}^{2}$, assuming $n\gg k$.
A call to nag_lapack_zpbstf (f08ut) may be followed by a call to nag_lapack_zhbgst (f08us) to solve the generalized eigenproblem $Az=\lambda Bz$, where $A$ and $B$ are banded and $B$ is positive definite.
The real analogue of this function is nag_lapack_dpbstf (f08uf).

## Example

See Example in nag_lapack_zhbgst (f08us).
```function f08ut_example

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

% Sove Az = lambda Bz
% A and B are the Hermitian banded positive definite matrices:
n = 4;
ka = int64(2);
a = [ -1.13+0.00i  1.94-2.10i -1.40+0.25i  0.00+0.00i;
1.94+2.10i -1.91+0.00i -0.82-0.89i -0.67+0.34i;
-1.40-0.25i -0.82+0.89i -1.87+0.00i -1.10-0.16i;
0.00+0.00i -0.67-0.34i -1.10+0.16i  0.50+0.00i];

kb = int64(1);
b = [  9.89+0.00i  1.08-1.73i  0.00+0.00i  0.00+0.00i;
1.08+1.73i  1.69+0.00i -0.04+0.29i  0.00+0.00i;
0.00+0.00i -0.04-0.29i  2.65+0.00i -0.33+2.24i;
0.00+0.00i  0.00+0.00i -0.33-2.24i  2.17+0.00i];

% Convert to general banded format ...
[~, ab, ifail] = f01zd( ...
'P', ka, ka, a, complex(zeros(ka+ka+1,n)));
[~, bb, ifail] = f01zd( ...
'P', kb, kb, b, complex(zeros(kb+kb+1,n)));
% ... and chop to give 'Upper' Hermitian banded format
ab = ab(1:ka+1,1:n);
bb = bb(1:kb+1,1:n);

% Factorize B
uplo = 'Upper';
[bbfac, info] = f08ut( ...
uplo, kb, bb);

% Reduce problem to standard form Cy = lambda*y
vect = 'N';
[cb, x, info] = f08us( ...
vect, uplo, ka, kb, ab, bbfac);

% Find eigenvalues lambda
jobz = 'No Vectors';
[~, w, ~, info] = f08hn( ...
jobz, uplo, ka, cb);

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

```
```f08ut example results

Eigenvalues:
-6.6089   -2.0416    0.1603    1.7712

```