<a name="Module:Scientific.MPI"><h1>Module Scientific.MPI</h1></a>

<p>This module contains a Python interface to the Message Passing
Interface (MPI), and standardized library for message-passing parallel
computing. Please read an introduction to MPI before using this
module; some terms in the documentation do not make much sense unless
you understand the principles of MPI.</p>

<p>This module contains an object, <tt>world</tt>, which represents the
default communicator in MPI. This communicator can be used directly
for sending and receiving data, or other communicators can be
derived from it.</p>

<p>A number of global constants are also defined ( <tt>max</tt>, <tt>min</tt>, <tt>prod</tt>,
<tt>sum</tt>, <tt>land</tt>, <tt>lor</tt>, <tt>lxor</tt>, <tt>band</tt>, <tt>bor</tt>, <tt>bxor</tt>, <tt>maxloc</tt> and
<tt>minloc</tt> ).  They are used to specify the desired operator in calls to
the <tt>reduce</tt> and <tt>allreduce</tt> methods of the communicator objects.
</p>

<h1>Submodules:</h1>
<ul><li><a href="Scientific_24.html">Module Scientific.MPI.IO</a></ul>
<hr width=70%>
<a name="Class:Scientific.MPI.MPICommunicator"><h2>Class MPICommunicator: MPI Communicator</h2></a>

<p>There is no constructor for MPI Communicator objects. The
default communicator is given by Scientific.MPI.world, and
other communicators can only be created by methods on an
existing communicator object.</p>

<p>A communicator object has two read-only attributes: <tt>rank</tt> is
an integer which indicates the rank of the current process in
the communicator, and <tt>size</tt> is an integer equal to the number
of processes that participate in the communicator.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>duplicate</i></b>()
<p>Returns a new communicator object with the same properties
as the original one.</p>

<li> <b><i>send</i></b>(<i>data</i>, <i>destination</i>, <i>tag</i>)
<p>Sends the contents of <i>data</i> (a string or any contiguous NumPy
array except for general object arrays) to the processor
whose rank is <i>destination</i>, using <i>tag</i> as an identifier.
</p>

<li> <b><i>nonblockingSend</i></b>(<i>data</i>, <i>destination</i>, <i>tag</i>)
<p>Sends the contents of <i>data</i> (a string or any contiguous NumPy
array except for general object arrays) to the processor
whose rank is <i>destination</i>, using <i>tag</i> as an identifier.
The send is nonblocking, i.e. the call returns immediately, even
if the destination process is not ready to receive.</p>

<p>The return value is an MPIRequest object.  It is used to
wait till the communication has actually happened.
</p>

<li> <b><i>receive</i></b>(<i>data</i>, <i>source</i>=<tt>None</tt>, <i>tag</i>=<tt>None</tt>)
<p>Receives an array from the process with rank <i>source</i>
with identifier <i>tag</i>. The default <i>source</i>=None means
that messages from any process are accepted. The value
of <i>data</i> can either be an array object, in which case it
must be contiguous and large enough to store the
incoming data; it must also have the correct shape.
Alternatively, <i>data</i> can be a string specifying
the data type (in practice, one would use Numeric.Int,
Numeric.Float, etc.). In the latter case, a new array
object is created to receive the data.</p>

<p>The return value is a tuple containing four elements:
the array containing the data, the source process rank
(an integer), the message tag (an integer), and the
number of elements that were received (an integer).
</p>

<li> <b><i>receiveString</i></b>(<i>source</i>=<tt>None</tt>, <i>tag</i>=<tt>None</tt>)
<p>Receives a string from the process with rank <i>source</i>
with identifier <i>tag</i>. The default <i>source</i>=None means
that messages from any process are accepted.</p>

<p>The return value is a tuple containing three elements:
the string containing the data, the source process rank
(an integer), and the message tag (an integer).
</p>

<li> <b><i>nonblockingReceive</i></b>(<i>data</i>, <i>source</i>=<tt>None</tt>, <i>tag</i>=<tt>None</tt>)
<p>Receives an array from the process with rank <i>source</i>
with identifier <i>tag</i>. The default <i>source</i>=None means
that messages from any process are accepted. The value
of <i>data</i> must be a contiguous array object, large enough
to store the incoming data; it must also have the correct
shape.  Unlike the blocking receive, the size of the array
must be known when the call is made, as nonblocking receives
of unknown quantities of data is not implemented.  For the
same reason there is no nonblocking_receiveString.</p>

<p>The return value is an MPIRequest object.  It is used to wait
until the data has arrived, and will give information about
the size, the source and the tag of the incoming message.
</p>

<li> <b><i>nonblockingProbe</i></b>(<i>source</i>=<tt>None</tt>, <i>tag</i>=<tt>None</tt>)
<p>Checks if a message from the process with rank <i>source</i>
and with identifier <i>tag</i> is available for immediate
reception. The return value is <tt>None</tt> if no message
is available, otherwise a <tt>(source, tag)</tt> tuple is
returned.
</p>

<li> <b><i>broadcast</i></b>(<i>array</i>, <i>root</i>)
<p>Sends data from the process with rank <i>root</i> to all
processes (including <i>root</i>). The parameter <i>array</i> can be
any contiguous NumPy array except for general object arrays.
On the process <i>root</i>, it holds the data to be sent. After
the call, the data in <i>array</i> is the same for all processors.
The shape and data type of <i>array</i> must be the same in
all processes.
</p>

<li> <b><i>share</i></b>(<i>send</i>, <i>receive</i>)
<p>Distributes data from each process to all other processes
in the communicator. The array <i>send</i> (any contiguous NumPy
array except for general object arrays) contains the data
to be sent by each process, the shape and data type must be
identical in all processes. The array <i>receive</i> must have
the same data type as <i>send</i> and one additional dimension
(the first one), whose length must be the number of processes
in the communicator. After the call, the value
of <i>receive[i]</i> is equal to the contents of the array <i>send</i>
in process i.
</p>

<li> <b><i>barrier</i></b>()
<p>Waits until all processes in the communicator have
called the same method, then all processes continue.</p>

<li> <b><i>abort</i></b>()
<p>Aborts all processes associated with the communicator.
For emergency use only.</p>

<li> <b><i>reduce</i></b>(<i>sendbuffer</i>, <i>receivebuffer</i>, <i>operation</i>, <i>root</i>)
<p>Combine data from all processes using <i>operation</i>, and
send the data to the process identified by <i>root</i>.</p>

<p><i>operation</i> is one of the operation objects defined globally
in the module: <tt>max</tt>, <tt>min</tt>, <tt>prod</tt>, <tt>sum</tt>, <tt>land</tt>, <tt>lor</tt>,
<tt>lxor</tt>, <tt>band</tt>, <tt>bor</tt>, bxor', <tt>maxloc</tt> and <tt>minloc</tt>.
</p>

<li> <b><i>allreduce</i></b>(<i>sendbuffer</i>, <i>receivebuffer</i>, <i>operation</i>, <i>root</i>)
<p>Combine data from all processes using <i>operation</i>, and
send the data to all processes in the communicator.</p>

<p><i>operation</i> is one of the operation objects defined globally
in the module: <tt>max</tt>, <tt>min</tt>, <tt>prod</tt>, <tt>sum</tt>, <tt>land</tt>, <tt>lor</tt>,
<tt>lxor</tt>, <tt>band</tt>, <tt>bor</tt>, bxor', <tt>maxloc</tt> and <tt>minloc</tt>.
</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.MPI.MPIError"><h2>Class MPIError: MPI call failed</h2></a>

<hr width=70%>
<a name="Class:Scientific.MPI.MPIRequest"><h2>Class MPIRequest: MPI Request</h2></a>

<p>There is no constructor for MPI Request objects.  They are
returned by nonblocking send and receives, and are used to
query the status of the message.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>wait</i></b>()
<p>Waits till the communication has completed.  If the
operation was a nonblocking send, there is no return value.
If the operation was a nonblocking receive, the return
value is a tuple containing four elements: the array
containing the data, the source process rank (an integer),
the message tag (an integer), and the number of elements
that were received (an integer).
</p>

</ul>