NAG C Library Function Document

nag_sparse_nherm_fac (f11dnc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{n}$ – IntegerInput

On entry: $n$, the order of the matrix $A$.

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

2:    $\mathbf{nnz}$ – IntegerInput

On entry: the number of nonzero elements in the matrix $A$.

Constraint: $1\le \mathbf{nnz}\le {\mathbf{n}}^2$.

3:    $\mathbf{a}\left[\mathbf{la}\right]$ – ComplexInput/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 nag_sparse_nherm_sort (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:    $\mathbf{la}$ – IntegerInput

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: $\mathbf{la}\ge 2\times \mathbf{nnz}$.

5:    $\mathbf{irow}\left[\mathbf{la}\right]$ – IntegerInput/Output

6:    $\mathbf{icol}\left[\mathbf{la}\right]$ – IntegerInput/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 nag_sparse_nherm_sort (f11znc)):

• $1\le \mathbf{irow}\left[\mathit{i}-1\right]\le \mathbf{n}$ and $1\le \mathbf{icol}\left[\mathit{i}-1\right]\le \mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{nnz}$;
• either $\mathbf{irow}\left[\mathit{i}-1\right]<\mathbf{irow}\left[\mathit{i}\right]$ or both $\mathbf{irow}\left[\mathit{i}-1\right]=\mathbf{irow}\left[\mathit{i}\right]$ and $\mathbf{icol}\left[\mathit{i}-1\right]<\mathbf{icol}\left[\mathit{i}\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{nnz}$.

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

7:    $\mathbf{lfill}$ – IntegerInput

On entry: if $\mathbf{lfill}\ge 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:    $\mathbf{dtol}$ – doubleInput

On entry: if $\mathbf{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 $\mathbf{lfill}<0$, $\mathbf{dtol}\ge 0.0$.

9:    $\mathbf{pstrat}$ – Nag_SparseNsym_PivInput

On entry: specifies the pivoting strategy to be adopted.

$\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_NoPiv}$

No pivoting is carried out.

$\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_UserPiv}$

Pivoting is carried out according to the user-defined input values of ipivp and ipivq.

$\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_PartialPiv}$

Partial pivoting by columns for stability is carried out.

$\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_CompletePiv}$

Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

Suggested value: $\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_CompletePiv}$.

Constraint: $\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_NoPiv}$, $\mathrm{Nag\_SparseNsym\_UserPiv}$, $\mathrm{Nag\_SparseNsym\_PartialPiv}$ or $\mathrm{Nag\_SparseNsym\_CompletePiv}$.

10:  $\mathbf{milu}$ – Nag_SparseNsym_FactInput

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

$\mathbf{milu}=\mathrm{Nag\_SparseNsym\_ModFact}$

The factorization is modified.

$\mathbf{milu}=\mathrm{Nag\_SparseNsym\_UnModFact}$

The factorization is not modified.

Constraint: $\mathbf{milu}=\mathrm{Nag\_SparseNsym\_ModFact}$ or $\mathrm{Nag\_SparseNsym\_UnModFact}$.

11:  $\mathbf{ipivp}\left[\mathbf{n}\right]$ – IntegerInput/Output

12:  $\mathbf{ipivq}\left[\mathbf{n}\right]$ – IntegerInput/Output

On entry: if $\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_UserPiv}$, $\mathbf{ipivp}\left[k-1\right]$ and $\mathbf{ipivq}\left[k-1\right]$ 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 $\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_UserPiv}$, ipivp and ipivq must both hold valid permutations of the integers on [1,n].

On exit: the pivot indices. If $\mathbf{ipivp}\left[k-1\right]=i$ and $\mathbf{ipivq}\left[k-1\right]=j$ then the element in row $i$ and column $j$ was used as the pivot at elimination stage $k$.

13:  $\mathbf{istr}\left[\mathbf{n}+1\right]$ – IntegerOutput

On exit: $\mathbf{istr}\left[\mathit{i}-1\right]-1$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$, is the starting address in the arrays a, irow and icol of row $i$ of the matrix $C$. $\mathbf{istr}\left[\mathbf{n}\right]-1$ is the address of the last nonzero element in $C$ plus one.

14:  $\mathbf{idiag}\left[\mathbf{n}\right]$ – IntegerOutput

On exit: $\mathbf{idiag}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$, holds the index of arrays a, irow and icol which holds the diagonal element in row $i$ of the matrix $C$.

15:  $\mathbf{nnzc}$ – Integer *Output

On exit: the number of nonzero elements in the matrix $C$.

16:  $\mathbf{npivm}$ – Integer *Output

On exit: if $\mathbf{npivm}>0$ it gives the number of pivots which were modified during the factorization to ensure that $M$ exists.

If $\mathbf{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 nag_sparse_nherm_fac (f11dnc) again with an increased value of lfill, a reduced value of dtol, or set $\mathbf{pstrat}=\mathrm{Nag\_SparseNsym\_CompletePiv}$. See also Section 9.5.

17:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_INT

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 1$.

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nnz}\ge 1$.

NE_INT_2

On entry, $\mathbf{la}=〈\mathit{\text{value}}〉$ and $\mathbf{nnz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{la}\ge 2\times \mathbf{nnz}$ 

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nnz}\le {\mathbf{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 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_INVALID_CS

On entry, $\mathit{I}=〈\mathit{\text{value}}〉$, $\mathbf{icol}\left[\mathit{I}-1\right]=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{icol}\left[\mathit{i}-1\right]\le \mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{nnz}$ 

On entry, $\mathit{I}=〈\mathit{\text{value}}〉$, $\mathbf{irow}\left[\mathit{I}-1\right]=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{irow}\left[\mathit{i}-1\right]\le \mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{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 $\left[1,\mathbf{n}\right]$.

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

On entry, a user-supplied value of ipivq lies outside the range $\left[1,\mathbf{n}\right]$.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_NOT_STRICTLY_INCREASING

On entry, $\mathbf{a}\left[i-1\right]$ is out of order: $i=〈\mathit{\text{value}}〉$.

On entry, the location ($\mathbf{irow}\left[\mathit{I}-1\right],\mathbf{icol}\left[\mathit{I}-1\right]$) is a duplicate: $\mathit{I}=〈\mathit{\text{value}}〉$.

NE_REAL

On entry, $\mathbf{dtol}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{dtol}\ge 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

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

Program Text (f11dnce.c)

10.2

Program Data

Program Data (f11dnce.d)

10.3

Program Results

Program Results (f11dnce.r)