Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_sparse_direct_real_gen_diag (f11mm)

## Purpose

nag_sparse_direct_real_gen_diag (f11mm) computes the reciprocal pivot growth factor of an $LU$ factorization of a real sparse matrix in compressed column (Harwell–Boeing) format.

## Syntax

[rpg, ifail] = f11mm(n, icolzp, a, iprm, il, lval, iu, uval)
[rpg, ifail] = nag_sparse_direct_real_gen_diag(n, icolzp, a, iprm, il, lval, iu, uval)

## Description

nag_sparse_direct_real_gen_diag (f11mm) computes the reciprocal pivot growth factor ${\mathrm{max}}_{j}\left({‖{A}_{j}‖}_{\infty }/{‖{U}_{j}‖}_{\infty }\right)$ from the columns ${A}_{j}$ and ${U}_{j}$ of an $LU$ factorization of the matrix $A$, ${P}_{r}A{P}_{c}=LU$ where ${P}_{r}$ is a row permutation matrix, ${P}_{c}$ is a column permutation matrix, $L$ is unit lower triangular and $U$ is upper triangular as computed by nag_sparse_direct_real_gen_lu (f11me).

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\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.
3:     $\mathrm{a}\left(:\right)$ – double array
The dimension of the array a must be at least ${\mathbf{icolzp}}\left({\mathbf{n}}+1\right)-1$, the number of nonzeros of the sparse matrix $A$
The array of nonzero values in the sparse matrix $A$.
4:     $\mathrm{iprm}\left(7×{\mathbf{n}}\right)$int64int32nag_int array
The column permutation which defines ${P}_{c}$, the row permutation which defines ${P}_{r}$, plus associated data structures as computed by nag_sparse_direct_real_gen_lu (f11me).
5:     $\mathrm{il}\left(:\right)$int64int32nag_int array
The dimension of the array il must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records the sparsity pattern of matrix $L$ as computed by nag_sparse_direct_real_gen_lu (f11me).
6:     $\mathrm{lval}\left(:\right)$ – double array
The dimension of the array lval must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records the nonzero values of matrix $L$ and some nonzero values of matrix $U$ as computed by nag_sparse_direct_real_gen_lu (f11me).
7:     $\mathrm{iu}\left(:\right)$int64int32nag_int array
The dimension of the array iu must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records the sparsity pattern of matrix $U$ as computed by nag_sparse_direct_real_gen_lu (f11me).
8:     $\mathrm{uval}\left(:\right)$ – double array
The dimension of the array uval must be at least as large as the dimension of the array of the same name in nag_sparse_direct_real_gen_lu (f11me)
Records some nonzero values of matrix $U$ as computed by nag_sparse_direct_real_gen_lu (f11me).

None.

### Output Parameters

1:     $\mathrm{rpg}$ – double scalar
The reciprocal pivot growth factor ${\mathrm{max}}_{j}\left({‖{A}_{j}‖}_{\infty }/{‖{U}_{j}‖}_{\infty }\right)$. If the reciprocal pivot growth factor is much less than $1$, the stability of the $LU$ factorization may be poor.
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

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=2$
Incorrect column permutations in array iprm.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Not applicable.

If the reciprocal pivot growth factor, rpg, is much less than $1$, then the factorization of the matrix $A$ could be poor. This means that using the factorization to obtain solutions to a linear system, forward error bounds and estimates of the condition number could be unreliable. Consider increasing the thresh argument in the call to nag_sparse_direct_real_gen_lu (f11me).

## Example

To compute the reciprocal pivot growth for the factorization of the matrix $A$, where
 $A= 2.00 1.00 0 0 0 0 0 1.00 -1.00 0 4.00 0 1.00 0 1.00 0 0 0 1.00 2.00 0 -2.00 0 0 3.00 .$
In this case, it should be equal to $1.0$.
```function f11mm_example

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

% Calculate reciprocal pivot growth from factorization of sparse A
n      = int64(5);
nz     = int64(11);
icolzp = [int64(1); 3; 5;  7; 9; 12];
irowix = [int64(1); 3; 1;  5; 2;  3;  2; 4; 3; 4; 5];
a      = [         2; 4; 1; -2; 1;  1; -1; 1; 1; 2; 3];

% Calculate COLAMD permutation
spec = 'M';
iprm = zeros(1, 7*n, 'int64');
[iprm, ifail] = f11md( ...
spec, n, icolzp, irowix, iprm);

% Factorise
thresh = 1;
nzlmx = int64(8*nz);
nzlumx = int64(8*nz);
nzumx = int64(8*nz);
[iprm, nzlumx, il, lval, iu, uval, nnzl, nnzu, flop, ifail] = ...
f11me( ...
n, irowix, a, iprm, thresh, nzlmx, nzlumx, nzumx);

% Calculate reciprocal pivot growth
[rpg, ifail] = f11mm( ...
n, icolzp, a, iprm, il, lval, iu, uval);

disp('Reciprocal pivot growth');
disp(rpg);

```
```f11mm example results

Reciprocal pivot growth
1

```