# Module Scientific.MPI

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.

This module contains only one object, `world`, 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.

# Submodules:

- Module Scientific.MPI.IO

## Class MPICommunicator: MPI Communicator

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.

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

Methods:

- duplicate()

  Returns a new communicator object with the same properties as the original one.

- send(data, destination, tag)

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

- receive(data, source=`None`, tag=`None`)

  Receives an array from the process with rank source with identifier tag. The default source=None means that messages from any process are accepted. The value of data 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, data 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.

  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).

- receiveString(source=`None`, tag=`None`)

  Receives a string from the process with rank source with identifier tag. The default source=None means that messages from any process are accepted.

  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).

- broadcast(array, root)

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

- share(send, receive)

  Distributes data from each process to all other processes in the communicator. The array send (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 receive must have the same data type as send and one additional dimension (the first one), whose length must be the number of processes in the communicator. After the call, the value of |receive|[i] is equal to the contents of the array send in process i.

- barrier()

  Waits until all processes in the communicator have called the same method, then all processes continue.

## Class MPIError: MPI call failed