NAG Toolbox: nag_matop_complex_band_pack (f01zd)

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)$ – complex 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)$ – complex 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)$ – complex 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)$ – complex 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: f01zd_example

function f01zd_example


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

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

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

matrix = 'General';
diag = ' ';
title1 = 'Unpacked Matrix A:';
[ifail] = x04da(matrix, diag, A, title1);
fprintf('\n');
title1 = 'Packed Matrix AB:';
[ifail] = x04da(matrix, diag, ab, title1);

f01zd example results

 Unpacked Matrix A:
             1          2          3          4          5
 1      1.1000     1.2000     0.0000     0.0000     0.0000
       -1.1000    -1.2000     0.0000     0.0000     0.0000

 2      2.1000     2.2000     2.3000     0.0000     0.0000
       -2.1000    -2.2000    -2.3000     0.0000     0.0000

 3      0.0000     3.2000     3.3000     3.4000     0.0000
        0.0000    -3.2000    -3.3000    -3.4000     0.0000

 4      0.0000     0.0000     4.3000     4.4000     4.5000
        0.0000     0.0000    -4.3000    -4.4000    -4.5000

 5      0.0000     0.0000     0.0000     5.4000     5.5000
        0.0000     0.0000     0.0000    -5.4000    -5.5000

 Packed Matrix AB:
             1          2          3          4          5
 1      0.0000     1.2000     2.3000     3.4000     4.5000
        0.0000    -1.2000    -2.3000    -3.4000    -4.5000

 2      1.1000     2.2000     3.3000     4.4000     5.5000
       -1.1000    -2.2000    -3.3000    -4.4000    -5.5000

 3      2.1000     3.2000     4.3000     5.4000     0.0000
       -2.1000    -3.2000    -4.3000    -5.4000     0.0000