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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.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 24.17. Profiling interface

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