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

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

complex_gen_precon_jacobi computes the approximate solution of a complex, Hermitian or non-Hermitian, sparse system of linear equations applying a number of Jacobi iterations. It is expected that complex_gen_precon_jacobi will be used as a preconditioner for the iterative solution of complex sparse systems of equations.

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f11/f11dxf.html

Parameters
storestr, length 1

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

The complete matrix is stored in CS format.

The lower triangle of the Hermitian 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 Hermitian 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.

acomplex, 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 complex_gen_sort() or complex_herm_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 .

bcomplex, array-like, shape

The right-hand side vector .

diagcomplex, 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.

See also Further Comments.

Returns
xcomplex, ndarray, shape

The approximate solution vector .

diagcomplex, ndarray, shape

If , unchanged on exit.

If , the diagonal elements of .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, or : .

(errno )

On entry, or : .

(errno )

On entry, or : .

(errno )

On entry, 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

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

where and .

complex_gen_precon_jacobi can be used both for non-Hermitian and Hermitian systems of equations. For Hermitian 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 complex_gen_precon_jacobi will be used as a preconditioner for the iterative solution of complex sparse systems of equations, using either the suite comprising the functions complex_herm_basic_setup(), complex_herm_basic_solver() and complex_herm_basic_diag(), for Hermitian systems, or the suite comprising the functions complex_gen_basic_setup(), complex_gen_basic_solver() and complex_gen_basic_diag(), for non-Hermitian 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