Installation
============
Requirements
------------
You need to have the following software properly installed in order to
build *MPI for Python*:
* A working MPI distribution, preferably a MPI-2 one built with
shared/dynamic libraries.
.. note:: If you want to build some MPI implementation from sources,
check the instructions at :ref:`building-mpi` in the appendix.
* A Python 2.3 to 2.7 or 3.0 to 3.1 distribution, with Python
library preferably built with shared/dynamic libraries.
.. note:: **Mac OS X** users employing a Python distribution built
with **universal binaries** may need to temporarily set the
environment variables :envvar:`MACOSX_DEPLOYMENT_TARGET`,
:envvar:`SDKROOT`, and :envvar:`ARCHFLAGS` to appropriate values
in the shell before trying to build/install *MPI for
Python*. Check the instructions at :ref:`macosx-universal-sdk` in
the appendix.
.. note:: Some MPI-1 implementations **do require** the actual
command line arguments to be passed in :cfunc:`MPI_Init()`. In
this case, you will need to use a rebuilt, MPI-enabled, Python
interpreter executable. *MPI for Python* has some support for
alleviating you from this task. Check the instructions at
:ref:`python-mpi` in the appendix.
Using **pip** or **easy_install**
---------------------------------
If you already have a working MPI (either if you installed it from
sources or by using a pre-built package from your favourite GNU/Linux
distribution) and the :program:`mpicc` compiler wrapper is on your
search path, you can use :program:`pip`::
$ [sudo] pip install mpi4py
or alternatively *setuptools* :program:`easy_install` (deprecated)::
$ [sudo] easy_install mpi4py
.. note:: If the :program:`mpicc` compiler wrapper is not on your
search path (or if it has a different name) you can use
:program:`env` to pass the environment variable :envvar:`MPICC`
providing the full path to the MPI compiler wrapper executable::
$ [sudo] env MPICC=/path/to/mpicc pip install mpi4py
$ [sudo] env MPICC=/path/to/mpicc easy_install mpi4py
Using **distutils**
-------------------
*MPI for Python* uses a standard distutils-based buildsystem. However,
some distutils commands (like *build*) have additional options:
* :option:`--mpicc=` : let you specify a special location or name for
the :program:`mpicc` compiler wrapper.
* :option:`--mpi=` : let you pass a section with MPI configuration
within a special configuration file.
* :option:`--configure` : runs exhaustive tests for checking about
missing MPI types/constants/calls. This option should be passed in
order to build *MPI for Python* against old MPI-1 implementations,
possibly providing a subset of MPI-2.
Downloading
^^^^^^^^^^^
The *MPI for Python* package is available for download at the project
website generously hosted by Google Code. You can use :program:`curl`
o :program:`wget` to get a release tarball::
$ curl -O http://mpi4py.googlecode.com/files/mpi4py-X.X.X.tar.gz
$ wget http://mpi4py.googlecode.com/files/mpi4py-X.X.X.tar.gz
Building
^^^^^^^^
After unpacking the release tarball::
$ tar -zxf mpi4py-X.X.X.tar.gz
$ cd mpi4py-X.X.X
the distribution is ready for building.
- If you use a MPI implementation providing a :program:`mpicc`
compiler wrapper (e.g., MPICH 1/2, Open MPI, LAM), it will be used
for compilation and linking. This is the preferred and easiest way
of building *MPI for Python*.
If :program:`mpicc` is located somewhere in your search path, simply
run the *build* command::
$ python setup.py build
If :program:`mpicc` is not in your search path or the compiler
wrapper has a different name, you can run the *build* command
specifying its location::
$ python setup.py build --mpicc=/where/you/have/mpicc
- Alternatively, you can provide all the relevant information about
your MPI distribution by editing the file called
:file:`mpi.cfg`. You can use the default section ``[mpi]`` or add a
new, custom section, for example ``[my_mpi]`` (see the examples
provided in the :file:`mpi.cfg` file)::
[mpi]
include_dirs = /usr/local/mpi/include
libraries = mpi
library_dirs = /usr/local/mpi/lib
runtime_library_dirs = /usr/local/mpi/lib
[other_mpi]
include_dirs = /opt/mpi/include ...
libraries = mpi ...
library_dirs = /opt/mpi/lib ...
runtime_library_dirs = /op/mpi/lib ...
...
and then run the *build* command, perhaps specifying you custom
configuration section::
$ python setup.py build --mpi=other_mpi
Installing
^^^^^^^^^^
After building, the distribution is ready for install.
If you have root privileges (either by log-in as the root user of by
using :command:`sudo`) and you want to install *MPI for Python* in
your system for all users, just do::
$ python setup.py install
The previous steps will install the :mod:`mpi4py` package at standard
location :file:`{prefix}/lib/python{X}.{X}/site-packages`.
If you do not have root privileges or you want to install *MPI for
Python* for your private use, you have two options depending on the
target Python version.
* For Python 2.6 and up::
$ python setup.py install --user
* For Python 2.5 and below (assuming your home directory is available
through the :envvar:`HOME` environment variable)::
$ python setup.py install --home=$HOME
Finally, add :file:`$HOME/lib/python` or :file:`$HOME/lib64/python`
to your :envvar:`PYTHONPATH` environment variable.
Testing
^^^^^^^
Issuing at the command line::
$ mpiexec -n 5 python demo/helloworld.py
or (in the case of older MPI-1 implementations)::
$ mpirun -np 5 python demo/helloworld.py
will launch a five-process run of the Python interpreter and run the
test scripts :file:`demo/helloworld.py`.
You can also run all the *unittest* scripts::
$ mpiexec -n 5 python test/runalltest.py
or, if you have nose_ unit testing framework installed::
$ mpiexec -n 5 nosetests -w test
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/
