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

PDSPGPR--Preconditioner for a General Sparse Matrix

This subroutine computes a preconditioner for the global general sparse matrix A that should be passed unchanged to the PDSPGIS 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. PDSPGIS may 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

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

as

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

Scope: local

Specified as: a one-dimensional array of (at least) length INFOA(1), containing long-precision real numbers.

ia1

is the local part of array IA1 produced by a previous call to PDSPASB.

Scope: local

Specified as: a one-dimensional array of (at least) length INFOA(2), containing fullword integers.

ia2

is the local part of array IA2 produced by a previous call to PDSPASB.

Scope: local

Specified as: a one-dimensional array of (at least) length INFOA(3), containing fullword integers.

infoa

is the array INFOA produced by a previous call to PDSPASB.

Specified as: an array of length 30, containing fullword integers.

prcs

See On Return.

lprcs

is the length of array PRCS.

Scope: local

Specified as: fullword integer, where:

If iprec = 0, lprcs >= 10.

If iprec = 1, lprcs >= 10+N_ROW.

If iprec = 2, lprcs >= 10+2(nnz)+N_ROW+N_COL+31

nnz is the number of non-zero elements (without duplicate coefficients) in the local part of the global general sparse matrix A.

desc_a

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

Specified as: an array of length DLEN, containing fullword integers.

info

See On Return.

On Return

prcs

is the preconditioner data structure that must be pass unchanged to PDSPGIS.

Scope: local

Returned as: a one-dimensional array of (at least) length lprcs, containing long-precision real numbers.

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

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

Notes and Coding Rules

1. Before you call this subroutine, you must have called PDGEASB and PDSPASB.
2. In your C program, info must be passed by reference.
3. For more details about N_ROW, N_COL, and other elements of desc_a, see Table 28.
4. For details about some of the elements stored in infoa see Table 27.
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 the discretization of difficult physical problems require preconditioning to have any convergence at all.

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.

Input-Argument and Miscellaneous Errors

Stage 1:  

1. The BLACS context is invalid.

Stage 2:  

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

Stage 3:  

1. The process grid is not np × 1.
2. desc_a is not valid.
3. iprec <> 0, 1, or 2
4. iprec = 0 and lprcs < 10
5. iprec = 1 and lprcs < 10+N_ROW
6. iprec = 2 and lprcs < 10+2(nnz)+N_ROW+N_COL+31
7. The storage format for A is not supported.

Stage 4:  

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.