Parallel Engineering and Scientific Subroutine Library for AIX Version 2 Release 3: Guide and Reference

PSPGPR--Preconditioner for a General Sparse Matrix

This subroutine computes a preconditioner for a global general sparse matrix A that should be passed unchanged to the PSPGIS subroutine. The preconditioners include diagonal scaling or an incomplete LU factorization.

Syntax

On Entry

iprec

is a flag that determines the type of preconditioning, where:

If iprec = 0, which is referred to as none, indicates the local part of the submatrix A is not preconditioned. PSPGIS will not be effective in this case, unless the coefficient matrix is well conditioned; if your input matrix is not well conditioned, you should consider using iprec = 1 or 2.

If iprec = 1, which is referred to as diagsc, indicates the local part of the submatrix A is preconditioned by a local diagonal submatrix.

If iprec = 2, which is referred to as ilu, indicates the local part of the submatrix A is preconditioned by a local incomplete LU factorization.

It is suggested that you use a preconditioner. For an explanation, see Notes and Coding Rules.

Scope: global

Type: required

Specified as: a fullword integer, where: iprec = 0, 1, or 2.

a

is the local part of the global general sparse matrix A, finalized on a preceding call to PSPASB.

Scope: local

Type: required

Specified as: the derived data type D_SPMAT.

prcs

See On Return.

desc_a

is the array descriptor for the global general sparse matrix A that was finalized in a call to PSPASB.

Type: required

Specified as: the derived data type DESC_TYPE.

info

See On Return.

On Return

prcs

is the preconditioner data structure prcs that must be passed unchanged to PSPGIS.

Scope: local

Type: required

Returned as: the derived data type D_PRECN.

info

has the following meaning, when info is present:

If info = 0, then no input-argument errors or computational errors occurred. This indicates a normal exit.

Note:

Because Parallel ESSL terminates the application if input-argument errors occur, the setting of info is irrelevant for these errors.

If info > 0, the value stored in info indicates the row index in the global general sparse matrix A where the preconditioner failed.

Scope: global

Type: optional

Returned as: a fullword integer; info >= 0.

Notes and Coding Rules

1. Before you call this subroutine, you must have called PSPASB and PGEASB.
2. PSPGPR allocates prcs, as necessary. Prior to further calls to PSPGPR with the same prcs, you must call PSPFREE; otherwise, there will be a memory leak.
3. For details about some of the elements stored in DESC_A%MATRIX_DATA, see Derived Data Type DESC_TYPE.
4. Parallel ESSL builds the preconditioner, prcs, which is specified as derived data type D_PRECN, and its components. All the components of derived data type D_PRECN are used for internal use only.
5. The convergence rate of an iterative method as applied to a given system of linear equations depends on the spectral properties of the coefficient matrix of the linear system; therefore it is often convenient to apply a linear transformation to the system such that the solution of the transformed system is the same (in exact arithmetic) as that of the original, but the spectral properties and the convergence behavior are more favorable. Such a transformation is called preconditioning. If a matrix M approximates A, then:

   (M^-1)Ax = (M^-1)b

   is a preconditioned system and M is called a preconditioner. In practice, the new coefficient matrix (M^-1)A is almost never formed explicitly, but rather its action is computed during the application of the iterative method. The effectiveness of the preconditioning operation depends on a trade-off between how well M approximates A and how costly it is to compute and invert it; no single preconditioner will give best overall performance under all situations. Note finally that it is quite rare for a linear system to behave well enough so as not to require preconditioning; indeed most linear systems originating from the discretization of difficult physical problems require preconditioning to have any convergence at all.

   See references [9] and [37].

Error Conditions

Computational Errors

1. The preconditioner for the sparse matrix A is unstable. For details, see the info output argument for this subroutine.

Resource Errors

1. Unable to allocate work space.
2. Unable to allocate component(s) of prcs.

Input-Argument and Miscellaneous Errors

Stage 1:  

1. desc_a has not been initialized.

Stage 2:  

1. The BLACS context is invalid.

Stage 3:  

1. This subroutine was called from outside the process grid.

Stage 4:  

1. The process grid is not np × 1.
2. desc_a component(s) are not valid.
3. iprec <> 0, 1, or 2
4. The storage format for A is not supported.

Stage 5:  

1. Each of the following global input arguments are checked to determine whether its value differs from the value specified on process P₀₀:

   iprec differs.