]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Drop the words scatter/gather in the documentation of such functions. 11228/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Mon, 23 Nov 2020 00:47:28 +0000 (17:47 -0700)
committerWolfgang Bangerth <bangerth@colostate.edu>
Mon, 23 Nov 2020 00:47:28 +0000 (17:47 -0700)
include/deal.II/dofs/dof_accessor.h
include/deal.II/lac/affine_constraints.h

index ad0ce0b61b6f9c96eb2f51c314811bfb78e5713d..e32702a48edb1a04125fc413ace25bc38185ba66 100644 (file)
@@ -1523,9 +1523,12 @@ public:
    */
 
   /**
-   * Return the values of the given vector restricted to the dofs of this cell
+   * Collect the values of the given vector restricted to the dofs of this cell
    * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
-   * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
+   * on line 0, dofs on line 1, etc, dofs on quad 0, etc. In other
+   * words, this function implements a
+   * [gather
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    *
    * The vector has to have the right size before being passed to this
    * function. This function is only callable for active cells.
@@ -1541,9 +1544,12 @@ public:
   get_dof_values(const InputVector &values, Vector<number> &local_values) const;
 
   /**
-   * Return the values of the given vector restricted to the dofs of this cell
+   * Collect the values of the given vector restricted to the dofs of this cell
    * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
-   * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
+   * on line 0, dofs on line 1, etc, dofs on quad 0, etc. In other
+   * words, this function implements a
+   * [gather
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    *
    * The vector has to have the right size before being passed to this
    * function. This function is only callable for active cells.
@@ -1561,9 +1567,12 @@ public:
                  ForwardIterator    local_values_end) const;
 
   /**
-   * Return the values of the given vector restricted to the dofs of this cell
+   * Collect the values of the given vector restricted to the dofs of this cell
    * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
-   * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
+   * on line 0, dofs on line 1, etc, dofs on quad 0, etc. In other
+   * words, this function implements a
+   * [gather
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    *
    * The vector has to have the right size before being passed to this
    * function. This function is only callable for active cells.
@@ -1589,6 +1598,9 @@ public:
    * This function is the counterpart to get_dof_values(): it takes a vector
    * of values for the degrees of freedom of the cell pointed to by this
    * iterator and writes these values into the global data vector @p values.
+   * In other words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    * This function is only callable for active cells.
    *
    * Note that for continuous finite elements, calling this function affects
@@ -1713,10 +1725,16 @@ public:
   /**
    * Distribute a local (cell based) vector to a global one by mapping the
    * local numbering of the degrees of freedom to the global one and entering
-   * the local values into the global vector.
+   * the local values into the global vector. In other words, this function
+   * implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    *
-   * The elements are <em>added</em> up to the elements in the global vector,
-   * rather than just set, since this is usually what one wants.
+   * The elements are <em>added</em> to the existing elements in the global
+   * vector, rather than just set, since this is usually what one wants. You may
+   * also want to take a look at the
+   * AffineConstraints::distribute_local_to_global() function if you need to
+   * deal with constraints.
    */
   template <typename number, typename OutputVector>
   void
@@ -1727,9 +1745,15 @@ public:
    * Distribute a local (cell based) vector in iterator format to a global one
    * by mapping the local numbering of the degrees of freedom to the global
    * one and entering the local values into the global vector.
+   * In other words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    *
-   * The elements are <em>added</em> up to the elements in the global vector,
-   * rather than just set, since this is usually what one wants.
+   * The elements are <em>added</em> to the existing elements in the global
+   * vector, rather than just set, since this is usually what one wants. You may
+   * also want to take a look at the
+   * AffineConstraints::distribute_local_to_global() function if you need to
+   * deal with constraints.
    */
   template <typename ForwardIterator, typename OutputVector>
   void
@@ -1741,6 +1765,9 @@ public:
    * Distribute a local (cell based) vector in iterator format to a global one
    * by mapping the local numbering of the degrees of freedom to the global
    * one and entering the local values into the global vector.
+   * In other words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
    *
    * The elements are <em>added</em> up to the elements in the global vector,
    * rather than just set, since this is usually what one wants. Moreover, the
index e787beb327be10a0b3846f1a4f19e260f4dbb7b7..5c05f90a54205d3ff0e087b6287c6f98622e63c2 100644 (file)
@@ -1108,7 +1108,11 @@ public:
   /**
    * This function takes a vector of local contributions (@p local_vector)
    * corresponding to the degrees of freedom indices given in @p
-   * local_dof_indices and distributes them to the global vector. In most
+   * local_dof_indices and distributes them to the global vector. In other
+   * words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
+   * In most
    * cases, these local contributions will be the result of an integration
    * over a cell or face of a cell. However, as long as @p local_vector and @p
    * local_dof_indices have the same number of elements, this function is
@@ -1156,7 +1160,11 @@ public:
   /**
    * This function takes a vector of local contributions (@p local_vector)
    * corresponding to the degrees of freedom indices given in @p
-   * local_dof_indices and distributes them to the global vector. In most
+   * local_dof_indices and distributes them to the global vector. In other
+   * words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
+   * In most
    * cases, these local contributions will be the result of an integration
    * over a cell or face of a cell. However, as long as @p local_vector and @p
    * local_dof_indices have the same number of elements, this function is
@@ -1244,7 +1252,11 @@ public:
   /**
    * This function takes a pointer to a vector of local contributions (@p
    * local_vector) corresponding to the degrees of freedom indices given in @p
-   * local_dof_indices and distributes them to the global vector. In most
+   * local_dof_indices and distributes them to the global vector. In other
+   * words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
+   * In most
    * cases, these local contributions will be the result of an integration
    * over a cell or face of a cell. However, as long as the entries in @p
    * local_dof_indices indicate reasonable global vector entries, this
@@ -1281,7 +1293,11 @@ public:
   /**
    * This function takes a matrix of local contributions (@p local_matrix)
    * corresponding to the degrees of freedom indices given in @p
-   * local_dof_indices and distributes them to the global matrix. In most
+   * local_dof_indices and distributes them to the global matrix. In other
+   * words, this function implements a
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
+   * In most
    * cases, these local contributions will be the result of an integration
    * over a cell or face of a cell. However, as long as @p local_matrix and @p
    * local_dof_indices have the same number of elements, this function is
@@ -1332,10 +1348,10 @@ public:
                              MatrixType &                  global_matrix) const;
 
   /**
-   * Does almost the same as the function above but can treat general
-   * rectangular matrices.  The main difference to achieve this is that the
-   * diagonal entries in constrained rows are left untouched instead of being
-   * filled with arbitrary values.
+   * This function does almost the same as the function above but can treat
+   * general rectangular matrices. The main difference to achieve this is that
+   * the diagonal entries in constrained rows are left untouched instead of
+   * being filled with arbitrary values.
    *
    * Since the diagonal entries corresponding to eliminated degrees of freedom
    * are not set, the result may have a zero eigenvalue, if applied to a
@@ -1366,9 +1382,9 @@ public:
                              MatrixType &                  global_matrix) const;
 
   /**
-   * Does almost the same as the function above for general rectangular
-   * matrices but uses different AffineConstraints objects on the row and
-   * column indices. The convention is that row indices are constrained
+   * This function does almost the same as the function above for general
+   * rectangular matrices but uses different AffineConstraints objects on the
+   * row and column indices. The convention is that row indices are constrained
    * according to the calling AffineConstraints <code>*this</code>, whereas
    * column indices are constrained according to the given AffineConstraints
    * <code>column_affine_constraints</code>. This function allows to handle the
@@ -1392,6 +1408,10 @@ public:
   /**
    * This function simultaneously writes elements into matrix and vector,
    * according to the constraints specified by the calling AffineConstraints.
+   * In other words, it performs the
+   * [scatter
+   * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing))
+   * of the corresponding functions for matrices and vectors at the same time.
    * This function can correctly handle inhomogeneous constraints as well. For
    * the parameter use_inhomogeneities_for_rhs see the documentation in
    * @ref constraints

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.