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

PSPASB--Assembles a General Sparse Matrix

This sparse utility subroutine uses the output from PSPINS to assemble the global general sparse matrix A and its array descriptor desc_a.

Syntax

On Entry

a

is the local part of the global general sparse matrix A that is produced by previous call(s) to PSPINS.

Scope: local

Type: required

Specified as: the derived data type D_SPMAT.

desc_a

is the array descriptor for the global general sparse matrix A that is produced by previous call(s) to PSPINS.

Type: required

Specified as: the derived data type DESC_TYPE.

mtype

indicates the form of the global sparse matrix A used, where:

If mtype = 'GEN', A is a general sparse matrix.

Scope: global

Type: optional

Specified as: a character variable of length 5; mtype = 'GEN'. The default value is 'GEN'.

stor

indicates the storage mode that the global general sparse matrix A is returned in, where:

If stor = 'DEF', this subroutine chooses an appropriate storage mode, which is an internal format accepted by the preconditioner and solver subroutines, for storing the global general sparse matrix A on output.

If stor = 'CSR', the global general sparse matrix A is stored in the storage-by-rows storage mode on output.

Scope: global

Type: optional

Specified as: a character variable of length 5; stor = 'DEF' or 'CSR'. The default value is 'DEF'.

dupflag

is a flag indicating how to use coefficients that are specified more than once on the same process; that is, duplicate coefficients within the same local part of the matrix A:

If dupflag = 0, this subroutine uses the first of the duplicate coefficients.

If dupflag = 1, this subroutine adds all the duplicate coefficients with the same indices.

If dupflag = 2, this subroutine raises an error condition indicating that there are unexpected duplicate coefficients.

Scope: global

Type: optional

Specified as: a fullword integer; dupflag = 0, 1, or 2. The default value is 0.

info

See On Return.

On Return

a

is the updated local part of the global general sparse matrix A, where:

If stor = 'DEF', this subroutine chooses an appropriate storage mode, which is an internal format accepted by the preconditioner and solver subroutines, for storing the global general sparse matrix A on output.

If stor = 'CSR', the global general sparse matrix A is stored in the storage-by-rows storage mode on output.

Scope: local

Type: required

Returned as: the derived data type D_SPMAT.

desc_a

is the final updated array descriptor for the global general sparse matrix A.

Type: required

Returned as: the derived data type DESC_TYPE.

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 one or more of the following computational errors occurred and the appropriate error messages were issued, indicating an error exit, where:

• If info = 1, the sparse matrix A contains duplicate coefficients.
• If info = 2, the sparse matrix A contains empty row(s).

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 PSPINS as many times as needed; that is, you must have completed building the matrix with call(s) to PSPINS before you place a call to this subroutine.
2. This subroutine accepts mixed case letters for the mtype and stor arguments.
3. For details about some of the elements stored in DESC_A%MATRIX_DATA, see Derived Data Type DESC_TYPE.

Error Conditions

Computational Errors

The sparse matrix A contains duplicate coefficients or empty row(s). For details, see the description of the info argument.

Resource Errors

1. Unable to allocate work space.
2. Unable to allocate component(s) of desc_a.
3. Unable to allocate component(s) of A.

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. desc_a component(s) are not valid.
2. The process grid is not np × 1.
3. The sparse matrix A is not valid.
4. mtype <> 'GEN'
5. stor <> 'DEF' or 'CSR'
6. dupflag <> 0, 1, or 2
7. Some local rows in the sparse matrix A are missing.

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

   mtype differs.

   stor differs.

   dupflag differs.