...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Getting started with Boost.MPI requires a working MPI implementation, a recent version of Boost, and some configuration information.
To get started with Boost.MPI, you will first need a working MPI implementation. There are many conforming MPI implementations available. Boost.MPI should work with any of the implementations, although it has only been tested extensively with:
You can test your implementation using the following simple program, which passes a message from one processor to another. Each processor prints a message to standard output.
#include <mpi.h> #include <iostream> int main(int argc, char* argv[]) { MPI_Init(&argc, &argv); int rank; MPI_Comm_rank(MPI_COMM_WORLD, &rank); if (rank == 0) { int value = 17; int result = MPI_Send(&value, 1, MPI_INT, 1, 0, MPI_COMM_WORLD); if (result == MPI_SUCCESS) std::cout << "Rank 0 OK!" << std::endl; } else if (rank == 1) { int value; int result = MPI_Recv(&value, 1, MPI_INT, 0, 0, MPI_COMM_WORLD, MPI_STATUS_IGNORE); if (result == MPI_SUCCESS && value == 17) std::cout << "Rank 1 OK!" << std::endl; } MPI_Finalize(); return 0; }
You should compile and run this program on two processors. To do this, consult
the documentation for your MPI implementation. With LAM/MPI,
for instance, you compile with the mpiCC
or mpic++
compiler, boot the LAM/MPI daemon, and run your program via mpirun
. For instance, if your program is
called mpi-test.cpp
,
use the following commands:
mpiCC -o mpi-test mpi-test.cpp lamboot mpirun -np 2 ./mpi-test lamhalt
When you run this program, you will see both Rank
0 OK!
and Rank
1 OK!
printed to the screen. However, they may
be printed in any order and may even overlap each other. The following output
is perfectly legitimate for this MPI program:
Rank Rank 1 OK! 0 OK!
If your output looks something like the above, your MPI implementation appears to be working with a C++ compiler and we're ready to move on.
Boost.MPI is not available in any version of Boost prior to the 1.35.x series. You may need to retrieve the latest version of Boost from CVS using the commands below. When CVS asks for a password, just hit "enter".
cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost login cvs -z3 -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost \ co -P boost
Boost.MPI uses version 2 of the Boost.Build
system for configuring and building the library binary. You will need a very
new version of Boost.Jam
(3.1.12 or later). If you already have Boost.Jam, run bjam
-v
to determine what version you are using.
Information about building Boost.Jam is available
here. However, most users need only run build.sh
in
the tools/build/jam_src
subdirectory of Boost. Then, copy
the resulting bjam
executable
some place convenient.
For many users using LAM/MPI,
MPICH, or OpenMPI, configuration is almost automatic.
If you don't already have a file user-config.jam
in
your home directory, copy tools/build/v2/user-config.jam
there.
For many users, MPI support can be enabled simply by adding the following
line to your user-config.jam file, which is used to configure Boost.Build
version 2.
using mpi ;
This should auto-detect MPI settings based on the MPI wrapper compiler in
your path, e.g., mpic++
.
If the wrapper compiler is not in your path, see below.
To actually build the MPI library, go into the top-level Boost directory and execute the command:
bjam --with-mpi
If your MPI wrapper compiler has a different name from the default, you can pass the name of the wrapper compiler as the first argument to the mpi module:
using mpi : /opt/mpich2-1.0.4/bin/mpiCC ;
If your MPI implementation does not have a wrapper compiler, or the MPI auto-detection
code does not work with your MPI's wrapper compiler, you can pass MPI-related
options explicitly via the second parameter to the mpi
module:
using mpi : : <find-shared-library>lammpio <find-shared-library>lammpi++ <find-shared-library>mpi <find-shared-library>lam <find-shared-library>dl ;
To see the results of MPI auto-detection, pass --debug-configuration
on the bjam command line.
The (optional) fourth argument configures Boost.MPI for running regression tests. These parameters specify the executable used to launch jobs (default: "mpirun") followed by any necessary arguments to this to run tests and tell the program to expect the number of processors to follow (default: "-np"). With the default parameters, for instance, the test harness will execute, e.g.,
mpirun -np 4 all_gather_test
Installation of Boost.MPI can be performed in the build step by specifying
install
on the command line
and (optionally) providing an installation location, e.g.,
bjam --with-mpi install
This command will install libraries into a default system location. To change
the path where libraries will be installed, add the option --prefix=PATH
.
To build applications based on Boost.MPI, compile and link them as you normally
would for MPI programs, but remember to link against the boost_mpi
and boost_serialization
libraries,
e.g.,
mpic++ -I/path/to/boost/mpi my_application.cpp -Llibdir \ -lboost_mpi-gcc-mt-1_35 -lboost_serialization-gcc-d-1_35.a
If you plan to use the Python bindings for
Boost.MPI in conjunction with the C++ Boost.MPI, you will also need to link
against the boost_mpi_python library, e.g., by adding -lboost_mpi_python-gcc-mt-1_35
to your link command. This step will only be necessary if you intend to register C++ types or use the skeleton/content
mechanism from within Python.
If you would like to verify that Boost.MPI is working properly with your
compiler, platform, and MPI implementation, a self-contained test suite is
available. To use this test suite, you will need to first configure Boost.Build
for your MPI environment and then run bjam
in libs/mpi/test
(possibly with some extra options). For LAM/MPI,
you will need to run lamboot
before running bjam
. For
MPICH, you may
need to create a machine file and pass -sMPIRUN_FLAGS="-machinefile <filename>"
to
Boost.Jam; see the section on configuration
for more information. If testing succeeds, bjam
will exit without errors.