Installation
============


Requirements
------------

You need to have the following software properly installed in order to
build the MPI module and the companion parallelized version of the
Python interpreter:

* A Python 2.3/2.4/2.5 distribution, with Python library preferably
  compiled as a dynamic library.

  .. note:: It is suggested to use a MPI-parallelized version of the
     Python interpreter supporting interactive parallel sessions.

* A working MPI distribution for your architecture, compiled with dynamic
  libraries. For example, on a GNU/Linux box this requirement can be
  accomplished by typing:

  + *MPICH 2* ::

        $ tar -zxf mpich2-X.X.X.tar.gz
        $ cd mpich2-X.X.X
        $ ./configure --enable-sharedlibs=gcc --prefix=/usr/local/mpich2
        $ make
        $ make install

  + *Open MPI* ::

        $ tar -zxf openmpi-X.X.X tar.gz
        $ cd openmpi-X.X.X
        $ ./configure --prefix=/usr/local/openmpi
        $ make all
        $ make install

  + *LAM* ::

        $ tar -zxf lam-X.X.X.tar.gz
        $ cd lam-X.X.X
        $ ./configure --enable-shared --prefix=/usr/local/lam
        $ make
        $ make install

  + *MPICH 1* ::

        $ tar -zxf mpich-X.X.X.tar.gz
        $ cd mpich-X.X.X
        $ ./configure --enable-sharedlib --prefix=/usr/local/mpich
        $ make
        $ make install

  .. note:: Perhaps the user will have to set his ``LD_LIBRARY_PATH``
     environmental variable (using ``export``, ``setenv`` or what
     applies to his system) pointing to the MPI library directory. In
     case of getting runtime linking error when running MPI programs,
     the following lines can be added to the user login shell script
     (``.profile``, ``.bashrc``, etc.).
      
     - *MPICH 2* ::

       $ MPI_DIR=/usr/local/mpich2
       $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MPI_DIR/lib

     - *Open MPI* ::

       $ MPI_DIR=/usr/local/openmpi
       $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MPI_DIR/lib

     - *LAM* ::

        $ MPI_DIR=/usr/local/lam
        $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MPI_DIR/lib

     - *MPICH 1* ::

        $ MPI_DIR=/usr/local/mpich
        $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MPI_DIR/lib/shared
	$ export MPICH_USE_SHLIB=yes

  .. warning:: MPICH 1 support for dynamic libraries is not completely
     transparent. Users should set environmental variable
     ``MPICH_USE_SHLIB`` to ``yes`` in order to avoid link problems
     when using ``mpicc``.


Building
--------

After downloading and unpacking the module distribution::

   $ 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 *mpicc* compiler wrapper
  (e.g., MPICH, OpenMPI, LAM), it will be used for compilation and
  linking. This is the preferred and easiest way of building MPI for
  Python.

  If ``mpicc`` is located somewhere in your search path, simply run
  the *build* command::

      $ python setup.py build

  If ``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 ``mpi.cfg``. You can use
  the default section ``[mpi]`` or add a new, custom section, for
  example ``[my_mpi]`` (see the examples provided in ``mpi.cfg``)::

     [mpi]

     include_dirs         = /usr/local/mpi/include
     libraries            = mpi
     library_dirs         = /usr/local/mpi/lib
     runtime_library_dirs = /usr/local/mpi/lib
        
     [my_mpi]
        
     include_dirs         = /opt/mpi/include ...
     libraries            = mpi ...
     library_dirs         = /opt/mpi/lib ...
     runtime_library_dirs = /op/mpi/lib ...
        
     ...

  and run the *build* command, perhaps specifying you custom section::

      $ python setup.py buil --mpi=my_mpi


Installing
----------

After building, the distribution is ready for install (perhaps you
will need root privileges)::

   $ python setup.py install

The previous steps will install the ``mpi4py`` package at standard
location ``<prefix>/lib/python<version>/site-packages``.


Testing
-------

Issuing at the command line::

   $ mpiexec -n 5 python tests/helloworld.py

or::

   $ mpirun -np 5 python tests/helloworld.py

will launch a five-process run of the Python interpreter and run
the test scripts ``tests/helloworld.py``.

You can also try *unittest* scripts located at ``tests/unittest``.
