NAG Library Function Document

nag_sparse_nsym_precon_ilu_solve (f11dbc)

nag_sparse_nsym_precon_ilu_solve (Nag_TransType trans, Integer n, const double a[], Integer la, const Integer irow[], const Integer icol[], const Integer ipivp[], const Integer ipivq[], const Integer istr[], const Integer idiag[], Nag_SparseNsym_CheckData check, const double y[], double x[], NagError *fail)

3 Description

nag_sparse_nsym_precon_ilu_solve (f11dbc) solves a system of linear equations

\begin{matrix} M x = y, & or & M^{T} x = y, \end{matrix}

according to the value of the argument trans, where the matrix

M = P L D U Q

, corresponds to an incomplete

L U

decomposition of a sparse matrix stored in coordinate storage (CS) format (see Section 2.1.1 in the f11 Chapter Introduction), as generated by nag_sparse_nsym_fac (f11dac).

In the above decomposition

L

is a lower triangular sparse matrix with unit diagonal elements,

D

is a diagonal matrix,

U

is an upper triangular sparse matrix with unit diagonal elements and,

P

and

Q

are permutation matrices.

L

D

and

U

are supplied to nag_sparse_nsym_precon_ilu_solve (f11dbc) through the matrix

C = L + D^{- 1} + U - 2 I

which is an n by n sparse matrix, stored in CS format, as returned by nag_sparse_nsym_fac (f11dac). The permutation matrices

P

and

Q

are returned from nag_sparse_nsym_fac (f11dac) via the arrays ipivp and ipivq.

It is envisaged that a common use of nag_sparse_nsym_precon_ilu_solve (f11dbc) will be to carry out the preconditioning step required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. nag_sparse_nsym_precon_ilu_solve (f11dbc) is used for this purpose by the Black Box function nag_sparse_nsym_fac_sol (f11dcc).

nag_sparse_nsym_precon_ilu_solve (f11dbc) may also be used in combination with nag_sparse_nsym_fac (f11dac) to solve a sparse system of linear equations directly (see Section 9.5 in nag_sparse_nsym_fac (f11dac)). This use of nag_sparse_nsym_precon_ilu_solve (f11dbc) is demonstrated in Section 10.

4 References

None.

5 Arguments

1: trans – Nag_TransTypeInput

On entry: specifies whether or not the matrix

M

is transposed.

$trans = Nag_NoTrans$: $M x = y$ is solved.
$trans = Nag_Trans$: $M^{T} x = y$ is solved.

Constraint:

trans = Nag_NoTrans

Nag_Trans

2: n – IntegerInput

On entry:

n

, the order of the matrix

M

. This must be the same value as was supplied in the preceding call to nag_sparse_nsym_fac (f11dac).

Constraint:

n \geq 1

3: a[la] – const doubleInput

On entry: the values returned in the array a by a previous call to nag_sparse_nsym_fac (f11dac).

4: la – IntegerInput

On entry: the dimension of the arrays a, irow and icol. This must be the same value returned by the preceding call to nag_sparse_nsym_fac (f11dac).

5: irow[la] – const IntegerInput

6: icol[la] – const IntegerInput

7: ipivp[n] – const IntegerInput

8: ipivq[n] – const IntegerInput

9: istr[ $n + 1$ ] – const IntegerInput

10: idiag[n] – const IntegerInput

On entry: the values returned in arrays irow, icol, ipivp, ipivq, istr and idiag by a previous call to nag_sparse_nsym_fac (f11dac).

11: check – Nag_SparseNsym_CheckDataInput

On entry: specifies whether or not the CS representation of the matrix

M

should be checked.

$check = Nag_SparseNsym_Check$: Checks are carried on the values of n, irow, icol, ipivp, ipivq, istr and idiag.
$check = Nag_SparseNsym_NoCheck$: None of these checks are carried out.

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_INT: On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 1$ .
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_CS: On entry, $i = ⟨value⟩$ , $icol [i - 1] = ⟨value⟩$ , and $n = ⟨value⟩$ .
Constraint: $icol [i - 1] \geq 1$ and $icol [i - 1] \leq n$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $i = ⟨value⟩$ , $irow [i - 1] = ⟨value⟩$ , $n = ⟨value⟩$ .
Constraint: $irow [i - 1] \geq 1$ and $irow [i - 1] \leq n$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
NE_INVALID_CS_PRECOND: On entry, $idiag [i - 1]$ appears to be incorrect: $i = ⟨value⟩$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, istr appears to be invalid.
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $istr [i - 1]$ is inconsistent with irow: $i = ⟨value⟩$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
NE_INVALID_ROWCOL_PIVOT: On entry, $i = ⟨value⟩$ , $ipivp [i - 1] = ⟨value⟩$ , $n = ⟨value⟩$ .
Constraint: $ipivp [i - 1] \geq 1$ and $ipivp [i - 1] \leq n$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $i = ⟨value⟩$ , $ipivq [i - 1] = ⟨value⟩$ , $n = ⟨value⟩$ .
Constraint: $ipivq [i - 1] \geq 1$ and $ipivq [i - 1] \leq n$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $ipivp [i - 1]$ is a repeated value: $i = ⟨value⟩$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, $ipivq [i - 1]$ is a repeated value: $i = ⟨value⟩$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
NE_NOT_STRICTLY_INCREASING: On entry, $a [i - 1]$ is out of order: $i = ⟨value⟩$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).
On entry, the location ( $irow [i - 1], icol [i - 1]$ ) is a duplicate: $i = ⟨value⟩$ .
Check that a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between calls to nag_sparse_nsym_precon_ilu_solve (f11dbc) and nag_sparse_nsym_fac (f11dac).

7 Accuracy

trans = Nag_NoTrans

the computed solution

x

is the exact solution of a perturbed system of equations

(M + δ M) x = y

, where

|δ M| \leq c (n) ε P |L| |D| |U| Q,

c (n)

is a modest linear function of

n

, and

ε

is the machine precision. An equivalent result holds when

trans = Nag_Trans

8 Parallelism and Performance

Not applicable.

9 Further Comments

9.1 Timing

The time taken for a call to nag_sparse_nsym_precon_ilu_solve (f11dbc) is proportional to the value of nnzc returned from nag_sparse_nsym_fac (f11dac).

9.2 Use of check

It is expected that a common use of nag_sparse_nsym_precon_ilu_solve (f11dbc) will be to carry out the preconditioning step required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. In this situation nag_sparse_nsym_precon_ilu_solve (f11dbc) is likely to be called many times with the same matrix

M

. In the interests of both reliability and efficiency, you are recommended to set

check = Nag_SparseNsym_Check

for the first of such calls, and for all subsequent calls set

check = Nag_SparseNsym_NoCheck

10 Example

This example reads in a sparse nonsymmetric matrix

A

and a vector

y

. It then calls nag_sparse_nsym_fac (f11dac), with

lfill = - 1

and

dtol = 0.0

, to compute the complete

L U

decomposition

A = P L D U Q .

Finally it calls nag_sparse_nsym_precon_ilu_solve (f11dbc) to solve the system

P L D U Q x = y .

NAG Library Function Documentnag_sparse_nsym_precon_ilu_solve (f11dbc)

+− Contents

1 Purpose

2 Specification