]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Document what a collective operation actually is. 16431/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Sun, 7 Jan 2024 18:31:22 +0000 (11:31 -0700)
committerWolfgang Bangerth <bangerth@colostate.edu>
Sun, 7 Jan 2024 18:31:22 +0000 (11:31 -0700)
15 files changed:
doc/doxygen/headers/glossary.h
include/deal.II/base/mpi.h
include/deal.II/distributed/tria.h
include/deal.II/grid/grid_tools.h
include/deal.II/grid/grid_tools_cache.h
include/deal.II/grid/grid_tools_geometry.h
include/deal.II/lac/la_parallel_vector.h
include/deal.II/lac/petsc_sparse_matrix.h
include/deal.II/lac/petsc_vector.h
include/deal.II/lac/petsc_vector_base.h
include/deal.II/lac/trilinos_block_sparse_matrix.h
include/deal.II/lac/trilinos_sparse_matrix.h
include/deal.II/lac/trilinos_sparsity_pattern.h
include/deal.II/lac/trilinos_vector.h
include/deal.II/lac/vector.h

index 62767ab8f3ffeca5efb69d51f9745728a9cff657..cde731c39a61bf3ab96538245482354a800381da 100644 (file)
  * </dd>
  *
  *
+ * <dt class="glossary">@anchor GlossCollectiveOperation <b>Collective operation</b></dt>
+ * <dd>
+ *   When running programs in parallel using MPI, a <em>collective
+ *   operation</em> is one in which all processes on an
+ *   @ref GlossMPICommunicator "MPI communicator"
+ *   have to participate. At its core, the concept of collective operations
+ *   rests on the mental model that MPI traditionally uses, namely where
+ *   processes communicate by sending messages to each other; in this model,
+ *   nothing happens if one process sends a message but the receiving process
+ *   does not expect or respond to it, or if one process needs access to a
+ *   piece of data stored elsewhere, but the storing process does not send it.
+ *
+ *   Collective operations are then operations that need to be called on all
+ *   processes at the same time to execute. An obvious example is calling the
+ *   `MPI_Sum` function in which every process provides a number that is then
+ *   summed over all processes. If in a program running with 4 processes only
+ *   three processes call `MPI_Sum`, the program will hang until the fourth
+ *   process eventually also gets to the place where this function is called.
+ *   If the fourth process never calls that function, for example because it
+ *   calls another MPI function in the belief that the other processes called
+ *   that function as well, a "deadlock" results: Every process is now waiting
+ *   for something to happen that cannot happen.
+ *
+ *   Many functions in deal.II are "collective operations" because internally
+ *   they call MPI functions that are collective. For some, this is obvious,
+ *   such as when you call
+ *   parallel::distributed::Triangulation::execute_coarsening_and_refinement()
+ *   in step-40, given that this function refines a mesh that is stored
+ *   in parallel on all processes in a parallel universe. In some other
+ *   cases, the name of the function is a hint that a function is collective,
+ *   such as in
+ *   GridTools::distributed_compute_point_locations() or
+ *   GridTools::build_global_description_tree(), where the "distributed"
+ *   and "global" components of the names are an indication; the latter
+ *   function also takes an explicit MPI communicator as argument. For yet
+ *   other functions, it is perhaps not as obvious that a function is
+ *   a collective operation. GridTools::volume() is an example; it is
+ *   collective because each process computes the volume of those cells it
+ *   locally owns, and these contributions then have to be added up.
+ * </dd>
+ *
+ *
  * <dt class="glossary">@anchor GlossColorization <b>Colorization</b></dt>
  * <dd><em>Colorization</em> is the process of marking certain parts of a
  * Triangulation with different labels. The use of the word <em>color</em>
index 5cdb0d26215b796140390dcbeecc9d231d09e971..bc0aab7339580b3a20d42dfbc541976ace60c930 100644 (file)
@@ -988,7 +988,7 @@ namespace Utilities
 
     /**
      * Return sum, average, minimum, maximum, processor id of minimum and
-     * maximum as a collective operation of on the given MPI
+     * maximum as a @ref GlossCollectiveOperation "collective operation" of on the given MPI
      * @ref GlossMPICommunicator "communicator"
      * @p mpi_communicator. Each processor's value is given in @p my_value and
      * the result will be returned. The result is available on all machines.
@@ -1005,7 +1005,7 @@ namespace Utilities
 
     /**
      * Same as above but returning the sum, average, minimum, maximum,
-     * process id of minimum and maximum as a collective operation on the
+     * process id of minimum and maximum as a @ref GlossCollectiveOperation "collective operation" on the
      * given MPI
      * @ref GlossMPICommunicator "communicator"
      * @p mpi_communicator for each entry of the vector.
@@ -1021,7 +1021,7 @@ namespace Utilities
 
     /**
      * Same as above but returning the sum, average, minimum, maximum,
-     * process id of minimum and maximum as a collective operation on the
+     * process id of minimum and maximum as a @ref GlossCollectiveOperation "collective operation" on the
      * given MPI
      * @ref GlossMPICommunicator "communicator"
      * @p mpi_communicator for each entry of the ArrayView.
@@ -1525,7 +1525,7 @@ namespace Utilities
      * owned indices, these indices will be treated correctly and the rank of
      * this process is returned for those entries.
      *
-     * @note This is a collective operation: all processes within the given
+     * @note This is a @ref GlossCollectiveOperation "collective operation": all processes within the given
      * communicator have to call this function. Since this function does not
      * use MPI_Alltoall or MPI_Allgather, but instead uses non-blocking
      * point-to-point communication instead, and only a single non-blocking
@@ -1551,7 +1551,7 @@ namespace Utilities
      * Compute the union of the input vectors @p vec of all processes in the
      *   MPI communicator @p comm.
      *
-     * @note This is a collective operation. The result will available on all
+     * @note This is a @ref GlossCollectiveOperation "collective operation". The result will available on all
      *   processes.
      */
     template <typename T>
index a478dfb4f2083c9afab5408a9cc4ecba609b5ebb..96856f4a4205b06bff36e52da5d81138b2ea0c92 100644 (file)
@@ -579,7 +579,7 @@ namespace parallel
       memory_consumption_p4est() const;
 
       /**
-       * A collective operation that produces a sequence of output files with
+       * A @ref GlossCollectiveOperation "collective operation" that produces a sequence of output files with
        * the given file base name that contain the mesh in VTK format.
        *
        * More than anything else, this function is useful for debugging the
index 66aad79dcb2689fdf6ccd4da602548e60dd19601..04ff6ee3004d56194db75b8495a9b4c9dfcb8dd6 100644 (file)
@@ -681,7 +681,7 @@ namespace GridTools
    * In a serial execution the first three elements of the tuple are the same
    * as in GridTools::compute_point_locations .
    *
-   * Note: this function is a collective operation.
+   * Note: this function is a @ref GlossCollectiveOperation "collective operation".
    *
    * @note The actual return type of this function, i.e., the type referenced
    * above as @p return_type, is
@@ -2813,7 +2813,7 @@ namespace GridTools
     const MPI_Comm                            mpi_communicator);
 
   /**
-   * In this collective operation each process provides a vector
+   * In this @ref GlossCollectiveOperation "collective operation" each process provides a vector
    * of bounding boxes and a communicator.
    * All these vectors are gathered on each of the processes,
    * organized in a search tree, and then returned.
@@ -2842,7 +2842,7 @@ namespace GridTools
    * the second being the rank of the process for which at least some
    * of the locally owned cells overlap with the bounding box.
    *
-   * @note This function is a collective operation.
+   * @note This function is a @ref GlossCollectiveOperation "collective operation".
    */
   template <int spacedim>
   RTree<std::pair<BoundingBox<spacedim>, unsigned int>>
index 9a25521f5824e94067db2d03f60b0cac9235bd98..3cef49f18b5d1f0c87d23a170adbccb6020fc5da 100644 (file)
@@ -205,7 +205,7 @@ namespace GridTools
      * Constructing or updating the rtree requires a call to
      * GridTools::build_global_description_tree(), which exchanges
      * bounding boxes between all processes using
-     * Utilities::MPI::all_gather(), a collective operation.
+     * Utilities::MPI::all_gather(), a @ref GlossCollectiveOperation "collective operation".
      * Therefore this function must be called by all processes
      * at the same time.
      *
index 5c7879503a4232d4733eee34970dbca0ccbef5a4..8fd7263aa8f32179d2ed4faf5d38dbe4b64f0d1a 100644 (file)
@@ -70,7 +70,7 @@ namespace GridTools
    *
    * This function also works for objects of type
    * parallel::distributed::Triangulation, in which case the function is a
-   * collective operation.
+   * @ref GlossCollectiveOperation "collective operation".
    *
    * @param tria The triangulation.
    * @return The dim-dimensional measure of the domain described by the
@@ -96,7 +96,7 @@ namespace GridTools
    *
    * This function also works for objects of type
    * parallel::distributed::Triangulation, in which case the function is a
-   * collective operation.
+   * @ref GlossCollectiveOperation "collective operation".
    *
    * @param tria The triangulation.
    * @param mapping The Mapping which computes the Jacobians used to
index 688c4226863e359a426b97e68a1fa912d52a095e..8b39a745e97c4b710064453f6d57f2d6df170ef4 100644 (file)
@@ -1154,7 +1154,7 @@ namespace LinearAlgebra
                            OutputIterator        values_begin) const;
       /**
        * Return whether the vector contains only elements with value zero.
-       * This is a collective operation. This function is expensive, because
+       * This is a @ref GlossCollectiveOperation "collective operation". This function is expensive, because
        * potentially all elements have to be checked.
        */
       bool
index fea15af48b52c06a66b9e6e6aca2c0b5664934b9..cac676de2ec3b23cfef0c5e77b6a9f8f1a5cfbb1 100644 (file)
@@ -384,7 +384,7 @@ namespace PETScWrappers
         /**
          * It is not safe to elide additions of zeros to individual elements
          * of this matrix. The reason is that additions to the matrix may
-         * trigger collective operations synchronizing buffers on multiple
+         * trigger @ref GlossCollectiveOperation "collective operations" synchronizing buffers on multiple
          * processes. If an addition is elided on one process, this may lead
          * to other processes hanging in an infinite waiting loop.
          */
index dd383953c0925eee337053789378e461fbc0528d..c76a7c043536902521577f522b5dab51540bb1bd 100644 (file)
@@ -380,7 +380,7 @@ namespace PETScWrappers
        * @copydoc PETScWrappers::VectorBase::all_zero()
        *
        * @note This function overloads the one in the base class to make this
-       * a collective operation.
+       * a @ref GlossCollectiveOperation "collective operation".
        */
       bool
       all_zero() const;
index 1a25e0260fc494b43c06a2e1c9f743b1e38318ef..1e7253ba6971b5abf90130e6491a32bf7e55dcdc 100644 (file)
@@ -625,7 +625,7 @@ namespace PETScWrappers
 
     /**
      * Return whether the vector contains only elements with value zero. This
-     * is a collective operation. This function is expensive, because
+     * is a @ref GlossCollectiveOperation "collective operation". This function is expensive, because
      * potentially all elements have to be checked.
      */
     bool
index 1ddbecb8bad049a96d9e2ea82d675fcf0acb2f49..32df581377afe876f20380119bd6a7cf88e6efd2 100644 (file)
@@ -207,7 +207,7 @@ namespace TrilinosWrappers
      * internal arrays, in order to be able to relay global indices into the
      * matrix to indices into the subobjects. You *must* call this function
      * each time after you have changed the size of the sub-objects. Note that
-     * this is a collective operation, i.e., it needs to be called on all MPI
+     * this is a @ref GlossCollectiveOperation "collective operation", i.e., it needs to be called on all MPI
      * processes. This command internally calls the method
      * <tt>compress()</tt>, so you don't need to call that function in case
      * you use <tt>collect_sizes()</tt>.
index dfd90b522f532bf28db07c8bef04e26cf00da172..bf3f293206aa35014ad198a58ace4b30881687f8 100644 (file)
@@ -666,7 +666,7 @@ namespace TrilinosWrappers
      * holds the sparsity_pattern structure because each processor sets its
      * rows.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     template <typename SparsityPatternType>
@@ -677,7 +677,7 @@ namespace TrilinosWrappers
      * This function reinitializes the Trilinos sparse matrix from a (possibly
      * distributed) Trilinos sparsity pattern.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      *
      * If you want to write to the matrix from several threads and use MPI,
@@ -693,7 +693,7 @@ namespace TrilinosWrappers
      * matrix. The values are not copied, but you can use copy_from() for
      * this.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     void
@@ -709,7 +709,7 @@ namespace TrilinosWrappers
      * sparsity structure of the input matrix should be used or the matrix
      * entries should be copied, too.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a deadlock.
      *
      * @note If a different sparsity pattern is given in the last argument
@@ -821,7 +821,7 @@ namespace TrilinosWrappers
      * processor just sets the elements in the sparsity pattern that belong to
      * its rows.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     template <typename SparsityPatternType>
@@ -840,7 +840,7 @@ namespace TrilinosWrappers
      * only implemented for input sparsity patterns of type
      * DynamicSparsityPattern.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     template <typename SparsityPatternType>
@@ -865,7 +865,7 @@ namespace TrilinosWrappers
      * sparsity structure of the input matrix should be used or the matrix
      * entries should be copied, too.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     template <typename number>
@@ -887,7 +887,7 @@ namespace TrilinosWrappers
      * sparsity structure of the input matrix should be used or the matrix
      * entries should be copied, too.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     template <typename number>
@@ -1004,7 +1004,7 @@ namespace TrilinosWrappers
      * Release all memory and return to a state just like after having called
      * the default constructor.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     void
@@ -1030,7 +1030,7 @@ namespace TrilinosWrappers
      *
      * In both cases, this function compresses the data structures and allows
      * the resulting matrix to be used in all other operations like
-     * matrix-vector products. This is a collective operation, i.e., it needs to
+     * matrix-vector products. This is a @ref GlossCollectiveOperation "collective operation", i.e., it needs to
      * be run on all processors when used in %parallel.
      *
      * See
index 0b219eec3a0dcd252446000eb729b144d7e2ecdd..d745d4491fb58fd3125699f51dd32f0463511320 100644 (file)
@@ -398,7 +398,7 @@ namespace TrilinosWrappers
      * Release all memory and return to a state just like after having called
      * the default constructor.
      *
-     * This is a collective operation that needs to be called on all
+     * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
      * processors in order to avoid a dead lock.
      */
     void
@@ -410,7 +410,7 @@ namespace TrilinosWrappers
      * actually generating a (Trilinos-based) matrix. This function also
      * exchanges non-local data that might have accumulated during the
      * addition of new elements. This function must therefore be called once
-     * the structure is fixed. This is a collective operation, i.e., it needs
+     * the structure is fixed. This is a @ref GlossCollectiveOperation "collective operation", i.e., it needs
      * to be run on all processors when used in parallel.
      */
     void
index fdf33ee8666daf9920d5d637192274f8e866adcf..440dacc539c1f45e455403f38236f987b885a2ec 100644 (file)
@@ -921,7 +921,7 @@ namespace TrilinosWrappers
 
       /**
        * Return whether the vector contains only elements with value zero. This
-       * is a collective operation. This function is expensive, because
+       * is a @ref GlossCollectiveOperation "collective operation". This function is expensive, because
        * potentially all elements have to be checked.
        */
       bool
index 36b9fefc2b40383b5eb1aac2f126570120a55181..92edce02029e294af2ae7ec1a2137ba1cc9893ed 100644 (file)
@@ -228,7 +228,7 @@ public:
    * the same time. This means that unless you use a split MPI communicator
    * then it is not normally possible for only one or a subset of processes
    * to obtain a copy of a parallel vector while the other jobs do something
-   * else. In other words, calling this function is a 'collective operation'
+   * else. In other words, calling this function is a @ref GlossCollectiveOperation "collective operation"
    * that needs to be executed by all MPI processes that jointly share @p v.
    */
   explicit Vector(const TrilinosWrappers::MPI::Vector &v);
@@ -433,7 +433,7 @@ public:
    * the same time. This means that unless you use a split MPI communicator
    * then it is not normally possible for only one or a subset of processes
    * to obtain a copy of a parallel vector while the other jobs do something
-   * else. In other words, calling this function is a 'collective operation'
+   * else. In other words, calling this function is a @ref GlossCollectiveOperation "collective operation"
    * that needs to be executed by all MPI processes that jointly share @p v.
    */
   Vector<Number> &

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.