factorization of a complex sparse non-Hermitian matrix, represented in coordinate storage format. This factorization may be used as a preconditioner in combination with f11bsc or f11dqc.

2 Specification

#include <nag.h>

void	f11dnc (Integer n, Integer nnz, Complex a[], Integer la, Integer irow[], Integer icol[], Integer lfill, double dtol, Nag_SparseNsym_Piv pstrat, Nag_SparseNsym_Fact milu, Integer ipivp[], Integer ipivq[], Integer istr[], Integer idiag[], Integer nnzc, Integer npivm, NagError *fail)

The function may be called by the names: f11dnc, nag_sparse_complex_gen_precon_ilu or nag_sparse_nherm_fac.

3 Description

f11dnc computes an incomplete

L U

factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of a complex sparse non-Hermitian

n \times n

matrix

A

. The factorization is intended primarily for use as a preconditioner with one of the iterative solvers f11bsc or f11dqc.

The decomposition is written in the form

A = M + R,

where

M = P L D U Q

and

L

is lower triangular with unit diagonal elements,

D

is diagonal,

U

is upper triangular with unit diagonals,

P

and

Q

are permutation matrices, and

R

is a remainder matrix.

The amount of fill-in occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill lfill, or the drop tolerance dtol.

The argument pstrat defines the pivoting strategy to be used. The options currently available are no pivoting, user-defined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability. The factorization may optionally be modified to preserve the row-sums of the original matrix.

The sparse matrix

A

is represented in coordinate storage (CS) format (see Section 2.1.1 in the F11 Chapter Introduction). The array a stores all the nonzero elements of the matrix

A

, while arrays irow and icol store the corresponding row and column indices respectively. Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrix

M

is returned in terms of the CS representation of the matrix

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

Further algorithmic details are given in Section 9.3.

4 References

Meijerink J and Van der Vorst H (1977) An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix Math. Comput. 31 148–162

Meijerink J and Van der Vorst H (1981) Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems J. Comput. Phys. 44 134–155

5 Arguments

1: $n$ – Integer Input

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 1

2: $nnz$ – Integer Input

On entry: the number of nonzero elements in the matrix

A

Constraint:

1 \leq nnz \leq n^{2}

3: $a [la]$ – Complex Input/Output

On entry: the nonzero elements in the matrix

A

, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function f11znc may be used to order the elements in this way.

On exit: the first nnz entries of a contain the nonzero elements of

A

and the next nnzc entries contain the elements of the matrix

C

. Matrix elements are ordered by increasing row index, and by increasing column index within each row.

4: $la$ – Integer Input

On entry: the dimension of the arrays a, irow and icol. These arrays must be of sufficient size to store both

A

(nnz elements) and

C

(nnzc elements).

Constraint:

la \geq 2 \times nnz

5: $irow [la]$ – Integer Input/Output

6: $icol [la]$ – Integer Input/Output

On entry: the row and column indices of the nonzero elements supplied in a.

Constraints:

irow and icol must satisfy these constraints (which may be imposed by a call to f11znc):

$1 \leq irow [i - 1] \leq n$ and $1 \leq icol [i - 1] \leq n$ , for $i = 1, 2, \dots, nnz$ ;
either $irow [i - 1] < irow [i]$ or both $irow [i - 1] = irow [i]$ and $icol [i - 1] < icol [i]$ , for $i = 1, 2, \dots, nnz$ .

On exit: the row and column indices of the nonzero elements returned in a.

7: $lfill$ – Integer Input

On entry: if

lfill \geq 0

its value is the maximum level of fill allowed in the decomposition (see Section 9.2). A negative value of lfill indicates that dtol will be used to control the fill instead.

8: $dtol$ – double Input

On entry: if

lfill < 0

, dtol is used as a drop tolerance to control the fill-in (see Section 9.2); otherwise dtol is not referenced.

Constraint: if

lfill < 0

dtol \geq 0.0

9: $pstrat$ – Nag_SparseNsym_Piv Input

On entry: specifies the pivoting strategy to be adopted.

$pstrat = Nag_SparseNsym_NoPiv$: No pivoting is carried out.
$pstrat = Nag_SparseNsym_UserPiv$: Pivoting is carried out according to the user-defined input values of ipivp and ipivq.
$pstrat = Nag_SparseNsym_PartialPiv$: Partial pivoting by columns for stability is carried out.
$pstrat = Nag_SparseNsym_CompletePiv$: Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

Suggested value:

pstrat = Nag_SparseNsym_CompletePiv

Constraint:

pstrat = Nag_SparseNsym_NoPiv

Nag_SparseNsym_UserPiv

Nag_SparseNsym_PartialPiv

Nag_SparseNsym_CompletePiv

10: $milu$ – Nag_SparseNsym_Fact Input

On entry: indicates whether or not the factorization should be modified to preserve row-sums (see Section 9.4).

$milu = Nag_SparseNsym_ModFact$: The factorization is modified.
$milu = Nag_SparseNsym_UnModFact$: The factorization is not modified.

Constraint:

milu = Nag_SparseNsym_ModFact

Nag_SparseNsym_UnModFact

11: $ipivp [n]$ – Integer Input/Output

12: $ipivq [n]$ – Integer Input/Output

On entry: if

pstrat = Nag_SparseNsym_UserPiv

ipivp [k - 1]

and

ipivq [k - 1]

must specify the row and column indices of the element used as a pivot at elimination stage

k

. Otherwise ipivp and ipivq need not be initialized.

Constraint: if

pstrat = Nag_SparseNsym_UserPiv

, ipivp and ipivq must both hold valid permutations of the integers on [1,n].

On exit: the pivot indices. If

ipivp [k - 1] = i

and

ipivq [k - 1] = j

then the element in row

i

and column

j

was used as the pivot at elimination stage

k

13: $istr [n + 1]$ – Integer Output

On exit:

istr [i - 1] - 1

, for

i = 1, 2, \dots, n

, is the starting address in the arrays a, irow and icol of row

i

of the matrix

C

istr [n] - 1

is the address of the last nonzero element in

C

plus one.

14: $idiag [n]$ – Integer Output

On exit:

idiag [i - 1]

, for

i = 1, 2, \dots, n

, holds the index of arrays a, irow and icol which holds the diagonal element in row

i

of the matrix

C

15: $nnzc$ – Integer * Output

On exit: the number of nonzero elements in the matrix

C

16: $npivm$ – Integer * Output

On exit: if

npivm > 0

it gives the number of pivots which were modified during the factorization to ensure that

M

exists.

npivm = −1

no pivot modifications were required, but a local restart occurred (see Section 9.3). The quality of the preconditioner will generally depend on the returned value of npivm.

If npivm is large the preconditioner may not be satisfactory. In this case it may be advantageous to call f11dnc again with an increased value of lfill, a reduced value of dtol, or set

pstrat = Nag_SparseNsym_CompletePiv

. See also Section 9.5.

17: $fail$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM: On entry, argument $⟨ value ⟩$ had an illegal value.
NE_INT: On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 1$ .

On entry, $nnz = ⟨ value ⟩$ .
Constraint: $nnz \geq 1$ .
NE_INT_2: On entry, $la = ⟨ value ⟩$ and $nnz = ⟨ value ⟩$ .
Constraint: $la \geq 2 \times nnz$

On entry, $nnz = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $nnz \leq n^{2}$
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.

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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_INVALID_CS: On entry, $I = ⟨ value ⟩$ , $icol [I - 1] = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $1 \leq icol [i - 1] \leq n$ , for $i = 1, 2, \dots, nnz$

On entry, $I = ⟨ value ⟩$ , $irow [I - 1] = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $1 \leq irow [i - 1] \leq n$ , for $i = 1, 2, \dots, nnz$
NE_INVALID_ROWCOL_PIVOT: On entry, a user-supplied value of ipivp is repeated.

On entry, a user-supplied value of ipivp lies outside the range $[1, n]$ .

On entry, a user-supplied value of ipivq is repeated.

On entry, a user-supplied value of ipivq lies outside the range $[1, n]$ .
NE_NO_LICENCE: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_NOT_STRICTLY_INCREASING: On entry, $a [i - 1]$ is out of order: $i = ⟨ value ⟩$ .

On entry, the location ( $irow [I - 1], icol [I - 1]$ ) is a duplicate: $I = ⟨ value ⟩$ .
NE_REAL: On entry, $dtol = ⟨ value ⟩$ .
Constraint: $dtol \geq 0.0$
NE_TOO_SMALL: The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase la, or reduce the fill by reducing lfill, or increasing dtol.

7 Accuracy

The accuracy of the factorization will be determined by the size of the elements that are dropped and the size of any modifications made to the pivot elements. If these sizes are small then the computed factors will correspond to a matrix close to

A

. The factorization can generally be made more accurate by increasing lfill, or by reducing dtol with

lfill < 0

If f11dnc is used in combination with f11bsc or f11dqc, the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

f11dnc is not threaded in any implementation.

9 Further Comments

9.1 Timing

The time taken for a call to f11dnc is roughly proportional to

{nnzc}^{2} / n

9.2 Control of Fill-in

lfill \geq 0

the amount of fill-in occurring in the incomplete factorization is controlled by limiting the maximum level of fill-in to lfill. The original nonzero elements of

A

are defined to be of level

0

. The fill level of a new nonzero location occurring during the factorization is defined as:

k = \max (k_{e}, k_{c}) + 1,

where

k_{e}

is the level of fill of the element being eliminated, and

k_{c}

is the level of fill of the element causing the fill-in.

lfill < 0

the fill-in is controlled by means of the drop tolerance dtol. A potential fill-in element

a_{i j}

occurring in row

i

and column

j

will not be included if:

| a_{i j} | < dtol \times α,

where

α

is the maximum modulus element in the matrix

A

For either method of control, any elements which are not included are discarded unless

milu = Nag_SparseNsym_ModFact

, in which case their contributions are subtracted from the pivot element in the relevant elimination row, to preserve the row-sums of the original matrix.

Should the factorization process break down a local restart process is implemented as described in Section 9.3. This will affect the amount of fill present in the final factorization.

9.3 Algorithmic Details

The factorization is constructed row by row. At each elimination stage a row index is chosen. In the case of complete pivoting this index is chosen in order to reduce fill-in. Otherwise the rows are treated in the order given, or some user-defined order.

The chosen row is copied from the original matrix

A

and modified according to those previous elimination stages which affect it. During this process any fill-in elements are either dropped or kept according to the values of lfill or dtol. In the case of a modified factorization (

milu = Nag_SparseNsym_ModFact

) the sum of the dropped terms for the given row is stored.

Finally the pivot element for the row is chosen and the multipliers are computed for this elimination stage. For partial or complete pivoting the pivot element is chosen in the interests of stability as the element of largest absolute value in the row. Otherwise the pivot element is chosen in the order given, or some user-defined order.

If the factorization breaks down because the chosen pivot element is zero, or there is no nonzero pivot available, a local restart recovery process is implemented. The modification of the given pivot row according to previous elimination stages is repeated, but this time keeping all fill-in. Note that in this case the final factorization will include more fill than originally specified by the user-supplied value of lfill or dtol. The local restart usually results in a suitable nonzero pivot arising. The original criteria for dropping fill-in elements is then resumed for the next elimination stage (hence the local nature of the restart process). Should this restart process also fail to produce a nonzero pivot element an arbitrary unit pivot is introduced in an arbitrarily chosen column. f11dnc returns an integer argument npivm which gives the number of these arbitrary unit pivots introduced. If no pivots were modified but local restarts occurred

npivm = −1

is returned.

9.4 Choice of Arguments

There is unfortunately no choice of the various algorithmic arguments which is optimal for all types of matrix, and some experimentation will generally be required for each new type of matrix encountered. The recommended approach is to start with

lfill = 0

and

pstrat = Nag_SparseNsym_CompletePiv

. If the value returned for npivm is significantly larger than zero, i.e., a large number of pivot modifications were required to ensure that

M

existed, the preconditioner is not likely to be satisfactory. In this case increase lfill until npivm falls to a value close to zero.

For certain classes of matrices (typically those arising from the discretization of elliptic or parabolic partial differential equations) the convergence rate of the preconditioned iterative solver can sometimes be significantly improved by using an incomplete factorization which preserves the row-sums of the original matrix. In these cases try setting

milu = Nag_SparseNsym_ModFact

9.5 Direct Solution of Sparse Linear Systems

Although it is not the primary purpose of the functions f11dnc and f11dpc, they may be used together to obtain a direct solution to a nonsingular sparse complex non-Hermitian linear system. To achieve this the call to f11dpc should be preceded by a complete

L U

factorization

A = P L D U Q = M .

A complete factorization is obtained from a call to f11dnc with

lfill < 0

and

dtol = 0.0

, provided

npivm \leq 0

on exit. A positive value of npivm indicates that

A

is singular, or ill-conditioned. A factorization with positive npivm may serve as a preconditioner, but will not result in a direct solution. It is, therefore, essential to check the output value of npivm if a direct solution is required.

The use of f11dnc and f11dpc as a direct method is illustrated in f11dpc.

10 Example

This example reads in a complex sparse non-Hermitian matrix

A

and calls f11dnc to compute an incomplete

L U

factorization. It then outputs the nonzero elements of both

A

and

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

The call to f11dnc has

lfill = 0

, and

pstrat = Nag_SparseNsym_CompletePiv

, giving an unmodified zero-fill

L U

factorization, with row pivoting for sparsity and column pivoting for stability.

f11dn: FL CL CPP AD PY MB

NAG CL Interfacef11dnc (complex_​gen_​precon_​ilu)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Timing

9.2 Control of Fill-in

9.3 Algorithmic Details

9.4 Choice of Arguments

9.5 Direct Solution of Sparse Linear Systems

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG CL Interface
f11dnc (complex_gen_precon_ilu)