mpi4py

This is the MPI for Python package.

The Message Passing Interface (MPI) is a standardized and portable message-passing system designed to function on a wide variety of parallel computers. The MPI standard defines the syntax and semantics of library routines and allows users to write portable programs in the main scientific programming languages (Fortran, C, or C++). Since its release, the MPI specification has become the leading standard for message-passing libraries for parallel computers.

MPI for Python provides MPI bindings for the Python programming language, allowing any Python program to exploit multiple processors. This package build on the MPI specification and provides an object oriented interface which closely follows MPI-2 C++ bindings.

Runtime configuration options

mpi4py.rc

This object has attributes exposing runtime configuration options that become effective at import time of the MPI module.

Attributes Summary

initialize

Automatic MPI initialization at import

threads

Request initialization with thread support

thread_level

Level of thread support to request

finalize

Automatic MPI finalization at exit

fast_reduce

Use tree-based reductions for objects

recv_mprobe

Use matched probes to receive objects

errors

Error handling policy

Attributes Documentation

mpi4py.rc.initialize

Automatic MPI initialization at import.

Type

bool

Default

True

mpi4py.rc.threads

Request initialization with thread support.

Type

bool

Default

True

mpi4py.rc.thread_level

Level of thread support to request.

Type

str

Default

"multiple"

Choices

"multiple", "serialized", "funneled", "single"

mpi4py.rc.finalize

Automatic MPI finalization at exit.

Type

None or bool

Default

None

mpi4py.rc.fast_reduce

Use tree-based reductions for objects.

Type

bool

Default

True

mpi4py.rc.recv_mprobe

Use matched probes to receive objects.

Type

bool

Default

True

mpi4py.rc.errors

Error handling policy.

Type

str

Default

"exception"

Choices

"exception", "default", "fatal"

See also

MPI4PY_RC_ERRORS

Example

MPI for Python features automatic initialization and finalization of the MPI execution environment. By using the mpi4py.rc object, MPI initialization and finalization can be handled programatically:

import mpi4py
mpi4py.rc.initialize = False  # do not initialize MPI automatically
mpi4py.rc.finalize = False    # do not finalize MPI automatically

from mpi4py import MPI # import the 'MPI' module

MPI.Init()      # manual initialization of the MPI environment
...             # your finest code here ...
MPI.Finalize()  # manual finalization of the MPI environment

Environment variables

The following environment variables override the corresponding attributes of the mpi4py.rc and MPI.pickle objects at import time of the MPI module.

Note

For variables of boolean type, accepted values are 0 and 1 (interpreted as False and True, respectively), and strings specifying a YAML boolean value (case-insensitive).

MPI4PY_RC_INITIALIZE
Type

bool

Default

True

Whether to automatically initialize MPI at import time of the mpi4py.MPI module.

New in version 3.1.0.

MPI4PY_RC_FINALIZE
Type

None | bool

Default

None

Choices

None, True, False

Whether to automatically finalize MPI at exit time of the Python process.

New in version 3.1.0.

MPI4PY_RC_THREADS
Type

bool

Default

True

Whether to initialize MPI with thread support.

New in version 3.1.0.

MPI4PY_RC_THREAD_LEVEL
Default

"multiple"

Choices

"single", "funneled", "serialized", "multiple"

The level of required thread support.

New in version 3.1.0.

MPI4PY_RC_FAST_REDUCE
Type

bool

Default

True

Whether to use tree-based reductions for objects.

New in version 3.1.0.

MPI4PY_RC_RECV_MPROBE
Type

bool

Default

True

Whether to use matched probes to receive objects.

MPI4PY_RC_ERRORS
Default

"exception"

Choices

"exception", "default", "fatal"

Controls default MPI error handling policy.

See also

mpi4py.rc.errors

New in version 3.1.0.

MPI4PY_PICKLE_PROTOCOL
Type

int

Default

pickle.HIGHEST_PROTOCOL

Controls the default pickle protocol to use when communicating Python objects.

See also

PROTOCOL attribute of the MPI.pickle object within the MPI module.

New in version 3.1.0.

MPI4PY_PICKLE_THRESHOLD
Type

int

Default

262144

Controls the default buffer size threshold for switching from in-band to out-of-band buffer handling when using pickle protocol version 5 or higher.

See also

Module mpi4py.util.pkl5.

New in version 3.1.2.

Miscellaneous functions

mpi4py.profile(name, *, path=None, logfile=None)

Support for the MPI profiling interface.

Parameters
  • name (str) – Name of the profiler library to load.

  • path (sequence of str, optional) – Additional paths to search for the profiler.

  • logfile (str, optional) – Filename prefix for dumping profiler output.

Return type

None

mpi4py.get_config()

Return a dictionary with information about MPI.

Return type

Dict[str, str]

mpi4py.get_include()

Return the directory in the package that contains header files.

Extension modules that need to compile against mpi4py should use this function to locate the appropriate include directory. Using Python distutils (or perhaps NumPy distutils):

import mpi4py
Extension('extension_name', ...
          include_dirs=[..., mpi4py.get_include()])
Return type

str