Some basic clean up and doc updates

Author: Thoemi09

c++/mpi/chunk.hpp

@@ -22,11 +22,11 @@
 #pragma once
 
 #include "./communicator.hpp"
+#include "./macros.hpp"
 
 #include <itertools/itertools.hpp>
 
 #include <iterator>
-#include <stdexcept>
 #include <utility>
 
 namespace mpi {
@@ -39,7 +39,7 @@ namespace mpi {
    * @details The optional parameter `min_size` can be used to first divide the range into equal parts of size
    * `min_size` before distributing them as evenly as possible across the number of specified subranges.
    *
-   * It throws an exception if `min_size < 1` or if it is not a divisor of `end`.
+   * It is expected that `min_size > 0` and that `min_size` is a divisor of `end`.
    *
    * @param end End of the integer range `[0, end)`.
    * @param nranges Number of subranges.
@@ -48,7 +48,7 @@ namespace mpi {
    * @return Length of the i<sup>th</sup> subrange.
    */
   [[nodiscard]] inline long chunk_length(long end, int nranges, int i, long min_size = 1) {
-    if (min_size < 1 || end % min_size != 0) throw std::runtime_error("Error in mpi::chunk_length: min_size must be a divisor of end");
+    EXPECTS_WITH_MESSAGE(min_size > 0 && end % min_size == 0, "Error in mpi::chunk_length: min_size must be a divisor of end");
     auto [node_begin, node_end] = itertools::chunk_range(0, end / min_size, nranges, i);
     return (node_end - node_begin) * min_size;
   }

c++/mpi/datatypes.hpp

@@ -91,8 +91,9 @@ namespace mpi {
   template <typename T> struct mpi_type<const T> : mpi_type<T> {};
 
   /**
-   * @brief Type trait to check if a type T has a corresponding MPI datatype, i.e. if mpi::mpi_type has been specialized.
-   * @tparam T Type to be checked.
+   * @brief Type trait to check if a type `T` has a corresponding MPI datatype, i.e. if mpi::mpi_type has been
+   * specialized.
+   * @tparam `T` Type to be checked.
    */
   template <typename T, typename = void> constexpr bool has_mpi_type = false;
 

c++/mpi/macros.hpp

@@ -87,12 +87,12 @@
 
 #ifdef NDEBUG
 
-#define EXPECTS(X)
-#define ASSERT(X)
-#define ENSURES(X)
-#define EXPECTS_WITH_MESSAGE(X, ...)
-#define ASSERT_WITH_MESSAGE(X, ...)
-#define ENSURES_WITH_MESSAGE(X, ...)
+#define EXPECTS(X) {}
+#define ASSERT(X) {}
+#define ENSURES(X) {}
+#define EXPECTS_WITH_MESSAGE(X, ...) {}
+#define ASSERT_WITH_MESSAGE(X, ...) {}
+#define ENSURES_WITH_MESSAGE(X, ...) {}
 
 #else
 

doc/DoxygenLayout.xml

@@ -22,6 +22,7 @@
       <tab type="user" url="@ref ex1" title="Example 1: Hello world!"/>
       <tab type="user" url="@ref ex2" title="Example 2: Use monitor to communicate errors"/>
       <tab type="user" url="@ref ex3" title="Example 3: Custom type and operator"/>
+      <tab type="user" url="@ref ex4" title="Example 4: Provide custom spezializations"/>
     </tab>
     <tab type="usergroup" url="@ref documentation" title="API Documentation">
       <tab type="usergroup" url="@ref mpi_essentials" title="MPI essentials">
@@ -50,17 +51,11 @@
         </tab>
       </tab>
       <tab type="user" url="@ref coll_comm" title="Collective MPI communication"/>
-      <tab type="usergroup" url="@ref mpi_lazy" title="Lazy MPI communication">
-        <tab type="user" url="@ref mpi::lazy" title="lazy"/>
-        <tab type="user" url="@ref mpi::tag::gather" title="gather tag"/>
-        <tab type="user" url="@ref mpi::tag::reduce" title="reduce tag"/>
-        <tab type="user" url="@ref mpi::tag::scatter" title="scatter tag"/>
-      </tab>
       <tab type="usergroup" url="@ref event_handling" title="Event handling">
         <tab type="user" url="@ref mpi::monitor" title="monitor"/>
       </tab>
       <tab type="usergroup" url="@ref utilities" title="Utilities">
-        <tab type="user" url="@ref mpi::contiguous_sized_range" title="contiguous_sized_range"/>
+        <tab type="user" url="@ref mpi::MPICompatibleRange" title="MPICompatibleRange"/>
       </tab>
       <tab type="filelist" visible="yes" title="" intro=""/>
     </tab>

doc/documentation.md

@@ -35,17 +35,7 @@ Furthermore, it offers tools to simplify the creation of custom MPI operations u
 
 ## Collective MPI communication
 
-The following generic collective communications are defined in @ref coll_comm "Collective MPI communication":
-
-* @ref mpi::all_gather "all_gather"
-* @ref mpi::all_reduce "all_reduce"
-* @ref mpi::all_reduce_in_place "all_reduce_in_place"
-* @ref mpi::broadcast "broadcast"
-* @ref mpi::gather "gather"
-* @ref mpi::reduce "reduce"
-* @ref mpi::reduce_in_place "reduce_in_place"
-* @ref mpi::scatter "scatter"
-
+**mpi** provides several generic @ref coll_comm "Collective MPI communication".
 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:
 
@@ -61,18 +51,11 @@ MPI_Bcast(vec.data(), static_cast<int>(vec.size()), MPI_DOUBLE, 0, MPI_COMM_WORL
 
 Under the hood, the generic mpi::broadcast implementation calls the specialized
 @ref "mpi::mpi_broadcast(std::vector< T >&, mpi::communicator, int)".
-The other generic functions are implemented in the same way.
-See the "Functions" section in @ref coll_comm to check which datatypes are supported out of the box.
+Other generic functions in **mpi** work similarly.
+See the "Functions" section in @ref coll_comm to check which datatypes and MPI operations 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
 
 @ref mpi_lazy can be used to provied collective MPI communication for lazy expression types.

doc/ex4.md

@@ -0,0 +1,63 @@
+@page ex4 Example 4: Provide custom spezializations
+
+[TOC]
+
+In this example, we show how to write a specialized `mpi_reduce_into` for a custom type.
+
+```cpp
+#include <mpi/mpi.hpp>
+#include <iostream>
+#include <vector>
+
+// Custom type.
+class foo {
+  public:
+  // Constructor.
+  foo(int x = 5) : x_(x) {}
+
+  // Get the value stored in the class.
+  int x() const { return x_; }
+
+  // Specialization of mpi_reduce_into for the custom type.
+  friend void mpi_reduce_into(foo const &f_in, foo &f_out, mpi::communicator c = {}, int root = 0, bool all = false, MPI_Op op = MPI_SUM) {
+    mpi::reduce_into(f_in.x_, f_out.x_, c, root, all, op);
+  }
+
+  private:
+  int x_;
+};
+
+int main(int argc, char *argv[]) {
+  // initialize MPI environment
+  mpi::environment env(argc, argv);
+  mpi::communicator world;
+
+  // create a vector of foo objects
+  std::vector<foo> vec {foo{1}, foo{2}, foo{3}, foo{4}, foo{5}};
+
+  // reduce the vector of foo objects
+  auto result = mpi::reduce(vec, world);
+
+  // print the result on rank 0
+  if (world.rank() == 0) {
+    std::cout << "Reduced vector: ";
+    for (auto const &f : result) std::cout << f.x() << " ";
+    std::cout << "\n";
+  }
+}
+```
+
+Output (running with `-n 4`):
+
+```
+Reduced vector: 4 8 12 16 20
+```
+
+Note that by providing a simple `mpi_reduce_into` for our custom `foo` type, we are able to reduce a `std::vector` of
+`foo` objects without any additional work.
+
+Under the hood, each `foo` object is reduced spearately using the above specialization.
+For large amounts of data or in performance critical code sections, this might not be desired.
+In such a case, it is usally better to make the type MPI compatible such that the reduction can be done with a single
+call to MPI C library.
+See @ref ex3 for more details.

doc/examples.md

@@ -5,13 +5,16 @@
 - @ref ex1 "Example 1: Hello world!"
 - @ref ex2 "Example 2: Use monitor to communicate errors"
 - @ref ex3 "Example 3: Custom type and operator"
+- @ref ex4 "Example 4: Provide custom spezializations"
 
 @section compiling Compiling the examples
 
-All examples have been compiled on a MacBook Pro with an Apple M2 Max chip and [open-mpi](https://www.open-mpi.org/) 4.1.5.
-We further used clang 16.0.6 together with cmake 3.27.2.
+All examples have been compiled on a MacBook Pro with an Apple M2 Max chip and [open-mpi](https://www.open-mpi.org/)
+5.0.1.
+We further used clang 19.1.7 together with cmake 3.31.5.
 
-Assuming that the actual example code is in a file `main.cpp`, the following generic `CMakeLists.txt` should work for all examples:
+Assuming that the actual example code is in a file `main.cpp`, the following generic `CMakeLists.txt` should work for
+all examples:
 
 ```cmake
 cmake_minimum_required(VERSION 3.20)
@@ -28,7 +31,7 @@ include (FetchContent)
 FetchContent_Declare(
   mpi
   GIT_REPOSITORY https://github.com/TRIQS/mpi.git
-  GIT_TAG        1.2.x
+  GIT_TAG        1.3.x
 )
 FetchContent_MakeAvailable(mpi)
 

doc/groups.dox

@@ -51,17 +51,46 @@
  * @brief Generic and specialized implementations for a subset of collective MPI communications (broadcast, reduce,
  * gather, scatter).
  *
- * @details The generic functions (mpi::broadcast, mpi::reduce, mpi::scatter, ...) call their more specialized
- * counterparts (e.g. mpi::mpi_broadcast, mpi::mpi_reduce, mpi::mpi_scatter, ...).
- *
- * **mpi** provides (some) implementations for
- * - scalar types that have a corresponding mpi::mpi_type,
- * - `std::vector` and `std::array` types with MPI compatible value types,
- * - `std::string` and
- * - `std::pair`.
- *
- * 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.
+ * @details **mpi** provides several generic collective communications routines as well as specializations for certain
+ * common types. The generic functions usually simply forward the call to one of the specializations (`mpi_broadcast`,
+ * `mpi_gather`, `mpi_gather_into`, `mpi_reduce`, `mpi_reduce_into`, `mpi_scatter` or `mpi_scatter_into`) using ADL but
+ * can also perform some additional checks. It is therefore recommended to always use the generic versions when
+ * possible.
+ *
+ * Here is a short overview of the available generic functions:
+ * - mpi::broadcast: Calls the specialization `mpi_broadcast`.
+ * - mpi::gather: Calls the specialization `mpi_gather` if it is implemented. Otherwise, it calls mpi::gather_into with
+ * a default constructed output object.
+ * - mpi::gather_into: Calls the specialization `mpi_gather_into`.
+ * - mpi::reduce: Calls the specialization `mpi_reduce` if it is implemented. Otherwise, it calls mpi::reduce_into with
+ * a default constructed output object.
+ * - mpi::reduce_in_place: Calls the specialization `mpi_reduce_into` with the same input and output object.
+ * - mpi::reduce_into: Calls the specialization `mpi_reduce_into`.
+ * - mpi::scatter: Calls the specialization `mpi_scatter` if it is implemented. Otherwise, it calls mpi::scatter_into
+ * with a default constructed output object.
+ * - mpi::scatter_into: Calls the specialization `mpi_scatter_into`.
+ *
+ * In case, all processes should receive the result of the MPI operation, one can use the convenience functions
+ * mpi::all_gather, mpi::all_gather_into, mpi::all_reduce, mpi::all_reduce_in_place or mpi::all_reduce_into. They
+ * forward the given arguments to their "non-all" counterparts with the `all` argument set to true.
+ *
+ * **mpi** provides various specializations for several types. For example,
+ * - for MPI compatible types, i.e. for types that have a corresponding mpi::mpi_type, it provides an
+ * @ref "mpi::mpi_broadcast(T &x, mpi::communicator, int)" "mpi_broadcast",
+ * @ref "mpi::mpi_reduce(T const &, mpi::communicator, int, bool, MPI_Op)" "mpi_reduce",
+ * @ref "mpi::mpi_reduce_into(T const &, T &, mpi::communicator, int, bool, MPI_Op)" "mpi_reduce_into",
+ * @ref "mpi::mpi_gather(T const &, mpi::communicator, int, bool)" "mpi_gather" and an
+ * @ref "mpi::mpi_gather_into(T const &, R &&, mpi::communicator, int, bool)" "mpi_gather_into".
+ * - for strings, it provides an @ref "mpi::mpi_broadcast(std::string &, mpi::communicator, int)" "mpi_broadcast"
+ * and an @ref "mpi::mpi_gather_into(std::string const &, std::string &, mpi::communicator, int, bool)"
+ * "mpi_gather_into".
+ *
+ * Users are encouraged to implement their own specializations for their custom types or in case a specialization is
+ * missing (see e.g. @ref ex4).
+ *
+ * Furthermore, there are several functions to simplify communicating (contiguous) ranges: mpi::broadcast_range,
+ * mpi::gather_range, mpi::reduce_range and mpi::scatter_range. Some of these range functions are more generic than
+ * others. Please check the documentation of the specific function for more details.
  */
 
 /**