naginterfaces.library.sparse.real_​symm_​solve_​ichol

naginterfaces.library.sparse.real_symm_solve_ichol(method, nnz, a, irow, icol, ipiv, istr, b, tol, maxitn, x)

real_symm_solve_ichol solves a real sparse symmetric system of linear equations, represented in symmetric coordinate storage format, using a conjugate gradient or Lanczos method, with incomplete Cholesky preconditioning.

For full information please refer to the NAG Library document for f11jc

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f11/f11jcf.html

Parameters

methodstr

Specifies the iterative method to be used.

$method=\text{'CG'}$

Conjugate gradient method.

$method=\text{'SYMMLQ'}$

Lanczos method (SYMMLQ).

nnzint

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 real_symm_precon_ichol().

afloat, array-like, shape $\left(\text{la}\right)$

The values returned in the array $a$ by a previous call to real_symm_precon_ichol().

irowint, array-like, shape $\left(\text{la}\right)$

The values returned in arrays $irow$, $icol$, $ipiv$ and $istr$ by a previous call to real_symm_precon_ichol().

icolint, array-like, shape $\left(\text{la}\right)$

The values returned in arrays $irow$, $icol$, $ipiv$ and $istr$ by a previous call to real_symm_precon_ichol().

ipivint, array-like, shape $\left(n\right)$

The values returned in arrays $irow$, $icol$, $ipiv$ and $istr$ by a previous call to real_symm_precon_ichol().

istrint, array-like, shape $(n+1)$

The values returned in arrays $irow$, $icol$, $ipiv$ and $istr$ by a previous call to real_symm_precon_ichol().

bfloat, array-like, shape $\left(n\right)$

The right-hand side vector $b$.

tolfloat

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

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

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

maxitnint

The maximum number of iterations allowed.

xfloat, array-like, shape $\left(n\right)$

An initial approximation to the solution vector $x$.

Returns

xfloat, ndarray, shape $\left(n\right)$

An improved approximation to the solution vector $x$.

rnormfloat

The final value of the residual norm ${\parallel r_k\parallel }_{\infty }$, where $k$ is the output value of $itn$.

itnint

The number of iterations carried out.

Raises

NagValueError

(errno $1$)

On entry, $maxitn=⟨value⟩$.

Constraint: $maxitn\ge 1$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol<1.0$.

(errno $1$)

On entry, $method=⟨value⟩$.

Constraint: $method=\text{'CG'}$ or $\text{'SYMMLQ'}$.

(errno $1$)

On entry, $\text{la}=⟨value⟩$ and $nnz=⟨value⟩$.

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

(errno $1$)

On entry, $nnz=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $nnz\le n\times (n+1)/2$.

(errno $1$)

On entry, $nnz=⟨value⟩$.

Constraint: $nnz\ge 1$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $2$)

On entry, the location ($irow[i-1],icol[i-1]$) is a duplicate: $i=⟨value⟩$.

(errno $2$)

On entry, $a[i-1]$ is out of order: $i=⟨value⟩$.

(errno $2$)

On entry, $i=⟨value⟩$, $icol[i-1]=⟨value⟩$, $irow[i-1]=⟨value⟩$.

Constraint: $icol[i-1]\ge 1$ and $icol[i-1]\le irow[i-1]$.

(errno $2$)

On entry, $i=⟨value⟩$, $irow[i-1]=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $irow[i-1]\ge 1$ and $irow[i-1]\le n$.

(errno $3$)

The SCS representation of the preconditioner is invalid.

(errno $5$)

The solution has not converged after $⟨value⟩$ iterations.

(errno $6$)

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

(errno $7$)

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

(errno $8$)

A serious error has occurred in an internal call: $IREVCM=⟨value⟩$. Check all function calls and array sizes. Seek expert help.

(errno $8$)

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

Warns

NagAlgorithmicWarning

(errno $4$)

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

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_symm_solve_ichol solves a real sparse symmetric linear system of equations

$$Ax=b\text{,}$$

using a preconditioned conjugate gradient method (see Meijerink and Van der Vorst (1977)), or a preconditioned Lanczos method based on the algorithm SYMMLQ (see Paige and Saunders (1975)). The conjugate gradient method is more efficient if $A$ is positive definite, but may fail to converge for indefinite matrices. In this case the Lanczos method should be used instead. For further details see Barrett et al. (1994).

real_symm_solve_ichol uses the incomplete Cholesky factorization determined by real_symm_precon_ichol() as the preconditioning matrix. A call to real_symm_solve_ichol must always be preceded by a call to real_symm_precon_ichol(). Alternative preconditioners for the same storage scheme are available by calling real_symm_solve_jacssor().

The matrix $A$, and the preconditioning matrix $M$, are represented in symmetric coordinate storage (SCS) format (see the F11 Introduction) in the arrays $a$, $irow$ and $icol$, as returned from real_symm_precon_ichol(). The array $a$ holds the nonzero entries in the lower triangular parts of these matrices, while $irow$ and $icol$ hold the corresponding row and column indices.

References

Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148–162

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617–629

Salvini, S A and Shaw, G J, 1995, An evaluation of new NAG Library solvers for large sparse symmetric linear systems, NAG Technical Report TR1/95