f11 Chapter Contents
f11 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_sparse_herm_precon_ssor_solve (f11jrc)

## 1  Purpose

nag_sparse_herm_precon_ssor_solve (f11jrc) solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a complex sparse Hermitian matrix, represented in symmetric coordinate storage format.

## 2  Specification

 #include #include
 void nag_sparse_herm_precon_ssor_solve (Integer n, Integer nnz, const Complex a[], const Integer irow[], const Integer icol[], const double rdiag[], double omega, Nag_SparseSym_CheckData check, const Complex y[], Complex x[], NagError *fail)

## 3  Description

nag_sparse_herm_precon_ssor_solve (f11jrc) solves a system of equations
 $Mx=y$
involving the preconditioning matrix
 $M=1ω2-ω D+ω L D-1 D+ω LH$
corresponding to symmetric successive-over-relaxation (SSOR) (see Young (1971)) on a linear system $Ax=b$, where $A$ is a sparse complex Hermitian matrix stored in symmetric coordinate storage (SCS) format (see Section 2.1.2 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$ and $\omega$ is a user-defined relaxation argument. Note that since $A$ is Hermitian the matrix $D$ is necessarily real.

## 4  References

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

## 5  Arguments

1:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 1$.
2:     nnzIntegerInput
On entry: the number of nonzero elements in the lower triangular part of the matrix $A$.
Constraint: $1\le {\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
3:     a[nnz]const ComplexInput
On entry: the nonzero elements in 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 nag_sparse_herm_sort (f11zpc) may be used to order the elements in this way.
4:     irow[nnz]const IntegerInput
5:     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_herm_sort (f11zpc)):
• $1\le {\mathbf{irow}}\left[\mathit{i}\right]\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left[\mathit{i}\right]\le {\mathbf{irow}}\left[\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,{\mathbf{nnz}}-1$;
• ${\mathbf{irow}}\left[\mathit{i}-1\right]<{\mathbf{irow}}\left[\mathit{i}\right]$ or ${\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$.
6:     rdiag[n]const doubleInput
On entry: 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.
On entry: the relaxation argument $\omega$.
Constraint: $0.0<{\mathbf{omega}}<2.0$.
8:     checkNag_SparseSym_CheckDataInput
On entry: specifies whether or not the input data should be checked.
${\mathbf{check}}=\mathrm{Nag_SparseSym_Check}$
Checks are carried out on the values of n, nnz, irow, icol and omega.
${\mathbf{check}}=\mathrm{Nag_SparseSym_NoCheck}$
None of these checks are carried out.
Constraint: ${\mathbf{check}}=\mathrm{Nag_SparseSym_Check}$ or $\mathrm{Nag_SparseSym_NoCheck}$.
9:     y[n]const ComplexInput
On entry: the right-hand side vector $y$.
10:   x[n]ComplexOutput
On exit: the solution vector $x$.
11:   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: ${\mathbf{nnz}}\ge 1$.
NE_INT_2
On entry, ${\mathbf{nnz}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/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_SCS
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{icol}}\left[i-1\right]=〈\mathit{\text{value}}〉$, ${\mathbf{irow}}\left[i-1\right]=〈\mathit{\text{value}}〉$.
Constraint: $1\le {\mathbf{icol}}\left[i-1\right]\le {\mathbf{irow}}\left[i-1\right]$.
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{irow}}\left[i-1\right]=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: $1\le {\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}}〉$. Consider calling nag_sparse_herm_sort (f11zpc) to reorder and sum or remove duplicates.
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

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+ωLT,$
$c\left(n\right)$ is a modest linear function of $n$, and $\epsilon$ is the machine precision.

## 8  Further Comments

### 8.1  Timing

The time taken for a call to nag_sparse_herm_precon_ssor_solve (f11jrc) is proportional to nnz.

## 9  Example

This example program solves the preconditioning equation $Mx=y$ for a $9$ by $9$ sparse complex Hermitian matrix $A$, given in symmetric coordinate storage (SCS) format.

### 9.1  Program Text

Program Text (f11jrce.c)

### 9.2  Program Data

Program Data (f11jrce.d)

### 9.3  Program Results

Program Results (f11jrce.r)