mpi4py — MPI for Python 3.1.4 documentation

# 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`

  See also

  `MPI4PY_RC_INITIALIZE`

mpi4py.rc.threads

  Request initialization with thread support.

  Type:

    `bool`

  Default:

    `True`

  See also

  `MPI4PY_RC_THREADS`

mpi4py.rc.thread_level

  Level of thread support to request.

  Type:

    `str`

  Default:

    `"multiple"`

  Choices:

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

  See also

  `MPI4PY_RC_THREAD_LEVEL`

mpi4py.rc.finalize

  Automatic MPI finalization at exit.

  Type:

    `None` or `bool`

  Default:

    `None`

  See also

  `MPI4PY_RC_FINALIZE`

mpi4py.rc.fast_reduce

  Use tree-based reductions for objects.

  Type:

    `bool`

  Default:

    `True`

  See also

  `MPI4PY_RC_FAST_REDUCE`

mpi4py.rc.recv_mprobe

  Use matched probes to receive objects.

  Type:

    `bool`

  Default:

    `True`

  See also

  `MPI4PY_RC_RECV_MPROBE`

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.

  See also

  `mpi4py.rc.initialize`

  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.

  See also

  `mpi4py.rc.finalize`

  New in version 3.1.0.

MPI4PY_RC_THREADS
  Type:

    `bool`

  Default:

    `True`

  Whether to initialize MPI with thread support.

  See also

  `mpi4py.rc.threads`

  New in version 3.1.0.

MPI4PY_RC_THREAD_LEVEL
  Default:

    `"multiple"`

  Choices:

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

  The level of required thread support.

  See also

  `mpi4py.rc.thread_level`

  New in version 3.1.0.

MPI4PY_RC_FAST_REDUCE
  Type:

    `bool`

  Default:

    `True`

  Whether to use tree-based reductions for objects.

  See also

  `mpi4py.rc.fast_reduce`

  New in version 3.1.0.

MPI4PY_RC_RECV_MPROBE
  Type:

    `bool`

  Default:

    `True`

  Whether to use matched probes to receive objects.

  See also

  `mpi4py.rc.recv_mprobe`

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