module Mpi:sig
..end
exception Error of string
Mpi
module encounters an error.
The string argument describes the error.type
communicator
typerank =
int
val comm_world : communicator
val comm_size : communicator -> int
val comm_rank : communicator -> rank
Mpi.comm_rank c
is between 0 (inclusive) and
Mpi.comm_size c
(exclusive).typetag =
int
0 .. 32767
.val send : 'a -> rank -> tag -> communicator -> unit
Mpi.send d dst tag comm
sends a message containing data d
to the node that has rank dst
in communicator comm
.
The message is sent with tag tag
. Depending on the
underlying MPI implementation, message sending can be
synchronous or asynchronous; that is, Mpi.send
can block
until the target node receives the message, or Mpi.send
can return before the target node has received the message.val receive : rank -> tag -> communicator -> 'a
Mpi.receive src tag comm
blocks until a message is available,
and returns the data contained in that message.
The src
argument selects the desired source for the message:
if src
is Mpi.any_source
, messages from any node in communicator
comm
are accepted; otherwise, only messages sent by the node
having rank src
in comm
are accepted.
Similarly, the tag
argument selects messages by their tag:
if tag
is Mpi.any_tag
, messages are accepted regardless of
their tags; otherwise, only messages with tag equal to tag
are accepted.
Warning: just like the Marshal.from_*
functions,
Mpi.receive
is not type-safe. The Caml value returned by
Mpi.receive
does not possess type 'a
for all 'a
; it has one, unique type which cannot be determined
at compile-type. The programmer should be careful about using
the returned value with the right type.
val receive_status : rank -> tag -> communicator -> 'a * rank * tag
Mpi.receive
, but returns a triple (d, src, tag)
where d
is the data associated with the message,
src
the rank of the node that sent the message,
and tag
the actual tag attached to the message.val probe : rank -> tag -> communicator -> rank * tag
Mpi.probe src tag comm
blocks until a message is available
on communicator comm
, with source and tag matching the
src
and tag
arguments as described in Mpi.receive
.
It then returns the rank of the node that sent the message
and the actual tag attached to the message. The message itself
is not read, and can be retrieved later with Mpi.receive
or Mpi.receive_status
.val any_tag : tag
val any_source : rank
tag
and src
arguments of
Mpi.receive
, Mpi.receive_status
and Mpi.probe
,
indicating that any message tag is acceptable (for Mpi.any_tag
)
or any message source is acceptable (for Mpi.any_source
).val send_int : int -> rank -> tag -> communicator -> unit
val receive_int : rank -> tag -> communicator -> int
val send_float : float -> rank -> tag -> communicator -> unit
val receive_float : rank -> tag -> communicator -> float
val send_int_array : int array -> rank -> tag -> communicator -> unit
val receive_int_array : int array -> rank -> tag -> communicator -> unit
val send_float_array : float array -> rank -> tag -> communicator -> unit
val receive_float_array : float array -> rank -> tag -> communicator -> unit
Mpi.send
and Mpi.receive
for communicating integers, floating-point numbers,
arrays of integers, and arrays of floating-point numbers.
These specialized versions are more efficient than
Mpi.send
and Mpi.receive
since less copying is involved.
The arguments to the Mpi.send_*
functions have the same
meaning as for Mpi.send
.
The arguments to Mpi.receive_int
and Mpi.receive_float
have the same meaning as for Mpi.receive
.
Mpi.receive_int_array
and Mpi.receive_float_array
have one extra argument, which is the array in which the data
of the received message is stored. The caller is responsible
for pre-allocating an array large enough to hold the incoming data.
It is an error to send a message using one of the specialized
Mpi.send_*
functions and receive it with the generic
Mpi.receive
function, and conversely.
val barrier : communicator -> unit
Mpi.barrier comm
suspends the calling process until all
nodes in communicator comm
are executing Mpi.barrier comm
.
Then all nodes return from Mpi.barrier
and continue executing.val broadcast : 'a -> rank -> communicator -> 'a
Mpi.broadcast d root comm
broadcasts data d
from node
with rank root
in comm
to all other nodes in comm
.
All nodes in comm
must call Mpi.broadcast
with the same
root
and comm
arguments. The d
argument is significant
only at node root
; it is ignored at other nodes.
Mpi.broadcast
returns the broadcast data.val broadcast_opt : 'a option -> rank -> communicator -> 'a
Mpi.broadcast
, except that the data (first argument)
is provided as an option type. The root node must provide a
first argument of the form Some d
where d
is the data to
broadcast. The other node provide None
as their first
argument.val broadcast_int : int -> rank -> communicator -> int
val broadcast_float : float -> rank -> communicator -> float
val broadcast_int_array : int array -> rank -> communicator -> unit
val broadcast_float_array : float array -> rank -> communicator -> unit
Mpi.broadcast
for integers, floats,
arrays of integers and arrays of floats. For
Mpi.broadcast_int
and Mpi.broadcast_float
, the broadcast
value is returned as result, and the first argument is significant
only at the root node.
For Mpi.broadcast_int_array
and Mpi.broadcast_float_array
,
the broadcast value is stored in the array passed as first argument;
thus, the first argument is significant at all nodes.val scatter : 'a array -> rank -> communicator -> 'a
Mpi.scatter a root comm
scatters the elements of array a
from node root
to all nodes in comm
. The node with rank i
in comm
receives the element a.(i)
and returns it as result
of Mpi.scatter
. The a
argument is significant only at node
root
; an empty array [||]
can be given as first argument
at other nodes.val scatter_int : int array -> rank -> communicator -> int
val scatter_float : float array -> rank -> communicator -> float
Mpi.scatter
for integers and floats.val scatter_int_array : int array -> int array -> rank -> communicator -> unit
val scatter_float_array : float array -> float array -> rank -> communicator -> unit
Mpi.scatter
for arrays of integers and
arrays of floats. Mpi.scatter_int_array src dst root comm
splits the array src
at node root
into Mpi.comm_size comm
chunks of size Array.length dst
, and sends the chunks to
each node, storing them into array dst
at each node.
The src
argument is significant only at node root
.
Mpi.scatter_int_array
is similar.val gather : 'a -> rank -> communicator -> 'a array
Mpi.gather d root comm
gathers the values of the d
argument
at all nodes onto node root
, and returns those values as an
array. At node root
, Mpi.gather
returns an array of
size Mpi.comm_size comm
; element number i
is the value
provided for argument d
by node i
. At other nodes,
the empty array [||]
is returned.val gather_int : int -> int array -> rank -> communicator -> unit
val gather_float : float -> float array -> rank -> communicator -> unit
Mpi.gather
for integers and floats.val gather_int_array : int array -> int array -> rank -> communicator -> unit
val gather_float_array : float array -> float array -> rank -> communicator -> unit
Mpi.gather
for arrays of integers and
arrays of floats. Mpi.gather_int_array src dst root comm
sends the arrays src
at each node to the node root
.
At node root
, the arrays are concatenated and stored in the
argument dst
. dst
is significant only at node root
.
Mpi.gather_int_array
is similar.val allgather : 'a -> communicator -> 'a array
val allgather_int : int -> int array -> communicator -> unit
val allgather_float : float -> float array -> communicator -> unit
val allgather_int_array : int array -> int array -> communicator -> unit
val allgather_float_array : float array -> float array -> communicator -> unit
Mpi.allgather*
functions behave like the corresponding
Mpi.gather*
functions, except that the result of the gather
operation is available at all nodes, not only at the root node.
In other terms, Mpi.allgather
is equivalent to Mpi.gather
at root r
followed by a broadcast of the result from node r
.type
intop =
| |
Int_max |
| |
Int_min |
| |
Int_sum |
| |
Int_prod |
| |
Int_land |
| |
Int_lor |
| |
Int_xor |
type
floatop =
| |
Float_max |
| |
Float_min |
| |
Float_sum |
| |
Float_prod |
max
and min
are maximum and minimum; sum
and prod
are summation (+
) and product (*
).
land
. lor
and lxor
are logical (bit-per-bit) and,
or and exclusive-or.val reduce_int : int -> intop -> rank -> communicator -> int
val reduce_float : float -> floatop -> rank -> communicator -> float
Mpi.reduce_int d op root comm
computes the value of
d0 op d1 op ... op dN
, where d0 ... dN
are the values of
the d
argument at every node in comm
. The result value
is returned at node with rank root
. A meaningless integer
is returned at other nodes. Mpi.reduce_float
is similar
except for the use of floating-point operations instead of
integer operations.val reduce_int_array : int array -> int array -> intop -> rank -> communicator -> unit
val reduce_float_array : float array ->
float array -> floatop -> rank -> communicator -> unit
Mpi.reduce_int_array d res op root comm
computes
Array.length d
reductions by operation op
simultaneously.
For every i
, the values of d.(i)
at every node
are combined using op
and the result is stored into dst.(i)
at node root
.val allreduce_int : int -> intop -> communicator -> int
val allreduce_float : float -> floatop -> communicator -> float
val allreduce_int_array : int array -> int array -> intop -> communicator -> unit
val allreduce_float_array : float array -> float array -> floatop -> communicator -> unit
Mpi.allreduce_*
operations are similar to the
corresponding Mpi.reduce_*
operations, except that the result
of the reduction is made available at all nodes.val scan_int : int -> intop -> communicator -> int
val scan_float : float -> floatop -> communicator -> float
Mpi.scan_int d res op comm
performs a scan operation over
the integers d
at every node. Let d0 ... dN
be the
values of the d
at every node in comm
. At node with rank R
,
Mpi.scan_int d res op comm
returns d0 op ... op dR
.
Mpi.scan_float
is similar.val scan_int_array : int array -> int array -> intop -> communicator -> unit
val scan_float_array : float array -> float array -> floatop -> communicator -> unit
Mpi.scan_int
and Mpi.scan_float
, but perform several
scanning operations on the elements of the input array (first
argument). The result is stored in the array passed as second
argument at the root node.val comm_compare : communicator -> communicator -> bool
true
if they are the same,
false
otherwise.typecolor =
int
val comm_split : communicator -> color -> int -> communicator
Mpi.comm_split comm col key
splits the communicator into
several communicators based on the values of col
and
key
at every node. For each distinct value of the col
argument, a new communicator is created. It contains all
nodes of comm
that have presented that particular value of
key
to Mpi.comm_split
. The ordering of nodes in the
new communicator is determined by the key
argument:
nodes are ordered by increasing values of key
, and in case
of ties, by their original order in comm
. Thus, to preserve
the same ordering as in comm
, it suffices that all nodes
present 0
as the key
argument. In each node, the communicator
returned is the one that corresponds to the color
argument
of that node.val color_none : color
Mpi.comm_split
, a node can pass Mpi.color_none
as the
col
argument to indicate that it does not want to be part
of any of the new communicators. Mpi.comm_split
then
returns a null communicator (allowing no communications) in
that node.val cart_create : communicator -> int array -> bool array -> bool -> communicator
Mpi.cart_create comm dims periodic reorder
embeds a cartesian
topology (multi-dimensional grid) on the nodes of
communicator comm
, and return a
new communicator with that information attached.
The length of dims
determines the number of dimensions of
the topology. For each dimension d
, dims.(d)
specifies
the number of nodes in that dimension, and periodic.(d)
says whether that dimension is periodic (wraps around) or not.
reorder
determines whether the ranks of nodes in the new
communicator can be reordered for better efficiency (true
)
or must remain the same as in comm
(false
).
The initial communicator comm
must contain at least as many
nodes as specified by dims
.val dims_create : int -> int array -> int array
Mpi.dims_create numnodes hints
helps determining a
suitable dims
argument to Mpi.cart_create
given a number of nodes numnodes
, the number of
dimensions required, and optional constraints.
The length of the hints
array determines the number of
dimensions. For each dimension d
, hints.(d)
, if not null,
is the number of nodes required along this dimension. If null,
Mpi.dims_create
figures out a suitable number.
For instance, Mpi.dims_create 24 [|0;0|]
returns reasonable
dimensions for a two-dimensional grid containing 24 nodes.
val cart_rank : communicator -> int array -> rank
Mpi.cart_rank comm coords
return the rank of the node in
the cartesian topology comm
that is at coordinates coords
.
The coords
array must have one element per dimension of the
cartesian topology. Individual coordinates range between 0
(inclusive) and the corresponding dimension (exclusive).val cart_coords : communicator -> rank -> int array
Mpi.cart_rank
.
Mpi.cart_coords comm r
returns the cartesian coordinates
of the node having rank r
in comm
.type
group
val comm_create : communicator -> group -> communicator
Mpi.comm_create comm group
creates a communicator
whose nodes are those described in group
. comm
is
the initial communicator; the nodes in group
must be
a subset of those in comm
. The null communicator is
returned to the nodes that are not part of group
.val group_size : group -> int
val group_rank : group -> rank
val group_translate_ranks : group -> rank array -> group -> rank array
Mpi.group_translate_ranks g1 ranks g2
translates the ranks
of a number of nodes from one group to another. rank
is an array of node ranks relative to group g1
. The
returned array contains the ranks for the same nodes, relative
to group g2
.val comm_group : communicator -> group
Mpi.comm_group comm
returns the group of all nodes belonging
to the communicator comm
, with the same ranks as in comm
.val group_union : group -> group -> group
val group_intersection : group -> group -> group
val group_difference : group -> group -> group
val group_incl : group -> rank array -> group
Mpi.group_incl group ranks
returns the subset of group
containing the nodes whose ranks are given in the array ranks
.val group_excl : group -> rank array -> group
Mpi.group_excl group ranks
returns the subset of group
containing the nodes whose ranks are not given in the array
ranks
.type
group_range = {
|
range_first : |
|
range_last : |
|
range_stride : |
range_first
; range_first + range_stride
; ...; range_last
).val group_range_incl : group -> group_range array -> group
Mpi.group_range_incl group ranges
returns the subset of group
containing the nodes whose ranks belong to the ranges
listed in ranges
.val group_range_excl : group -> group_range array -> group
Mpi.group_range_excl group ranges
returns the subset of group
containing the nodes whose ranks do not belong to the ranges
listed in ranges
.val wtime : unit -> float