Metadata-Version: 2.2
Name: mpi4py
Version: 4.0.2
Summary: Python bindings for MPI
Author: Lisandro Dalcin
Author-email: dalcinl@gmail.com
License: BSD-3-Clause
Project-URL: Homepage, https://mpi4py.github.io
Project-URL: Documentation, https://mpi4py.readthedocs.io/en/stable/
Project-URL: Source, https://github.com/mpi4py/mpi4py
Project-URL: Issues, https://github.com/mpi4py/mpi4py/issues
Project-URL: Discussions, https://github.com/mpi4py/mpi4py/discussions
Project-URL: Downloads, https://github.com/mpi4py/mpi4py/releases
Keywords: scientific computing,parallel computing,message passing interface,MPI
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: GPU
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: BSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: C
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE.rst
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

==============
MPI for Python
==============

This package provides Python bindings for the *Message Passing
Interface* (MPI_) standard. It is implemented on top of the MPI
specification and exposes an API which grounds on the standard MPI-2
C++ bindings.

.. _MPI: https://www.mpi-forum.org

Features
========

This package supports:

* Convenient communication of any *picklable* Python object

  + point-to-point (send & receive)
  + collective (broadcast, scatter & gather, reductions)

* Fast communication of Python object exposing the *Python buffer
  interface* (NumPy arrays, builtin bytes/string/array objects)

  + point-to-point (blocking/nonblocking/persistent send & receive)
  + collective (broadcast, block/vector scatter & gather, reductions)

* Process groups and communication domains

  + Creation of new intra/inter communicators
  + Cartesian & graph topologies

* Parallel input/output:

  + read & write
  + blocking/nonblocking & collective/noncollective
  + individual/shared file pointers & explicit offset

* Dynamic process management

  + spawn & spawn multiple
  + accept/connect
  + name publishing & lookup

* One-sided operations

  + remote memory access (put, get, accumulate)
  + passive target synchronization (start/complete & post/wait)
  + active target synchronization (lock & unlock)


Install
=======

Using **pip**
-------------

You can install the latest mpi4py release from its source distribution
at `PyPI <https://pypi.org/project/mpi4py/>`_ using ``pip``::

  $ python -m pip install mpi4py

You can also install the in-development version with::

  $ python -m pip install git+https://github.com/mpi4py/mpi4py

or::

  $ python -m pip install https://github.com/mpi4py/mpi4py/tarball/master

.. note::

   Installing mpi4py from its source distribution (available at PyPI)
   or Git source code repository (available at GitHub) requires a C
   compiler and a working MPI implementation with development headers
   and libraries.

.. warning::

   ``pip`` keeps previously built wheel files on its cache for future
   reuse. If you want to reinstall the ``mpi4py`` package using a
   different or updated MPI implementation, you have to either first
   remove the cached wheel file with::

     $ python -m pip cache remove mpi4py

   or ask ``pip`` to disable the cache::

     $ python -m pip install --no-cache-dir mpi4py


Using **conda**
---------------

The `conda-forge`_ community provides ready-to-use binary packages
from an ever growing collection of software libraries built around the
multi-platform *conda* package manager. Four MPI implementations are
available on conda-forge: Open MPI (Linux and macOS), MPICH (Linux and
macOS), Intel MPI (Linux and Windows) and Microsoft MPI (Windows).
You can install mpi4py and your preferred MPI implementation using the
``conda`` package manager:

* to use MPICH do::

  $ conda install -c conda-forge mpi4py mpich

* to use Open MPI do::

  $ conda install -c conda-forge mpi4py openmpi

* to use Intel MPI do::

  $ conda install -c conda-forge mpi4py impi_rt

* to use Microsoft MPI do::

  $ conda install -c conda-forge mpi4py msmpi

MPICH and many of its derivatives are ABI-compatible. You can provide
the package specification ``mpich=X.Y.*=external_*`` (where ``X`` and
``Y`` are the major and minor version numbers) to request the conda
package manager to use system-provided MPICH (or derivative)
libraries. Similarly, you can provide the package specification
``openmpi=X.Y.*=external_*`` to use system-provided Open MPI
libraries.

The ``openmpi`` package on conda-forge has built-in CUDA support, but
it is disabled by default. To enable it, follow the instruction
outlined during ``conda install``. Additionally, UCX support is also
available once the ``ucx`` package is installed.

.. warning::

   Binary conda-forge packages are built with a focus on
   compatibility. The MPICH and Open MPI packages are build in a
   constrained environment with relatively dated OS images. Therefore,
   they may lack support for high-performance features like
   cross-memory attach (XPMEM/CMA). In production scenarios, it is
   recommended to use external (either custom-built or system-provided)
   MPI installations. See the relevant conda-forge documentation about
   `using external MPI libraries <cf-mpi-docs_>`_ .

.. _conda-forge: https://conda-forge.org/
.. _cf-mpi-docs: https://conda-forge.org/docs/user/tipsandtricks/#using-external-message-passing-interface-mpi-libraries


Linux
-----

On **Fedora Linux** systems (as well as **RHEL** and their derivatives
using the EPEL software repository), you can install binary packages
with the system package manager:

* using ``dnf`` and the ``mpich`` package::

  $ sudo dnf install python3-mpi4py-mpich

* using ``dnf`` and the ``openmpi`` package::

  $ sudo dnf install python3-mpi4py-openmpi

Please remember to load the correct MPI module for your chosen MPI
implementation:

* for the ``mpich`` package do::

  $ module load mpi/mpich-$(arch)
  $ python -c "from mpi4py import MPI"

* for the ``openmpi`` package do::

  $ module load mpi/openmpi-$(arch)
  $ python -c "from mpi4py import MPI"

On **Ubuntu Linux** and **Debian Linux** systems, binary packages are
available for installation using the system package manager::

  $ sudo apt install python3-mpi4py

Note that on Ubuntu/Debian systems, the mpi4py package uses Open
MPI. To use MPICH, install the ``libmpich-dev`` and ``python3-dev``
packages (and any other required development tools). Afterwards,
install mpi4py from sources using ``pip``.


macOS
-----

**macOS** users can install mpi4py using the `Homebrew`_ package
manager::

  $ brew install mpi4py

Note that the Homebrew mpi4py package uses Open MPI. Alternatively,
install the ``mpich`` package and next install mpi4py from sources
using ``pip``.

.. _Homebrew: https://brew.sh/


Windows
-------

**Windows** users can install mpi4py from binary wheels hosted on the
Python Package Index (PyPI) using ``pip``::

  $ python -m pip install mpi4py

The Windows wheels available on PyPI are specially crafted to work
with either the `Intel MPI <I_MPI_>`_ or the `Microsoft MPI <MSMPI_>`_
runtime, therefore requiring a separate installation of any one of
these packages.

.. _I_MPI: https://software.intel.com/intel-mpi-library
.. _MSMPI: https://learn.microsoft.com/message-passing-interface/microsoft-mpi

Intel MPI is under active development and supports recent version of
the MPI standard. Intel MPI can be installed with ``pip`` (see the
`impi-rt`_ package on PyPI), being therefore straightforward to get it
up and running within a Python environment. Intel MPI can also be
installed system-wide as part of the Intel HPC Toolkit for Windows or
via standalone online/offline installers.

.. _impi-rt: https://pypi.org/project/impi-rt/


Citation
========

If MPI for Python been significant to a project that leads to an
academic publication, please acknowledge that fact by citing the
project.

* M. Rogowski, S. Aseeri, D. Keyes, and L. Dalcin,
  *mpi4py.futures: MPI-Based Asynchronous Task Execution for Python*,
  IEEE Transactions on Parallel and Distributed Systems, 34(2):611-622, 2023.
  https://doi.org/10.1109/TPDS.2022.3225481

* L. Dalcin and Y.-L. L. Fang,
  *mpi4py: Status Update After 12 Years of Development*,
  Computing in Science & Engineering, 23(4):47-54, 2021.
  https://doi.org/10.1109/MCSE.2021.3083216

* L. Dalcin, P. Kler, R. Paz, and A. Cosimo,
  *Parallel Distributed Computing using Python*,
  Advances in Water Resources, 34(9):1124-1139, 2011.
  https://doi.org/10.1016/j.advwatres.2011.04.013

* L. Dalcin, R. Paz, M. Storti, and J. D'Elia,
  *MPI for Python: performance improvements and MPI-2 extensions*,
  Journal of Parallel and Distributed Computing, 68(5):655-662, 2008.
  https://doi.org/10.1016/j.jpdc.2007.09.005

* L. Dalcin, R. Paz, and M. Storti,
  *MPI for Python*,
  Journal of Parallel and Distributed Computing, 65(9):1108-1115, 2005.
  https://doi.org/10.1016/j.jpdc.2005.03.010
