NAG Toolbox: nag_sparse_direct_real_gen_setup (f11md)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Indicates the permutation to be applied.

$\mathbf{spec}=\text{'N'}$

The identity permutation is used (i.e., the columns are not permuted).

$\mathbf{spec}=\text{'U'}$

The permutation in the iprm array is used, as supplied by you.

$\mathbf{spec}=\text{'M'}$

The permutation computed by the COLAMD algorithm is used

Constraint: $\mathbf{spec}=\text{'N'}$, $\text{'U'}$ or $\text{'M'}$.

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

$n$, the order of the matrix $A$.

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

3:     $\mathrm{icolzp}\left(:\right)$ – int64int32nag_int array

The dimension of the array icolzp must be at least $\mathbf{n}+1$

$\mathbf{icolzp}\left(i\right)$ contains the index in $A$ of the start of a new column. See Compressed column storage (CCS) format in the F11 Chapter Introduction.

4:     $\mathrm{irowix}\left(:\right)$ – int64int32nag_int array

The dimension of the array irowix must be at least $\mathbf{icolzp}\left(\mathbf{n}+1\right)-1$, the number of nonzeros of the sparse matrix $A$

$\mathbf{irowix}\left(i\right)$ contains the row index in $A$ for element $A\left(i\right)$. See Compressed column storage (CCS) format in the F11 Chapter Introduction.

5:     $\mathrm{iprm}\left(7\times \mathbf{n}\right)$ – int64int32nag_int array

The first $\mathbf{n}$ entries contain the column permutation supplied by you. This will be used if $\mathbf{spec}=\text{'U'}$, and ignored otherwise. If used, it must consist of a permutation of all the integers in the range $\left[0,\left(\mathbf{n}-1\right)\right]$, the leftmost column of the matrix $A$ denoted by $0$ and the rightmost by $\mathbf{n}-1$. Labelling columns in this way, $\mathbf{iprm}\left(i\right)=j$ means that column $i-1$ of $A$ is in position $j$ in $A{P}_c$, where $P_{r}A{P}_c=LU$ expresses the factorization to be performed.

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{iprm}\left(7\times \mathbf{n}\right)$ – int64int32nag_int array

A new permutation is returned in the first $\mathbf{n}$ entries. The rest of the array contains data structures that will be used by other functions. The function computes the column elimination tree for $A$ and a post-order permutation on the tree. It then compounds the iprm permutation given or computed by the COLAMD algorthm with the post-order permutation. This array is needed by the $LU$ factorization function nag_sparse_direct_real_gen_lu (f11me) and associated functions nag_sparse_direct_real_gen_solve (f11mf), nag_sparse_direct_real_gen_refine (f11mh) and nag_sparse_direct_real_gen_diag (f11mm) and should be passed to them unchanged.

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

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

On entry, $\mathbf{spec}=\_$.
Constraint: $\mathbf{spec}=\text{'N'}$, $\text{'U'}$ or $\text{'M'}$.

   $\mathbf{ifail}=2$

Incorrect column permutations in array iprm.

   $\mathbf{ifail}=3$

COLAMD algorithm failed.

   $\mathbf{ifail}=4$

Incorrect specification of argument icolzp.

   $\mathbf{ifail}=5$

Incorrect specification of argument irowix.

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

function f11md_example


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

n = int64(5);
icolzp = [int64(1); 3; 5; 7; 9; 12];
irowix = [int64(1); 3; 1; 5; 2; 3; 2; 4; 3; 4; 5];
iprm = zeros(1, 7*n, 'int64');

% Calculate COLAMD permutation
spec = 'M';
[iprm, ifail] = f11md( ...
                       spec, n, icolzp, irowix, iprm);
fprintf('\nCOLAMD Permutation\n');
disp(int2str(iprm(1:n)));

% Calculate user permutation
spec = 'U';
iprm(1:n)= [4, 3, 2, 1, 0];
[iprm, ifail] = f11md( ...
                       spec, n, icolzp, irowix, iprm);
fprintf('\nUser Permutation\n');
disp(int2str(iprm(1:n)));

% Calculate natural permutation
spec = 'N';
[iprm, ifail] = f11md( ...
                       spec, n, icolzp, irowix, iprm);
fprintf('\nNatural Permutation\n');
disp(int2str(iprm(1:n)));

f11md example results


COLAMD Permutation
1  0  4  3  2

User Permutation
4  3  2  1  0

Natural Permutation
0  1  2  3  4