Guide and Reference

Utilities (Message Passing)

This chapter describes the utility subroutines.

Overview of the Utility Subroutines

The utility subroutines perform general service functions that support Parallel ESSL, rather than mathematical computations.

Table 109. List of Utility Subroutines (Message Passing)

Descriptive Name Integer Subroutine Page
Determine the Level of Parallel ESSL Installed on Your System IPESSL IPESSL--Determine the Level of Parallel ESSL Installed on Your System
Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process NUMROC NUMROC--Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process

Descriptive Name	Integer Subroutine	Page
Determine the Level of Parallel ESSL Installed on Your System	IPESSL	IPESSL--Determine the Level of Parallel ESSL Installed on Your System
Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process	NUMROC	NUMROC--Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process

Utility Subroutines

This section contains the utility subroutine descriptions.

IPESSL--Determine the Level of Parallel ESSL Installed on Your System

This function returns the current level of Parallel ESSL installed on your system, where the level consists of a version number, release number, and modification number, plus the fix number of the most recent PTF installed.
Note: This subroutine is useful to you in those instances where your program is using a subroutine or feature that exists only in certain levels of Parallel ESSL. It is also useful when your program is dependent upon certain PTFs being applied to Parallel ESSL.

Syntax

Fortran	IPESSL ()
C and C++	ipessl ();

On Return

Function value

is the level of Parallel ESSL installed on your system. It is provided as a fullword integer in the form vvrrmmff, where each two digits represents a part of the level:

vv is the version number.
rr is the release number.
mm is the modification number.
ff is the fix number of the most recent PTF installed.

Scope: global

Returned as: a fullword integer; vvrrmmff > 0.

Notes

To use IPESSL effectively, you must install your Parallel ESSL PTFs in their proper sequential order. As part of the result, IPESSL returns the value ff of the most recent PTF installed, rather than the highest number PTF installed. Therefore, if you do not install your PTFs sequentially, the ff value returned by IPESSL does not reflect the actual level of ESSL.
Declare the IPESSL function in your program as returning a fullword integer value.
For the first release of Parallel ESSL for AIX Version 4, vv = 01 and rr = 01, and IPESSL returns 1010000.

Example

This example shows several ways to use the IPESSL function. Most typically, you use IPESSL for checking the version and release level of Parallel ESSL. Suppose you are dependent on a new capability in Parallel ESSL, such as a new subroutine or feature, provided for the first time in (fictitious) Parallel ESSL Version 3 Release 2. You can add the following check in your program before using the new capability:

   IF IPESSL() >= 3020000

By specifying 0000 for mmff, the modification and fix level, you are independent of the order in which your modifications and PTFs are installed.

Less typically, you use IPESSL for checking the PTF level of Parallel ESSL. Suppose you are dependent on (fictitious) PTF 24 being installed on your Parallel ESSL Version 1 Release 0 system You want to know whether to call a different user-callable subroutine to set up your array data. You can add the following check in your program before making the call:

   IF IPESSL() >= 1000024

If your system support group installed the Parallel ESSL PTFs in their proper sequential order, this test works properly; otherwise, it is unpredictable.

NUMROC--Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process

This function computes the local number of rows or columns of a block-cyclically distributed matrix contained in a process row or process column, respectively, indicated by the calling sequence argument iproc.

See references [14] and [15].

Syntax

Fortran	NUMROC (`n`, `nb`, `iproc`, `isrcproc`, `nprocs`)
C and C++	numroc (`n`, `nb`, `iproc`, `isrcproc`, `nprocs`);

On Entry

n

is the number of rows M_ or columns N_ in a global matrix that has been block-cyclically distributed.

Scope: global

Specified as: a fullword integer; n >= 0.

nb

is the row block size MB_ or the column block size NB_.

Scope: global

Specified as: a fullword integer; nb > 0.

iproc

is process row index myrow or the process column index mycol.

Scope: local

Specified as: a fullword integer; 0 <= iproc < nprocs.

isrcproc

is the process row RSRC_ or the process column CSRC_ over which the first row or column, respectively, of the global matrix is distributed.

Scope: global

Specified as: a fullword integer; 0 <= isrcproc < nprocs.

nprocs

is the number of rows nprow or the number of columns npcol in the process grid.

Scope: global

Specified as: a fullword integer; nprocs > 0.

On Return

Function value

is the local number of rows or columns of a block-cyclically distributed matrix contained in a process row or process column, respectively, indicated by the calling sequence argument iproc.

Scope: local

Returned as: a fullword integer.

Note

The variables p and nprow are used interchangeably to indicate the number of rows in a process grid. The variables q and npcol are used interchangeably to indicate the number of columns in a process grid.

Error Conditions

Computational Errors

None

Resource Errors

None

Input-Argument and Miscellaneous Errors

Stage 1

nb <= 0
nprocs <= 0

Example

This example shows the local invocations of NUMROC from four processes in a 2 × 2 process grid, using a global symmetric matrix of order 9.

Call Statements and Input

ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET(0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)

The NUMROC function invocations and associated data on each process are shown in "Local Invocations of NUMROC."

The pertinent array descriptor values for global matrix C are shown below:

Desc_C
M_ 9
N_ 9
MB_ 4
NB_ 4
RSRC_ 0
CSRC_ 0

	Desc_C
M_	9
N_	9
MB_	4
NB_	4
RSRC_	0
CSRC_	0

Global symmetric matrix C of order 9 is stored in upper storage mode with block sizes 4 × 4:

B,D             0                       1                2
     *                                                       *
     | -6.0  0.0  0.0  0.0  |   0.0 -2.0 -2.0  0.0  |   -2.0 |
     |   .  -6.0 -2.0  0.0  |  -2.0 -4.0  0.0 -4.0  |   -2.0 |
 0   |   .    .  -6.0 -2.0  |  -2.0  0.0  2.0  0.0  |    6.0 |
     |   .    .    .  -6.0  |   2.0  0.0  2.0  0.0  |    2.0 |
     | ---------------------|-----------------------|------- |
     |   .    .    .    .   |  -8.0 -4.0  0.0 -2.0  |    0.0 |
     |   .    .    .    .   |    .  -6.0  0.0 -4.0  |   -6.0 |
 1   |   .    .    .    .   |    .    .  -4.0  0.0  |    0.0 |
     |   .    .    .    .   |    .    .    .  -4.0  |   -4.0 |
     | ---------------------|-----------------------|------- |
 2   |   .    .    .    .   |    .    .    .    .   |  -16.0 |
     *                                                       *

The following is the 2 × 2 process grid:

B,D 0 2 1
0
2
P₀₀ P₀₁
1 P₁₀ P₁₁

B,D	0 2	1
0 2	P₀₀	P₀₁
1	P₁₀	P₁₁

Local arrays for C:

p,q  |             0              |           1
-----|----------------------------|----------------------
     | -6.0  0.0  0.0  0.0  -2.0  |   0.0 -2.0 -2.0  0.0
     |   .  -6.0 -2.0  0.0  -2.0  |  -2.0 -4.0  0.0 -4.0
 0   |   .    .  -6.0 -2.0   6.0  |  -2.0  0.0  2.0  0.0
     |   .    .    .  -6.0   2.0  |   2.0  0.0  2.0  0.0
     |   .    .    .    .  -16.0  |    .    .    .    .
-----|----------------------------|----------------------
     |   .    .    .    .   0.0   |  -8.0 -4.0  0.0 -2.0
     |   .    .    .    .  -6.0   |    .  -6.0  0.0 -4.0
 1   |   .    .    .    .   0.0   |    .    .  -4.0  0.0
     |   .    .    .    .  -4.0   |    .    .    .  -4.0

Local Invocations of NUMROC:

p,q  |                      0                       |                       1
-----|----------------------------------------------|----------------------------------------------
     |             M_C  MB_C  MYROW  RSRC_C  NPROW  |              M_C  MB_C  MYROW  RSRC_C  NPROW
     |              |    |     |       |      |     |               |    |     |       |      |
     | MP = NUMROC( 9,   4,    0,      0,     2)    |  MP = NUMROC( 9,   4,    0,      0,     2)
 0   |                                              |
     |             N_C  NB_C  MYCOL  CSRC_C  NPCOL  |              N_C  NB_C  MYCOL  CSRC_C  NPCOL
     |              |    |     |       |      |     |               |    |     |       |      |
     | NQ = NUMROC( 9,   4,    0,      0,     2)    |  NQ = NUMROC( 9,   4,    1,      0,     2)
-----|----------------------------------------------|----------------------------------------------
     |             M_C  MB_C  MYROW  RSRC_C  NPROW  |              M_C  MB_C  MYROW  RSRC_C  NPROW
     |              |    |     |       |      |     |               |    |     |       |      |
     | MP = NUMROC( 9,   4,    1,      0,     2)    |  MP = NUMROC( 9,   4,    1,      0,     2)
 1   |                                              |
     |             N_C  NB_C  MYCOL  CSRC_C  NPCOL  |              N_C  NB_C  MYCOL  CSRC_C  NPCOL
     |              |    |     |       |      |     |               |    |     |       |      |
     | NQ = NUMROC( 9,   4,    0,      0,     2)    |  NQ = NUMROC( 9,   4,    1,      0,     2)

Output:

The local number of rows MP and columns NQ of the block-cyclically distributed matrix returned by NUMROC on each process:

p,q  |   0    |    1
-----|--------|--------
 0   |  MP=5  |   MP=5
     |  NQ=5  |   NQ=4
-----|--------|--------
 1   |  MP=4  |   MP=4
     |  NQ=5  |   NQ=4

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]