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

### Optional Input Parameters

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

lda ldb

### Output Parameters

1:     a(lda,n) – double array
ldam$\mathit{lda}\ge {\mathbf{m}}$.
If job = 'U'${\mathbf{job}}=\text{'U'}$, then the leading m$m$ by n$n$ part of a contains the band matrix stored in unpacked form. Elements of the leading m$m$ by n$n$ part of a that are not within the banded part of the matrix are assigned the value zero.
2:     b(ldb, : $:$) – double array
The first dimension of the array b will be (kl + ku + 1)$\left({\mathbf{kl}}+{\mathbf{ku}}+1\right)$
The second dimension of the array will be min (m + ku,n)$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}}+{\mathbf{ku}},{\mathbf{n}}\right)$
ldb(kl + ku + 1)$\mathit{ldb}\ge \left({\mathbf{kl}}+{\mathbf{ku}}+1\right)$.
If job = 'P'${\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:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, job ≠ 'P'${\mathbf{job}}\ne \text{'P'}$ or 'U'$\text{'U'}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, kl < 0${\mathbf{kl}}<0$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, ku < 0${\mathbf{ku}}<0$.
ifail = 4${\mathbf{ifail}}=4$
 On entry, lda < m$\mathit{lda}<{\mathbf{m}}$.
ifail = 5${\mathbf{ifail}}=5$
 On entry, ldb < kl + ku + 1$\mathit{ldb}<{\mathbf{kl}}+{\mathbf{ku}}+1$.
ifail = 6${\mathbf{ifail}}=6$
 On entry, m < 1${\mathbf{m}}<1$, or n < 1${\mathbf{n}}<1$.

Not applicable.

None.

## Example

```function nag_matop_real_band_pack_example
job = 'Pack';
kl = int64(1);
ku = int64(1);
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 = [0, 0, 0, 0, 0;
0, 0, 0, 0, 0;
0, 0, 0, 0, 0];
[aOut, bOut, ifail] = nag_matop_real_band_pack(job, kl, ku, a, b)
```
```

aOut =

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

bOut =

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

ifail =

0

```
```function f01zc_example
job = 'Pack';
kl = int64(1);
ku = int64(1);
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 = [0, 0, 0, 0, 0;
0, 0, 0, 0, 0;
0, 0, 0, 0, 0];
[aOut, bOut, ifail] = f01zc(job, kl, ku, a, b)
```
```

aOut =

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

bOut =

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

ifail =

0

```