From: Peter Munch Date: Fri, 27 Aug 2021 07:28:23 +0000 (+0200) Subject: Extend the documentation of VT::point_values() X-Git-Tag: v9.4.0-rc1~1004^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2493ddd7d5bc16d3ad51bd12df663ee74dde2a6e;p=dealii.git Extend the documentation of VT::point_values() --- diff --git a/include/deal.II/numerics/vector_tools_evaluate.h b/include/deal.II/numerics/vector_tools_evaluate.h index 9ba6455ebe..90cd3c0c81 100644 --- a/include/deal.II/numerics/vector_tools_evaluate.h +++ b/include/deal.II/numerics/vector_tools_evaluate.h @@ -68,6 +68,46 @@ namespace VectorTools * Given a (distributed) solution vector @p vector, evaluate the values at * the (arbitrary and even remote) points specified by @p evaluation_points. * + * The following code snippet shows the usage of this function. Given + * a Mapping object, a DoFHandler object, and solution vector as well as a + * vector filled with points at which the vector should be evaluated, this + * function returns a vector with values at those points. Furthermore, the + * function initializes the communication pattern within the cache + * Utilities::MPI::RemotePointEvaluation, which can be efficiently used in + * further function calls (see also the function below). + * + * @code + * // first usage: set up cache + * Utilities::MPI::RemotePointEvaluation cache; + * + * const auto result_1 = VectorToos::point_values( + * mapping, dof_handler_1, vector_1, evaluation_points, cache); + * + * // further usages: reuse the cache + * const auto result_2 = VectorToos::point_values( + * cache, dof_handler_2, vector_2); + * @endcode + * + * Note that different DoFHandler objects can be passed to different + * calls of this function. However, the underlying Triangulation object + * needs to be the same if the cache should be reused. + * + * Alternatively, the user can set up the cache via + * Utilities::MPI::RemotePointEvaluation::reinit() manually: + * + * @code + * // set up cache manually + * Utilities::MPI::RemotePointEvaluation cache; + * cache.reinit(evaluation_points, triangulation, mapping); + * + * // use the cache + * const auto result_1 = VectorToos::point_values( + * cache, dof_handler_1, vector_1); + * + * const auto result_2 = VectorToos::point_values( + * cache, dof_handler_2, vector_2); + * @endcode + * * @warning This is a collective call that needs to be executed by all * processors in the communicator. */ @@ -87,7 +127,8 @@ namespace VectorTools * above function. * * @note Refinement/coarsening/repartitioning leads to the invalidation of the - * cache so that the above function has to be called again. + * cache so that the above function has to be called again. See also the + * example above. * * @warning This is a collective call that needs to be executed by all * processors in the communicator. @@ -103,6 +144,12 @@ namespace VectorTools /** * Given a (distributed) solution vector @p vector, evaluate the gradients at * the (arbitrary and even remote) points specified by @p evaluation_points. + * + * @note The same comments as in the case of point_values() are true for this + * function. + * + * @warning This is a collective call that needs to be executed by all + * processors in the communicator. */ template std::vector::gradient_type> @@ -119,8 +166,11 @@ namespace VectorTools * the points specified by @p cache which might have been set up by the * above function. * - * @note Refinement/coarsening/repartitioning leads to the invalidation of the - * cache so that the above function has to be called again. + * @note The same comments as in the case of point_values() are true for this + * function. + * + * @warning This is a collective call that needs to be executed by all + * processors in the communicator. */ template std::vector::gradient_type>