NAG Library Function Document
nag_sparse_sym_precon_ssor_solve (f11jdc)
1
Purpose
nag_sparse_sym_precon_ssor_solve (f11jdc) solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a real sparse symmetric matrix, represented in symmetric coordinate storage format.
2
Specification
#include <nag.h> |
#include <nagf11.h> |
void |
nag_sparse_sym_precon_ssor_solve (Integer n,
Integer nnz,
const double a[],
const Integer irow[],
const Integer icol[],
const double rdiag[],
double omega,
Nag_SparseSym_CheckData check,
const double y[],
double x[],
NagError *fail) |
|
3
Description
nag_sparse_sym_precon_ssor_solve (f11jdc) solves a system of equations
involving the preconditioning matrix
corresponding to symmetric successive-over-relaxation (SSOR) (see
Young (1971)) on a linear system
, where
is a sparse symmetric matrix stored in symmetric coordinate storage (SCS) format (see
Section 2.1.2 in the f11 Chapter Introduction).
In the definition of given above is the diagonal part of , is the strictly lower triangular part of , and is a user-defined relaxation parameter.
It is envisaged that a common use of
nag_sparse_sym_precon_ssor_solve (f11jdc) will be to carry out the preconditioning step required in the application of
nag_sparse_sym_basic_solver (f11gec) to sparse linear systems. For an illustration of this use of
nag_sparse_sym_precon_ssor_solve (f11jdc) see the example program given in
Section 10.1.
nag_sparse_sym_precon_ssor_solve (f11jdc) is also used for this purpose by the Black Box function
nag_sparse_sym_sol (f11jec).
4
References
Young D (1971) Iterative Solution of Large Linear Systems Academic Press, New York
5
Arguments
- 1:
– IntegerInput
-
On entry: , the order of the matrix .
Constraint:
.
- 2:
– IntegerInput
-
On entry: the number of nonzero elements in the lower triangular part of .
Constraint:
.
- 3:
– const doubleInput
-
On entry: the nonzero elements in the lower triangular part of the matrix
, 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_sym_sort (f11zbc) may be used to order the elements in this way.
- 4:
– const IntegerInput
- 5:
– const IntegerInput
-
On entry: the row and column indices of the nonzero elements supplied in array
a.
Constraints:
irow and
icol must satisfy these constraints (which may be imposed by a call to
nag_sparse_sym_sort (f11zbc)):
- and , for ;
- or and , for .
- 6:
– const doubleInput
-
On entry: the elements of the diagonal matrix , where is the diagonal part of .
- 7:
– doubleInput
-
On entry: the relaxation parameter .
Constraint:
.
- 8:
– Nag_SparseSym_CheckDataInput
-
On entry: specifies whether or not the input data should be checked.
- Checks are carried out on the values of n, nnz, irow, icol and omega.
- None of these checks are carried out.
Constraint:
or .
- 9:
– const doubleInput
-
On entry: the right-hand side vector .
- 10:
– doubleOutput
-
On exit: the solution vector .
- 11:
– NagError *Input/Output
-
The NAG error argument (see
Section 3.7 in How to Use the NAG Library and its Documentation).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_2
-
On entry, and .
Constraint:
- 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.
See
Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
- NE_INVALID_SCS
-
On entry, , and .
Constraint: and .
On entry, , and .
Constraint: and .
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
- NE_NOT_STRICTLY_INCREASING
-
On entry, is out of order: .
On entry, the location (
) is a duplicate:
. Consider calling
nag_sparse_sym_sort (f11zbc) to reorder and sum or remove duplicates.
- NE_REAL
-
On entry, .
Constraint:
- NE_ZERO_DIAG_ELEM
-
The matrix has no diagonal entry in row .
7
Accuracy
The computed solution
is the exact solution of a perturbed system of equations
, where
is a modest linear function of
, and
is the
machine precision.
8
Parallelism and Performance
nag_sparse_sym_precon_ssor_solve (f11jdc) is not threaded in any implementation.
The time taken for a call to
nag_sparse_sym_precon_ssor_solve (f11jdc) is proportional to
nnz.
It is expected that a common use of
nag_sparse_sym_precon_ssor_solve (f11jdc) will be to carry out the preconditioning step required in the application of
nag_sparse_sym_basic_solver (f11gec) to sparse symmetric linear systems. In this situation
nag_sparse_sym_precon_ssor_solve (f11jdc) is likely to be called many times with the same matrix
. In the interests of both reliability and efficiency, you are recommended to set
for the first of such calls, and to set
for all subsequent calls.
10
Example
This example solves a sparse symmetric linear system of equations
using the conjugate-gradient (CG) method with SSOR preconditioning.
The CG algorithm itself is implemented by the reverse communication function
nag_sparse_sym_basic_solver (f11gec), 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 , a matrix-vector product is required. This is implemented by a call to nag_sparse_sym_matvec (f11xec).
- If , a solution of the preconditioning equation is required. This is achieved by a call to nag_sparse_sym_precon_ssor_solve (f11jdc).
- If , nag_sparse_sym_basic_solver (f11gec) 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_sym_basic_solver (f11gec).
10.1
Program Text
Program Text (f11jdce.c)
10.2
Program Data
Program Data (f11jdce.d)
10.3
Program Results
Program Results (f11jdce.r)