From: Wolfgang Bangerth Date: Mon, 23 Nov 2020 00:47:28 +0000 (-0700) Subject: Drop the words scatter/gather in the documentation of such functions. X-Git-Tag: v9.3.0-rc1~868^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F11228%2Fhead;p=dealii.git Drop the words scatter/gather in the documentation of such functions. --- diff --git a/include/deal.II/dofs/dof_accessor.h b/include/deal.II/dofs/dof_accessor.h index ad0ce0b61b..e32702a48e 100644 --- a/include/deal.II/dofs/dof_accessor.h +++ b/include/deal.II/dofs/dof_accessor.h @@ -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 &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 added up to the elements in the global vector, - * rather than just set, since this is usually what one wants. + * The elements are added 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 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 added up to the elements in the global vector, - * rather than just set, since this is usually what one wants. + * The elements are added 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 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 added up to the elements in the global vector, * rather than just set, since this is usually what one wants. Moreover, the diff --git a/include/deal.II/lac/affine_constraints.h b/include/deal.II/lac/affine_constraints.h index e787beb327..5c05f90a54 100644 --- a/include/deal.II/lac/affine_constraints.h +++ b/include/deal.II/lac/affine_constraints.h @@ -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 *this, whereas * column indices are constrained according to the given AffineConstraints * column_affine_constraints. 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