From: Niklas Fehn Date: Wed, 13 May 2020 11:56:39 +0000 (+0200) Subject: clarify documentation of FEEvaluation::set_dof_values() X-Git-Tag: v9.3.0-rc1~1635^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9ecfa6da4db20c40dd896fef2c10f549a964f5fa;p=dealii.git clarify documentation of FEEvaluation::set_dof_values() --- diff --git a/include/deal.II/matrix_free/fe_evaluation.h b/include/deal.II/matrix_free/fe_evaluation.h index 838565b81a..1689ce9701 100644 --- a/include/deal.II/matrix_free/fe_evaluation.h +++ b/include/deal.II/matrix_free/fe_evaluation.h @@ -165,7 +165,14 @@ public: * temporary solution should always have homogeneous constraints and this * method is the correct one. * - * If this class was constructed without a MatrixFree object and the + * If the given vector template class is a block vector (determined through + * the template function 'IsBlockVector::value', which checks + * for vectors derived from dealii::BlockVectorBase) or an + * std::vector or std::vector, this function reads + * @p n_components blocks from the block vector starting at the index + * @p first_index. For non-block vectors, @p first_index is ignored. + * + * @note If this class was constructed without a MatrixFree object and the * information is acquired on the fly through a * DoFHandler::cell_iterator, only one single cell is used by this * class and this function extracts the values of the underlying components @@ -173,13 +180,6 @@ public: * MatrixFree object and lead to a structure that does not effectively use * vectorization in the evaluate routines based on these values (instead, * VectorizedArray::size() same copies are worked on). - * - * If the given vector template class is a block vector (determined through - * the template function 'IsBlockVector::value', which checks - * for vectors derived from dealii::BlockVectorBase) or an - * std::vector or std::vector, this function reads - * @p n_components blocks from the block vector starting at the index - * @p first_index. For non-block vectors, @p first_index is ignored. */ template void @@ -197,7 +197,14 @@ public: * as MatrixFree can only handle homogeneous constraints. Note that if * vectorization is enabled, the DoF values for several cells are set. * - * If this class was constructed without a MatrixFree object and the + * If the given vector template class is a block vector (determined through + * the template function 'IsBlockVector::value', which checks + * for vectors derived from dealii::BlockVectorBase) or an + * std::vector or std::vector, this function reads + * @p n_components blocks from the block vector starting at the index + * @p first_index. For non-block vectors, @p first_index is ignored. + * + * @note If this class was constructed without a MatrixFree object and the * information is acquired on the fly through a * DoFHandler::cell_iterator, only one single cell is used by this * class and this function extracts the values of the underlying components @@ -205,13 +212,6 @@ public: * MatrixFree object and lead to a structure that does not effectively use * vectorization in the evaluate routines based on these values (instead, * VectorizedArray::size() same copies are worked on). - * - * If the given vector template class is a block vector (determined through - * the template function 'IsBlockVector::value', which checks - * for vectors derived from dealii::BlockVectorBase) or an - * std::vector or std::vector, this function reads - * @p n_components blocks from the block vector starting at the index - * @p first_index. For non-block vectors, @p first_index is ignored. */ template void @@ -223,16 +223,24 @@ public: * sums them into the vector @p dst. The function also applies constraints * during the write operation. The functionality is hence similar to the * function AffineConstraints::distribute_local_to_global. If vectorization - * is enabled, the DoF values for several cells are used. The mask can be - * used to suppress the write access for some of the cells contained in the - * current cell vectorization batch, e.g. in case of local time stepping, - * where some cells are excluded from a call. A value of `true` in the - * bitset means that the respective lane index will be processed, whereas a - * value of `false` skips this index. The default setting is a bitset that - * contains all ones, which will write the accumulated integrals to all - * cells in the batch. + * is enabled, the DoF values for several cells are used. * - * If this class was constructed without a MatrixFree object and the + * If the given vector template class is a block vector (determined through + * the template function 'IsBlockVector::value', which checks + * for vectors derived from dealii::BlockVectorBase) or an + * std::vector or std::vector, this function + * writes to @p n_components blocks of the block vector starting at the + * index @p first_index. For non-block vectors, @p first_index is ignored. + * + * The @p mask can be used to suppress the write access for some of the + * cells contained in the current cell vectorization batch, e.g. in case of + * local time stepping, where some cells are excluded from a call. A value + * of `true` in the bitset means that the respective lane index will be + * processed, whereas a value of `false` skips this index. The default + * setting is a bitset that contains all ones, which will write the + * accumulated integrals to all cells in the batch. + * + * @note If this class was constructed without a MatrixFree object and the * information is acquired on the fly through a * DoFHandler::cell_iterator, only one single cell is used by this * class and this function extracts the values of the underlying components @@ -240,13 +248,6 @@ public: * MatrixFree object and lead to a structure that does not effectively use * vectorization in the evaluate routines based on these values (instead, * VectorizedArray::size() same copies are worked on). - * - * If the given vector template class is a block vector (determined through - * the template function 'IsBlockVector::value', which checks - * for vectors derived from dealii::BlockVectorBase) or an - * std::vector or std::vector, this function - * writes to @p n_components blocks of the block vector starting at the - * index @p first_index. For non-block vectors, @p first_index is ignored. */ template void @@ -264,7 +265,20 @@ public: * by the current cell are overwritten. Thus, if a degree of freedom is * associated to more than one cell (as usual in continuous finite * elements), the values will be overwritten and only the value written last - * is retained. The mask can be used to suppress the write access for some + * is retained. Please note that in a parallel context this function might + * also touch degrees of freedom owned by other MPI processes, so that a + * subsequent update or accumulation of ghost values as done by + * MatrixFree::loop() might invalidate the degrees of freedom set by this + * function. + * + * If the given vector template class is a block vector (determined through + * the template function 'IsBlockVector::value', which checks + * for vectors derived from dealii::BlockVectorBase) or an + * std::vector or std::vector, this function + * writes to @p n_components blocks of the block vector starting at the + * index @p first_index. For non-block vectors, @p first_index is ignored. + * + * The @p mask can be used to suppress the write access for some * of the cells contained in the current cell vectorization batch, e.g. in * case of local time stepping, where some cells are excluded from a call. * A value of `true` in the bitset means that the respective lane index will @@ -272,7 +286,7 @@ public: * setting is a bitset that contains all ones, which will write the * accumulated integrals to all cells in the batch. * - * If this class was constructed without a MatrixFree object and the + * @note If this class was constructed without a MatrixFree object and the * information is acquired on the fly through a * DoFHandler::cell_iterator, only one single cell is used by this * class and this function extracts the values of the underlying components @@ -281,12 +295,6 @@ public: * vectorization in the evaluate routines based on these values (instead, * VectorizedArray::size() same copies are worked on). * - * If the given vector template class is a block vector (determined through - * the template function 'IsBlockVector::value', which checks - * for vectors derived from dealii::BlockVectorBase) or an - * std::vector or std::vector, this function - * writes to @p n_components blocks of the block vector starting at the - * index @p first_index. For non-block vectors, @p first_index is ignored. */ template void