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

PADALL--Allocates Space for an Array Descriptor for a General Sparse Matrix

This sparse utility subroutine allocates space for an array descriptor, which is needed to establish a mapping between the global general sparse matrix A and its corresponding distributed memory location. This subroutine also initializes the components of the array descriptor desc_a.

Syntax

On Entry

n

is the order of the global general sparse matrix A and the size of the index space.

Scope: global

Type: required

Specified as: a fullword integer, where: n > 0.

parts

is a user-supplied subroutine that specifies a mapping between a global index for an element in the global general sparse matrix A and its corresponding storage location on one or more processes.

Sample parts subroutines for common types of data distributions are shown in Sample PARTS Subroutine.

For details about how you must define the PARTS subroutine, see Programming Considerations for the Parts Subroutine (Fortran 90 and Fortran 77).

Scope: global

Type: required

Specified as: parts must be declared as an external subroutine in your application program. It can be whatever name you choose.

desc_a

See On Return.

icontxt

is the BLACS context parameter.

Scope: global

Type: required

Specified as: a fullword integer that was returned in a prior call to BLACS_GRIDINIT or BLACS_GRIDMAP.

On Return

desc_a

is the local space allocated for the array descriptor for the global general sparse matrix A. This subroutine also initializes the components of the array descriptor desc_a. The components of desc_a are updated with subsequent calls to PSPINS and finalized with a call to PSPASB.

Table 25 describes some of the elements of MATRIX_DATA, which is one component of the array descriptor, that you may want to reference. However, your application programs should not modify the components of the array descriptor directly. These components should only be updated with calls to PSPINS and PSPASB.

Type: required

Returned as: the derived data type DESC_TYPE.

Notes and Coding Rules

1. Before you call this subroutine, you must create a np × 1 process grid, where np is the number of processes.
2. PADALL allocates desc_a as necessary. Prior to further calls to PADALL with the same desc_a, you must call PADFREE; otherwise, there will be a memory leak.

Error Conditions

Computational Errors

None

Resource Errors

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

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. n <= 0

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

   n differs.

Stage 5:  

1. pv or nv, output from the user-supplied parts subroutine, was not valid. For valid values, see the appropriate argument description in Programming Considerations for the Parts Subroutine (Fortran 90 and Fortran 77).