Getting started

| Home | Libraries | People | FAQ | More

## Getting started

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:

- Open MPI 1.0.x
- LAM/MPI 7.x
- MPICH 1.2.x

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.

### Getting Boost.MPI

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

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

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