NAG Library Function Document

nag_superlu_refine_lu (f11mhc)

nag_superlu_refine_lu (Nag_OrderType order, Nag_TransType trans, Integer n, const Integer icolzp[], const Integer irowix[], const double a[], const Integer iprm[], const Integer il[], const double lval[], const Integer iu[], const double uval[], Integer nrhs, const double b[], Integer pdb, double x[], Integer pdx, double ferr[], double berr[], NagError *fail)

3 Description

nag_superlu_refine_lu (f11mhc) returns the backward errors and estimated bounds on the forward errors for the solution of a real system of linear equations with multiple right-hand sides

A X = B

A^{T} X = B

. The function handles each right-hand side vector (stored as a column of the matrix

B

) independently, so we describe the function of nag_superlu_refine_lu (f11mhc) in terms of a single right-hand side

b

and solution

x

Given a computed solution

x

, the function computes the component-wise backward error

β

. This is the size of the smallest relative perturbation in each element of

A

and

b

such that if

x

is the exact solution of a perturbed system:

\begin{matrix} (A + δ A) x = b + δ b \\ then |δ a_{i j}| \leq β |a_{i j}| and |δ b_{i}| \leq β |b_{i}| . \end{matrix}

Then the function estimates a bound for the component-wise forward error in the computed solution, defined by:

\max_{i}^{} |x_{i} - {\hat{x}}_{i}| / \max_{i}^{} |x_{i}|

where

\hat{x}

is the true solution.

The function uses the

L U

factorization

P_{r} A P_{c} = L U

computed by nag_superlu_lu_factorize (f11mec) and the solution computed by nag_superlu_solve_lu (f11mfc).

4 References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

5 Arguments

1: order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: trans – Nag_TransTypeInput

On entry: specifies whether

A X = B

A^{T} X = B

is solved.

$trans = Nag_NoTrans$: $A X = B$ is solved.
$trans = Nag_Trans$: $A^{T} X = B$ is solved.

Constraint:

trans = Nag_NoTrans

Nag_Trans

3: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

4: icolzp[ $\dim$ ] – const IntegerInput

Note: the dimension, dim, of the array icolzp must be at least

n + 1

On entry:

icolzp [i - 1]

contains the index in

A

of the start of a new column. See Section 2.1.3 in the f11 Chapter Introduction.

5: irowix[ $\dim$ ] – const IntegerInput

Note: the dimension, dim, of the array irowix must be at least

icolzp [n] - 1

, the number of nonzeros of the sparse matrix

A

On entry: the row index array of the sparse matrix

A

6: a[ $\dim$ ] – const doubleInput

Note: the dimension, dim, of the array a must be at least

icolzp [n] - 1

, the number of nonzeros of the sparse matrix

A

On entry: the array of nonzero values in the sparse matrix

A

7: iprm[ $7 \times n$ ] – const IntegerInput

On entry: the column permutation which defines

P_{c}

, the row permutation which defines

P_{r}

, plus associated data structures as computed by nag_superlu_lu_factorize (f11mec).

8: il[ $\dim$ ] – const IntegerInput

Note: the dimension, dim, of the array il must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records the sparsity pattern of matrix

L

as computed by nag_superlu_lu_factorize (f11mec).

9: lval[ $\dim$ ] – const doubleInput

Note: the dimension, dim, of the array lval must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records the nonzero values of matrix

L

and some nonzero values of matrix

U

as computed by nag_superlu_lu_factorize (f11mec).

10: iu[ $\dim$ ] – const IntegerInput

Note: the dimension, dim, of the array iu must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records the sparsity pattern of matrix

U

as computed by nag_superlu_lu_factorize (f11mec).

11: uval[ $\dim$ ] – const doubleInput

Note: the dimension, dim, of the array uval must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records some nonzero values of matrix

U

as computed by nag_superlu_lu_factorize (f11mec).

12: nrhs – IntegerInput

On entry:

nrhs

, the number of right-hand sides in

B

Constraint:

nrhs \geq 0

13: b[ $\dim$ ] – const doubleInput

Note: the dimension, dim, of the array b must be at least

$\max (1, pdb \times nrhs)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdb)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

B

is stored in

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

nrhs

right-hand side matrix

B

14: pdb – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array b.

Constraints:

if $order = Nag_ColMajor$ , $pdb \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pdb \geq \max (1, nrhs)$ .

15: x[ $\dim$ ] – doubleInput/Output

Note: the dimension, dim, of the array x must be at least

$\max (1, pdx \times nrhs)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdx)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

X

is stored in

$x [(j - 1) \times pdx + i - 1]$ when $order = Nag_ColMajor$ ;
$x [(i - 1) \times pdx + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

nrhs

solution matrix

X

, as returned by nag_superlu_solve_lu (f11mfc).

On exit: the

n

nrhs

improved solution matrix

X

16: pdx – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array x.

Constraints:

if $order = Nag_ColMajor$ , $pdx \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pdx \geq \max (1, nrhs)$ .

17: ferr[nrhs] – doubleOutput

On exit:

ferr [j - 1]

contains an estimated error bound for the

j

th solution vector, that is, the

j

th column of

X

, for

j = 1, 2, \dots, nrhs

18: berr[nrhs] – doubleOutput

On exit:

berr [j - 1]

contains the component-wise backward error bound

β

for the

j

th solution vector, that is, the

j

th column of

X

, for

j = 1, 2, \dots, nrhs

19: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument number $〈value〉$ had an illegal value.; On entry, argument $〈value〉$ had an illegal value.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $nrhs = 〈value〉$ .
Constraint: $nrhs \geq 0$ .; On entry, $pdb = 〈value〉$ .
Constraint: $pdb > 0$ .; On entry, $pdx = 〈value〉$ .
Constraint: $pdx > 0$ .
NE_INT_2: On entry, $pdb = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdb \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $nrhs = 〈value〉$ .
Constraint: $pdb \geq \max (1, nrhs)$ .; On entry, $pdx = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdx \geq \max (1, n)$ .; On entry, $pdx = 〈value〉$ and $nrhs = 〈value〉$ .
Constraint: $pdx \geq \max (1, nrhs)$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_PERM_COL: Incorrect Column Permutations in array iprm.
NE_INVALID_PERM_ROW: Incorrect Row Permutations in array iprm.

7 Accuracy

The bounds returned in ferr are not rigorous, because they are estimated, not computed exactly; but in practice they almost always overestimate the actual error.

8 Further Comments

At most five steps of iterative refinement are performed, but usually only one or two steps are required.

Estimating the forward error involves solving a number of systems of linear equations of the form

A x = b

A^{T} x = b

;

9 Example

This example solves the system of equations

A X = B

using iterative refinement and to compute the forward and backward error bounds, where

A = (\begin{matrix} 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 \end{matrix}) and B = (\begin{matrix} 1.56 & 3.12 \\ - 0.25 & - 0.50 \\ 3.60 & 7.20 \\ 1.33 & 2.66 \\ 0.52 & 1.04 \end{matrix}) .

Here

A

is nonsymmetric and must first be factorized by nag_superlu_lu_factorize (f11mec).

NAG Library Function Documentnag_superlu_refine_lu (f11mhc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_superlu_refine_lu (f11mhc)