NAG Library Function Document
nag_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 <nag.h> |
#include <nagf11.h> |
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
according to the value of the argument
trans, where the matrix
corresponds to symmetric successive-over-relaxation (SSOR) (see
Young (1971)) applied to a linear system
, where
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 given above is the diagonal part of , is the strictly lower triangular part of , is the strictly upper triangular part of , and is a user-defined relaxation parameter.
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 10.
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:
– Nag_TransTypeInput
-
On entry: specifies whether or not the matrix
is transposed.
- is solved.
- is solved.
Constraint:
or .
- 2:
– IntegerInput
-
On entry: , the order of the matrix .
Constraint:
.
- 3:
– IntegerInput
-
On entry: the number of nonzero elements in the matrix .
Constraint:
.
- 4:
– const doubleInput
-
On entry: the nonzero elements in 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_nsym_sort (f11zac) may be used to order the elements in this way.
- 5:
– const IntegerInput
- 6:
– 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)):
- and , for ;
- either or both and , for .
- 7:
– const doubleInput
-
On entry: the elements of the diagonal matrix , where is the diagonal part of .
- 8:
– doubleInput
-
On entry: the relaxation parameter .
Constraint:
.
- 9:
– Nag_SparseNsym_CheckDataInput
-
On entry: specifies whether or not the CS representation of the matrix
should be checked.
- Checks are carried on the values of n, nnz, irow, icol and omega.
- None of these checks are carried out.
Constraint:
or .
- 10:
– const doubleInput
-
On entry: the right-hand side vector .
- 11:
– doubleOutput
-
On exit: the solution vector .
- 12:
– 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_CS
-
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: .
- NE_REAL
-
On entry, .
Constraint: .
- NE_ZERO_DIAG_ELEM
-
The matrix has no diagonal entry in row .
7
Accuracy
If
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. An equivalent result holds when
.
8
Parallelism and Performance
nag_sparse_nsym_precon_ssor_solve (f11ddc) is not threaded in any implementation.
The time taken for a call to
nag_sparse_nsym_precon_ssor_solve (f11ddc) is proportional to
nnz.
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
. In the interests of both reliability and efficiency, you are recommended to set
for the first of such calls, and for all subsequent calls set
.
10
Example
This example solves a sparse linear system of equations:
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 , a matrix-vector product is required. This is implemented by a call to nag_sparse_nsym_matvec (f11xac).
- If , a transposed matrix-vector product is required in the estimation of the norm of . This is implemented by a call to nag_sparse_nsym_matvec (f11xac).
- If , a solution of the preconditioning equation is required. This is achieved by a call to nag_sparse_nsym_precon_ssor_solve (f11ddc).
- If , 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).
10.1
Program Text
Program Text (f11ddce.c)
10.2
Program Data
Program Data (f11ddce.d)
10.3
Program Results
Program Results (f11ddce.r)