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_dpbstf (f08uf)

## Purpose

nag_lapack_dpbstf (f08uf) computes a split Cholesky factorization of a real symmetric positive definite band matrix.

## Syntax

[bb, info] = f08uf(uplo, kb, bb, 'n', n)
[bb, info] = nag_lapack_dpbstf(uplo, kb, bb, 'n', n)

## Description

nag_lapack_dpbstf (f08uf) computes a split Cholesky factorization of a real symmetric positive definite band matrix $B$. It is designed to be used in conjunction with nag_lapack_dsbgst (f08ue).
The factorization has the form $B={S}^{\mathrm{T}}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)$ – double 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$ symmetric 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)$ – double 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εSTS,$
$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 $n{\left(k+1\right)}^{2}$, assuming $n\gg k$.
A call to nag_lapack_dpbstf (f08uf) may be followed by a call to nag_lapack_dsbgst (f08ue) to solve the generalized eigenproblem $Az=\lambda Bz$, where $A$ and $B$ are banded and $B$ is positive definite.
The complex analogue of this function is nag_lapack_zpbstf (f08ut).

## Example

See Example in nag_lapack_dsbgst (f08ue).
```function f08uf_example

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

% Sove Az = lambda Bz
% A and B are the symmetric banded positive definite matrices:
n = 4;
% A has 2 off-diagionals
ka = int64(2);
a = [ 0.24,  0.39,  0.42,  0.00;
0.39, -0.11,  0.79,  0.63;
0.42,  0.79, -0.25,  0.48;
0.00,  0.63,  0.48, -0.03];
% B has 1 off-diagonal
kb = int64(1);
b = [ 2.07   0.95   0.00   0.00;
0.95   1.69  -0.29   0.00;
0.00  -0.29   0.65  -0.33;
0.00   0.00  -0.33   1.17];

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

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

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

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

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

```
```f08uf example results

Eigenvalues:
-0.8305   -0.6401    0.0992    1.8525

```

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