]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Document some common MPI terms and link to them. 2021/head
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Mon, 28 Dec 2015 21:42:21 +0000 (15:42 -0600)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Mon, 28 Dec 2015 21:42:21 +0000 (15:42 -0600)
doc/doxygen/headers/glossary.h
examples/step-17/doc/intro.dox
include/deal.II/base/mpi.h

index 599d8a9613f80eb83ba716dfa65f00404079f6c5..fd2adb68ddfa565d1dc088c08b5e0130e18d19f3 100644 (file)
  * </dd>
  *
  *
+ * <dt class="glossary">@anchor GlossMPICommunicator <b>MPI Communicator</b></dt>
+ * <dd>
+ * In the language of the Message Passing Interface (MPI), a communicator
+ * can be thought of as a mail system that allows sending messages to
+ * other members of the mail system. Within each communicator, each
+ * @ref GlossMPIProcess "process" has a
+ * @ref GlossMPIRank "rank" (the equivalent of a house number) that
+ * allows to identify senders and receivers of messages. It is not
+ * possible to send messages via a communicator to receivers that are
+ * not part of this communicator/mail service.
+ *
+ * When starting a parallel program via a command line call such as
+ * @code
+ *  mpirun -np 32 ./step-17
+ * @endcode
+ * (or the equivalent used in the batch submission system used on your
+ * cluster) the MPI system starts 32 copies of the step-17 executable.
+ * Each of these has access to the <code>MPI_COMM_WORLD</code> communicator
+ * that then consists of all 32 processors, each with its own rank. A subset
+ * of processes within this MPI universe can later agree to create other
+ * communicators that allow communication between only a subset of
+ * processes.
+ * </dd>
+ *
+ *
+ * <dt class="glossary">@anchor GlossMPIProcess <b>MPI Process</b></dt>
+ * <dd>
+ * When running parallel jobs on distributed memory machines, one
+ * almost always uses MPI. There, a command line call such as
+ * @code
+ *  mpirun -np 32 ./step-17
+ * @endcode
+ * (or the equivalent used in the batch submission system used on your
+ * cluster) starts 32 copies of the step-17 executable. Some of these may actually
+ * run on the same machine, but in general they will be running on different
+ * machines that do not have direct access to each other's memory space.
+ *
+ * In the language of the Message Passing Interface (MPI), each of these
+ * copies of the same executable running on (possibly different) machines
+ * are called <i>processes</i>. The collection of all processes running in
+ * parallel is called the "MPI Universe" and is identified by the
+ * @ref GlossMPICommunicator "MPI communicator" <code>MPI_COMM_WORLD</code>.
+ *
+ * Each process has immediate access only to the objects in its own
+ * memory space. A process can not read from or write into the memory
+ * of other processes. As a consequence, the only way by which
+ * processes can communicate is by sending each other messages. That
+ * said (and as explained in the introduction to step-17), one
+ * typically calls higher level MPI functions in which all processes
+ * that are part of a communicator participate. An example would
+ * be computing the sum over a set of integers where each process
+ * provides one term of the sum.
+ * </dd>
+ *
+ *
+ * <dt class="glossary">@anchor GlossMPIRank <b>MPI Rank</b></dt>
+ * <dd>
+ * In the language of the Message Passing Interface (MPI), the <i>rank</i>
+ * of an @ref GlossMPIProcess "MPI process" is the number this process
+ * carries within the set <code>MPI_COMM_WORLD</code> of all processes
+ * currently running as one parallel job. More correctly, it is the
+ * number within an @ref GlossMPICommunicator "MPI communicator" that
+ * groups together a subset of all processes with one parallel job
+ * (where <code>MPI_COMM_WORLD</code> simply denotes the <i>complete</i>
+ * set of processes).
+ *
+ * Within each communicator, each process has a unique rank, distinct from the
+ * all other processes' ranks, that allows
+ * identifying one recipient or sender in MPI communication calls. Each
+ * process, running on one processor, can inquire about its own rank
+ * within a communicator by calling Utilities::MPI::this_mpi_process().
+ * The total number of processes participating in a communicator (i.e.,
+ * the <i>size</i> of the communicator) can be obtained by calling
+ * Utilities::MPI::n_mpi_processes().
+ * </dd>
+ *
  *
  * <dt class="glossary">@anchor mg_paper <b>%Multigrid paper</b></dt>
  * <dd>The "multigrid paper" is a paper by B. Janssen and G. Kanschat, titled
  * While in principle this property
  * can be used in any way application programs deem useful (it is simply an
  * integer associated with each cell that can indicate whatever you want), at
- * least for programs that run in %parallel it usually denotes the MPI rank
- * (or number) of the processor that "owns" this cell.
+ * least for programs that run in %parallel it usually denotes the
+ * @ref GlossMPIRank "MPI rank" of the processor that "owns" this cell.
  *
  * For programs that are parallelized based on MPI but where each processor
  * stores the entire triangulation (as in, for example, step-17 and step-18,
index 68acf8b55b436d788526031a9ac4d024f831d87a..4b97145dc90d54e0c00cd5771e6221657e1a6bb1 100644 (file)
@@ -103,11 +103,13 @@ program via
 @endcode
 which means to run it on (say) 32 processors. (If you are on a cluster system,
 you typically need to <i>schedule</i> the program to run whenever 32 processors
-become available; this is typically described in the documentation of your
+become available; this will be described in the documentation of your
 cluster. But under the hood, whenever those processors become available,
 the same call as above will generally be executed.) What this does is that
 the MPI system will start 32 <i>copies</i> of the <code>step-17</code>
-executable. This may happen on different machines that can't even read
+executable. (The MPI term for each of these running executables is that you
+have 32 @ref GlossMPIProcess "MPI processes".)
+This may happen on different machines that can't even read
 from each others' memory spaces, or it may happen on the same machine, but
 the end result is the same: each of these 32 copies will run with some
 memory allocated to it by the operating system, and it will not directly
index 72cc8a3940ddd98609499d9c849013316139d54d..0783b6be24b365d41e4820e155e496280a83653d 100644 (file)
@@ -65,13 +65,15 @@ namespace Utilities
   {
     /**
      * Return the number of MPI processes there exist in the given
-     * communicator object. If this is a sequential job, it returns 1.
+     * @ref GlossMPICommunicator "communicator" object. If this is
+     * a sequential job, it returns 1.
      */
     unsigned int n_mpi_processes (const MPI_Comm &mpi_communicator);
 
     /**
-     * Return the number of the present MPI process in the space of processes
-     * described by the given communicator. This will be a unique value for
+     * Return the @ref GlossMPIRank "rank of the present MPI process"
+     * in the space of processes described by the given
+     * @ref GlossMPICommunicator "communicator". This will be a unique value for
      * each process between zero and (less than) the number of all processes
      * (given by get_n_mpi_processes()).
      */
@@ -83,8 +85,8 @@ namespace Utilities
      * processors. To do that, the other processors need to know who to expect
      * messages from. This function computes this information.
      *
-     * @param mpi_comm A communicator that describes the processors that are
-     * going to communicate with each other.
+     * @param mpi_comm A @ref GlossMPICommunicator "communicator" that describes
+     * the processors that are going to communicate with each other.
      *
      * @param destinations The list of processors the current process wants to
      * send information to. This list need not be sorted in any way. If it
@@ -101,7 +103,8 @@ namespace Utilities
                                                   const std::vector<unsigned int> &destinations);
 
     /**
-     * Given a communicator, generate a new communicator that contains the
+     * Given a @ref GlossMPICommunicator "communicator", generate a new
+     * communicator that contains the
      * same set of processors but that has a different, unique identifier.
      *
      * This functionality can be used to ensure that different objects, such
@@ -115,7 +118,8 @@ namespace Utilities
 
     /**
      * Return the sum over all processors of the value @p t. This function is
-     * collective over all processors given in the communicator. If deal.II is
+     * collective over all processors given in the @ref GlossMPICommunicator "communicator".
+     * If deal.II is
      * not configured for use of MPI, this function simply returns the value
      * of @p t. This function corresponds to the <code>MPI_Allreduce</code>
      * function, i.e. all processors receive the result of this operation.
@@ -198,7 +202,8 @@ namespace Utilities
 
     /**
      * Return the maximum over all processors of the value @p t. This function
-     * is collective over all processors given in the communicator. If deal.II
+     * is collective over all processors given in the
+     * @ref GlossMPICommunicator "communicator". If deal.II
      * is not configured for use of MPI, this function simply returns the
      * value of @p t. This function corresponds to the
      * <code>MPI_Allreduce</code> function, i.e. all processors receive the
@@ -248,7 +253,8 @@ namespace Utilities
 
     /**
      * Return the minimum over all processors of the value @p t. This function
-     * is collective over all processors given in the communicator. If deal.II
+     * is collective over all processors given in the
+     * @ref GlossMPICommunicator "communicator". If deal.II
      * is not configured for use of MPI, this function simply returns the
      * value of @p t. This function corresponds to the
      * <code>MPI_Allreduce</code> function, i.e. all processors receive the
@@ -314,8 +320,9 @@ namespace Utilities
 
     /**
      * Returns sum, average, minimum, maximum, processor id of minimum and
-     * maximum as a collective operation of on the given MPI communicator @p
-     * mpi_communicator . Each processor's value is given in @p my_value and
+     * maximum as a 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.
      *
      * @note Sometimes, not all processors need a result and in that case one
@@ -337,7 +344,7 @@ namespace Utilities
      * control the number threads used in each MPI task.
      *
      * If deal.II is configured with PETSc, the library will also be
-     * initialized in the beginning and destructed at the end automatically
+     * initialized in the beginning and destroyed at the end automatically
      * (internally by calling PetscInitialize() and PetscFinalize()).
      *
      * If a program uses MPI one would typically just create an object of this

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.