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

PDSPASB--Assembles a General Sparse Matrix

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

Syntax

On Entry

as

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

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 that is produced by previous call(s) to PDSPINS.

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 that is produced by previous call(s) to PDSPINS.

Scope: local

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

infoa

is the array INFOA that is produced by previous call(s) to PDSPINS.

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

desc_a

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

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

mtype

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

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

Scope: global

Specified as: a character variable of length 5; mtype = '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

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

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

Specified as: a fullword integer; dupflag = 0, 1, or 2.

info

See On Return.

On Return

as

is the updated local part of array AS 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

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

ia1

is the updated local part of array IA2.

Scope: local

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

ia2

is the updated local part of array IA2.

Scope: local

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

infoa

is the updated array INFOA.

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

desc_a

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

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

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

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

Notes and Coding Rules

1. In your C program, info must be passed by reference.
2. This subroutine accepts mixed case letters for the mtype and stor arguments.
3. Before you call this subroutine, you must have called PDSPINS as many times as needed; that is, you must have completed building the matrix with call(s) to PDSPINS before you place a call to this subroutine.
4. Your program must declare mtype and stor to be characters of length 5 with blanks padded to the right. C programs can use the fifth character for the null terminator.
5. For more details about N_ROW, N_COL, and other elements of desc_a, see Table 28.
6. For details about some of the elements stored in infoa, see Table 27.

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 deallocate 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. 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 4:  

1. DLEN is too small. For valid values, see Array Descriptor.
2. INFOA(1) < max(2,nnze); that is, the size of AS < max(2,nnze)
3. INFOA(2) < max(3,(nnze+N_ROW)); that is, the size of IA1 < max(3,(nnze+N_ROW))
4. INFOA(3) < max(3,(nnze+N_COL)); that is, the size of IA2 < max(3,(nnze+N_COL))

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.