NAG Library Function Document

nag_sparse_sym_sol (f11jec)

1  Purpose

2  Specification

3  Description

• no preconditioning;
• Jacobi preconditioning (see Young (1971);
• symmetric successive-over-relaxation (SSOR) preconditioning (see Young (1971)).

4  References

5  Arguments

1:    $\mathbf{method}$ – Nag_SparseSym_MethodInput

On entry: specifies the iterative method to be used.

$\mathbf{method}=\mathrm{Nag\_SparseSym\_CG}$

The conjugate gradient method is used.

$\mathbf{method}=\mathrm{Nag\_SparseSym\_Lanczos}$

The Lanczos method (SYMMLQ) is used.

Constraint: $\mathbf{method}=\mathrm{Nag\_SparseSym\_CG}$ or $\mathrm{Nag\_SparseSym\_Lanczos}$.

2:    $\mathbf{precon}$ – Nag_SparseSym_PrecTypeInput

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

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

No preconditioning is used.

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

Symmetric successive-over-relaxation is used.

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

Jacobi preconditioning is used.

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

3:    $\mathbf{n}$ – IntegerInput

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

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

4:    $\mathbf{nnz}$ – IntegerInput

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

Constraint: $1\le \mathbf{nnz}\le \mathbf{n}\times \left(\mathbf{n}+1\right)/2$.

5:    $\mathbf{a}\left[\mathbf{nnz}\right]$ – const doubleInput

On entry: the nonzero elements of the lower triangular part 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_sym_sort (f11zbc) may be used to order the elements in this way.

6:    $\mathbf{irow}\left[\mathbf{nnz}\right]$ – const IntegerInput

7:    $\mathbf{icol}\left[\mathbf{nnz}\right]$ – 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_sym_sort (f11zbc)):;
• $1\le \mathbf{irow}\left[\mathit{i}\right]\le \mathbf{n}$ and $1\le \mathbf{icol}\left[\mathit{i}\right]\le \mathbf{irow}\left[\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$;
• $\mathbf{irow}\left[\mathit{i}-1\right]<\mathbf{irow}\left[\mathit{i}\right]$ or $\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:    $\mathbf{omega}$ – doubleInput

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

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

9:    $\mathbf{b}\left[\mathbf{n}\right]$ – const doubleInput

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

10:  $\mathbf{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 },\sqrt{\mathbf{n}},\epsilon \right)$ is used, where $\epsilon$ is the machine precision. Otherwise $\tau =\max \left(\mathbf{tol},10\epsilon ,\sqrt{\mathbf{n}},\epsilon \right)$ is used.

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

11:  $\mathbf{maxitn}$ – IntegerInput

On entry: the maximum number of iterations allowed.

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

12:  $\mathbf{x}\left[\mathbf{n}\right]$ – doubleInput/Output

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

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

13:  $\mathbf{rnorm}$ – double *Output

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

14:  $\mathbf{itn}$ – Integer *Output

On exit: the number of iterations carried out.

15:  $\mathbf{comm}$ – Nag_Sparse_Comm *Input/Output

On entry/exit: a pointer to a structure of type Nag_Sparse_Comm whose members are used by the iterative solver.

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

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

6  Error Indicators and Warnings

NE_ACC_LIMIT

The required accuracy could not be obtained. However, a reasonable accuracy has been obtained and further iterations cannot improve the result.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument method had an illegal value.

On entry, argument precon had an illegal value.

NE_COEFF_NOT_POS_DEF

The matrix of coefficients appears not to be positive definite (conjugate gradient method only).

NE_INT_2

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{nnz}\le \mathbf{n}\times \left(\mathbf{n}+1\right)/2$.

NE_INT_ARG_LT

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

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

The required accuracy has not been obtained in maxitn iterations.

NE_PRECOND_NOT_POS_DEF

The preconditioner appears not to be positive definite.

NE_REAL

On entry, $\mathbf{omega}=〈\mathit{\text{value}}〉$.
Constraint: $0.0\le \mathbf{omega}\le 2.0$.

NE_REAL_ARG_GE

On entry, tol must not be greater than or equal to 1.0: $\mathbf{tol}=〈\mathit{\text{value}}〉$.

NE_SYMM_MATRIX_DUP

A nonzero element has been supplied which does not lie in the lower triangular part of the matrix $A$, is out of order, or has duplicate row and column indices, i.e., one or more of the following constraints has been violated:

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

Call nag_sparse_sym_sort (f11zbc) to reorder and sum or remove duplicates.

NE_ZERO_DIAGONAL_ELEM

The matrix $A$ has a zero diagonal element. Jacobi and SSOR preconditioners are not appropriate for this problem.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f11jece.c)

10.2  Program Data

Program Data (f11jece.d)

10.3  Program Results

Program Results (f11jece.r)