NAG Toolbox: nag_matop_real_tri_pack (f01za)

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)$ – double 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)$ – double 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$, 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)$ – double 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)$ – double 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: f01za_example

function f01za_example


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

a = [1.1, 1.2, 1.3, 1.4;
     0,   2.2, 2.3, 2.4;
     0,   0,   3.3, 3.4;
     0,   0,   0,   4.4];
b = zeros(10, 1);

job  = 'Pack';
uplo = 'U';
diag = 'N';

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

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

f01za example results

Unpacked Matrix A:
    1.1000    1.2000    1.3000    1.4000
         0    2.2000    2.3000    2.4000
         0         0    3.3000    3.4000
         0         0         0    4.4000


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