naginterfaces.library.sparse.real_​symm_​precon_​ichol_​solve

naginterfaces.library.sparse.real_symm_precon_ichol_solve(a, irow, icol, ipiv, istr, y, check='N')

real_symm_precon_ichol_solve solves a system of linear equations involving the incomplete Cholesky preconditioning matrix generated by real_symm_precon_ichol().

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

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

Parameters

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

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

The right-hand side vector $y$.

checkstr, length 1, optional

Specifies whether or not the input data should be checked.

$check=\text{'C'}$

Checks are carried out on the values of $\text{n}$, $irow$, $icol$, $ipiv$ and $istr$.

$check=\text{'N'}$

No checks are carried out.

See also Further Comments.

Returns

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

The solution vector $x$.

Raises

NagValueError

(errno $1$)

On entry, $check=⟨value⟩$.

Constraint: $check=\text{'C'}$ or $\text{'N'}$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $3$)

On entry, $ipiv[i-1]$ is a repeated value: $i=⟨value⟩$.

(errno $3$)

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

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

(errno $3$)

On entry, $istr[i-1]$ is inconsistent with $irow$: $i=⟨value⟩$.

(errno $3$)

On entry, the location ($irow[\text{I}-1],icol[\text{I}-1]$) is a duplicate: $\text{I}=⟨value⟩$.

(errno $3$)

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

(errno $3$)

On entry, $\text{I}=⟨value⟩$, $icol[\text{I}-1]=⟨value⟩$ and $irow[\text{I}-1]=⟨value⟩$.

Constraint: $icol[\text{I}-1]\ge 1$ and $icol[\text{I}-1]\le irow[\text{I}-1]$.

(errno $3$)

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$)

On entry, $istr$ appears to be invalid.

Notes

real_symm_precon_ichol_solve solves a system of linear equations

$$Mx=y$$

involving the preconditioning matrix $M=PLD{L}^T{P}^T$, corresponding to an incomplete Cholesky decomposition of a sparse symmetric matrix stored in symmetric coordinate storage (SCS) format (see the F11 Introduction), as generated by real_symm_precon_ichol().

In the above decomposition $L$ is a lower triangular sparse matrix with unit diagonal, $D$ is a diagonal matrix and $P$ is a permutation matrix. $L$ and $D$ are supplied to real_symm_precon_ichol_solve through the matrix

$$C=L+D^{-1}-I$$

which is a lower triangular $\text{n}$ by $\text{n}$ sparse matrix, stored in SCS format, as returned by real_symm_precon_ichol(). The permutation matrix $P$ is returned from real_symm_precon_ichol() via the array $ipiv$.

It is envisaged that a common use of real_symm_precon_ichol_solve will be to carry out the preconditioning step required in the application of real_symm_basic_solver() to sparse symmetric linear systems. real_symm_precon_ichol_solve is used for this purpose by the Black Box function real_symm_solve_ichol().

real_symm_precon_ichol_solve may also be used in combination with real_symm_precon_ichol() to solve a sparse symmetric positive definite system of linear equations directly (see Further Comments).