NAG C Library Function Document

nag_sparse_sym_chol_sol (f11jcc)

1

Purpose

2

Specification

3

Description

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{n}$ – IntegerInput

On entry: the order of the matrix $A$. This must be the same value as was supplied in the preceding call to nag_sparse_sym_chol_fac (f11jac).

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

3:    $\mathbf{nnz}$ – IntegerInput

On entry: the number of nonzero elements in the lower triangular part of the matrix $A$. This must be the same value as was supplied in the preceding call to nag_sparse_sym_chol_fac (f11jac).

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

4:    $\mathbf{a}\left[\mathbf{la}\right]$ – const doubleInput

On entry: the values returned in array a by a previous call to nag_sparse_sym_chol_fac (f11jac).

5:    $\mathbf{la}$ – IntegerInput

On entry: the second dimension of the arrays a, irow and icol.This must be the same value as returned by a previous call to nag_sparse_sym_chol_fac (f11jac).

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

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

7:    $\mathbf{icol}\left[\mathbf{la}\right]$ – const IntegerInput

8:    $\mathbf{ipiv}\left[\mathbf{n}\right]$ – const IntegerInput

9:    $\mathbf{istr}\left[\mathbf{n}+1\right]$ – const IntegerInput

On entry: the values returned in the arrays irow, icol, ipiv and istr by a previous call to nag_sparse_sym_chol_fac (f11jac).

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

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

11:  $\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$.

12:  $\mathbf{maxitn}$ – IntegerInput

On entry: the maximum number of iterations allowed.

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

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

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

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

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

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

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

On exit: the number of iterations carried out.

16:  $\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.

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_2_INT_ARG_LT

On entry, $\mathbf{la}=〈\mathit{\text{value}}〉$ while $\mathbf{nnz}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{la}\ge 2\times \mathbf{nnz}$.

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.

NE_COEFF_NOT_POS_DEF

The matrix of coefficients appears not to be positive definite.

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_INVALID_SCS

The SCS representation of the matrix $A$ is invalid. Check that the call to nag_sparse_sym_chol_sol (f11jcc) has been preceded by a valid call to nag_sparse_sym_chol_fac (f11jac), and that the arrays a, irow and icol have not been corrupted between the two calls.

NE_INVALID_SCS_PRECOND

The SCS representation of the preconditioning matrix $M$ is invalid. Check that the call to nag_sparse_sym_chol_sol (f11jcc) has been preceded by a valid call to nag_sparse_sym_chol_fac (f11jac), and that the arrays a, irow, icol, ipiv and istr have not been corrupted between the two calls.

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_ARG_GE

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

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (f11jcce.c)

10.2

Program Data

Program Data (f11jcce.d)

10.3

Program Results

Program Results (f11jcce.r)