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')[source]

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://www.nag.com/numeric/nl/nagdoc_28.7/flhtml/f11/f11dkf.html

Parameters
storestr, length 1

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

The complete matrix is stored in CS format.

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

transstr, length 1

If , specifies whether the approximate solution of or of is required.

The approximate solution of is calculated.

The approximate solution of is calculated.

Suggested value: if the matrix is symmetric and stored in CS format, it is recommended that for reasons of efficiency.

initstr, length 1

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

must contain the diagonal of .

will store the diagonal of on exit.

Suggested value: on first entry; , subsequently, unless has been overwritten.

niterint

The number of Jacobi iterations requested.

afloat, array-like, shape

If , the nonzero elements in the matrix (CS format).

If , the nonzero elements in the lower triangle of the matrix (SCS format).

In both cases, the elements of either 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

If , the row indices of the nonzero elements supplied in .

If , the row and column indices of the nonzero elements of the lower triangle of the matrix supplied in .

icolint, array-like, shape

If , the column indices of the nonzero elements supplied in .

If , the row and column indices of the nonzero elements of the lower triangle of the matrix supplied in .

bfloat, array-like, shape

The right-hand side vector .

diagfloat, array-like, shape

If , the diagonal elements of .

checkstr, length 1, optional

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

Checks are carried out on the values of , , , ; if , is also checked.

None of these checks are carried out.

Returns
xfloat, ndarray, shape

The approximate solution vector .

diagfloat, ndarray, shape

If , unchanged on exit.

If , the diagonal elements of .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, the location () is a duplicate: .

(errno )

On entry, is out of order: .

(errno )

On entry, , and .

Constraint: and .

(errno )

On entry, , and .

Constraint: and .

(errno )

On entry, , and .

Constraint: and .

(errno )

On entry, the element is zero: .

(errno )

On entry, the diagonal element of the th row is zero or missing: .

Notes

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

where and .

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 can be supplied using coordinate storage (CS), or only the nonzero elements of the lower triangle of , 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