Clicking on the name of a routine will take you to description of that routine and its parameters. After the description of the routine, there will be an option to view an example of its use. If you choose to view this example, the call to the selected BLACS routine will be at the top of your screen, so you will probably want to scroll upward in order to see the code before the call.
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 )
BLACS_PINFO( MYPNUM, NPROCS )
This routine is used when some initial system information is required before the BLACS are set up. On all platforms except PVM, NPROCS is the actual number of processes available for use (i.e. NPROWS * NPCOLS <= NPROCS). In PVM, the virtual machine may not have been set up before this call, and therefore no parallel machine exists. In this case, NPROCS will be returned as less than one. If a process has been spawned via the keyboard, it will receive MYPNUM of 0, and all other processes will get MYPNUM of -1. This allows the user to distinguish between processes, so that only one reads in data, etc. Only after the virtual machine has been set up (via a call to BLACS_SETUP or SETPVMTIDS) will this routine return the correct values for MYPNUM and NPROCS.
See EXAMPLE
BLACS_SETUP( MYPNUM, NPROCS )
This routine only accomplishes meaningful work in the PVM BLACS. On all other platforms, it is functionally equivalent to BLACS_PINFO. The BLACS assume a static system: you start with a given number of processes, and that is all you will ever have. PVM supplies a dynamic system, allowing processes to be added to the system on the fly. BLACS_SETUP is used to actually allocate the virtual machine and spawn off processes. It reads in a file called blacs_setup.dat, who's first line must be the name of your executable. The second line is optional, but if it exists, it should be a PVM spawn flag. Legal values at this time are 0 (PvmTaskDefault), 4 (PvmTaskDebug), 8 (PvmTaskTrace), and 12 (PvmTaskDebug + PvmTaskTrace). The primary reason for this line is to allow the user to easily turn on and off PVM debugging. Additional lines, if any, specify what machines should be added to the current configuration before spawning NPROCS-1 processes to the machines in a round robin fashion. NPROCS is input on the process which has no PVM parent (i.e. MYPNUM=0), and both parameters are output for all processes. Therefore, on PVM systems, the call to BLACS_PINFO informs you that the virtual machine has not been set up, and a call to BLACS_SETUP then sets up the machine and returns the real values for MYPNUM and NPROCS. Note that if the file blacs_setup.dat does not exist, the BLACS will prompt the user for the executable name, and processes will be spawned to the current PVM configuration.
See EXAMPLE See blacs_setup.dat EXAMPLE
SETPVMTIDS( NTASKS, TIDS )
SETPVMTIDS, as its name implies, is a PVM specific routine. SETPVMTIDS is the advanced PVM user's BLACS_SETUP. BLACS_SETUP may be too restrictive for someone who is using PVM outside the BLACS. For example, they may want to start the main process (process {0,0}) via a call to pvm_spawn, rather than starting it from the keyboard as BLACS_SETUP requires. SETPVMTIDS requires two parameters from the user. The first is the total number of processes (or tasks) that any BLACS grid will use. Remember that the BLACS is a static system: if you have P processes at the beginning of its execution, you must have those same P processes when the BLACS finish execution. Therefore, the user must set NTASKS to be the largest number of nodes of any grid he will use.
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).
BLACS_GRIDINIT( ICONTXT, ORDER, NPROW, NPCOL )
All BLACS codes must call this routine, or its sister routine BLACS_GRIDMAP. These routines take the available processes, and assign, or map, them into a BLACS process grid. In other words, they establish how the BLACS coordinate system will map into the native machine's process numbering system. Each BLACS grid is contained in a context (its own message passing universe), so that it does not interfere with distributed operations which occur within other grids/contexts. These grid creation routines may be called repeatedly in order to define additional contexts/grids.
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
BLACS_GRIDMAP( ICONTXT, USERMAP, LDUMAP, NPROW, NPCOL )
All BLACS codes must call this routine, or its sister routine BLACS_GRIDINIT. These routines take the available processes, and assign, or map, them into a BLACS process grid. In other words, they establish how the BLACS coordinate system will map into the native machine's process numbering system. Each BLACS grid is contained in a context (its own message passing universe), so that it does not interfere with distributed operations which occur within other grids/contexts. These grid creation routines may be called repeatedly in order to define additional contexts/grids.
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
BLACS_ABORT( ICONTXT, ERRORNUM )
When a catastrophic error occurs, the user may need to abort all processes. BLACS_ABORT exists for this reason. Note that both parameters are input, but that BLACS_ABORT uses them only in printing out the error message. The context handle passed in may be anything (i.e., it need not be a valid context handle). This routine kills all BLACS processes, not just those confined to a particular context.
BLACS_GRIDEXIT( ICONTXT )
Contexts consume resources, and therefore the user should release them when they are no longer needed. BLACS_GRIDEXIT frees a context. After the freeing of a context, the context no longer exists, and its handle may be re-used if new contexts are defined.
BLACS_BARRIER( ICONTXT, SCOPE )
This routines holds up execution of all processes within the indicated scope until they have all called the routine.
BLACS_GRIDINFO( ICONTXT, NPROW, NPCOL, MYPROW, MYPCOL )
Returns information on the current grid. If the context handle does not point at a valid context, all quantities are returned as -1.
See EXAMPLE
BLACS_PCOORD( ICONTXT, PNUM, PROW, PCOL )
Given the system process number, returns the row and column coordinates in the BLACS' process grid.
See EXAMPLE
INTEGER FUNCTION BLACS_PNUM( ICONTXT, PROW, PCOL )
This function returns the system process number of the process at {PROW, PCOL} in the process grid.
See EXAMPLE
BLACS_GET( ICONTXT, WHAT, VAL )
Gets the values the BLACS are using for internal defaults. Some values are tied to a BLACS context, and some are more general. The most common use is in retrieving a default system context for input into BLACS_GRIDINIT or BLACS_GRIDMAP. Some systems, such as MPI, supply their own version of context. For those users who mix system code with BLACS code, we therefore need to be able to form a BLACS context in reference to a system context. Thus, the grid creation routines take a system context as input. If you wish to have strictly portable code, you may use BLACS_GET to retrieve a default system context which will include all available processes. This value is not tied to a BLACS context, obviously, so the parameter ICONTXT is unused.
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:
See EXAMPLE
BLACS_SET( ICONTXT, WHAT, VAL )
Sets BLACS internal defaults. The action taken is dependent upon WHAT, as follows:
BLACS_FREEBUFF( ICONTXT, WAIT )
The BLACS have at least one internal buffer that is used for packing messages (the number of internal buffers depends on what platform you are running the BLACS on). On systems where memory is tight, keeping this buffer(s) around may become expensive. Calling this routine will release the BLACS buffer. However, the next call to a communication routine which requires packing will cause the buffer to be reallocated.
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.
BLACS_EXIT( CONTINUE )
This routine should be called when a process has finished all use of the BLACS. It frees all BLACS contexts and releases all memory the BLACS have allocated. CONTINUE indicates whether the user will be using the underlying communication platform after the BLACS are finished. This information is most important for the PVM BLACS. If CONTINUE is set to 0, then pvm_exit will be called; otherwise, it will not. If the user sets CONTINUE not equal to 0, he is indicating that he will be calling explicit PVM send/recvs after the BLACS are done, so that the process cannot tell the virtual machine that it is done. It then becomes the user's responsibility to make sure his code calls pvm_exit. PVM users should either call BLACS_EXIT or explicitly call pvm_exit to avoid PVM problems.
See EXAMPLE
vGESD2D( ICONTXT, M, N, A, LDA, RDEST, CDEST ) vTRSD2D( ICONTXT, UPLO, DIAG, M, N, A, LDA, RDEST, CDEST )
These calls take the indicated matrix and send it to the destination process located at {RDEST, CDEST} in the process grid. Return from the routine indicates that the buffer (the matrix A) may be reused. The routine is locally blocking, i.e. it will return even if the corresponding receive is not posted.
See EXAMPLE
vGERV2D( ICONTXT, M, N, A, LDA, RSRC, CSRC ) vTRRV2D( ICONTXT, UPLO, DIAG, M, N, A, LDA, RSRC, CSRC )
These calls receive a message from process {RSRC, CSRC} into the matrix A. This routine is globally-blocking, i.e. return from the routine indicates that the message has been received into A.
See EXAMPLE
vGEBS2D( ICONTXT, SCOPE, TOP, M, N, A, LDA ) vTRBS2D( ICONTXT, SCOPE, TOP, UPLO, DIAG, M, N, A, LDA )
These routines start a broadcast along a scope. All other processes within the scope must call broadcast/receive for the broadcast to proceed. At the end of a broadcast, all processes within the scope will possess the data in the matrix A. Broadcasts may be globally-blocking. This means no process is guaranteed to return from a broadcast until all processes in the scope have called the appropriate routine (broadcast/send or broadcast/receive).
See EXAMPLE
vGEBR2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RSRC, CSRC ) vTRBR2D( ICONTXT, SCOPE, TOP, UPLO, DIAG, M, N, A, LDA, RSRC, CSRC )
These routines receive and participate in a broadcast along a scope. At the end of a broadcast, all processes within the scope will possess the data in the matrix A. Broadcasts may be globally-blocking. This means no process is guaranteed to return from a broadcast until all processes in the scope have called the appropriate routine (broadcast/send or broadcast/receive).
See EXAMPLE
vGSUM2D( ICONTXT, SCOPE, TOP, M, N, A, LDA, RDEST, CDEST )
The sum is element-wise, i.e., each element of A is summed with the corresponding element of the other process's matrices. Combines may be globally-blocking, so they must be programmed as if no process returns until all have called the routine.
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 )
Performs an elementwise absolute value max/min, i.e., each element of A is compared with the corresponding element of the other process's matrices. Remember: the value of A is returned, but the absolute value is used to determine the max/min (the 1-norm is used for complex numbers). Combines may be globally-blocking, so they must be programmed as if no process returns until all have called the routine.
See EXAMPLE