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 :c:func:`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`
or :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/
