| Home | Libraries | People | FAQ | More

## Mapping from C MPI to Boost.MPI

This section provides tables that map from the functions and constants of the standard C MPI to their Boost.MPI equivalents. It will be most useful for users that are already familiar with the C or Fortran interfaces to MPI, or for porting existing parallel programs to Boost.MPI.

Note that this is not a perfect one to one mapping, the Boost.MPI will sometime use function from the C API in a way that is transparent for the end user. For example, `MPI_Probe and friends` can be used to implement asynchronous send/recv.

Table 23.1. Point-to-point communication

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_ANY_SOURCE` | `any_source`
`MPI_ANY_TAG` | `any_tag`
`MPI_Bsend` | unsupported
`MPI_Bsend_init` | unsupported
`MPI_Buffer_attach` | unsupported
`MPI_Buffer_detach` | unsupported
`MPI_Cancel` | `request::cancel`
`MPI_Get_count` | `status::count`
`MPI_Ibsend` | unsupported
`MPI_Iprobe` | `communicator::iprobe`
`MPI_Irsend` | unsupported
`MPI_Isend` | `communicator::isend`
`MPI_Issend` | unsupported
`MPI_Irecv` | `communicator::irecv`
`MPI_Probe` | `communicator::probe`
`MPI_PROC_NULL` | unsupported
`MPI_Recv` | `communicator::recv`
`MPI_Recv_init` | unsupported
`MPI_Request_free` | unsupported
`MPI_Rsend` | unsupported
`MPI_Rsend_init` | unsupported
`MPI_Send` | `communicator::send`
`MPI_Sendrecv` | `communicator::sendrecv`
`MPI_Sendrecv_replace` | unsupported
`MPI_Send_init` | unsupported
`MPI_Ssend` | unsupported
`MPI_Ssend_init` | unsupported
`MPI_Start` | unsupported
`MPI_Startall` | unsupported
`MPI_Test` | `request::test`
`MPI_Testall` | `test_all`
`MPI_Testany` | `test_any`
`MPI_Testsome` | `test_some`
`MPI_Test_cancelled` | `status::cancelled`
`MPI_Wait` | `request::wait`
`MPI_Waitall` | `wait_all`
`MPI_Waitany` | `wait_any`
`MPI_Waitsome` | `wait_some`

Boost.MPI automatically maps C and C++ data types to their MPI equivalents. The following table illustrates the mappings between C++ types and MPI datatype constants.

Table 23.2. Datatypes

C Constant | Boost.MPI Equivalent
--- | ---
`MPI_CHAR` | `signed char`
`MPI_SHORT` | `signed short int`
`MPI_INT` | `signed int`
`MPI_LONG` | `signed long int`
`MPI_UNSIGNED_CHAR` | `unsigned char`
`MPI_UNSIGNED_SHORT` | `unsigned short int`
`MPI_UNSIGNED_INT` | `unsigned int`
`MPI_UNSIGNED_LONG` | `unsigned long int`
`MPI_FLOAT` | `float`
`MPI_DOUBLE` | `double`
`MPI_LONG_DOUBLE` | `long double`
`MPI_BYTE` | unused
`MPI_PACKED` | used internally for serialized data types
`MPI_LONG_LONG_INT` | `long long int`, if supported by compiler
`MPI_UNSIGNED_LONG_LONG_INT` | `unsigned long long int`, if supported by compiler
`MPI_FLOAT_INT` | `std::pair<float, int>`
`MPI_DOUBLE_INT` | `std::pair<double, int>`
`MPI_LONG_INT` | `std::pair<long, int>`
`MPI_2INT` | `std::pair<int, int>`
`MPI_SHORT_INT` | `std::pair<short, int>`
`MPI_LONG_DOUBLE_INT` | `std::pair<long double, int>`

Boost.MPI does not provide direct wrappers to the MPI derived datatypes functionality. Instead, Boost.MPI relies on the Boost.Serialization library to construct MPI datatypes for user-defined classes. The section on user-defined data types describes this mechanism, which is used for types that marked as "MPI datatypes" using `is_mpi_datatype`.

The derived datatypes table that follows describes which C++ types correspond to the functionality of the C MPI's datatype constructor. Boost.MPI may not actually use the C MPI function listed when building datatypes of a certain form. Since the actual datatypes built by Boost.MPI are typically hidden from the user, many of these operations are called internally by Boost.MPI.

Table 23.3. Derived datatypes

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_Address` | used automatically in Boost.MPI for MPI version 1.x
`MPI_Get_address` | used automatically in Boost.MPI for MPI version 2.0 and higher
`MPI_Type_commit` | used automatically in Boost.MPI
`MPI_Type_contiguous` | arrays
`MPI_Type_extent` | used automatically in Boost.MPI
`MPI_Type_free` | used automatically in Boost.MPI
`MPI_Type_hindexed` | any type used as a subobject
`MPI_Type_hvector` | unused
`MPI_Type_indexed` | any type used as a subobject
`MPI_Type_lb` | unsupported
`MPI_Type_size` | used automatically in Boost.MPI
`MPI_Type_struct` | user-defined classes and structs with MPI 1.x
`MPI_Type_create_struct` | user-defined classes and structs with MPI 2.0 and higher
`MPI_Type_ub` | unsupported
`MPI_Type_vector` | used automatically in Boost.MPI

MPI's packing facilities store values into a contiguous buffer, which can later be transmitted via MPI and unpacked into separate values via MPI's unpacking facilities. As with datatypes, Boost.MPI provides an abstract interface to MPI's packing and unpacking facilities. In particular, the two archive classes `packed_oarchive` and `packed_iarchive` can be used to pack or unpack a contiguous buffer using MPI's facilities.

Table 23.4. Packing and unpacking

C Function | Boost.MPI Equivalent
--- | ---
`MPI_Pack` | `packed_oarchive`
`MPI_Pack_size` | used internally by Boost.MPI
`MPI_Unpack` | `packed_iarchive`

Boost.MPI supports a one-to-one mapping for most of the MPI collectives. For each collective provided by Boost.MPI, the underlying C MPI collective will be invoked when it is possible (and efficient) to do so.

Table 23.5. Collectives

C Function | Boost.MPI Equivalent
--- | ---
`MPI_Allgather` | `all_gather`
`MPI_Allgatherv` | most uses supported by `all_gather`
`MPI_Allreduce` | `all_reduce`
`MPI_Alltoall` | `all_to_all`
`MPI_Alltoallv` | most uses supported by `all_to_all`
`MPI_Barrier` | `communicator::barrier`
`MPI_Bcast` | `broadcast`
`MPI_Gather` | `gather`
`MPI_Gatherv` | most uses supported by `gather`, other usages supported by `gatherv`
`MPI_Reduce` | `reduce`
`MPI_Reduce_scatter` | unsupported
`MPI_Scan` | `scan`
`MPI_Scatter` | `scatter`
`MPI_Scatterv` | most uses supported by `scatter`, other uses supported by `scatterv`
`MPI_IN_PLACE` | supported implicitly by `all_reduce by omitting the output value`

Boost.MPI uses function objects to specify how reductions should occur in its equivalents to `MPI_Allreduce`, `MPI_Reduce`, and `MPI_Scan`. The following table illustrates how predefined and user-defined reduction operations can be mapped between the C MPI and Boost.MPI.

Table 23.6. Reduction operations

C Constant | Boost.MPI Equivalent
--- | ---
`MPI_BAND` | `bitwise_and`
`MPI_BOR` | `bitwise_or`
`MPI_BXOR` | `bitwise_xor`
`MPI_LAND` | `std::logical_and`
`MPI_LOR` | `std::logical_or`
`MPI_LXOR` | `logical_xor`
`MPI_MAX` | `maximum`
`MPI_MAXLOC` | unsupported
`MPI_MIN` | `minimum`
`MPI_MINLOC` | unsupported
`MPI_Op_create` | used internally by Boost.MPI
`MPI_Op_free` | used internally by Boost.MPI
`MPI_PROD` | `std::multiplies`
`MPI_SUM` | `std::plus`

MPI defines several special communicators, including `MPI_COMM_WORLD` (including all processes that the local process can communicate with), `MPI_COMM_SELF` (including only the local process), and `MPI_COMM_EMPTY` (including no processes). These special communicators are all instances of the `communicator` class in Boost.MPI.

Table 23.7. Predefined communicators

C Constant | Boost.MPI Equivalent
--- | ---
`MPI_COMM_WORLD` | a default-constructed `communicator`
`MPI_COMM_SELF` | a `communicator` that contains only the current process
`MPI_COMM_EMPTY` | a `communicator` that evaluates false

Boost.MPI supports groups of processes through its `group` class.

Table 23.8. Group operations and constants

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_GROUP_EMPTY` | a default-constructed `group`
`MPI_Group_size` | `group::size`
`MPI_Group_rank` | memberref boost::mpi::group::rank `group::rank`
`MPI_Group_translate_ranks` | memberref boost::mpi::group::translate_ranks `group::translate_ranks`
`MPI_Group_compare` | operators `==` and `!=`
`MPI_IDENT` | operators `==` and `!=`
`MPI_SIMILAR` | operators `==` and `!=`
`MPI_UNEQUAL` | operators `==` and `!=`
`MPI_Comm_group` | `communicator::group`
`MPI_Group_union` | operator `|` for groups
`MPI_Group_intersection` | operator `&` for groups
`MPI_Group_difference` | operator `-` for groups
`MPI_Group_incl` | `group::include`
`MPI_Group_excl` | `group::exclude`
`MPI_Group_range_incl` | unsupported
`MPI_Group_range_excl` | unsupported
`MPI_Group_free` | used automatically in Boost.MPI

Boost.MPI provides manipulation of communicators through the `communicator` class.

Table 23.9. Communicator operations

C Function | Boost.MPI Equivalent
--- | ---
`MPI_Comm_size` | `communicator::size`
`MPI_Comm_rank` | `communicator::rank`
`MPI_Comm_compare` | operators `==` and `!=`
`MPI_Comm_dup` | `communicator` class constructor using `comm_duplicate`
`MPI_Comm_create` | `communicator` constructor
`MPI_Comm_split` | `communicator::split`
`MPI_Comm_free` | used automatically in Boost.MPI

Boost.MPI currently provides support for inter-communicators via the `intercommunicator` class.

Table 23.10. Inter-communicator operations

C Function | Boost.MPI Equivalent
--- | ---
`MPI_Comm_test_inter` | use `communicator::as_intercommunicator`
`MPI_Comm_remote_size` | `boost::mpi::intercommunicator::remote_size` `intercommunicator::remote_size`
`MPI_Comm_remote_group` | `intercommunicator::remote_group`
`MPI_Intercomm_create` | `intercommunicator` constructor
`MPI_Intercomm_merge` | `intercommunicator::merge`

Boost.MPI currently provides no support for attribute caching.

Table 23.11. Attributes and caching

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_NULL_COPY_FN` | unsupported
`MPI_NULL_DELETE_FN` | unsupported
`MPI_KEYVAL_INVALID` | unsupported
`MPI_Keyval_create` | unsupported
`MPI_Copy_function` | unsupported
`MPI_Delete_function` | unsupported
`MPI_Keyval_free` | unsupported
`MPI_Attr_put` | unsupported
`MPI_Attr_get` | unsupported
`MPI_Attr_delete` | unsupported

Boost.MPI will provide complete support for creating communicators with different topologies and later querying those topologies. Support for graph topologies is provided via an interface to the Boost Graph Library (BGL), where a communicator can be created which matches the structure of any BGL graph, and the graph topology of a communicator can be viewed as a BGL graph for use in existing, generic graph algorithms.

Table 23.12. Process topologies

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_GRAPH` | unnecessary; use `communicator::as_graph_communicator`
`MPI_CART` | unnecessary; use `communicator::has_cartesian_topology`
`MPI_Cart_create` | `cartesian_communicator` constructor
`MPI_Dims_create` | `cartesian_dimensions`
`MPI_Graph_create` | `graph_communicator ctors`
`MPI_Topo_test` | `communicator::as_graph_communicator`, `communicator::has_cartesian_topology`
`MPI_Graphdims_get` | `num_vertices`, `num_edges`
`MPI_Graph_get` | `vertices`, `edges`
`MPI_Cartdim_get` | `cartesian_communicator::ndims`
`MPI_Cart_get` | `cartesian_communicator::topology`
`MPI_Cart_rank` | `cartesian_communicator::rank`
`MPI_Cart_coords` | `cartesian_communicator::coordinates`
`MPI_Graph_neighbors_count` | `out_degree`
`MPI_Graph_neighbors` | `out_edges`, `adjacent_vertices`
`MPI_Cart_shift` | `cartesian_communicator::shifted_ranks`
`MPI_Cart_sub` | `cartesian_communicator` constructor
`MPI_Cart_map` | unsupported
`MPI_Graph_map` | unsupported

Boost.MPI supports environmental inquires through the `environment` class.

Table 23.13. Environmental inquiries

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_TAG_UB` | unnecessary; use `environment::max_tag`
`MPI_HOST` | unnecessary; use `environment::host_rank`
`MPI_IO` | unnecessary; use `environment::io_rank`
`MPI_Get_processor_name` | `environment::processor_name`

Boost.MPI translates MPI errors into exceptions, reported via the `exception` class.

Table 23.14. Error handling

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_ERRORS_ARE_FATAL` | unused; errors are translated into Boost.MPI exceptions
`MPI_ERRORS_RETURN` | unused; errors are translated into Boost.MPI exceptions
`MPI_errhandler_create` | unused; errors are translated into Boost.MPI exceptions
`MPI_errhandler_set` | unused; errors are translated into Boost.MPI exceptions
`MPI_errhandler_get` | unused; errors are translated into Boost.MPI exceptions
`MPI_errhandler_free` | unused; errors are translated into Boost.MPI exceptions
`MPI_Error_string` | used internally by Boost.MPI
`MPI_Error_class` | `exception::error_class`

The MPI timing facilities are exposed via the Boost.MPI `timer` class, which provides an interface compatible with the Boost Timer library.

Table 23.15. Timing facilities

C Function/Constant | Boost.MPI Equivalent
--- | ---
`MPI_WTIME_IS_GLOBAL` | unnecessary; use `timer::time_is_global`
`MPI_Wtime` | use `timer::elapsed` to determine the time elapsed from some specific starting point
`MPI_Wtick` | `timer::elapsed_min`

MPI startup and shutdown are managed by the construction and destruction of the Boost.MPI `environment` class.

Table 23.16. Startup/shutdown facilities

C Function | Boost.MPI Equivalent
--- | ---
`MPI_Init` | `environment` constructor
`MPI_Finalize` | `environment` destructor
`MPI_Initialized` | `environment::initialized`
`MPI_Abort` | `environment::abort`

Boost.MPI does not provide any support for the profiling facilities in MPI 1.1.

Table 23.17. Profiling interface

C Function | Boost.MPI Equivalent
--- | ---
`PMPI_*` routines | unsupported
`MPI_Pcontrol` | unsupported