naginterfaces.library.sparse.real_​gen_​precon_​jacobi

naginterfaces.library.sparse.real_gen_precon_jacobi(store, trans, init, niter, a, irow, icol, b, diag, check='N')

real_gen_precon_jacobi computes the approximate solution of a real, symmetric or nonsymmetric, sparse system of linear equations applying a number of Jacobi iterations. It is expected that real_gen_precon_jacobi will be used as a preconditioner for the iterative solution of real sparse systems of equations.

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

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

Parameters

storestr, length 1

Specifies whether the matrix $A$ is stored using symmetric coordinate storage (SCS) (applicable only to a symmetric matrix $A$) or coordinate storage (CS) (applicable to both symmetric and non-symmetric matrices).

$store=\text{'N'}$

The complete matrix $A$ is stored in CS format.

$store=\text{'S'}$

The lower triangle of the symmetric matrix $A$ is stored in SCS format.

transstr, length 1

If $store=\text{'N'}$, specifies whether the approximate solution of $Ax=b$ or of $A^{T}x=b$ is required.

$trans=\text{'N'}$

The approximate solution of $Ax=b$ is calculated.

$trans=\text{'T'}$

The approximate solution of $A^{T}x=b$ is calculated.

Suggested value: if the matrix $A$ is symmetric and stored in CS format, it is recommended that $trans=\text{'N'}$ for reasons of efficiency.

initstr, length 1

On first entry, $init$ should be set to ‘I’, unless the diagonal elements of $A$ are already stored in the array $diag$. If $diag$ already contains the diagonal of $A$, it must be set to ‘N’.

$init=\text{'N'}$

$diag$ must contain the diagonal of $A$.

$init=\text{'I'}$

$diag$ will store the diagonal of $A$ on exit.

Suggested value: $init=\text{'I'}$ on first entry; $init=\text{'N'}$, subsequently, unless $diag$ has been overwritten.

niterint

The number of Jacobi iterations requested.

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

If $store=\text{'N'}$, the nonzero elements in the matrix $A$ (CS format).

If $store=\text{'S'}$, the nonzero elements in the lower triangle of the matrix $A$ (SCS format).

In both cases, the elements of either $A$ or of its lower triangle must be ordered by increasing row index and by increasing column index within each row.

Multiple entries for the same row and columns indices are not permitted.

The function real_gen_sort() or real_symm_sort() may be used to reorder the elements in this way for CS and SCS storage, respectively.

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

If $store=\text{'N'}$, the row indices of the nonzero elements supplied in $a$.

If $store=\text{'S'}$, the row and column indices of the nonzero elements of the lower triangle of the matrix $A$ supplied in $a$.

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

If $store=\text{'N'}$, the column indices of the nonzero elements supplied in $a$.

If $store=\text{'S'}$, the row and column indices of the nonzero elements of the lower triangle of the matrix $A$ supplied in $a$.

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

The right-hand side vector $b$.

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

If $init=\text{'N'}$, the diagonal elements of $A$.

checkstr, length 1, optional

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

$check=\text{'C'}$

Checks are carried out on the values of $\text{n}$, $\text{nnz}$, $irow$, $icol$; if $init=\text{'N'}$, $diag$ is also checked.

$check=\text{'N'}$

None of these checks are carried out.

See also Further Comments.

Returns

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

The approximate solution vector $x_{niter}$.

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

If $init=\text{'N'}$, unchanged on exit.

If $init=\text{'I'}$, the diagonal elements of $A$.

Raises

NagValueError

(errno $1$)

On entry, $niter=⟨value⟩$.

Constraint: $niter\ge 1$.

(errno $1$)

On entry, $check=⟨value⟩$.

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

(errno $1$)

On entry, $init=⟨value⟩$.

Constraint: $init=\text{'N'}$ or $\text{'I'}$.

(errno $1$)

On entry, $trans=⟨value⟩$.

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

(errno $1$)

On entry, $store=⟨value⟩$.

Constraint: $store=\text{'N'}$ or $\text{'S'}$.

(errno $2$)

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

Constraint: $\text{nnz}\le n^2$.

(errno $2$)

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

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

(errno $2$)

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

Constraint: $\text{nnz}\ge 1$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(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 $n=⟨value⟩$.

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

(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, $\text{I}=⟨value⟩$, $irow[\text{I}-1]=⟨value⟩$ and $n=⟨value⟩$.

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

(errno $4$)

On entry, the element $diag[\text{I}-1]$ is zero: $\text{I}=⟨value⟩$.

(errno $5$)

On entry, the diagonal element of the $\text{I}$th row is zero or missing: $\text{I}=⟨value⟩$.

Notes

real_gen_precon_jacobi computes the approximate solution of the real sparse system of linear equations $Ax=b$ using $niter$ iterations of the Jacobi algorithm (see also Golub and Van Loan (1996) and Young (1971)):

$$x_{k+1}=x_k+D^{-1}(b-A{x}_k)$$

where $k=1,2,\dots ,niter$ and $x_0=0$.

real_gen_precon_jacobi can be used both for nonsymmetric and symmetric systems of equations. For symmetric matrices, either all nonzero elements of the matrix $A$ can be supplied using coordinate storage (CS), or only the nonzero elements of the lower triangle of $A$, using symmetric coordinate storage (SCS) (see the F11 Introduction).

It is expected that real_gen_precon_jacobi will be used as a preconditioner for the iterative solution of real sparse systems of equations, using either the suite comprising the functions real_symm_basic_setup(), real_symm_basic_solver() and real_symm_basic_diag(), for symmetric systems, or the suite comprising the functions real_gen_basic_setup(), real_gen_basic_solver() and real_gen_basic_diag(), for nonsymmetric systems of equations.

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York