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

PDSPGIS--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

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.

nrhs

the number of right-hand sides.

Scope: global

Specified as: a fullword integer; nrhs = 1.

b

is the local part of the matrix b, containing the right-hand side of the matrix problem produced on a previous call to PDGEASB.

Scope: local

Specified as: an ldb by (at least) length nrhs array, containing long-precision real numbers.

ldb

is the leading dimension of the local array B.

Scope: local

Specified as: a fullword integer; ldb >= max(1,N_ROW)

x

is 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 PDGEASB.

Scope: local

Specified as: an ldx by (at least) nrhs array, containing long-precision real numbers.

ldx

is the leading dimension of the local array X.

Scope: local

Specified as: a fullword integer; ldx >= max(1,N_ROW)

prcs

is the preconditioner data structure prcs produced by a previous call to PDSPGPR.

Scope: local

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

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.

iparm

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

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

  If IPARM(1) = 0, the following defaults are used:

  methd = 1

  istopc = 1

  itmax = 500

  itrace = 0

  eps = 10^-8

  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, itmax, of iterations 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 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

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) is the relative accuracy epsilon, referred to as eps, used in the stopping criterion.
• RPARM(2), see On Return.
• RPARM(3) through RPARM(20) are reserved.

Scope: global

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 the local part of the solution vector x

Scope: local

Returned as: an array of (at least) length N_ROW, containing long-precision real numbers.

iparm

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

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

Scope: global

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

iter >= 0

rparm

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

• 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

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:

1. You can increase the number of iterations and call this subroutine again without making any other changes to your program.
2. You can change the requested precision and/or the stopping criterion; your original precision requirement may be too stringent under a given stopping criterion.
3. 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

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

Notes and Coding Rules

1. In your C program, info must be passed by reference.
2. Before you call this subroutine, you must have called PDSPGPR.
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.

Error Conditions

Computational Errors

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

   Note:

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

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

   1. You can increase the number of iterations and call this subroutine again without making any other changes to your program.
   2. You can change the requested precision and/or the stopping criterion; your original precision requirement may be too stringent under a given stopping criterion.
   3. 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. 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. nrhs <> 1
4. eps < 0.0
5. methd <> 1, 2, or 3
6. The preconditioner data structure prcs is not valid.
7. istopc <> 1, 2, or 3
8. itmax < 0
9. itrace < 0
10. The sparse matrix A is not valid.
11. The storage format for the sparse matrix A is not supported.

Stage 4:  

1. ldb < max(1,N_ROW)
2. ldx < max(1,N_ROW)
3. The preconditioner data structure prcs is not valid.

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₀₀:

   iparm differs.

   rparm differs.

   eps differs.

   methd differs.

   istopc differs.

   itmax differs.

   itrace differs.

   Some element(s) of prcs differ.