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_matop_real_band_pack (f01zc)

## Purpose

nag_matop_real_band_pack (f01zc) copies a real band matrix stored in a packed array into an unpacked array, or vice versa.

## Syntax

[a, b, ifail] = f01zc(job, kl, ku, a, b, 'm', m, 'n', n)
[a, b, ifail] = nag_matop_real_band_pack(job, kl, ku, a, b, 'm', m, 'n', n)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 22: m was made optional

## Description

nag_matop_real_band_pack (f01zc) unpacks a band matrix that is stored in a packed array, or packs a band matrix that is stored in an unpacked array. The band matrix has $m$ rows, $n$ columns, ${k}_{l}$ nonzero subdiagonals, and ${k}_{u}$ nonzero superdiagonals. This function is intended for possible use in conjunction with functions from Chapters F07 and F08, where functions that use band matrices store them in the packed form described below.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{job}$ – string (length ≥ 1)
Specifies whether the band matrix is to be packed or unpacked.
${\mathbf{job}}=\text{'P'}$ (Pack)
The band matrix is to be packed into array b.
${\mathbf{job}}=\text{'U'}$ (Unpack)
The band matrix is to be unpacked into array a.
Constraint: ${\mathbf{job}}=\text{'P'}$ or $\text{'U'}$.
2:     $\mathrm{kl}$int64int32nag_int scalar
${k}_{l}$, the number of subdiagonals of the band matrix.
Constraint: ${\mathbf{kl}}\ge 0$.
3:     $\mathrm{ku}$int64int32nag_int scalar
${k}_{u}$, the number of superdiagonals of the band matrix.
Constraint: ${\mathbf{ku}}\ge 0$.
4:     $\mathrm{a}\left(\mathit{lda},{\mathbf{n}}\right)$ – double array
lda, the first dimension of the array, must satisfy the constraint $\mathit{lda}\ge {\mathbf{m}}$.
If ${\mathbf{job}}=\text{'P'}$, then the leading $m$ by $n$ part of a must contain the band matrix stored in unpacked form. Elements of the array that lie outside the banded part of the matrix are not referenced and need not be assigned.
5:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b must be at least $\left({\mathbf{kl}}+{\mathbf{ku}}+1\right)$.
The second dimension of the array b must be at least $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}}+{\mathbf{ku}},{\mathbf{n}}\right)$.
If ${\mathbf{job}}=\text{'U'}$, then b must contain the band matrix in packed form, in the leading $\left({k}_{l}+{k}_{u}+1\right)$ by $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m+{k}_{u},n\right)$ part of the array. The matrix is packed column by column, with the leading diagonal of the matrix in row $\left({k}_{u}+1\right)$ of b, the first superdiagonal starting at position $2$ in row ${k}_{u}$, the first subdiagonal starting at position $1$ in row $\left({k}_{u}+2\right)$, and so on. Elements of b that are not needed to store the band matrix, for instance the leading ${k}_{u}$ by ${k}_{u}$ triangle, are not referenced and need not be assigned.

### Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
2:     $\mathrm{n}$int64int32nag_int scalar
Default: For m, the first dimension of the array a. the second dimension of the array a.
$m$ and $n$, the number of rows and columns of the band matrix, respectively.
Constraints:
• ${\mathbf{m}}>0$;
• ${\mathbf{n}}>0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},{\mathbf{n}}\right)$ – double array
If ${\mathbf{job}}=\text{'U'}$, then the leading $m$ by $n$ part of a contains the band matrix stored in unpacked form. Elements of the leading $m$ by $n$ part of a that are not within the banded part of the matrix are assigned the value zero.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b will be $\left({\mathbf{kl}}+{\mathbf{ku}}+1\right)$.
The second dimension of the array b will be $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}}+{\mathbf{ku}},{\mathbf{n}}\right)$.
If ${\mathbf{job}}=\text{'P'}$, then b contains the band matrix stored in packed form. Elements of b that are not needed to store the band matrix are not referenced.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{job}}\ne \text{'P'}$ or $\text{'U'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{kl}}<0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{ku}}<0$.
${\mathbf{ifail}}=4$
 On entry, $\mathit{lda}<{\mathbf{m}}$.
${\mathbf{ifail}}=5$
 On entry, $\mathit{ldb}<{\mathbf{kl}}+{\mathbf{ku}}+1$.
${\mathbf{ifail}}=6$
 On entry, ${\mathbf{m}}<1$, or ${\mathbf{n}}<1$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

None.

## Example

This example reads a matrix $A$ in unpacked form, and copies it to the packed matrix $B$.
```function f01zc_example

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

job = 'Pack';
kl = int64(1);
ku = int64(1);
n  = 5;
a = [1.1, 1.2, 0,   0,   0;
2.1, 2.2, 2.3, 0,   0;
0,   3.2, 3.3, 3.4, 0;
0,   0,   4.3, 4.4, 4.5;
0,   0,   0,   5.4, 5.5];
b = zeros(kl+ku+1,n);

[A, ab, ifail] = f01zc(job, kl, ku, a, b);

disp('Unpacked Matrix A:');
disp(A);
fprintf('\n');
disp('Packed Matrix AB:');
disp(ab);

```
```f01zc example results

Unpacked Matrix A:
1.1000    1.2000         0         0         0
2.1000    2.2000    2.3000         0         0
0    3.2000    3.3000    3.4000         0
0         0    4.3000    4.4000    4.5000
0         0         0    5.4000    5.5000

Packed Matrix AB:
0    1.2000    2.3000    3.4000    4.5000
1.1000    2.2000    3.3000    4.4000    5.5000
2.1000    3.2000    4.3000    5.4000         0

```