API Documentation

Table of Contents

• • MPI essentials
  • MPI datatypes and operations
  • Collective MPI communication
  • Lazy MPI communication
  • Event handling
  • Utilities

mpi implements various high-level C++ wrappers around their low-level C counterparts. It is not intended as a full replacement for the C implementation. Instead it tries to help the user with the most common tasks like initializing and finalizing an MPI environment or sending data via collective communications.

The following provides a detailed reference documentation grouped into logical units.

If you are looking for a specific function, class, etc., try using the search bar in the top left corner.

MPI essentials

MPI essentials provide the user with two classes necessary for any MPI program:

• The mpi::environment class is used to initialize and finialize the MPI execution environment. It calls MPI_Init in its constructor and MPI_Finalize in its destructor. There should be at most one instance in every program and it is usually created at the very beginning of the main function.
• The mpi::communicator class is a simple wrapper around an MPI_Comm object. Besides storing the MPI_Comm object, it also provides some convient functions for getting the size of the communicator, the rank of the current process or for splitting an existing communicator.

It further contains the convenient function mpi::is_initialized and the static boolean mpi::has_env.

MPI datatypes and operations

MPI datatypes and operations map various C++ datatypes to MPI datatypes and help the user with registering their own datatypes to be used in MPI communications. Furthermore, it offers tools to simplify the creation of custom MPI operations usually required in MPI_Reduce or MPI_Accumulate functions.

Collective MPI communication

The following generic collective communications are defined in Collective MPI communication:

• all_gather
• all_reduce
• all_reduce_in_place
• broadcast
• gather
• reduce
• reduce_in_place
• scatter

They offer a much simpler interface than their MPI C library analogs. For example, the following broadcasts a std::vector<double> from the process with rank 0 to all others:

mpi::broadcast(vec);

Compare this with the call to the C library:

MPI_Bcast(vec.data(), static_cast<int>(vec.size()), MPI_DOUBLE, 0, MPI_COMM_WORLD);

Under the hood, the generic mpi::broadcast implementation calls the specialized mpi::mpi_broadcast(std::vector< T >&, mpi::communicator, int). The other generic functions are implemented in the same way. See the "Functions" section in Collective MPI communication to check which datatypes are supported out of the box.

In case your datatype is not supported, you are free to provide your own specialization.

Furthermore, there are several functions to simplify communicating generic, contiguous ranges:

• mpi::broadcast_range,
• mpi::gather_range,
• mpi::reduce_in_place_range,
• mpi::reduce_range and
• mpi::scatter_range.

Lazy MPI communication

Lazy MPI communication can be used to provied collective MPI communication for lazy expression types. Most users probably won't need to use this functionality directly.

We refer the interested reader to TRIQS/nda for more details.

Event handling

Event handling provides the mpi::monitor class which can be used to communicate and handle events across multiple processes.

Example 2: Use monitor to communicate errors shows a simple use case.

Utilities

Utilities is a collection of various other tools in mpi which do not fit into any other category above.

For users, the most useful of them is probably mpi::check_mpi_call. A wrapper function that checks the error code returned by MPI C library routines and throws an exception in case the code is != MPI_SUCCESS.