mpi.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

boost::mpi::packed_iarchive `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 Collectives
  [[C Function] [Boost.MPI Equivalent]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node73.html#Node73
`MPI_Allgather`]] [[funcref boost::mpi::all_gather `all_gather`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node73.html#Node73
`MPI_Allgatherv`]] [most uses supported by [funcref boost::mpi::all_gather `all_gather`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node82.html#Node82
`MPI_Allreduce`]] [[funcref boost::mpi::all_reduce `all_reduce`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node75.html#Node75
`MPI_Alltoall`]] [[funcref boost::mpi::all_to_all `all_to_all`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node75.html#Node75
`MPI_Alltoallv`]] [most uses supported by [funcref boost::mpi::all_to_all `all_to_all`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node66.html#Node66
`MPI_Barrier`]] [[memberref
boost::mpi::communicator::barrier `communicator::barrier`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node67.html#Node67
`MPI_Bcast`]] [[funcref boost::mpi::broadcast `broadcast`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node69.html#Node69
`MPI_Gather`]] [[funcref boost::mpi::gather `gather`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node69.html#Node69
`MPI_Gatherv`]] [most uses supported by [funcref boost::mpi::gather `gather`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node77.html#Node77
`MPI_Reduce`]] [[funcref boost::mpi::reduce `reduce`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node83.html#Node83
`MPI_Reduce_scatter`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node84.html#Node84
`MPI_Scan`]] [[funcref boost::mpi::scan `scan`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node71.html#Node71
`MPI_Scatter`]] [[funcref boost::mpi::scatter `scatter`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node71.html#Node71
`MPI_Scatterv`]] [most uses supported by [funcref boost::mpi::scatter `scatter`]]]
]

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
[@http://www.mpi-forum.org/docs/mpi-11-html/node78.html#Node78
predefined] and
[@http://www.mpi-forum.org/docs/mpi-11-html/node80.html#Node80
user-defined] reduction operations can be mapped between the C MPI and
Boost.MPI.

[table Reduction operations
  [[C Constant] [Boost.MPI Equivalent]]

  [[`MPI_BAND`] [[classref boost::mpi::bitwise_and `bitwise_and`]]]
  [[`MPI_BOR`] [[classref boost::mpi::bitwise_or `bitwise_or`]]]
  [[`MPI_BXOR`] [[classref boost::mpi::bitwise_xor `bitwise_xor`]]]
  [[`MPI_LAND`] [`std::logical_and`]]
  [[`MPI_LOR`] [`std::logical_or`]]
  [[`MPI_LXOR`] [[classref boost::mpi::logical_xor `logical_xor`]]]
  [[`MPI_MAX`] [[classref boost::mpi::maximum `maximum`]]]
  [[`MPI_MAXLOC`] [unsupported]]
  [[`MPI_MIN`] [[classref boost::mpi::minimum `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 [classref boost::mpi::communicator
`communicator`] class in Boost.MPI.

[table Predefined communicators
  [[C Constant] [Boost.MPI Equivalent]]

  [[`MPI_COMM_WORLD`] [a default-constructed [classref boost::mpi::communicator `communicator`]]]
  [[`MPI_COMM_SELF`] [a [classref boost::mpi::communicator `communicator`] that contains only the current process]]
  [[`MPI_COMM_EMPTY`] [a [classref boost::mpi::communicator `communicator`] that evaluates false]]
]

Boost.MPI supports groups of processes through its [classref
boost::mpi::group `group`] class.

[table Group operations and constants
  [[C Function/Constant] [Boost.MPI Equivalent]]

  [[`MPI_GROUP_EMPTY`] [a default-constructed [classref
  boost::mpi::group `group`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97
  `MPI_Group_size`]] [[memberref boost::mpi::group::size `group::size`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97
  `MPI_Group_rank`]] [memberref boost::mpi::group::rank `group::rank`]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97
  `MPI_Group_translate_ranks`]] [memberref boost::mpi::group::translate_ranks `group::translate_ranks`]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97
  `MPI_Group_compare`]] [operators `==` and `!=`]]
  [[`MPI_IDENT`] [operators `==` and `!=`]]
  [[`MPI_SIMILAR`] [operators `==` and `!=`]]
  [[`MPI_UNEQUAL`] [operators `==` and `!=`]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Comm_group`]] [[memberref
  boost::mpi::communicator::group `communicator::group`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_union`]] [operator `|` for groups]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_intersection`]] [operator `&` for groups]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_difference`]] [operator `-` for groups]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_incl`]] [[memberref boost::mpi::group::include `group::include`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_excl`]] [[memberref boost::mpi::group::include `group::exclude`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_range_incl`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98
  `MPI_Group_range_excl`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node99.html#Node99
  `MPI_Group_free`]] [used automatically in Boost.MPI]]
]

Boost.MPI provides manipulation of communicators through the [classref
boost::mpi::communicator `communicator`] class.

[table Communicator operations
  [[C Function] [Boost.MPI Equivalent]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101
  `MPI_Comm_size`]] [[memberref boost::mpi::communicator::size `communicator::size`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101
  `MPI_Comm_rank`]] [[memberref boost::mpi::communicator::rank
  `communicator::rank`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101
  `MPI_Comm_compare`]] [operators `==` and `!=`]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102
  `MPI_Comm_dup`]] [[classref boost::mpi::communicator `communicator`]
  class constructor using `comm_duplicate`]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102
  `MPI_Comm_create`]] [[classref boost::mpi::communicator
  `communicator`] constructor]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102
  `MPI_Comm_split`]] [[memberref boost::mpi::communicator::split
  `communicator::split`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node103.html#Node103
  `MPI_Comm_free`]] [used automatically in Boost.MPI]]
]

Boost.MPI currently provides support for inter-communicators via the
[classref boost::mpi::intercommunicator `intercommunicator`] class.

[table Inter-communicator operations
  [[C Function] [Boost.MPI Equivalent]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node112.html#Node112
  `MPI_Comm_test_inter`]] [use [memberref boost::mpi::communicator::as_intercommunicator `communicator::as_intercommunicator`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node112.html#Node112
  `MPI_Comm_remote_size`]] [[memberref boost::mpi::intercommunicator::remote_size] `intercommunicator::remote_size`]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node112.html#Node112
  `MPI_Comm_remote_group`]] [[memberref boost::mpi::intercommunicator::remote_group `intercommunicator::remote_group`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node113.html#Node113
  `MPI_Intercomm_create`]] [[classref boost::mpi::intercommunicator `intercommunicator`] constructor]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node113.html#Node113
  `MPI_Intercomm_merge`]] [[memberref boost::mpi::intercommunicator::merge `intercommunicator::merge`]]]
]

Boost.MPI currently provides no support for attribute caching.

[table Attributes and caching
 [[C Function/Constant] [Boost.MPI Equivalent]]

 [[`MPI_NULL_COPY_FN`] [unsupported]]
 [[`MPI_NULL_DELETE_FN`] [unsupported]]
 [[`MPI_KEYVAL_INVALID`] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `MPI_Keyval_create`]] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `MPI_Copy_function`]] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `MPI_Delete_function`]] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `MPI_Keyval_free`]] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `MPI_Attr_put`]] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `MPI_Attr_get`]] [unsupported]]
 [[[@http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119
 `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
[@http://www.boost.org/libs/graph/doc/index.html 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 Process topologies
  [[C Function/Constant] [Boost.MPI Equivalent]]
  
  [[`MPI_GRAPH`] [unnecessary; use [memberref boost::mpi::communicator::has_graph_topology `communicator::has_graph_topology`]]]
  [[`MPI_CART`] [unnecessary; use [memberref boost::mpi::communicator::has_cartesian_topology `communicator::has_cartesian_topology`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node133.html#Node133
  `MPI_Cart_create`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node134.html#Node134
  `MPI_Dims_create`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node135.html#Node135
  `MPI_Graph_create`]] [[memberref
  boost::mpi::communicator::with_graph_topology
  `communicator::with_graph_topology`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Topo_test`]] [[memberref
  boost::mpi::communicator::has_graph_topology
  `communicator::has_graph_topology`], [memberref
  boost::mpi::communicator::has_cartesian_topology
  `communicator::has_cartesian_topology`]]] 
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Graphdims_get`]] [[funcref boost::mpi::num_vertices
  `num_vertices`], [funcref boost::mpi::num_edges `num_edges`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Graph_get`]] [[funcref boost::mpi::vertices
  `vertices`], [funcref boost::mpi::edges `edges`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Cartdim_get`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Cart_get`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Cart_rank`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Cart_coords`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Graph_neighbors_count`]] [[funcref boost::mpi::out_degree
  `out_degree`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136
  `MPI_Graph_neighbors`]] [[funcref boost::mpi::out_edges
  `out_edges`], [funcref boost::mpi::adjacent_vertices `adjacent_vertices`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node137.html#Node137
  `MPI_Cart_shift`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node138.html#Node138
  `MPI_Cart_sub`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node139.html#Node139
  `MPI_Cart_map`]] [unsupported]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node139.html#Node139
  `MPI_Graph_map`]] [unsupported]]
]

Boost.MPI supports environmental inquires through the [classref
boost::mpi::environment `environment`] class.

[table Environmental inquiries
  [[C Function/Constant] [Boost.MPI Equivalent]]

  [[`MPI_TAG_UB`] [unnecessary; use [memberref
  boost::mpi::environment::max_tag `environment::max_tag`]]]
  [[`MPI_HOST`] [unnecessary; use [memberref
  boost::mpi::environment::host_rank `environment::host_rank`]]]
  [[`MPI_IO`] [unnecessary; use [memberref
  boost::mpi::environment::io_rank `environment::io_rank`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node143.html#Node147
  `MPI_Get_processor_name`]] 
  [[memberref boost::mpi::environment::processor_name
  `environment::processor_name`]]]
]

Boost.MPI translates MPI errors into exceptions, reported via the
[classref boost::mpi::exception `exception`] class.

[table 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]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148
  `MPI_errhandler_create`]] [unused; errors are translated into
  Boost.MPI exceptions]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148
  `MPI_errhandler_set`]] [unused; errors are translated into
  Boost.MPI exceptions]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148
  `MPI_errhandler_get`]] [unused; errors are translated into
  Boost.MPI exceptions]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148
  `MPI_errhandler_free`]] [unused; errors are translated into
  Boost.MPI exceptions]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148
  `MPI_Error_string`]] [used internally by Boost.MPI]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node149.html#Node149
  `MPI_Error_class`]] [[memberref boost::mpi::exception::error_class `exception::error_class`]]]
]

The MPI timing facilities are exposed via the Boost.MPI [classref
boost::mpi::timer `timer`] class, which provides an interface
compatible with the [@http://www.boost.org/libs/timer/index.html Boost
Timer library].

[table Timing facilities
  [[C Function/Constant] [Boost.MPI Equivalent]]

  [[`MPI_WTIME_IS_GLOBAL`] [unnecessary; use [memberref
  boost::mpi::timer::time_is_global `timer::time_is_global`]]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node150.html#Node150
  `MPI_Wtime`]] [use [memberref boost::mpi::timer::elapsed
  `timer::elapsed`] to determine the time elapsed from some specific
  starting point]]
  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node150.html#Node150
  `MPI_Wtick`]] [[memberref boost::mpi::timer::elapsed_min `timer::elapsed_min`]]]
]

MPI startup and shutdown are managed by the construction