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.

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