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

PSPGIS--Iterative Linear System Solver for a General Sparse Matrix

This subroutine solves a general sparse linear system of equations, using an iterative algorithm, with or without preconditioning. The methods include the more smoothly converging variant of the CGS method (Bi-CGSTAB), conjugate gradient squared (CGS), or transpose-free quasi-minimal residual method (TFQMR).

See references [7], [9], [12], and [35].

Syntax

On Entry

a

is the local part of the coefficient matrix A, produced on a previous call to PSPASB.

Scope: local

Type: required

Specified as: the derived data type D_SPMAT.

b

is a pointer to the local part of the global vector b, containing the right-hand side of the matrix problem and produced on a previous call to PGEASB.

Scope: local

Type: required

Specified as: a pointer to an assumed-shape array with shape (:), containing long-precision real numbers.

x

is a pointer to the local part of the global vector x, containing the initial guess to the solution of the linear system and produced on a previous call to PGEASB.

Scope: local

Type: required

Specified as: a pointer to an assumed-shape array with shape (:), containing long-precision real numbers.

prcs

is the preconditioner data structure prcs, produced on a previous call to PSPGPR.

Scope: local

Type: required

Specified as: the derived data type D_PRECN.

desc_a

is the array descriptor, produced on a previous call to PSPASB, for the global general sparse matrix A.

Type: required

Specified as: the derived data type DESC_TYPE.

iparm

is an array of parameters, IPARM(i), where:

• IPARM(1) is the flag, referred to as methd, used to select the iterative procedure used, where:

  If methd = 1, the more smoothly converging variant of the CGS method, referred to as Bi-CGSTAB, is used.

  If methd = 2, the conjugate gradient squared method, referred to as CGS, is used.

  If methd = 3, the transpose-free quasi-minimal residual method, referred to as TFQMR, is used.

• IPARM(2) is the flag, istopc, used to select the stopping criterion used in the computation, where the following items are used in the definitions of the stopping criteria below:
  • epsilon is the desired relative accuracy and is stored in eps
  • x_j is the solution found at the j-th iteration.
  • r_j and r₀ are the preconditioned residuals obtained at iterations j and 0, respectively. (The residual at iteration j is defined as b-Ax_j.)

  If istopc = 1, the iterative method is stopped when:

  ||r_j||₂ / ||x_j||₂ < epsilon

  If istopc = 2, the iterative method is stopped when:

  ||r_j||₂ / ||r₀||₂ < epsilon

  If istopc = 3, the iterative method is stopped when:

  ||x_j -x_j-1||₂ / ||x_j||₂ < epsilon

  Note:

  Stopping criterion 3 performs poorly with the TFQMR method; therefore, if you specify TFQMR (methd = 3), you should not specify stopping criterion 3.

• IPARM(3) is the maximum number of iterations itmax allowed.
• IPARM(4), referred to as itrace, has the following meaning:

  If itrace = 0, then itrace is ignored.

  If itrace > 0, an informational message about the convergence, which is based on the stopping criterion described in istopc, is issued at every itrace-th iteration and upon exit.

• IPARM(5), see On Return.
• IPARM(6) through IPARM(20) are reserved.

Scope: global

Type: optional

Default:

methd = 1

istopc = 1

itmax = 500

itrace = 0

Specified as: an array of length 20, containing fullword integers, where:

methd = 1, 2, or 3

istopc = 1, 2, or 3

itmax >= 0

itrace >= 0

IPARM(6) through IPARM(20) should be set to zero.

rparm

is an array of parameters, RPARM(i), where:

• RPARM(1), referred to as eps, is the relative accuracy epsilon used in the stopping criterion.
• RPARM(2), see On Return.
• RPARM(3) through RPARM(20) are reserved.

Scope: global

Type: optional

Default: eps = 10^-8

Specified as: an array of length 20, containing long-precision real numbers, where:

eps >= 0.

RPARM(3) through RPARM(20) should be set to zero.

info

See On Return.

On Return

x

is a pointer to the local part of the solution vector x

Scope: local

Type: required

Returned as: a pointer to an assumed-shape array of shape (:), containing long-precision real numbers.

iparm

has the following meaning, when iparm is present:

IPARM(5) is the number of iterations, iter, performed by this subroutine.

Scope: global

Type: optional

Returned as: an array of length 20, containing fullword integers, where iter >= 0.

rparm

has the following meaning, when rparm is present:

RPARM(2) contains the estimate of the error, err, of the solution, according to the stopping criterion, istopc, in use. For details, see the istopc argument description.

Scope: global

Type: optional

Returned as: an array of length 20, containing long-precision real numbers, where err >= 0.

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, then this subroutine exceeded itmax iterations without converging. You may want to try the following to get your matrix to converge:

• You can increase the number of iterations and call this subroutine again without making any other changes to your program.
• You can change the requested precision and/or the stopping criterion; your original precision requirement may be too stringent under a given stopping criterion.
• You can use a preconditioner if you were not already doing so, or to change the one you were using. Note also that the efficiency of the preconditioner may depend on the data distribution strategy adopted. See Notes and Coding Rules.

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 PSPGPR.
2. For details about some of the elements stored in DESC_A%MATRIX_DATA, see Derived Data Type DESC_TYPE.
3. 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.

Error Conditions

Computational Errors

This subroutine exceeded itmax iterations without converging. Vector x contains the approximate solution computed at the last iteration.

Note:

If the preconditioner computed by PSPGPR failed because the sparse matrix A is unstable, the results returned by this subroutine are unpredictable. For details, see the info output argument for PSPGPR.

You may want to try the following to get your matrix to converge:

• You can increase the number of iterations and call this subroutine again without making any other changes to your program.
• You can change the requested precision and/or the stopping criterion; your original precision requirement may be too stringent under a given stopping criterion.
• You can use a preconditioner if you were not already doing so, or to change the one you were using. Note also that the efficiency of the preconditioner may depend on the data distribution strategy adopted. See Notes and Coding Rules.

Resource Errors

1. Unable to allocate work space.

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. The sparse matrix A is not valid.
4. size(iparm) < 20
5. size(rparm) < 20
6. eps < 0.0
7. methd <> 1, 2, or 3
8. iprec <> 0, 1, or 2
9. istopc <> 1, 2, or 3
10. itmax < 0
11. itrace < 0
12. The storage format for the sparse matrix A is not supported.

Stage 5:  

1. size(x) < DESC_A%MATRIX_DATA(N_ROW)
2. size(b) < DESC_A%MATRIX_DATA(N_ROW)
3. The preconditioner data structure prcs is not valid.

Stage 6:  

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

   eps differs.

   methd differs.

   istopc differs.

   itmax differs.

   itrace differs.

   Component(s) of prcs differ.