naginterfaces.library.sparse.complex_​herm_​solve_​jacssor

naginterfaces.library.sparse.complex_herm_solve_jacssor(method, precon, a, irow, icol, omega, b, tol, maxitn, x)

complex_herm_solve_jacssor solves a complex sparse Hermitian system of linear equations, represented in symmetric coordinate storage format, using a conjugate gradient or Lanczos method, without preconditioning, with Jacobi or with SSOR preconditioning.

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

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

Parameters

methodstr

Specifies the iterative method to be used.

$method=\text{'CG'}$

Conjugate gradient method.

$method=\text{'SYMMLQ'}$

Lanczos method (SYMMLQ).

preconstr, length 1

Specifies the type of preconditioning to be used.

$precon=\text{'N'}$

No preconditioning.

$precon=\text{'J'}$

Jacobi.

$precon=\text{'S'}$

Symmetric successive-over-relaxation (SSOR).

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

The nonzero elements of the lower triangular part of 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 complex_herm_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$.

omegafloat

If $precon=\text{'S'}$, $omega$ is the relaxation parameter $\omega$ to be used in the SSOR method. Otherwise $omega$ need not be initialized.

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

The right-hand side vector $b$.

tolfloat

The required tolerance. Let $x_k$ denote the approximate solution at iteration $k$, and $r_k$ the corresponding residual. The algorithm is considered to have converged at iteration $k$ if

$${\parallel r_k\parallel }_{\infty }\le \tau \times ({\parallel b\parallel }_{\infty }+{\parallel A\parallel }_{\infty }{\parallel x_k\parallel }_{\infty })\text{.}$$

If $tol\le 0.0$, $\tau =max\left(\sqrt{ϵ},10ϵ,\sqrt{n}ϵ\right)$ is used, where $ϵ$ is the machine precision. Otherwise $\tau =max(tol,10ϵ,\sqrt{n}ϵ)$ is used.

maxitnint

The maximum number of iterations allowed.

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

An initial approximation to the solution vector $x$.

Returns

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

An improved approximation to the solution vector $x$.

rnormfloat

The final value of the residual norm $\parallel r_k\parallel$, where $k$ is the output value of $itn$.

itnint

The number of iterations carried out.

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

The elements of the diagonal matrix $D^{-1}$, where $D$ is the diagonal part of $A$. Note that since $A$ is Hermitian the elements of $D^{-1}$ are necessarily real.

Raises

NagValueError

(errno $1$)

On entry, $maxitn=⟨value⟩$.

Constraint: $maxitn\ge 1$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol<1.0$.

(errno $1$)

On entry, $method\ne \text{'CG'}$ or $\text{'SYMMLQ'}$: $method=⟨value⟩$.

(errno $1$)

On entry, $omega=⟨value⟩$.

Constraint: $0.0<omega<2.0$.

(errno $1$)

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

(errno $1$)

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

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

(errno $1$)

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

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

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $2$)

On entry, the location ($irow[\text{I}-1],icol[\text{I}-1]$) is a duplicate: $\text{I}=⟨value⟩$.

(errno $2$)

On entry, $a[i-1]$ is out of order: $i=⟨value⟩$.

(errno $2$)

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

On entry, $i=⟨value⟩$, $irow[i-1]=⟨value⟩$ and $n=⟨value⟩$.

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

(errno $3$)

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

(errno $3$)

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

(errno $4$)

The required accuracy could not be obtained. However, a reasonable accuracy has been achieved and further iterations could not improve the result.

(errno $5$)

The solution has not converged after $⟨value⟩$ iterations.

(errno $6$)

The preconditioner appears not to be positive definite. The computation cannot continue.

(errno $7$)

The matrix of the coefficients $a$ appears not to be positive definite. The computation cannot continue.

(errno $8$)

A serious error, code $⟨value⟩$, has occurred in an internal call. Check all function calls and array sizes. Seek expert help.

(errno $9$)

The matrix $A$ has a non-real diagonal entry in row $⟨value⟩$.

Notes

complex_herm_solve_jacssor solves a complex sparse Hermitian linear system of equations

$$Ax=b\text{,}$$

using a preconditioned conjugate gradient method (see Barrett et al. (1994)), or a preconditioned Lanczos method based on the algorithm SYMMLQ (see Paige and Saunders (1975)). The conjugate gradient method is more efficient if $A$ is positive definite, but may fail to converge for indefinite matrices. In this case the Lanczos method should be used instead. For further details see Barrett et al. (1994).

complex_herm_solve_jacssor allows the following choices for the preconditioner:

• no preconditioning;

• Jacobi preconditioning (see Young (1971));

• symmetric successive-over-relaxation (SSOR) preconditioning (see Young (1971)).

For incomplete Cholesky (IC) preconditioning see complex_herm_solve_ilu().

The matrix $A$ is represented in symmetric coordinate storage (SCS) format (see the F11 Introduction) in the arrays $a$, $irow$ and $icol$. The array $a$ holds the nonzero entries in the lower triangular part of the matrix, while $irow$ and $icol$ hold the corresponding row and column indices.

References

Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617–629

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