Routine names preceded by a lower case 'v' are type-dependent routines. The v is replaced as shown in the following table to arrive at the correct routine name for a given data type:

v MEANING ----- ------------------------------------------------ I Integer data is to be operated on. S Single precision real data is to be operated on. D Double precision real data is to be operated on. C Single precision complex data is to operated on. Z Double precision complex data is to operated on.

BLACS_PINFO ( MYPNUM, NPROCS ) BLACS_SETUP ( MYPNUM, NPROCS ) SETPVMTIDS ( NTASKS, TIDS ) BLACS_GET ( ICONTXT, WHAT, VAL ) BLACS_SET ( ICONTXT, WHAT, VAL ) BLACS_GRIDINIT( ICONTXT, ORDER, NPROW, NPCOL ) BLACS_GRIDMAP ( ICONTXT, USERMAP, LDUMAP, NPROW, NPCOL )

BLACS_FREEBUFF( ICONTXT, WAIT ) BLACS_GRIDEXIT( ICONTXT ) BLACS_ABORT ( ICONTXT, ERRORNUM ) BLACS_EXIT ( CONTINUE )

BLACS_GRIDINFO( ICONTXT, NPROW, NPCOL, MYPROW, MYPCOL ) BLACS_PNUM ( ICONTXT, PROW, PCOL ) BLACS_PCOORD ( ICONTXT, PNUM, PROW, PCOL )

BLACS_BARRIER( ICONTXT, SCOPE )

vGESD2D( ICONTXT, M, N, A, LDA, RDEST, CDEST ) vTRSD2D( ICONTXT, UPLO, DIAG, M, N, A, LDA, RDEST, CDEST )

vGERV2D( ICONTXT, M, N, A, LDA, RSRC, CSRC ) vTRRV2D( ICONTXT, UPLO, DIAG, M, N, A, LDA, RSRC, CSRC )

vGEBS2D( ICONTXT, SCOPE, TOP, M, N, A, LDA ) vTRBS2D( ICONTXT, SCOPE, TOP, UPLO, DIAG, M, N, A, LDA )

vGEBR2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RSRC, CSRC ) vTRBR2D( ICONTXT, SCOPE, TOP, UPLO, DIAG, M, N, A, LDA, RSRC, CSRC )

vGSUM2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RDEST, CDEST ) vGAMX2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RA, CA, RCFLAG, RDEST, CDEST ) vGAMN2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RA, CA, RCFLAG, RDEST, CDEST )

- MYPNUM
- (output) INTEGER

An integer between 0 and (NPROCS - 1) which uniquely identifies each process. - NPROCS
- (output) INTEGER

The number of processes available for BLACS use.

See EXAMPLE

- MYPNUM
- (output) INTEGER

An integer between 0 and (NPROCS - 1) which uniquely identifies each process. - NPROCS
- (input/output) INTEGER

On the process spawned from the keyboard (rather than from pvmspawn), this parameter is input, and indicates the number of processes to create when building the virtual machine. For all other processes, it will be output.

See EXAMPLE See blacs_setup.dat EXAMPLE

- NTASKS
- (input) INTEGER

The number of PVM tasks the user has spawned. - TIDS
- (input) INTEGER array of dimension (NTASKS)

This array contains the list of NTASKS PVM TIDS to participate in the BLACS.

The second argument required by SETPVMTIDS is a list of tids in an integer array of at least length NTASKS. All processes require these inputs. This means that in order to use SETPVMTIDS, the PVM user should spawn off all of his processes, keeping their TIDS in an integer array, then send that array to all participating processes, and finally have them all call SETPVMTIDS. At this point, he has performed the actions inherent in a BLACS_SETUP call, and he may then proceed to use the BLACS as usual (can make calls to BLACS_PINFO, and then to BLACS_GRIDINIT or BLACS_GRIDMAP, and then proceed with the normal BLACS code).

- ICONTXT
- (input/output) INTEGER

On input, an integer handle indicating the system context to be used in creating the BLACS context. The user may obtain a default system context via a call to BLACS_GET. On output, the integer handle to the created BLACS context. - ORDER
- (input) CHARACTER*1

Indicates how to map processes to BLACS grid. Choices are:

- 'R' : Use row-major natural ordering.
- 'C' : Use column-major natural ordering.
- ELSE: Use row-major natural ordering.

- NPROW
- (input) INTEGER

Indicates how many process rows the process grid should contain. - NPCOL
- (input) INTEGER

Indicates how many process columns the process grid should contain.

The creation of a grid requires input from all processes which are defined to be in it. It is therefore a globally blocking operation. Processes belonging to more than one grid will have to agree on which grid formation will be serviced first, much like the globally blocking sum or broadcast.

These grid creation routines set up various internals for the BLACS, and so one of them must be called before any calls are made to the non-initialization BLACS.

Note that these routines map already-existing processes to a grid: the processes are not created dynamically. On most parallel machines, the processes will be actual processors (hardware), and they are "created" when the user runs his executable. When using the PVM BLACS, if the virtual machine has not been set up yet, the routine BLACS_SETUP should be used to create the virtual machine. If the PVM user wishes to use a virtual machine he has already set up using explicit PVM calls, the routine SETPVMTIDS may be used.

This routine creates a simple `NPROW x NPCOL` process grid.
This process grid will use the first ` NPROW * NPCOL` processes,
and assign them to the grid in a row- or column-major natural ordering.
If these process-to-grid mappings are unacceptable, BLACS_GRIDINIT's more
complex sister routine BLACS_GRIDMAP must be called instead.

See EXAMPLE

- ICONTXT
- (input/output) INTEGER

On input, an integer handle indicating the system context to be used in creating the BLACS context. The user may obtain a default system context via a call to BLACS_GET. On output, the integer handle to the created BLACS context. - USERMAP
- (input) INTEGER array, dimension (LDUMAP, NPCOL)

Input array indicating the process-to-grid mapping. - LDUMAP
- (input) INTEGER, LDUMAP >= NPROW

The leading dimension of the 2D array USERMAP - NPROW
- (input) INTEGER

Indicates how many process rows the process grid should contain. - NPCOL
- (input) INTEGER

Indicates how many process columns the process grid should contain.

The creation of a grid requires input from all processes which are defined to be in it. It is therefore a globally blocking operation. Processes belonging to more than one grid will have to agree on which grid formation will be serviced first, much like the globally blocking sum or broadcast.

These grid creation routines set up various internals for the BLACS, and so one of them must be called before any calls are made to the non-initialization BLACS.

Note that these routines map already-existing processes to a grid: the processes are not created dynamically. On most parallel machines, the processes will be actual processors (hardware), and they are "created" when the user runs his executable. When using the PVM BLACS, if the virtual machine has not been set up yet, the routine BLACS_SETUP should be used to create the virtual machine. If the PVM user wishes to use a virtual machine he has already set up using explicit PVM calls, the routine SETPVMTIDS may be used.

This routine allows the user to map processes to the process grid in an arbitrary
manner. USERMAP(i,j) holds the process number of the process to be placed in
{i, j} of the process grid. On most distributed systems, this process number
will simply by a machine defined number between 0 ... NPROCS-1. For
PVM these node numbers will be the PVM TIDS (Task IDs).
BLACS_GRIDMAP is not for the
inexperienced user -- BLACS_GRIDINIT is much simpler. BLACS_GRIDINIT
simply performs a GRIDMAP where the first `NPROW * NPCOL` processes
are mapped into the current grid in a row-major natural ordering.
BLACS_GRIDMAP allows the experienced user to take advantage of his system's
actual layout (i.e. he can map nodes that are physically connected to be
neighbors in the BLACS grid, etc.). BLACS_GRIDMAP also opens the way for
{\it multigridding}: the user can separate his nodes into arbitrary grids,
join them together at some later date, and then re-split them into new grids.
BLACS_GRIDMAP also provides the ability to make arbitrary grids or subgrids
(e.g., a "nearest neighbor" grid), which can greatly facilitate operations among
processes which do not fall on a row or column of the main process grid.

See EXAMPLE

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context which is aborting. - ERRORNUM
- (input) INTEGER.

User defined integer error number.

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context to be freed.

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - SCOPE
- (input) CHARACTER*1.

Indicates whether a process row (`SCOPE='R'`), column (`'C'`), or entire grid (`'A'`) will participate in barrier.

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - NPROW
- (output) INTEGER.

On output, it contains the number of process rows in the current process grid. - NPCOL
- (output) INTEGER.

On output, it contains the number of process columns in the current process grid. - MYPROW
- (output) INTEGER.

On output, it contains the calling process's row coordinate in the process grid. - MYPCOL
- (output) INTEGER.

On output, it contains the calling process's column coordinate in the process grid.

See EXAMPLE

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - PNUM
- (input) INTEGER.

The process number who's coordinates are to be determined. This is the process number of the underlying machine (i.e., it will be a TID for PVM). - PROW
- (output) INTEGER.

On output, the row coordinate of process PNUM in the BLACS grid. - PCOL
- (output) INTEGER.

On output, the column coordinate of process PNUM in the BLACS grid.

See EXAMPLE

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - PROW
- (input) INTEGER.

The row coordinate of the process who's system process number is to be determined. - PCOL
- (input) INTEGER.

The column coordinate of the process who's system process number is to be determined.

See EXAMPLE

- ICONTXT
- (input) INTEGER.

On WHATs that are tied to a particular context, this is the integer handle indicating the context. Otherwise, it is ignored. - WHAT
- (input) INTEGER.

What BLACS internal(s) should be returned in VAL. Present options are:- WHAT = 0 : Handle indicating default system context;
- WHAT = 1 : The BLACS message ID range;
- WHAT = 2 : The BLACS debug level the library was compiled with;
- WHAT = 10: Handle indicating the system context used to define the BLACS context whose handle is ICONTXT;
- WHAT = 11: Number of rings multiring topology is presently using;
- WHAT = 12: Number of branches general tree topology is presently using.

- VAL
- (output) INTEGER.

The value the BLACS internal presently is.

BLACS_GET returns information on three quantities which are tied to an individual BLACS context, which is passed in as ICONTXT. The information which may be retrieved is:

- The handle of the system context upon which this BLACS context was defined.
- The number of rings for TOP = 'M' (multiring broadcast);
- The number of branches for TOP = 'T' (general tree broadcast/general tree gather).

See EXAMPLE

- ICONTXT
- (input) INTEGER.

On WHATs that are tied to a particular context, this is the integer handle indicating the context. Otherwise, it is ignored. - WHAT
- (input) INTEGER.

What BLACS internal should be set. Present values are:- 1 = The BLACS message ID range;
- 11 = number of rings for multiring topology to use;
- 12 = number of branches for general tree topology to use.

- VAL (input) INTEGER array of dimension (*)

- The value(s) to set internals to. Its specific meaning is dependent on WHAT, as discussed below.

- WHAT = 1 : Setting the BLACS message ID range

- If the user wishes to mix the BLACS with other message-passing
packages, he may restrict the BLACS to a certain message ID range,
which he ensures is not used by the non-BLACS routines.
The message ID range must be set
*before*the first call to BLACS_GRIDMAP or BLACS_GRIDINIT. Subsequent calls will have no effect. Because the message ID range is not tied to a particular context, the parameter ICONTXT is ignored, and VAL is defined as:- VAL (input) INTEGER array of dimension (2)

- VAL(1) : The smallest message ID (also called message type or
message tag) the BLACS should use.

- VAL(2) : The largest message ID (also called message type or
message tag) the BLACS should use.

- VAL (input) INTEGER array of dimension (2)
- WHAT = 11 : Set number of rings for TOP = 'M' (multiring broadcast)

- This quantity is tied to a context, thus ICONTXT is used,
and VAL is defined as:
- VAL (input) INTEGER array of dimension (1)

- VAL(1): The number of rings for multiring topology to use.

- VAL (input) INTEGER array of dimension (1)
- WHAT = 12 : Set number of branches for TOP = 'T'
(general tree broadcast/general tree gather).

- This quantity is tied to a context, thus ICONTXT is used,
and VAL is defined as:
- VAL (input) INTEGER array of dimension (1)

- VAL(1): The number of branches for general tree topology to use.

- VAL (input) INTEGER array of dimension (1)

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - WHAT
- (input) INTEGER.

Whether to wait on non-blocking operations or not.

The parameter WAIT determines whether the BLACS should wait for any non-blocking operations to complete or not. If WAIT = 0, the BLACS will free any buffers that can be freed without waiting. If WAIT is not 0, the BLACS will free all internal buffers, even if non-blocking operations must be completed first.

- CONTINUE
- (input) INTEGER.

If CONTINUE is non-zero, it is assume the user will continue using the machine after the BLACS are done. Otherwise, it is assumed that no message passing will be done after the BLACS_EXIT call.

See EXAMPLE

vGESD2D( ICONTXT, M, N, A, LDA, RDEST, CDEST )

vTRSD2D( ICONTXT, UPLO, DIAG, M, N, A, LDA, RDEST, CDEST )

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - UPLO, DIAG, M, N, A, LDA
- (input) These parameters describe the matrix to be sent. See MATRIX SHAPES for details.
- RDEST
- (input) INTEGER

The process row coordinate of the process to send the message to. - CDEST
- (input) INTEGER

The process column coordinate of the process to send the message to.

See EXAMPLE

vGERV2D( ICONTXT, M, N, A, LDA, RSRC, CSRC )

vTRRV2D( ICONTXT, UPLO, DIAG, M, N, A, LDA, RSRC, CSRC )

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - UPLO, DIAG, M, N, LDA
- (input) These parameters describe the matrix to be sent. See MATRIX SHAPES for details.
- A
- (output) array of dimension (LDA,N)

Array to receive the incoming message into. - RSRC
- (input) INTEGER

The process row coordinate of the source of the message. - CSRC
- (input) INTEGER

The process column coordinate of the source of the message.

See EXAMPLE

vGEBS2D( ICONTXT, SCOPE, TOP, M, N, A, LDA )

vTRBS2D( ICONTXT, SCOPE, TOP, UPLO, DIAG, M, N, A, LDA )

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - SCOPE
- (input) CHARACTER*1

Indicates what scope the broadcast should proceed on. Limited to 'Row', 'Column', or 'All'. - TOP
- (input) CHARACTER*1

Indicates the communication pattern to use for the broadcast. See BLACS TOPOLOGY for details. - UPLO, DIAG, M, N, A, LDA
- (input) These parameters describe the matrix to be sent. See MATRIX SHAPES for details.

See EXAMPLE

vGEBR2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RSRC, CSRC )

vTRBR2D( ICONTXT, SCOPE, TOP, UPLO, DIAG, M, N, A, LDA, RSRC, CSRC )

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - SCOPE
- (input) CHARACTER*1

Indicates what scope the broadcast should proceed on. Limited to 'Row', 'Column', or 'All'. - TOP
- (input) CHARACTER*1

Indicates the communication pattern to use for the broadcast. See BLACS TOPOLOGY for details. - UPLO, DIAG, M, N, LDA
- (input) These parameters describe the matrix to be sent. See MATRIX SHAPES for details.
- A array of dimension (LDA,N)

- (output)

Array to receive the incoming message into. - RSRC
- (input) INTEGER

The process row coordinate of the process who called broadcast/send. - CSRC
- (input) INTEGER

The process column coordinate of the process who called broadcast/send.

See EXAMPLE

vGSUM2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RDEST, CDEST )

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - SCOPE
- (input) CHARACTER*1

Indicates what scope the combine should proceed on. Limited to 'Row', 'Column', or 'All'. - TOP
- (input) CHARACTER*1

Indicates the communication pattern to use during the combine. See BLACS TOPOLOGY for details. - UPLO, DIAG, M, N, LDA
- (input) These parameters describe the matrix to be sent. See MATRIX SHAPES for details.
- A
- (input/output) array of dimension (LDA,N)

On input, the matrix to be added to produce the sum. On output, it contains the result (if this process is selected to receive the answer), or intermediate (useless) results (if process not selected to receive the result). - RDEST
- (input) INTEGER

The process row coordinate of the process who should receive the result. If RDEST = -1, all processes within the indicated scope receive the answer. - CDEST
- (input) INTEGER

The process column coordinate of the process who should receive the result. If RDEST = -1, CDEST is ignored.

See EXAMPLE

vGAMX2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RA, CA, RCFLAG, RDEST, CDEST )

vGAMN2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RA, CA, RCFLAG, RDEST, CDEST )

- ICONTXT
- (input) INTEGER.

Integer handle indicating the context. - SCOPE
- (input) CHARACTER*1

Indicates what scope the combine should proceed on. Limited to 'Row', 'Column', or 'All'. - TOP
- (input) CHARACTER*1

Indicates the communication pattern to use during the combine. See BLACS TOPOLOGY for details. - UPLO, DIAG, M, N, LDA
- (input) These parameters describe the matrix to be operated on. See MATRIX SHAPES for details.
- RCFLAG
- (input) INTEGER

If RCFLAG = -1, then the arrays RA and CA are not referenced and need not exist. Otherwise, RCFLAG indicates the leading dimension of these arrays, and so must be >= M. - A
- (input/output) array of dimension (LDA,N)

On input, the matrix to be compared with to produce the max/min. On output, it contains the result (if this process is selected to receive the answer), or intermediate (useless) results (if process not selected to receive the result). - RA
- (output) INTEGER array of dimension (RCFLAG,N)

If RCFLAG = -1, this array will not be referenced, and need not exist. Otherwise it is an integer array (of size at least RCFLAG x N) indicating the row index of the process that provided the maximum/minimum. If the calling process is not selected to receive the result, this array will contain intermediate (useless) results. - CA
- (output) INTEGER array of dimension (LDIA,N)

If RCFLAG = -1, this array will not be referenced, and need not exist. Otherwise it is an integer array (of size at least RCFLAG x N) indicating the column index of the process that provided the maximum/minimum. If the calling process is not selected to receive the result, this array will contain intermediate (useless) results. - RDEST
- (input) INTEGER

The process row coordinate of the process who should receive the result. If RDEST = -1, all processes within the indicated scope receive the answer. - CDEST
- (input) INTEGER

The process column coordinate of the process who should receive the result. If RDEST = -1, CDEST is ignored.

See EXAMPLE