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_zpbsv (f07hn)

## Purpose

nag_lapack_zpbsv (f07hn) computes the solution to a complex system of linear equations
 $AX=B ,$
where $A$ is an $n$ by $n$ Hermitian positive definite band matrix of bandwidth $\left(2{k}_{d}+1\right)$ and $X$ and $B$ are $n$ by $r$ matrices.

## Syntax

[ab, b, info] = f07hn(uplo, kd, ab, b, 'n', n, 'nrhs_p', nrhs_p)
[ab, b, info] = nag_lapack_zpbsv(uplo, kd, ab, b, 'n', n, 'nrhs_p', nrhs_p)

## Description

nag_lapack_zpbsv (f07hn) uses the Cholesky decomposition to factor $A$ as $A={U}^{\mathrm{H}}U$ if ${\mathbf{uplo}}=\text{'U'}$ or $A=L{L}^{\mathrm{H}}$ if ${\mathbf{uplo}}=\text{'L'}$, where $U$ is an upper triangular band matrix, and $L$ is a lower triangular band matrix, with the same number of superdiagonals or subdiagonals as $A$. The factored form of $A$ is then used to solve the system of equations $AX=B$.

## References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{uplo}$ – string (length ≥ 1)
If ${\mathbf{uplo}}=\text{'U'}$, the upper triangle of $A$ is stored.
If ${\mathbf{uplo}}=\text{'L'}$, the lower triangle of $A$ is stored.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
2:     $\mathrm{kd}$int64int32nag_int scalar
${k}_{d}$, the number of superdiagonals of the matrix $A$ if ${\mathbf{uplo}}=\text{'U'}$, or the number of subdiagonals if ${\mathbf{uplo}}=\text{'L'}$.
Constraint: ${\mathbf{kd}}\ge 0$.
3:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – complex array
The first dimension of the array ab must be at least ${\mathbf{kd}}+1$.
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 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{.}$
4:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs_p}}\right)$.
The $n$ by $r$ right-hand side matrix $B$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array b and the second dimension of the array ab.
$n$, the number of linear equations, i.e., the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{nrhs_p}$int64int32nag_int scalar
Default: the second dimension of the array b.
$r$, the number of right-hand sides, i.e., the number of columns of the matrix $B$.
Constraint: ${\mathbf{nrhs_p}}\ge 0$.

### Output Parameters

1:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – complex array
The first dimension of the array ab will be ${\mathbf{kd}}+1$.
The second dimension of the array ab will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If ${\mathbf{info}}={\mathbf{0}}$, the triangular factor $U$ or $L$ from the Cholesky factorization $A={U}^{\mathrm{H}}U$ or $A=L{L}^{\mathrm{H}}$ of the band matrix $A$, in the same storage format as $A$.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs_p}}\right)$.
If ${\mathbf{info}}={\mathbf{0}}$, the $n$ by $r$ solution matrix $X$.
3:     $\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}}<0$
If ${\mathbf{info}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.
${\mathbf{info}}>0$
The leading minor of order $_$ of $A$ is not positive definite, so the factorization could not be completed, and the solution has not been computed.

## Accuracy

The computed solution for a single right-hand side, $\stackrel{^}{x}$, satisfies an equation of the form
 $A+E x^=b ,$
where
 $E1 = Oε A1$
and $\epsilon$ is the machine precision. An approximate error bound for the computed solution is given by
 $x^-x1 x1 ≤ κA E1 A1 ,$
where $\kappa \left(A\right)={‖{A}^{-1}‖}_{1}{‖A‖}_{1}$, the condition number of $A$ with respect to the solution of the linear equations. See Section 4.4 of Anderson et al. (1999) for further details.
nag_lapack_zpbsvx (f07hp) is a comprehensive LAPACK driver that returns forward and backward error bounds and an estimate of the condition number. Alternatively, nag_linsys_complex_posdef_band_solve (f04cf) solves $Ax=b$ and returns a forward error bound and condition estimate. nag_linsys_complex_posdef_band_solve (f04cf) calls nag_lapack_zpbsv (f07hn) to solve the equations.

When $n\gg k$, the total number of floating-point operations is approximately $4n{\left(k+1\right)}^{2}+16nkr$, where $k$ is the number of superdiagonals and $r$ is the number of right-hand sides.
The real analogue of this function is nag_lapack_dpbsv (f07ha).

## Example

This example solves the equations
 $Ax=b ,$
where $A$ is the Hermitian positive definite band matrix
 $A = 9.39i+0.00 1.08-1.73i 0.00i+0.00 0.00i+0.00 1.08+1.73i 1.69i+0.00 -0.04+0.29i 0.00i+0.00 0.00i+0.00 -0.04-0.29i 2.65i+0.00 -0.33+2.24i 0.00i+0.00 0.00i+0.00 -0.33-2.24i 2.17i+0.00$
and
 $b = -12.42+68.42i -9.93+00.88i -27.30-00.01i 5.31+23.63i .$
Details of the Cholesky factorization of $A$ are also output.
```function f07hn_example

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

uplo = 'U';
kd = int64(1);
n  = int64(4);
ab = [0,          1.08 - 1.73i,  -0.04 + 0.29i,  -0.33 + 2.24i;
9.39 + 0i,  1.69 + 0i,      2.65 + 0i,      2.17 + 0i];

b = [ -12.42 + 68.42i;
-9.93 +  0.88i;
-27.3  -  0.01i;
5.31 + 23.63i];

[abf, x, info] = f07hn( ...
uplo, kd, ab, b);

disp('Solution');
disp(x);

kl = int64(0);
[ifail] = x04de( ...
n, n, kl, kd, abf, 'Cholesky factor');

```
```f07hn example results

Solution
-1.0000 + 8.0000i
2.0000 - 3.0000i
-4.0000 - 5.0000i
7.0000 + 6.0000i

Cholesky factor
1          2          3          4
1      3.0643     0.3524
0.0000    -0.5646

2                 1.1167    -0.0358
0.0000     0.2597

3                            1.6066    -0.2054
0.0000     1.3942

4                                       0.4289
0.0000
```