NAG Toolbox: nag_sparse_direct_real_gen_refine (f11mh)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Specifies whether $AX=B$ or $A^{\mathrm{T}}X=B$ is solved.

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

$AX=B$ is solved.

$\mathbf{trans}=\text{'T'}$

$A^{\mathrm{T}}X=B$ is solved.

Constraint: $\mathbf{trans}=\text{'N'}$ or $\text{'T'}$.

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{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$

The row index array of sparse matrix $A$.

4:     $\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$.

5:     $\mathrm{iprm}\left(7\times \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).

6:     $\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).

7:     $\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).

8:     $\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).

9:     $\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).

10:   $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array

The first dimension of the array b must be at least $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array b must be at least $\max \left(1,\mathbf{nrhs\_p}\right)$.

The $n$ by $\mathit{nrhs}$ right-hand side matrix $B$.

11:   $\mathrm{x}\left(\mathit{ldx},:\right)$ – double array

The first dimension of the array x must be at least $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array x must be at least $\max \left(1,\mathbf{nrhs\_p}\right)$.

The $n$ by $\mathit{nrhs}$ solution matrix $X$, as returned by nag_sparse_direct_real_gen_solve (f11mf).

Optional Input Parameters

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

Default: the first dimension of the arrays b, x. (An error is raised if these dimensions are not equal.)

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

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

2:     $\mathrm{nrhs\_p}$ – int64int32nag_int scalar

Default: the second dimension of the arrays b, x.

$\mathit{nrhs}$, the number of right-hand sides in $B$.

Constraint: $\mathbf{nrhs\_p}\ge 0$.

Output Parameters

1:     $\mathrm{x}\left(\mathit{ldx},:\right)$ – double array

The first dimension of the array x will be $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array x will be $\max \left(1,\mathbf{nrhs\_p}\right)$.

The $n$ by $\mathit{nrhs}$ improved solution matrix $X$.

2:     $\mathrm{ferr}\left(\mathbf{nrhs\_p}\right)$ – double array

$\mathbf{ferr}\left(\mathit{j}\right)$ contains an estimated error bound for the $\mathit{j}$th solution vector, that is, the $\mathit{j}$th column of $X$, for $\mathit{j}=1,2,\dots ,\mathit{nrhs}$.

3:     $\mathrm{berr}\left(\mathbf{nrhs\_p}\right)$ – double array

$\mathbf{berr}\left(\mathit{j}\right)$ contains the component-wise backward error bound $\beta$ for the $\mathit{j}$th solution vector, that is, the $\mathit{j}$th column of $X$, for $\mathit{j}=1,2,\dots ,\mathit{nrhs}$.

4:     $\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: $\mathit{ldb}\ge \max \left(1,\mathbf{n}\right)$.

Constraint: $\mathit{ldx}\ge \max \left(1,\mathbf{n}\right)$.

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

Constraint: $\mathbf{nrhs\_p}\ge 0$.

On entry, $\mathbf{trans}=\_$.
Constraint: $\mathbf{trans}=\text{'N'}$ or $\text{'T'}$.

   $\mathbf{ifail}=2$

Incorrect row permutations in array iprm.

   $\mathbf{ifail}=3$

Incorrect column permutations in array iprm.

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

function f11mh_example


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

% Solve AX=B for sparse A

% A and B 
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];
b = [  1.56,  3.12;
      -0.25, -0.50;
       3.60,  7.20;
       1.33,  2.66;
       0.52,  1.04];

% 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);

% Compute solution in x
x     = b;
trans = 'N';

[x, ifail] = f11mf( ...
                    trans, iprm, il, lval, iu, uval, x);

% Improve solution, and compute backward errors and estimated
% bounds on the forward errors
[x, ferr, berr, ifail] = ...
  f11mh( ...
         trans, icolzp, irowix, a, iprm, il, lval, iu, uval, b, x);

fprintf('Solutions:\n');
disp(x);
fprintf('Estmated Forward Error:\n');
fprintf('%8.1e\n', ferr);
fprintf('\nEstmated Backward Error:\n');
fprintf('%8.1e\n', berr);

f11mh example results

Solutions:
    0.7000    1.4000
    0.1600    0.3200
    0.5200    1.0400
    0.7700    1.5400
    0.2800    0.5600

Estmated Forward Error:
 5.0e-15
 5.0e-15

Estmated Backward Error:
 3.6e-17
 3.6e-17