NAG Toolbox: nag_matop_real_band_pack (f01zc)

Purpose

Syntax

Description

References

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 $\min \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 $\min \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 $\min \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

   $\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$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f01zc_example

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