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

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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11dxf.html

Parameters

storestr, length 1

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

$store=\text{'N'}$

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

$store=\text{'S'}$

The lower triangle of the Hermitian 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^{H}x=b$ is required.

$trans=\text{'N'}$

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

$trans=\text{'T'}$

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

Suggested value: if the matrix $A$ is Hermitian 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.

acomplex, 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 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 $\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$.

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

The right-hand side vector $b$.

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

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

The approximate solution vector $x_{niter}$.

diagcomplex, 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\ne \text{'N'}$ or $\text{'C'}$: $check=⟨value⟩$.

(errno $1$)

On entry, $init\ne \text{'N'}$ or $\text{'I'}$: $init=⟨value⟩$.

(errno $1$)

On entry, $trans\ne \text{'N'}$ or $\text{'T'}$: $trans=⟨value⟩$.

(errno $1$)

On entry, $store\ne \text{'N'}$ or $\text{'S'}$: $store=⟨value⟩$.

(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, $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, $\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

complex_gen_precon_jacobi computes the approximate solution of the complex 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$.

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