1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
Installation
============
Requirements
------------
You need to have the following software properly installed in order to
build *MPI for Python*:
* A working MPI implementation, preferably supporting MPI-3 and 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.
* Python 2.7, 3.5 or above.
.. 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**
-------------
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`::
$ python -m pip 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::
$ env MPICC=/path/to/mpicc python -m pip install mpi4py
.. warning::
:program:`pip` keeps previouly built wheel files on its cache for
future reuse. If you want to reinstall the :mod:`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 :program:`pip` to disable the cache::
$ python -m pip install --no-cache-dir mpi4py
Using **distutils**
-------------------
The *MPI for Python* package is available for download at the project
website generously hosted by GitHub. You can use :program:`curl`
or :program:`wget` to get a release tarball.
* Using :program:`curl`::
$ curl -O https://github.com/mpi4py/mpi4py/releases/download/X.Y.Z/mpi4py-X.Y.Z.tar.gz
* Using :program:`wget`::
$ wget https://github.com/mpi4py/mpi4py/releases/download/X.Y.Z/mpi4py-X.Y.Z.tar.gz
After unpacking the release tarball::
$ tar -zxf mpi4py-X.Y.Z.tar.gz
$ cd mpi4py-X.Y.Z
the package is ready for building.
*MPI for Python* uses a standard distutils-based build system. However,
some distutils commands (like *build*) have additional options:
.. cmdoption:: --mpicc=
Lets you specify a special location or name for the
:program:`mpicc` compiler wrapper.
.. cmdoption:: --mpi=
Lets you pass a section with MPI configuration within a special
configuration file.
.. cmdoption:: --configure
Runs exhaustive tests for checking about missing MPI types,
constants, and functions. This option should be passed in order to
build *MPI for Python* against old MPI-1 or MPI-2 implementations,
possibly providing a subset of MPI-3.
If you use a MPI implementation providing a :program:`mpicc` compiler
wrapper (e.g., MPICH, Open MPI), 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 implementation by editing the file called :file:`mpi.cfg`. You can
use the default section ``[mpi]`` or add a new, custom section, for
example ``[other_mpi]`` (see the examples provided in the
:file:`mpi.cfg` file as a starting point to write your own section)::
[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
After building, the package 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, just do::
$ python setup.py install --user
Testing
-------
To quickly test the installation::
$ mpiexec -n 5 python -m mpi4py.bench helloworld
Hello, World! I am process 0 of 5 on localhost.
Hello, World! I am process 1 of 5 on localhost.
Hello, World! I am process 2 of 5 on localhost.
Hello, World! I am process 3 of 5 on localhost.
Hello, World! I am process 4 of 5 on localhost.
If you installed from source, issuing at the command line::
$ mpiexec -n 5 python demo/helloworld.py
or (in the case of ancient MPI-1 implementations)::
$ mpirun -np 5 python `pwd`/demo/helloworld.py
will launch a five-process run of the Python interpreter and run the
test script :file:`demo/helloworld.py` from the source distribution.
You can also run all the *unittest* scripts::
$ mpiexec -n 5 python test/runtests.py
or, if you have nose_ unit testing framework installed::
$ mpiexec -n 5 nosetests -w test
.. _nose: https://nose.readthedocs.io/
or, if you have `py.test`_ unit testing framework installed::
$ mpiexec -n 5 py.test test/
.. _py.test: https://docs.pytest.org/
|
