NAG Library Function Document

nag_sparse_nherm_sol (f11dsc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     method – Nag_SparseNsym_MethodInput

On entry: specifies the iterative method to be used.

$\mathbf{method}=\mathrm{Nag\_SparseNsym\_RGMRES}$

Restarted generalized minimum residual method.

$\mathbf{method}=\mathrm{Nag\_SparseNsym\_CGS}$

Conjugate gradient squared method.

$\mathbf{method}=\mathrm{Nag\_SparseNsym\_BiCGSTAB}$

Bi-conjugate gradient stabilized ($\ell$) method.

$\mathbf{method}=\mathrm{Nag\_SparseNsym\_TFQMR}$

Transpose-free quasi-minimal residual method.

Constraint: $\mathbf{method}=\mathrm{Nag\_SparseNsym\_RGMRES}$, $\mathrm{Nag\_SparseNsym\_CGS}$, $\mathrm{Nag\_SparseNsym\_BiCGSTAB}$ or $\mathrm{Nag\_SparseNsym\_TFQMR}$.

2:     precon – Nag_SparseNsym_PrecTypeInput

On entry: specifies the type of preconditioning to be used.

$\mathbf{precon}=\mathrm{Nag\_SparseNsym\_NoPrec}$

No preconditioning.

$\mathbf{precon}=\mathrm{Nag\_SparseNsym\_JacPrec}$

Jacobi.

$\mathbf{precon}=\mathrm{Nag\_SparseNsym\_SSORPrec}$

Symmetric successive-over-relaxation (SSOR).

Constraint: $\mathbf{precon}=\mathrm{Nag\_SparseNsym\_NoPrec}$, $\mathrm{Nag\_SparseNsym\_JacPrec}$ or $\mathrm{Nag\_SparseNsym\_SSORPrec}$.

3:     n – IntegerInput

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

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

4:     nnz – IntegerInput

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

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

5:     a[nnz] – const ComplexInput

On entry: the nonzero elements of 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.

6:     irow[nnz] – const IntegerInput

7:     icol[nnz] – const IntegerInput

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

Constraints:

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

• $1\le \mathbf{irow}\left[\mathit{i}\right]\le \mathbf{n}$ and $1\le \mathbf{icol}\left[\mathit{i}\right]\le \mathbf{n}$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$;
• 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}-1$.

8:     omega – doubleInput

On entry: if $\mathbf{precon}=\mathrm{Nag\_SparseNsym\_SSORPrec}$, omega is the relaxation argument $\omega$ to be used in the SSOR method. Otherwise omega need not be initialized and is not referenced.

Constraint: $0.0<\mathbf{omega}<2.0$.

9:     b[n] – const ComplexInput

On entry: the right-hand side vector $b$.

10:   m – IntegerInput

On entry: if $\mathbf{method}=\mathrm{Nag\_SparseNsym\_RGMRES}$, m is the dimension of the restart subspace.

If $\mathbf{method}=\mathrm{Nag\_SparseNsym\_BiCGSTAB}$, m is the order $\ell$ of the polynomial Bi-CGSTAB method.

Otherwise, m is not referenced.

Constraints:

• if $\mathbf{method}=\mathrm{Nag\_SparseNsym\_RGMRES}$, $0<\mathbf{m}\le \min \left(\mathbf{n},50\right)$;
• if $\mathbf{method}=\mathrm{Nag\_SparseNsym\_BiCGSTAB}$, $0<\mathbf{m}\le \min \left(\mathbf{n},10\right)$.

11:   tol – doubleInput

On entry: the required tolerance. Let $x_k$ denote the approximate solution at iteration $k$, and $r_k$ the corresponding residual. The algorithm is considered to have converged at iteration $k$ if

$${‖r_k‖}_{\infty }\le \tau \times \left({‖b‖}_{\infty }+{‖A‖}_{\infty }{‖x_k‖}_{\infty }\right)\text{.}$$

If $\mathbf{tol}\le 0.0$, $\tau =\max \left(\sqrt{\epsilon },10\epsilon ,\sqrt{n}\epsilon \right)$ is used, where $\epsilon$ is the machine precision. Otherwise $\tau =\max \left(\mathbf{tol},10\epsilon ,\sqrt{n}\epsilon \right)$ is used.

Constraint: $\mathbf{tol}<1.0$.

12:   maxitn – IntegerInput

On entry: the maximum number of iterations allowed.

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

13:   x[n] – ComplexInput/Output

On entry: an initial approximation to the solution vector $x$.

On exit: an improved approximation to the solution vector $x$.

14:   rnorm – double *Output

On exit: the final value of the residual norm ${‖r_k‖}_{\infty }$, where $k$ is the output value of itn.

15:   itn – Integer *Output

On exit: the number of iterations carried out.

16:   fail – NagError *Input/Output

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

6  Error Indicators and Warnings

NE_ACCURACY

The required accuracy could not be obtained. However a reasonable accuracy may have been achieved.

NE_ALG_FAIL

Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_CONVERGENCE

The solution has not converged after $⟨\mathit{\text{value}}⟩$ iterations.

NE_ENUM_INT_2

On entry, $\mathbf{m}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $0<\mathbf{m}\le \min \left(\mathbf{n},⟨\mathit{\text{value}}⟩\right)$.

On entry, $\mathbf{method}=⟨\mathit{\text{value}}⟩$, $\mathbf{n}=⟨\mathit{\text{value}}⟩$ and $\mathbf{m}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{method}=\mathrm{Nag\_SparseNsym\_BiCGSTAB}$, $0<\mathbf{m}\le \min \left(\mathbf{n},10\right)$.

On entry, $\mathbf{method}=⟨\mathit{\text{value}}⟩$, $\mathbf{n}=⟨\mathit{\text{value}}⟩$ and $\mathbf{m}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{method}=\mathrm{Nag\_SparseNsym\_RGMRES}$, $0<\mathbf{m}\le \min \left(\mathbf{n},50\right)$.

NE_INT

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

NE_INVALID_CS

On entry, $i=⟨\mathit{\text{value}}⟩$, $\mathbf{icol}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{icol}\left[i-1\right]\ge 1$ and $\mathbf{icol}\left[i-1\right]\le \mathbf{n}$.

On entry, $i=⟨\mathit{\text{value}}⟩$, $\mathbf{irow}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{irow}\left[i-1\right]\ge 1$ and $\mathbf{irow}\left[i-1\right]\le \mathbf{n}$.

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{omega}=⟨\mathit{\text{value}}⟩$.
Constraint: $0.0<\mathbf{omega}<2.0$ 

On entry, $\mathbf{tol}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{tol}<1.0$.

NE_ZERO_DIAG_ELEM

The matrix $A$ has a zero diagonal entry in row $⟨\mathit{\text{value}}⟩$.

The matrix $A$ has no diagonal entry in row $⟨\mathit{\text{value}}⟩$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f11dsce.c)

10.2  Program Data

Program Data (f11dsce.d)

10.3  Program Results

Program Results (f11dsce.r)