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

naginterfaces.library.sparse.real_gen_precon_ssor_solve(trans, a, irow, icol, rdiag, omega, y, check='N')

real_gen_precon_ssor_solve solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a real sparse nonsymmetric matrix, represented in coordinate storage format.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11ddf.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{nnz}\right)$

The nonzero elements in the matrix $A$, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function real_gen_sort() may be used to order the elements in this way.

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

The row indices of the nonzero elements supplied in array $a$.

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

The column indices of the nonzero elements supplied in array $a$.

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

The elements of the diagonal matrix $D^{-1}$, where $D$ is the diagonal part of $A$.

omegafloat

The relaxation parameter $\omega$.

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}$, $\text{nnz}$, $irow$, $icol$ and $omega$.

$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, $check=⟨value⟩$.

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

(errno $1$)

On entry, $trans=⟨value⟩$.

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

(errno $2$)

On entry, $omega=⟨value⟩$.

Constraint: $0.0<omega<2.0$.

(errno $2$)

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

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

(errno $2$)

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

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

(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, $i=⟨value⟩$, $irow[i-1]=⟨value⟩$ and $n=⟨value⟩$.

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

(errno $4$)

The matrix $A$ has no diagonal entry in row $⟨value⟩$.

Notes

real_gen_precon_ssor_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=\frac{1}{\omega (2-\omega )}(D+\omega L)D^{-1}(D+\omega U)$$

corresponds to symmetric successive-over-relaxation (SSOR) (see Young (1971)) applied to a linear system $Ax=b$, where $A$ is a real sparse nonsymmetric matrix stored in coordinate storage (CS) format (see the F11 Introduction).

In the definition of $M$ given above $D$ is the diagonal part of $A$, $L$ is the strictly lower triangular part of $A$, $U$ is the strictly upper triangular part of $A$, and $\omega$ is a user-defined relaxation parameter.

It is envisaged that a common use of real_gen_precon_ssor_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_ssor_solve is also used for this purpose by the Black Box function real_gen_solve_jacssor().

References

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