relentless.mpi.Communicator#

class relentless.mpi.Communicator(comm=None, root=0)#

MPI communicator.

Wrapper around an MPI communicator. Methods will gracefully degrade to single-processor functions if not running under MPI or there is only a single rank in the communicator.

Parameters:

comm (mpi4py.MPI.Comm) – Communicator backend. Defaults to None, which is converted to mpi4py.MPI.COMM_WORLD if running under MPI.
root (int) – Root rank index (defaults to 0).

Raises:

IndexError – If the root rank does not lie within the valid range for the communicator.

Methods

`barrier`()	Create barrier for all ranks in the MPI communicator.
`bcast`(data[, root])	Broadcast Python object to all ranks.
`bcast_numpy`(data[, root])	Broadcast NumPy array to all ranks.
`load_json`(filename[, root])	Load a JSON file and broadcast.
`loadtxt`(filename[, root])	Load text from a file and broadcast.

Attributes

`comm`	`mpi4py.MPI.Comm` MPI communicator.
`enabled`	True if MPI communication is enabled.
`rank`	Index of rank in the MPI communicator.
`rank_is_root`	True if the MPI rank is the root rank.
`root`	Index of the root rank in the MPI communicator.
`size`	Number of ranks in the MPI communicator.

barrier()#: Create barrier for all ranks in the MPI communicator.

bcast(data, root=None)#

Broadcast Python object to all ranks.

Broadcasting is a one-to-all communication pattern that can be used to synchronize data across ranks. This method wraps around the mpi4py.MPI.Comm.bcast() method, which only operates on Python data types that are picklable. If you need to broadcast a NumPy array that uses the Python buffer protocol, you should use bcast_numpy().

Parameters:

data (object) – Any Python picklable object.
root (int) – Rank to broadcast from. If None (default), broadcast from the root of the communicator.

Returns:

The broadcast data on all ranks.

Return type:

object

Example

Broadcast an integer:

comm = relentless.mpi.Communicator()
if comm.rank_is_root:
    x = 42
else:
    x = None
x = comm.bcast(x)

bcast_numpy(data, root=None)#

Broadcast NumPy array to all ranks.

Broadcasting is a one-to-all communication pattern that can be used to synchronize data across ranks. This method wraps around the mpi4py.MPI.Comm.Bcast() method for NumPy arrays. The method will ensure that data has the correct size and type on all ranks by first broadcasting this information; if data is not allocated in this way, it will be allocated automatically.

Parameters:

data (numpy.ndarray) – NumPy array to broadcast.
root (int) – Rank to broadcast from. If None (default), broadcast from the root of the communicator.

Returns:

The broadcast array on all ranks.

Return type:

numpy.ndarray

Examples

Broadcast an array:

comm = relentless.mpi.Communicator()
if comm.rank_is_root:
    x = numpy.array([1,2,3], dtype=numpy.int32)
else:
    x = None
x = comm.bcast_numpy(x)

Broadcast an array with pre-existing storage:

comm = relentless.mpi.Communicator()
if comm.rank_is_root:
    x = numpy.array([1,2,3], dtype=numpy.int32)
else:
    x = numpy.empty(3, dtype=numpy.int32)
x = comm.bcast_numpy(x)

property comm#

mpi4py.MPI.Comm MPI communicator.

This attribute is None if running on a single processor.

property enabled#

True if MPI communication is enabled.

Type:: bool

load_json(filename, root=None)#

Load a JSON file and broadcast.

Data is loaded from file using json.load() on the root rank, then broadcast to all ranks. This function can be called with essentially no overhead in single-processor calculations, but prevents oversubscribing file handles when running under MPI.

Parameters:

filename (str) – Name of the file to load.
root (int) – Rank to broadcast from. If None (default), broadcast from the root of the communicator.

Returns:

The data from filename.

Return type:

dict

Example

Load a file:

comm = relentless.mpi.Communicator()
dat = comm.load_json("ensemble.json")

loadtxt(filename, root=None, **kwargs)#

Load text from a file and broadcast.

Data is loaded from file using numpy.loadtxt() on the root rank, then broadcast to all ranks. This function can be called with essentially no overhead in single-processor calculations, but prevents oversubscribing file handles when running under MPI.

Parameters:

filename (str) – Name of the file to load.
root (int) – Rank to broadcast from. If None (default), broadcast from the root of the communicator.
**kwargs – Optional keyword arguments to numpy.loadtxt().

Returns:

The data from filename.

Return type:

numpy.ndarray

Example

Load a file:

comm = relentless.mpi.Communicator()
dat = comm.loadtxt("gr.dat")

property rank#

Index of rank in the MPI communicator.

Type:: int

property rank_is_root#

True if the MPI rank is the root rank.

Type:: bool

property root#

Index of the root rank in the MPI communicator.

Type:: int

property size#

Number of ranks in the MPI communicator.

Type:: int