NAG CL Interface
f11dtc (complex_​gen_​precon_​bdilu)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{n}$ – Integer Input

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

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

2: $\mathbf{nnz}$ – Integer Input

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]$ – 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 matrices $C_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$ stored consecutively. Within each block the matrix elements are ordered by increasing row index, and by increasing column index within each row.

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

Note: the minimum value for la is only appropriate if lfill and dtol are set such that minimal fill-in occurs. If this is not the case then we recommend that la is set much larger than the minimum value indicated in the constraint.

Constraint: $\mathbf{la}\ge 2\times \mathbf{nnz}$.

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

6: $\mathbf{icol}\left[\mathbf{la}\right]$ – 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\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{nb}$ – Integer Input

On entry: the number of diagonal blocks to factorize.

Constraint: $1\le \mathbf{nb}\le \mathbf{n}$.

8: $\mathbf{istb}\left[\mathbf{nb}+1\right]$ – const Integer Input

On entry: $\mathbf{istb}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$, holds the indices in arrays indb, ipivp, ipivq and idiag that, on successful exit from this function, define block $\mathit{b}$. Let $r_{\mathit{b}}$ denote the number of rows in block $\mathit{b}$; then $\mathbf{istb}\left[\mathit{b}\right]=\mathbf{istb}\left[\mathit{b}-1\right]+r_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$. Thus, $\mathbf{istb}\left[\mathbf{nb}\right]$ holds the sum of the number of rows in all blocks plus $\mathbf{istb}\left[0\right]$.

Constraint: $\mathbf{istb}\left[0\right]\ge 1,\mathbf{istb}\left[\mathit{b}-1\right]<\mathbf{istb}\left[\mathit{b}\right]$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

9: $\mathbf{indb}\left[\mathbf{lindb}\right]$ – const Integer Input

On entry: indb must hold the row indices appearing in each diagonal block, stored consecutively. Thus the elements $\mathbf{indb}\left[k_b-1\right]$, for $k_b=\mathbf{istb}\left[b-1\right],\mathbf{istb}\left[b-1\right]+1,\dots ,\mathbf{istb}\left[b\right]-2,\mathbf{istb}\left[b\right]-1$, are the row indices in the $\mathit{b}$th block, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

Constraint: $1\le \mathbf{indb}\left[\mathit{m}-1\right]\le \mathbf{n}$, for $m=\mathbf{istb}\left[0\right],\mathbf{istb}\left[0\right]+1,\dots ,\mathbf{istb}\left[\mathbf{nb}\right]-1$.

10: $\mathbf{lindb}$ – Integer Input

On entry: the dimension of the arrays indb, ipivp, ipivq and idiag.

Constraint: $\mathbf{lindb}\ge \mathbf{istb}\left[\mathbf{nb}\right]-1$.

11: $\mathbf{lfill}\left[\mathbf{nb}\right]$ – const Integer Input

On entry: if $\mathbf{lfill}\left[b-1\right]\ge 0$ its value is the maximum level of fill allowed in the decomposition of the block $b$ (see Section 9.2 in f11dnc). A negative value of $\mathbf{lfill}\left[b-1\right]$ indicates that $\mathbf{dtol}\left[b-1\right]$ will be used to control the fill in block $b$ instead.

12: $\mathbf{dtol}\left[\mathbf{nb}\right]$ – const double Input

On entry: if $\mathbf{lfill}\left[b-1\right]<0$ then $\mathbf{dtol}\left[b-1\right]$ is used as a drop tolerance in block $b$ to control the fill-in (see Section 9.2 in f11dnc); otherwise $\mathbf{dtol}\left[b-1\right]$ is not referenced.

Constraint: if $\mathbf{lfill}\left[b-1\right]<0$, $\mathbf{dtol}\left[\mathit{b}-1\right]\ge 0.0$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

13: $\mathbf{pstrat}\left[\mathbf{nb}\right]$ – const Nag_SparseNsym_Piv Input

On entry: $\mathbf{pstrat}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$, specifies the pivoting strategy to be adopted in the block as follows:

$\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_NoPiv}$

No pivoting is carried out.

$\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_UserPiv}$

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

$\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_PartialPiv}$

Partial pivoting by columns for stability is carried out.

$\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_CompletePiv}$

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

Suggested value: $\mathbf{pstrat}\left[\mathit{b}-1\right]=\mathrm{Nag\_SparseNsym\_CompletePiv}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

Constraint: $\mathbf{pstrat}\left[\mathit{b}-1\right]=\mathrm{Nag\_SparseNsym\_NoPiv}$, $\mathrm{Nag\_SparseNsym\_UserPiv}$, $\mathrm{Nag\_SparseNsym\_PartialPiv}$ or $\mathrm{Nag\_SparseNsym\_CompletePiv}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

14: $\mathbf{milu}\left[\mathbf{nb}\right]$ – const Nag_SparseNsym_Fact Input

On entry: $\mathbf{milu}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$, indicates whether or not the factorization in block $\mathit{b}$ should be modified to preserve row-sums (see Section 9.4 in f11dnc).

$\mathbf{milu}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_ModFact}$

The factorization is modified.

$\mathbf{milu}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_UnModFact}$

The factorization is not modified.

Constraint: $\mathbf{milu}\left[\mathit{b}-1\right]=\mathrm{Nag\_SparseNsym\_ModFact}$ or $\mathrm{Nag\_SparseNsym\_UnModFact}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

15: $\mathbf{ipivp}\left[\mathbf{lindb}\right]$ – Integer Input/Output

16: $\mathbf{ipivq}\left[\mathbf{lindb}\right]$ – Integer Input/Output

On entry: if $\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_UserPiv}$, $\mathbf{ipivp}\left[\mathbf{istb}\left[b-1\right]+k-2\right]$ and $\mathbf{ipivq}\left[\mathbf{istb}\left[b-1\right]+k-2\right]$ must specify the row and column indices of the element used as a pivot at elimination stage $k$ of the factorization of the block. Otherwise ipivp and ipivq need not be initialized.

Constraint: if $\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_UserPiv}$, the elements $\mathbf{istb}\left[b-1\right]-1$ to $\mathbf{istb}\left[b\right]-2$ of ipivp and ipivq must both hold valid permutations of the integers on $[1,\mathbf{istb}\left[b\right]-\mathbf{istb}\left[b-1\right]]$.

On exit: the row and column indices of the pivot elements, arranged consecutively for each block, as for indb. If $\mathbf{ipivp}\left[\mathbf{istb}\left[b-1\right]+k-2\right]=i$ and $\mathbf{ipivq}\left[\mathbf{istb}\left[b-1\right]+k-2\right]=j$, the element in row $i$ and column $j$ of $A_b$ was used as the pivot at elimination stage $k$.

17: $\mathbf{istr}\left[\mathbf{lindb}+1\right]$ – Integer Output

On exit: $\mathbf{istr}\left[\mathbf{istb}\left[\mathit{b}-1\right]+\mathit{k}-2\right]$, gives the index in the arrays a, irow and icol of row $\mathit{k}$ of the matrix $C_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$ and $\mathit{k}=1,2,\dots ,\mathbf{istb}\left[\mathit{b}\right]-\mathbf{istb}\left[\mathit{b}-1\right]$.

$\mathbf{istr}\left[\mathbf{istb}\left[\mathbf{nb}\right]-1\right]$ contains $\mathbf{nnz}+\mathbf{nnzc}+1$.

18: $\mathbf{idiag}\left[\mathbf{lindb}\right]$ – Integer Output

On exit: $\mathbf{idiag}\left[\mathbf{istb}\left[\mathit{b}-1\right]+\mathit{k}-2\right]$, gives the index in the arrays a, irow and icol of the diagonal element in row $\mathit{k}$ of the matrix $C_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$ and $\mathit{k}=1,2,\dots ,\mathbf{istb}\left[\mathit{b}\right]-\mathbf{istb}\left[\mathit{b}-1\right]$.

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

On exit: the sum total number of nonzero elements in the matrices $C_{\mathit{b}}$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

20: $\mathbf{npivm}\left[\mathbf{nb}\right]$ – Integer Output

On exit: if $\mathbf{npivm}\left[b-1\right]>0$ it gives the number of pivots which were modified during the factorization to ensure that $M_b$ exists.

If $\mathbf{npivm}\left[\mathit{b}-1\right]=-1$ no pivot modifications were required, but a local restart occurred (see Section 9.3 in f11dnc). The quality of the preconditioner will generally depend on the returned values of $\mathbf{npivm}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

If $\mathbf{npivm}\left[b-1\right]$ is large, for some $b$, the preconditioner may not be satisfactory. In this case it may be advantageous to call f11dtc again with an increased value of $\mathbf{lfill}\left[b-1\right]$, a reduced value of $\mathbf{dtol}\left[b-1\right]$, or $\mathbf{pstrat}\left[b-1\right]=\mathrm{Nag\_SparseNsym\_CompletePiv}$.

21: $\mathbf{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 $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

On entry, $\mathbf{istb}\left[0\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{istb}\left[0\right]\ge 1$.

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{nb}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le \mathbf{nb}\le \mathbf{n}$.

On entry, $\mathbf{nnz}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nnz}\le {\mathbf{n}}^2$.

NE_INT_3

On entry, $\mathbf{lindb}=⟨\mathit{\text{value}}⟩$, $\mathbf{istb}\left[\mathbf{nb}\right]-1=⟨\mathit{\text{value}}⟩$ and $\mathbf{nb}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lindb}\ge \mathbf{istb}\left[\mathbf{nb}\right]-1$.

NE_INT_ARRAY

On entry, $\mathbf{indb}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le \mathbf{indb}\left[m-1\right]\le \mathbf{n}$, for $m=\mathbf{istb}\left[0\right],\mathbf{istb}\left[0\right]+1,\dots ,\mathbf{istb}\left[\mathbf{nb}\right]-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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.

NE_INVALID_CS

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

On entry, $\mathbf{irow}\left[⟨\mathit{\text{value}}⟩\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, the user-supplied value of ipivp for block $⟨\mathit{\text{value}}⟩$ lies outside its range.

On entry, the user-supplied value of ipivp for block $⟨\mathit{\text{value}}⟩$ was repeated.

On entry, the user-supplied value of ipivq for block $⟨\mathit{\text{value}}⟩$ lies outside its range.

On entry, the user-supplied value of ipivq for block $⟨\mathit{\text{value}}⟩$ was repeated.

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, element $⟨\mathit{\text{value}}⟩$ of a was out of order.

On entry, for $b=⟨\mathit{\text{value}}⟩$, $\mathbf{istb}\left[b\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{istb}\left[b-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{istb}\left[\mathit{b}\right]>\mathbf{istb}\left[\mathit{b}-1\right]$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

On entry, location $⟨\mathit{\text{value}}⟩$ of $(\mathbf{irow},\mathbf{icol})$ was a duplicate.

NE_REAL_ARRAY

On entry, $\mathbf{dtol}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{dtol}\left[\mathit{b}-1\right]\ge 0.0$, for $\mathit{b}=1,2,\dots ,\mathbf{nb}$.

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

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results