Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Getting started

MPI Implementation
Configure and Build
Installing and Using Boost.MPI
Testing Boost.MPI

Getting started with Boost.MPI requires a working MPI implementation, a recent version of Boost, and some configuration information.

MPI Implementation

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,
    if (result == MPI_SUCCESS && value == 17)
      std::cout << "Rank 1 OK!" << std::endl;
  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
mpirun -np 2 ./mpi-test

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.

Configure and Build

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 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

Installing and Using Boost.MPI

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.

Testing Boost.MPI

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.