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

PADINIT--Initializes an Array Descriptor for a General Sparse Matrix

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

Syntax

On Entry

n

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

Scope: global

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

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

desc_a

is the array descriptor for the global general sparse matrix A. DESC_A(11), which is the length of the array descriptor, DLEN, is the only element that you must specify. To determine a sufficient value, see Array Descriptor.

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

icontxt

is the BLACS context parameter.

Scope: global

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

On Return

desc_a

is the array descriptor for the global general sparse matrix A. This subroutine initializes the remaining elements in the array descriptor desc_a. The elements of desc_a are updated with subsequent calls to PDSPINS and finalized with a call to PDSPASB.

Table 28 describes some of the elements of the array descriptor that you may want to reference. Your application programs should not modify the elements of the array descriptor directly. The elements should only be updated with calls to PDSPINS and PDSPASB.

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

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. N_ROW is stable after you have placed a call to this subroutine. N_COL is stable after you have placed a call to PDSPASB. For more details about N_ROW, N_COL, and other elements of desc_a, see Table 28.

Error Conditions

Computational Errors

None.

Resource Errors

None.

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).
2. DLEN is too small. For valid values, see Array Descriptor.