NAG Toolbox: nag_matop_complex_tri_pack (f01zb)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{job}$ – string (length ≥ 1)

Specifies whether the triangular matrix is to be packed or unpacked.

$\mathbf{job}=\text{'P'}$ (Pack)

The matrix is to be packed into array b.

$\mathbf{job}=\text{'U'}$ (Unpack)

The matrix is to be unpacked into array a.

Constraint: $\mathbf{job}=\text{'P'}$ or $\text{'U'}$.

2:     $\mathrm{uplo}$ – string (length ≥ 1)

Specifies the type of the matrix to be copied

$\mathbf{uplo}=\text{'L'}$ (Lower)

The matrix is lower triangular. In this case the packed vector holds, or will hold on exit, the matrix elements in the following order: $\left(1,1\right),\left(2,1\right),\dots ,\left(\mathbf{n},1\right),\left(2,2\right),\left(3,2\right),\dots ,\left(\mathbf{n},2\right)$, etc..

$\mathbf{uplo}=\text{'U'}$ (Upper)

The matrix is upper triangular. In this case the packed vector holds, or will hold on exit, the matrix elements in the following order: $\left(1,1\right)$, $\left(1,2\right)$, $\left(2,2\right)$, $\left(1,3\right)$, $\left(2,3\right)$, $\left(3,3\right)$, $\left(1,4\right)$, etc..

Constraint: $\mathbf{uplo}=\text{'L'}$ or $\text{'U'}$.

3:     $\mathrm{diag}$ – string (length ≥ 1)

Must specify whether the diagonal elements of the matrix are to be copied.

$\mathbf{diag}=\text{'B'}$ (Blank)

The diagonal elements of the matrix are not referenced and not copied.

$\mathbf{diag}=\text{'U'}$ (Unit diagonal)

The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are copied as such.

$\mathbf{diag}=\text{'N'}$ (Non-unit diagonal)

The diagonal elements of the matrix are referenced and copied.

Constraint: $\mathbf{diag}=\text{'B'}$, $\text{'U'}$ or $\text{'N'}$.

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{n}$.

If $\mathbf{job}=\text{'P'}$, then the leading n by n part of a must contain the matrix to be copied, stored in unpacked form, in the upper or lower triangle depending on argument uplo. The opposite triangle of a is not referenced and need not be assigned.

5:     $\mathrm{b}\left(\left(\mathbf{n}\times \left(\mathbf{n}+1\right)\right)/2\right)$ – complex array

If $\mathbf{job}=\text{'U'}$, then b must contain the triangular matrix packed by column.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the first dimension of the array a and the second dimension of the array a. (An error is raised if these dimensions are not equal.)

n must specify the number of rows and columns of the triangular matrix.

Constraint: $\mathbf{n}>0$.

Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},\mathbf{n}\right)$ – complex array

If $\mathbf{job}=\text{'U'}$, then the leading n by n part of array a contains the copied matrix, stored in unpacked form, in the upper or lower triangle depending on argument uplo. The opposite triangle of a is not referenced.

2:     $\mathrm{b}\left(\left(\mathbf{n}\times \left(\mathbf{n}+1\right)\right)/2\right)$ – complex array

If $\mathbf{job}=\text{'P'}$, then b contains the triangular matrix packed by column.

Note that b must have space for the diagonal elements of the matrix, even if these are not stored.

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{uplo}\ne \text{'L'}$ or $\text{'U'}$.

   $\mathbf{ifail}=3$

On entry,

$\mathbf{diag}\ne \text{'N'}$, $\text{'U'}$ or $\text{'B'}$.

   $\mathbf{ifail}=4$

On entry,

$\mathbf{n}<1$.

   $\mathbf{ifail}=5$

On entry,

$\mathit{lda}<\mathbf{n}$.

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

function f01zb_example


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

job = 'Pack';
uplo = 'U';
diag = 'N';
a = [ 1.1 + 1.1i,  1.2 + 1.2i,  1.3 + 1.3i,  1.4 + 1.4i;
      0   + 0i,    2.2 + 2.2i,  2.3 + 2.3i,  2.4 + 2.4i;
      0   + 0i,    0   + 0i,    3.3 + 3.3i,  3.4 + 3.4i;
      0   + 0i,    0   + 0i,    0   + 0i,    4.4 + 4.4i];
b =  complex(zeros(10, 1));

[A, ap, ifail] = f01zb(job, uplo, diag, a, b);

disp('Unpacked Matrix A:');
disp(A);
fprintf('\n');
disp('Packed Vector ap:');
disp(ap);

f01zb example results

Unpacked Matrix A:
   1.1000 + 1.1000i   1.2000 + 1.2000i   1.3000 + 1.3000i   1.4000 + 1.4000i
   0.0000 + 0.0000i   2.2000 + 2.2000i   2.3000 + 2.3000i   2.4000 + 2.4000i
   0.0000 + 0.0000i   0.0000 + 0.0000i   3.3000 + 3.3000i   3.4000 + 3.4000i
   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   4.4000 + 4.4000i


Packed Vector ap:
   1.1000 + 1.1000i
   1.2000 + 1.2000i
   2.2000 + 2.2000i
   1.3000 + 1.3000i
   2.3000 + 2.3000i
   3.3000 + 3.3000i
   1.4000 + 1.4000i
   2.4000 + 2.4000i
   3.4000 + 3.4000i
   4.4000 + 4.4000i