tclmpi Namespace Reference

Functions
proc	init ()
proc	initialized ()
proc	conv_set (handler)
proc	conv_get (handler)
proc	finalize ()
proc	finalized ()
proc	abort (comm, errorcode)
proc	comm_size (comm)
proc	comm_rank (comm)
proc	comm_split (comm, color, key)
proc	comm_free (comm)
proc	barrier (comm)
proc	bcast (data, type, root, comm)
proc	scatter (data, type, root, comm)
proc	allgather (data, type, comm)
proc	gather (data, type, root, comm)
proc	allreduce (data, type, op, comm)
proc	reduce (data, type, op, root, comm)
proc	send (data, type, dest, tag, comm)
proc	isend (data, type, dest, tag, comm)
proc	recv (type, source, tag, comm, status={})
proc	irecv (type, source, tag, comm)
proc	probe (source, tag, comm, status={})
proc	wait (request, status={})
proc	waitall (requests, status={})

Variables
variable	version = "1.2"
	version number of this package
variable	auto = tclmpi::auto
	constant for automatic data type
variable	int = tclmpi::int
	constant for integer data type
variable	intint = tclmpi::intint
	constant for integer pair data type
variable	double = tclmpi::double
	constant for double data type
variable	dblint = tclmpi::dblint
	constant for double/int pair data type
variable	comm_world = tclmpi::comm_world
	constant for world communicator
variable	comm_self = tclmpi::comm_self
	constant for self communicator
variable	comm_null = tclmpi::comm_null
	constant empty communicator
variable	any_source = tclmpi::any_source
	constant to accept messages from any source rank
variable	any_tag = tclmpi::any_tag
	constant to accept messages with any tag
variable	sum = tclmpi::sum
	summation operation
variable	prod = tclmpi::prod
	product operation
variable	max = tclmpi::max
	maximum operation
variable	min = tclmpi::min
	minimum operation
variable	land = tclmpi::land
	logical and operation
variable	band = tclmpi::band
	bitwise and operation
variable	lor = tclmpi::lor
	logical or operation
variable	bor = tclmpi::bor
	bitwise or operation
variable	lxor = tclmpi::lxor
	logical xor operation
variable	bxor = tclmpi::bxor
	bitwise xor operation
variable	maxloc = tclmpi::maxloc
	maximum and location operation
variable	minloc = tclmpi::minloc
	minimum and location operation
variable	error = tclmpi::error
	throw a Tcl error when a data conversion fails
variable	abort = tclmpi::abort
	call MPI_Abort() when a data conversion fails
variable	tozero = tclmpi::tozero
	silently assign zero for failed data conversions
variable	undefined = tclmpi::undefined
	constant to indicate an undefined number

Detailed Description

TclMPI package Tcl namespace

Function Documentation

abort()

proc tclmpi::abort	(	comm	,
		errorcode
	)

Terminates the MPI environment from Tcl

Parameters

comm	Tcl representation of an MPI communicator
errorcode	an integer that will be returned as exit code to the OS

This command makes a best attempt to abort all tasks sharing the communicator and exit with the provided error code. Only one task needs to call tclmpi::abort. This command terminates the program, so there can be no return value.

For implementation details see TclMPI_Abort().

allgather()

proc tclmpi::allgather	(	data	,
		type	,
		comm
	)

Collects data from all processes on the communicator

Parameters

data	data to be distributed (Tcl data object)
type	data type to be used (string constant)
comm	Tcl representation of an MPI communicator

Returns

data that was collected or empty

This command collects data the provided list from all processes sharing the communicator. The data argument has to be present on all processes and has to be of the same length. The data resulting from the gather will be stored in the return value of the command for all processes. This function call is an implicit synchronization.

For implementation details see TclMPI_Allgather().

allreduce()

proc tclmpi::allreduce	(	data	,
		type	,
		op	,
		comm
	)

Combines data from all processes and distributes the result back to them

Parameters

data	data to be reduced (Tcl data object)
type	data type to be used (string constant)
op	reduction operation (string constant)
comm	Tcl representation of an MPI communicator

Returns

data resulting from the reduction operation

This command performs a global reduction operation op on the provided data object across all processes participating in the communicator comm. If data is a list, then the reduction will be done across each respective entry of the same list index. The result is distributed to all processes and used as return value of the command. This command only supports the data types tclmpi::int and tclmpi::double and tclmpi::intint for operations tclmpi::maxloc and tclmpi::minloc. The following reduction operations are supported: tclmpi::max (maximum), tclmpi::min (minimum), tclmpi::sum (sum), tclmpi::prod (product), tclmpi::land (logical and), tclmpi::band (bitwise and), tclmpi::lor (logical or), tclmpi::bor (bitwise or), tclmpi::lxor (logical exclusive or), tclmpi::bxor (bitwise exclusive or), tclmpi::maxloc (max value and location), tclmpi::minloc (min value and location). This function call is an implicit synchronization.

For implementation details see TclMPI_Allreduce().

barrier()

proc tclmpi::barrier

(

comm

)

Synchronize MPI processes

Parameters

comm	Tcl representation of an MPI communicator

Blocks the caller until all processes sharing the communicator have called it; the call returns at any process only after all processes have entered the call and thus effectively synchronizes the processes. This function has no return value.

For implementation details see TclMPI_Barrier().

bcast()

proc tclmpi::bcast	(	data	,
		type	,
		root	,
		comm
	)

Broadcasts data from one process to all processes on the communicator

Parameters

data	data to be broadcast (Tcl data object)
type	data type to be used (string constant)
root	rank of process that is providing the data (integer)
comm	Tcl representation of an MPI communicator

Returns

data that was broadcast

This command broadcasts the provided data object (list or single number or string) from the process with rank root on the communicator comm to all processes sharing the communicator. The data argument has to be present on all processes but will be ignored on all but the root process. The data resulting from the broadcast will be stored in the return value of the command on all processes. This is important when the data type is not tclmpi::auto, since using other data types may incur an irreversible conversion of the data elements. This function call is an implicit synchronization.

For implementation details see TclMPI_Bcast().

comm_free()

proc tclmpi::comm_free

(

comm

)

Deletes a dynamically created communicator and frees its resources

Parameters

comm	Tcl representation of an MPI communicator

This operation marks the MPI communicator associated with it Tcl representation comm for deallocation by the underlying MPI library. Any pending communications using this communicator will still complete normally.

For implementation details see TclMPI_Comm_free().

comm_rank()

proc tclmpi::comm_rank

(

comm

)

Returns the rank of the current process in an MPI communicator

Parameters

comm	Tcl representation of an MPI communicator

Returns

rank on the communicator (integer between 0 and size-1)

This function gives the rank of the process in the particular communicator. Many programs will be written with a manager-worker model, where one process (such as the rank-zero process) will play a supervisory role, and the other processes will serve as compute nodes. In this framework, tclmpi::comm_size and tclmpi::comm_rank are useful for determining the roles of the various processes of a communicator.

For implementation details see TclMPI_Comm_rank().

comm_size()

proc tclmpi::comm_size

(

comm

)

Returns the number of processes involved in an MPI communicator

Parameters

comm	Tcl representation of an MPI communicator

Returns

number of MPI processes on communicator

This function indicates the number of processes involved in a communicator. For tclmpi::comm_world, it indicates the total number of processes available. This call is often used in combination with tclmpi::comm_rank to determine the amount of concurrency available for a specific library or program. tclmpi::comm_rank indicates the rank of the process that calls it in the range from 0...size-1, where size is the return value of tclmpi::comm_size.

For implementation details see TclMPI_Comm_size().

comm_split()

proc tclmpi::comm_split	(	comm	,
		color	,
		key
	)

Creates new communicators based on "color" and "key" flags

Parameters

comm	Tcl representation of an MPI communicator
color	subset assignment (non-negative integer or tclmpi::undefined)
key	relative rank assignment (integer)

Returns

Tcl representation of the newly created MPI communicator

This function partitions the group associated with comm into disjoint subgroups, one for each value of color. Each subgroup contains all processes of the same color. Within each subgroup, the processes are ranked in the order defined by the value of the argument key, with ties broken according to their rank in the old group. A new communicator is created for each subgroup and returned in newcomm. A process may supply the color value tclmpi::undefined, in which case the function returns tclmpi::comm_null. This is a collective call, but each process is permitted to provide different values for color and key.

The following example shows how to construct a communicator where the ranks are reversed in comparison to the world communicator.

set comm tclmpi::comm_world
set size [::tclmpi::comm_size $comm]
set key  [::tclmpi::comm_rank $comm]
set revcomm [::tclmpi::comm_split $comm 1 $key]

For implementation details see TclMPI_Comm_split().

conv_get()

proc tclmpi::conv_get

(

handler

)

Return a string constant naming the error handler for TclMPI data conversions

Returns

string constant for error handler

This function allows to query which error handler is currently active for Tcl data conversions inside TclMPI. For details on the error handlers, see tclmpi::conv_set.

For implementation details see TclMPI_Conv_get().

conv_set()

proc tclmpi::conv_set

(

handler

)

Set the error handler for TclMPI data conversions

Parameters

handler

string constant for error handler

This function sets what action TclMPI should take if a data conversion to tclmpi::int or tclmpi::double fails. When using data types other than tclmpi::auto, the corresponding data needs to be converted from the internal Tcl representatin to the selected native format. However, this does not always succeed for a variety of reasons. With this function TclMPI allows the programmer to define how this is handled. There are currently three handlers available: tclmpi::error (the default setting), tclmpi::abort, and tclmpi::tozero. For tclmpi::error a Tcl error is raised that can be intercepted with catch and TclMPI immediately returns to the calling function. For tclmpi::abort an error message is written directly to the screen and parallel execution on the current communicator is terminated via MPI_Abort(). For tclmpi::tozero the error is silently ignored and the data element set to zero. This command has no return value.

For implementation details see TclMPI_Conv_set().

finalize()

proc tclmpi::finalize

(

)

Shut down the MPI environment from Tcl

This command closes the MPI environment and cleans up all MPI states. All processes much call this routine before exiting. Calling this function before calling tclmpi::init is an error. After calling this function, no more TclMPI commands including tclmpi::finalize and tclmpi::init may be used. This command takes no arguments and has no return value.

For implementation details see TclMPI_Finalize().

finalized()

proc tclmpi::finalized

(

)

Check if MPI environment was finalized from Tcl

Returns

boolean value of whether MPI has been shut down

This command checks if tclmpi::finalize has already been called or whether the MPI environment has been shut down otherwise. Since initializing MPI multiple times is an error, you can call this function to determine whether you need to call tclmpi::finalize and whether it is (still) allowed to call tclmpi::init in your Tcl script. This command takes no arguments.

For implementation details see TclMPI_Finalized().

gather()

proc tclmpi::gather	(	data	,
		type	,
		root	,
		comm
	)

Collects data from all processes on the communicator

Parameters

data	data to be distributed (Tcl data object)
type	data type to be used (string constant)
root	rank of process that will receive the data (integer)
comm	Tcl representation of an MPI communicator

Returns

data that was collected or empty

This command collects data the provided list from the process with rank root on the communicator comm to all processes sharing the communicator. The data argument has to be present on all processes and has to be of the same length. The data resulting from the gather will be stored in the return value of the command on the root process. This function call is an implicit synchronization. This procedure is the reverse operation of tclmpi::scatter.

For implementation details see TclMPI_Gather().

init()

proc tclmpi::init

(

)

Initialize the MPI environment from Tcl

This command initializes the MPI environment. Needs to be called before any other TclMPI commands. MPI can be initialized at most once, so calling tclmpi::init multiple times is an error. Like in the C bindings for MPI, tclmpi::init will scan the argument vector, the global variable $argv, for any MPI implementation specific flags and will remove them. The global variable $argc will be adjusted accordingly. This command takes no arguments and has no return value.

For implementation details see TclMPI_Init().

initialized()

proc tclmpi::initialized

(

)

Check if MPI environment is initialized from Tcl

Returns

boolean value of whether MPI has been initialized

This command checks if tclmpi::init has already been called or whether the MPI environment has been set up otherwise. Since initializing MPI multiple times is an error, you can call this function to determine whether you need to call tclmpi::init in your Tcl script. This command takes no arguments.

For implementation details see TclMPI_Initalized().

irecv()

proc tclmpi::irecv	(	type	,
		source	,
		tag	,
		comm
	)

Initiate a non-blocking receive

Parameters

type	data type to be used (string constant)
source	rank of sending process or tclmpi::any_source
tag	message identification tag or tclmpi::any_tag
comm	Tcl representation of an MPI communicator

Returns

Tcl representation of generated MPI request

This procedure provides a non-blocking receive operation, i.e. it returns immediately. The call does not return any data but a request handle of the form tclmpi::req#, with # being a unique integer number. This request handle is best stored in a variable and needs to be passed to a tclmpi::wait call to wait for completion of the receive and pass the data to the calling code as return value of the wait call. The type argument has to match that of the corresponding send command. Instead of a specific source rank, the constant tclmpi::any_source can be used and similarly tclmpi::any_tag as tag, to not select on source rank or tag, respectively.

For implementation details see TclMPI_Irecv().

isend()

proc tclmpi::isend	(	data	,
		type	,
		dest	,
		tag	,
		comm
	)

Perform a non-blocking send

Parameters

data	data to be sent (Tcl data object)
type	data type to be used (string constant)
dest	rank of destination process (non-negative integer)
tag	message identification tag (integer)
comm	Tcl representation of an MPI communicator

Returns

Tcl representation of generated MPI request

This function performs a regular non-blocking send to process rank dest on communicator comm. The choice of data type determines how data is being sent and thus unlike in the C-bindings the corresponding receive has to use the same data data type. As a non-blocking call, the function will return immediately. The return value is a string representing the generated MPI request and it can be passed to a call to tclmpi::wait in order to wait for its completion and release all reserved storage associated with the request.

For implementation details see TclMPI_Isend().

probe()

proc tclmpi::probe	(	source	,
		tag	,
		comm	,
		status	= {}
	)

Blocking test for a message

Parameters

source	rank of sending process or tclmpi::any_source
tag	message identification tag or tclmpi::any_tag
comm	Tcl representation of an MPI communicator
status	variable name for status array (string)

Returns

empty

This function allows to check for an incoming message on the communicator comm without actually receiving it. Nevertheless, this call is blocking, i.e. it will not return unless there is actually a message pending that matches the requirements of source rank and message tag. Instead of a specific source rank, the constant tclmpi::any_source can be used and similarly tclmpi::any_tag as tag, to accept send requests from any rank or tag, respectively. The (optional) status argument would be the name of a variable in which status information about the message will be stored in the form of an array. This associative array has the entries MPI_SOURCE (rank of sender), MPI_TAG (tag of message), COUNT_CHAR (size of message in bytes), COUNT_INT (size of message in tclmpi::int units), COUNT_DOUBLE (size of message in tclmpi::double units).

For implementation details see TclMPI_Probe().

recv()

proc tclmpi::recv	(	type	,
		source	,
		tag	,
		comm	,
		status	= {}
	)

Perform a blocking receive

Parameters

type	data type to be used (string constant)
source	rank of sending process or tclmpi::any_source
tag	message identification tag or tclmpi::any_tag
comm	Tcl representation of an MPI communicator
status	variable name for status array (string)

Returns

the received data

This procedure provides a blocking receive operation, i.e. it only returns after the message is received in full. The received data will be passed as return value. The type argument has to match that of the corresponding send command. Instead of using a specific source rank, the constant tclmpi::any_source can be used and similarly tclmpi::any_tag as tag. This way the receive operation will not select a message based on source rank or tag, respectively. The (optional) status argument would be the name of a variable in which status information about the receive will be stored in the form of an array. The associative array has the entries MPI_SOURCE (rank of sender), MPI_TAG (tag of message), COUNT_CHAR (size of message in bytes), COUNT_INT (size of message in tclmpi::int units), COUNT_DOUBLE (size of message in tclmpi::double units).

For implementation details see TclMPI_Recv().

reduce()

proc tclmpi::reduce	(	data	,
		type	,
		op	,
		root	,
		comm
	)

Combines data from all processes on one process

Parameters

data	data to be reduced (Tcl data object)
type	data type to be used (string constant)
op	reduction operation (string constant)
root	rank of process that is receiving the result (integer)
comm	Tcl representation of an MPI communicator

Returns

data resulting from the reduction operation

This command performs a global reduction operation op on the provided data object across all processes participating in the communicator comm. If data is a list, then the reduction will be done across each respective entry of the same list index. The result is collect on the process with rank root and used as return value of the command. For all other processes the return value is empty. This command only supports the data types tclmpi::int and tclmpi::double and tclmpi::intint for operations tclmpi::maxloc and tclmpi::minloc. The following reduction operations are supported: tclmpi::max (maximum), tclmpi::min (minimum), tclmpi::sum (sum), tclmpi::prod (product), tclmpi::land (logical and), tclmpi::band (bitwise and), tclmpi::lor (logical or), tclmpi::bor (bitwise or), tclmpi::lxor (logical exclusive or), tclmpi::bxor (bitwise exclusive or), tclmpi::maxloc (max value and location), tclmpi::minloc (min value and location). This function call is an implicit synchronization.

For implementation details see TclMPI_Reduce().

scatter()

proc tclmpi::scatter	(	data	,
		type	,
		root	,
		comm
	)

Distributes data from one process to all processes on the communicator

Parameters

data	data to be distributed (Tcl data object)
type	data type to be used (string constant)
root	rank of process that is providing the data (integer)
comm	Tcl representation of an MPI communicator

Returns

data that was distributed

This command distributes the provided list of data from the process with rank root on the communicator comm to all processes sharing the communicator. The data argument has to be present on all processes but will be ignored on all but the root process. The data resulting from the scatter will be stored in the return value of the command. The data will be distributed evenly, so the length of the list has to be divisible by the number of processes on the communicator. This procedure is the reverse operation of tclmpi::gather. This function call is an implicit synchronization.

For implementation details see TclMPI_Scatter().

send()

proc tclmpi::send	(	data	,
		type	,
		dest	,
		tag	,
		comm
	)

Perform a blocking send

Parameters

data	data to be sent (Tcl data object)
type	data type to be used (string constant)
dest	rank of destination process (non-negative integer)
tag	message identification tag (integer)
comm	Tcl representation of an MPI communicator

This function performs a regular blocking send to process rank dest on communicator comm. The choice of data type determines how data is being sent and thus unlike in the C-bindings the corresponding receive has to use the same data data type. As a blocking call, the function will only return when all data is sent. This function has no return value.

For implementation details see TclMPI_Send().

wait()

proc tclmpi::wait	(	request	,
		status	= {}
	)

Non-blocking test for a message

Parameters

source	rank of sending process or tclmpi::any_source
tag	message identification tag or tclmpi::any_tag
comm	Tcl representation of an MPI communicator
status	variable name for status array (string)

Returns

1 or 0 depending on whether a pending request was detected

This function allows to check for an incoming message on the communicator comm without actually receiving it. Unlike tclmpi::probe, this call is non-blocking, i.e. it will return immediately and report whether there is a message pending or not in its return value (1 or 0, respectively). Instead of a specific source rank, the constant tclmpi::any_source can be used and similarly tclmpi::any_tag as tag, to test for send requests from any rank or tag, respectively. The (optional) status argument would be the name of a variable in which status information about the message will be stored in the form of an array. This associative array has the entries MPI_SOURCE (rank of sender), MPI_TAG (tag of message), COUNT_CHAR (size of message in bytes), COUNT_INT (size of message in tclmpi::int units), COUNT_DOUBLE (size of message in tclmpi::double units).

For implementation details see TclMPI_Iprobe(). Wait for MPI request completion

Parameters

request	Tcl representation of an MPI request
status	variable name for status array (string)

Returns

empty or received data that was associated with the request

This function takes a communication request created by a non-blocking send or receive call (tclmpi::isend or tclmpi::irecv) and waits for its completion. In case of a send, it will merely wait until the matching communication is completed and any resources associated with the request will be releaseed. If the request was generated by a non-blocking receive call, tclmpi::wait will hand the received data to the calling routine in its return value. The (optional) status argument would be the name of a variable in which the resulting status information will be stored in the form of an associative array. The associative array will have the entries MPI_SOURCE (rank of sender), MPI_TAG (tag of message), COUNT_CHAR (size of message in bytes), COUNT_INT (size of message in tclmpi::int units), COUNT_DOUBLE (size of message in tclmpi::double units).

For implementation details see TclMPI_Wait().

waitall()

proc tclmpi::waitall	(	requests	,
		status	= {}
	)

Wait for multiple MPI request completions

Parameters

requests	List of Tcl representations of an MPI request
status	variable name to store list with deserialization of the status arrays (string)

Returns

empty or list of received data that was associated with the request

This function takes a list communication requests created by non-blocking send or receive calls (tclmpi::isend or tclmpi::irecv) and waits for the completion of all of them. In case of a send, it will merely wait until the matching communication is completed and any resources associated with the request will be releaseed. If the request was generated by a non-blocking receive call, tclmpi::wait will hand the received data to the calling routine in its return value. The (optional) status argument would be the name of a variable in which the resulting status information will be stored in the form of a list of lists, one entry per request. The corresponding associative arrays - like they are created by tclmpi::wait - can reconstituted using the array set command.

::tclmpi::waitall [list $req1 $req2] status
array set status1 [lindex $status 0]
array set status2 [lindex $status 1]

This call is implemented in Tcl as a wrapper around tclmpi::wait