f11 Chapter Contents
f11 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_sparse_nsym_precon_ssor_solve (f11ddc)

## 1  Purpose

nag_sparse_nsym_precon_ssor_solve (f11ddc) 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.

## 2  Specification

 #include #include
 void nag_sparse_nsym_precon_ssor_solve (Nag_TransType trans, Integer n, Integer nnz, const double a[], const Integer irow[], const Integer icol[], const double rdiag[], double omega, Nag_SparseNsym_CheckData check, const double y[], double x[], NagError *fail)

## 3  Description

nag_sparse_nsym_precon_ssor_solve (f11ddc) solves a system of linear equations
 $Mx=y, or MTx=y,$
according to the value of the argument trans, where the matrix
 $M=1ω2-ω D+ω L D-1 D+ω 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 Section 2.1.1 in the f11 Chapter 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 argument.
It is envisaged that a common use of nag_sparse_nsym_precon_ssor_solve (f11ddc) will be to carry out the preconditioning step required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. For an illustration of this use of nag_sparse_nsym_precon_ssor_solve (f11ddc) see the example program given in Section 9. nag_sparse_nsym_precon_ssor_solve (f11ddc) is also used for this purpose by the Black Box function nag_sparse_nsym_sol (f11dec).

## 4  References

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

## 5  Arguments

1:     transNag_TransTypeInput
On entry: specifies whether or not the matrix $M$ is transposed.
${\mathbf{trans}}=\mathrm{Nag_NoTrans}$
$Mx=y$ is solved.
${\mathbf{trans}}=\mathrm{Nag_Trans}$
${M}^{\mathrm{T}}x=y$ is solved.
Constraint: ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ or $\mathrm{Nag_Trans}$.
2:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 1$.
3:     nnzIntegerInput
On entry: the number of nonzero elements in the matrix $A$.
Constraint: $1\le {\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
4:     a[nnz]const doubleInput
On entry: 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 nag_sparse_nsym_sort (f11zac) may be used to order the elements in this way.
5:     irow[nnz]const IntegerInput
6:     icol[nnz]const IntegerInput
On entry: the row and column indices of the nonzero elements supplied in array a.
Constraints:
irow and icol must satisfy the following constraints (which may be imposed by a call to nag_sparse_nsym_sort (f11zac)):
• $1\le {\mathbf{irow}}\left[\mathit{i}\right]\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left[\mathit{i}\right]\le {\mathbf{n}}$, for $\mathit{i}=0,1,\dots ,{\mathbf{nnz}}-1$;
• either ${\mathbf{irow}}\left[\mathit{i}-1\right]<{\mathbf{irow}}\left[\mathit{i}\right]$ or both ${\mathbf{irow}}\left[\mathit{i}-1\right]={\mathbf{irow}}\left[\mathit{i}\right]$ and ${\mathbf{icol}}\left[\mathit{i}-1\right]<{\mathbf{icol}}\left[\mathit{i}\right]$, for $\mathit{i}=1,2,\dots ,{\mathbf{nnz}}-1$.
7:     rdiag[n]const doubleInput
On entry: the elements of the diagonal matrix ${D}^{-1}$, where $D$ is the diagonal part of $A$.
On entry: the relaxation argument $\omega$.
Constraint: $0.0<{\mathbf{omega}}<2.0$.
9:     checkNag_SparseNsym_CheckDataInput
On entry: specifies whether or not the CS representation of the matrix $M$ should be checked.
${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$
Checks are carried on the values of n, nnz, irow, icol and omega.
${\mathbf{check}}=\mathrm{Nag_SparseNsym_NoCheck}$
None of these checks are carried out.
Constraint: ${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$ or $\mathrm{Nag_SparseNsym_NoCheck}$.
10:   y[n]const doubleInput
On entry: the right-hand side vector $y$.
11:   x[n]doubleOutput
On exit: the solution vector $x$.
12:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{nnz}}=〈\mathit{\text{value}}〉$.
Constraint: $1\le {\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
NE_INT_2
On entry, ${\mathbf{nnz}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: $1\le {\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_CS
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{icol}}\left[i-1\right]=〈\mathit{\text{value}}〉$, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{icol}}\left[i-1\right]\ge 1$ and ${\mathbf{icol}}\left[i-1\right]\le {\mathbf{n}}$.
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{irow}}\left[i-1\right]=〈\mathit{\text{value}}〉$, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{irow}}\left[i-1\right]\ge 1$ and ${\mathbf{irow}}\left[i-1\right]\le {\mathbf{n}}$.
NE_NOT_STRICTLY_INCREASING
On entry, ${\mathbf{a}}\left[i-1\right]$ is out of order: $i=〈\mathit{\text{value}}〉$.
On entry, the location (${\mathbf{irow}}\left[i-1\right],{\mathbf{icol}}\left[i-1\right]$) is a duplicate: $i=〈\mathit{\text{value}}〉$.
NE_REAL
On entry, ${\mathbf{omega}}=〈\mathit{\text{value}}〉$.
Constraint: $0.0<{\mathbf{omega}}<2.0$.
NE_ZERO_DIAG_ELEM
The matrix $A$ has no diagonal entry in row $〈\mathit{\text{value}}〉$.

## 7  Accuracy

If ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ the computed solution $x$ is the exact solution of a perturbed system of equations $\left(M+\delta M\right)x=y$, where
 $δM≤cnεD+ωLD-1D+ωU,$
$c\left(n\right)$ is a modest linear function of $n$, and $\epsilon$ is the machine precision. An equivalent result holds when ${\mathbf{trans}}=\mathrm{Nag_Trans}$.

### 8.1  Timing

The time taken for a call to nag_sparse_nsym_precon_ssor_solve (f11ddc) is proportional to nnz.

### 8.2  Use of check

It is expected that a common use of nag_sparse_nsym_precon_ssor_solve (f11ddc) will be to carry out the preconditioning step required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. In this situation nag_sparse_nsym_precon_ssor_solve (f11ddc) is likely to be called many times with the same matrix $M$. In the interests of both reliability and efficiency, you are recommended to set ${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$ for the first of such calls, and for all subsequent calls set ${\mathbf{check}}=\mathrm{Nag_SparseNsym_NoCheck}$.

## 9  Example

This example solves a sparse linear system of equations:
 $Ax=b,$
using RGMRES with SSOR preconditioning.
The RGMRES algorithm itself is implemented by the reverse communication function nag_sparse_nsym_basic_solver (f11bec), which returns repeatedly to the calling program with various values of the argument irevcm. This argument indicates the action to be taken by the calling program.
• If ${\mathbf{irevcm}}=1$, a matrix-vector product $v=Au$ is required. This is implemented by a call to nag_sparse_nsym_matvec (f11xac).
• If ${\mathbf{irevcm}}=-1$, a transposed matrix-vector product $v={A}^{\mathrm{T}}u$ is required in the estimation of the norm of $A$. This is implemented by a call to nag_sparse_nsym_matvec (f11xac).
• If ${\mathbf{irevcm}}=2$, a solution of the preconditioning equation $Mv=u$ is required. This is achieved by a call to nag_sparse_nsym_precon_ssor_solve (f11ddc).
• If ${\mathbf{irevcm}}=4$, nag_sparse_nsym_basic_solver (f11bec) has completed its tasks. Either the iteration has terminated, or an error condition has arisen.
For further details see the function document for nag_sparse_nsym_basic_solver (f11bec).

### 9.1  Program Text

Program Text (f11ddce.c)

### 9.2  Program Data

Program Data (f11ddce.d)

### 9.3  Program Results

Program Results (f11ddce.r)