NAG Library Function Document

nag_sparse_herm_chol_sol (f11jqc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     method – Nag_SparseSym_MethodInput

On entry: specifies the iterative method to be used.

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

Conjugate gradient method.

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

Lanczos method (SYMMLQ).

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

2:     n – IntegerInput

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

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

3:     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_herm_chol_fac (f11jnc).

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

4:     a[la] – const ComplexInput

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

5:     la – IntegerInput

On entry: the dimension of the arrays a, irow and icol. This must be the same value as was supplied in the preceding call to nag_sparse_herm_chol_fac (f11jnc).

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

6:     irow[la] – const IntegerInput

7:     icol[la] – const IntegerInput

8:     ipiv[n] – const IntegerInput

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

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

10:   b[n] – const ComplexInput

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

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 has been achieved.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

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

NE_COEFF_NOT_POS_DEF

The matrix of the coefficients a appears not to be positive definite. The computation cannot continue.

NE_CONVERGENCE

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

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{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}\times \left(\mathbf{n}+1\right)/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.

A serious error, code $⟨\mathit{\text{value}}⟩$, has occurred in an internal call to nag_sparse_herm_basic_solver (f11gsc). Check all function calls and array sizes. Seek expert help.

A serious error, code $⟨\mathit{\text{value}}⟩$, has occurred in an internal call to $⟨\mathit{\text{value}}⟩$. Check all function calls and array sizes. Seek expert help.

NE_INVALID_SCS

On entry, $i=⟨\mathit{\text{value}}⟩$, $\mathbf{icol}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, $\mathbf{irow}\left[i-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{icol}\left[i-1\right]\ge 1$ and $\mathbf{icol}\left[i-1\right]\le \mathbf{irow}\left[i-1\right]$.
Check that a, irow, icol, ipiv and istr have not been corrupted between calls to nag_sparse_herm_chol_fac (f11jnc) and nag_sparse_herm_chol_sol (f11jqc).

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}$.
Check that a, irow, icol, ipiv and istr have not been corrupted between calls to nag_sparse_herm_chol_fac (f11jnc) and nag_sparse_herm_chol_sol (f11jqc).

NE_INVALID_SCS_PRECOND

The SCS representation of the preconditioner is invalid. Check that a, irow, icol, ipiv and istr have not been corrupted between calls to nag_sparse_herm_chol_fac (f11jnc) and nag_sparse_herm_chol_sol (f11jqc).

NE_NOT_STRICTLY_INCREASING

On entry, $\mathbf{a}\left[i-1\right]$ is out of order: $i=⟨\mathit{\text{value}}⟩$. Check that a, irow, icol, ipiv and istr have not been corrupted between calls to nag_sparse_herm_chol_fac (f11jnc) and nag_sparse_herm_chol_sol (f11jqc).

On entry, the location ($\mathbf{irow}\left[i-1\right],\mathbf{icol}\left[i-1\right]$) is a duplicate: $i=⟨\mathit{\text{value}}⟩$. Check that a, irow, icol, ipiv and istr have not been corrupted between calls to nag_sparse_herm_chol_fac (f11jnc) and nag_sparse_herm_chol_sol (f11jqc).

NE_PRECOND_NOT_POS_DEF

The preconditioner appears not to be positive definite. The computation cannot continue.

NE_REAL

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

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f11jqce.c)

10.2  Program Data

Program Data (f11jqce.d)

10.3  Program Results

Program Results (f11jqce.r)