naginterfaces.library.sparse.real_​gen_​precon_​ilu_​solve

naginterfaces.library.sparse.real_gen_precon_ilu_solve(trans, a, irow, icol, ipivp, ipivq, istr, idiag, y, check='N')

real_gen_precon_ilu_solve solves a system of linear equations involving the incomplete $LU$ preconditioning matrix generated by real_gen_precon_ilu().

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11dbf.html

Parameters

transstr, length 1

Specifies whether or not the matrix $M$ is transposed.

$trans=\text{'N'}$

$Mx=y$ is solved.

$trans=\text{'T'}$

$M^{T}x=y$ is solved.

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

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

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

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_ilu().

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

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_ilu().

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

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_ilu().

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

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_ilu().

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

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_ilu().

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

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_ilu().

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

The right-hand side vector $y$.

checkstr, length 1, optional

Specifies whether or not the CS representation of the matrix $M$ should be checked.

$check=\text{'C'}$

Checks are carried on the values of $\text{n}$, $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$.

$check=\text{'N'}$

None of these 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, $trans=⟨value⟩$.

Constraint: $trans=\text{'N'}$ or $\text{'T'}$.

(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, $ipivq[i-1]$ is a repeated value: $i=⟨value⟩$.

(errno $3$)

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

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

(errno $3$)

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

(errno $3$)

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

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

(errno $3$)

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

(errno $3$)

On entry, $idiag[i-1]$ appears to be incorrect: $i=⟨value⟩$.

(errno $3$)

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

(errno $3$)

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

(errno $3$)

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

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

(errno $3$)

On entry, $i=⟨value⟩$, $irow[i-1]=⟨value⟩$, $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_gen_precon_ilu_solve solves a system of linear equations

$$\begin{array}{ccc}Mx=y\text{,}& \text{or}& M^{T}x=y\text{,}\end{array}$$

according to the value of the argument $trans$, where the matrix $M=PLDUQ$, corresponds to an incomplete $LU$ decomposition of a sparse matrix stored in coordinate storage (CS) format (see the F11 Introduction), as generated by real_gen_precon_ilu().

In the above decomposition $L$ is a lower triangular sparse matrix with unit diagonal elements, $D$ is a diagonal matrix, $U$ is an upper triangular sparse matrix with unit diagonal elements and, $P$ and $Q$ are permutation matrices. $L$, $D$ and $U$ are supplied to real_gen_precon_ilu_solve through the matrix

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

which is an $\text{n}$ by $\text{n}$ sparse matrix, stored in CS format, as returned by real_gen_precon_ilu(). The permutation matrices $P$ and $Q$ are returned from real_gen_precon_ilu() via the arrays $ipivp$ and $ipivq$.

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

real_gen_precon_ilu_solve may also be used in combination with real_gen_precon_ilu() to solve a sparse system of linear equations directly (see Further Comments).

See also

naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main()