From: Wolfgang Bangerth Date: Tue, 20 Feb 2024 17:00:17 +0000 (-0700) Subject: Minor updates to the documentation of a few functions. X-Git-Tag: relicensing~8^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16680%2Fhead;p=dealii.git Minor updates to the documentation of a few functions. --- diff --git a/include/deal.II/multigrid/mg_transfer_global_coarsening.h b/include/deal.II/multigrid/mg_transfer_global_coarsening.h index 13b0919991..3953cdd680 100644 --- a/include/deal.II/multigrid/mg_transfer_global_coarsening.h +++ b/include/deal.II/multigrid/mg_transfer_global_coarsening.h @@ -215,13 +215,13 @@ class MGTwoLevelTransferBase : public Subscriptor { public: /** - * Perform prolongation. + * Perform prolongation on a solution vector. */ virtual void prolongate_and_add(VectorType &dst, const VectorType &src) const = 0; /** - * Perform restriction. + * Perform restriction on a residual vector. */ virtual void restrict_and_add(VectorType &dst, const VectorType &src) const = 0; @@ -230,7 +230,8 @@ public: * Perform interpolation of a solution vector from the fine level to the * coarse level. This function is different from restriction, where a * weighted residual is transferred to a coarser level (transposition of - * prolongation matrix). + * prolongation matrix). In other words, restriction acts on right hand + * side vectors, whereas interpolation acts on solution vectors. */ virtual void interpolate(VectorType &dst, const VectorType &src) const = 0; @@ -274,20 +275,23 @@ public: MGTwoLevelTransferBase(); /** - * Perform prolongation. + * Perform prolongation on a solution vector. */ void prolongate_and_add(VectorType &dst, const VectorType &src) const; /** - * Perform restriction. + * Perform restriction on a residual vector. */ void restrict_and_add(VectorType &dst, const VectorType &src) const; /** * Perform interpolation of a solution vector from the fine level to the - * coarse level. + * coarse level. This function is different from restriction, where a + * weighted residual is transferred to a coarser level (transposition of + * prolongation matrix). In other words, restriction acts on right hand + * side vectors, whereas interpolation acts on solution vectors. */ virtual void interpolate(VectorType &dst, const VectorType &src) const = 0; @@ -445,20 +449,19 @@ class MGTwoLevelTransfer : public MGTwoLevelTransferBase { public: /** - * Perform prolongation. + * @copydoc MGTwoLevelTransferBase::prolongate_and_add */ void prolongate_and_add(VectorType &dst, const VectorType &src) const override; /** - * Perform restriction. + * @copydoc MGTwoLevelTransferBase::restrict_and_add */ void restrict_and_add(VectorType &dst, const VectorType &src) const override; /** - * Perform interpolation of a solution vector from the fine level to the - * coarse level. + * @copydoc MGTwoLevelTransferBase::interpolate */ void interpolate(VectorType &dst, const VectorType &src) const override; @@ -568,8 +571,7 @@ public: const unsigned int fe_degree_coarse); /** - * Perform interpolation of a solution vector from the fine level to the - * coarse level. + * @copydoc MGTwoLevelTransferBase::interpolate */ void interpolate( diff --git a/include/deal.II/numerics/vector_tools_interpolate.h b/include/deal.II/numerics/vector_tools_interpolate.h index f31463d473..36c96ce106 100644 --- a/include/deal.II/numerics/vector_tools_interpolate.h +++ b/include/deal.II/numerics/vector_tools_interpolate.h @@ -197,9 +197,13 @@ namespace VectorTools const ComponentMask &component_mask = {}); /** - * Compute the interpolation of a @p dof1-function @p u1 to a @p dof2-function - * @p u2, where @p dof1 and @p dof2 represent different triangulations with - * a common coarse grid. + * Compute the interpolation of a @p dof_handler_1 function @p u1 (i.e., + * a function defined on the mesh that underlies @p dof_handler_1, using + * the finite element associated with that DoFHandler) to + * a @p dof_handler_2 function @p u2 (i.e., a function defined on the mesh + * and finite element associated with @p dof_handler_2). This function + * assumes that @p dof_handler_1 and @p dof_handler_2 are defined on + * (possibly different) triangulations that have a common coarse grid. * * dof1 and dof2 need to have the same finite element discretization. * @@ -212,32 +216,34 @@ namespace VectorTools * For this case (continuous elements on grids with hanging nodes), please * use the interpolate_to_different_mesh function with an additional * AffineConstraints argument, see below, or make the field conforming - * yourself by calling the @p AffineConstraints::distribute function of your + * yourself by calling the AffineConstraints::distribute() function of your * hanging node constraints object. * * @note This function works with parallel::distributed::Triangulation, but * only if the parallel partitioning is the same for both meshes (see the * parallel::distributed::Triangulation::no_automatic_repartitioning - * flag). + * flag). In practice, this is rarely the case because two triangulations, + * partitioned in their own ways, will not typically have corresponding + * cells owned by the same process, and implementing the interpolation + * procedure would require transfering data between processes in ways + * that are difficult to implement efficiently. * * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type} */ template DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type) - void interpolate_to_different_mesh(const DoFHandler &dof1, - const VectorType &u1, - const DoFHandler &dof2, - VectorType &u2); + void interpolate_to_different_mesh( + const DoFHandler &dof_handler_1, + const VectorType &u1, + const DoFHandler &dof_handler_2, + VectorType &u2); /** - * Compute the interpolation of a @p dof1-function @p u1 to a @p dof2-function - * @p u2, where @p dof1 and @p dof2 represent different triangulations with - * a common coarse grid. - * - * dof1 and dof2 need to have the same finite element discretization. + * This is a variation of the previous function that takes an additional + * constraint object as argument. * - * @p constraints is a hanging node constraints object corresponding to @p - * dof2. This object is particularly important when interpolating onto + * @p constraints is a hanging node constraints object corresponding to + * @p dof2. This object is particularly important when interpolating onto * continuous elements on grids with hanging nodes (locally refined grids): * Without it - due to cellwise interpolation - the resulting output vector * does not necessarily respect continuity requirements at hanging nodes. @@ -247,15 +253,16 @@ namespace VectorTools template DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type) void interpolate_to_different_mesh( - const DoFHandler &dof1, + const DoFHandler &dof_handler_1, const VectorType &u1, - const DoFHandler &dof2, + const DoFHandler &dof_handler_2, const AffineConstraints &constraints, VectorType &u2); /** * The same function as above, but takes an InterGridMap object directly as - * a parameter. Useful for interpolating several vectors at the same time. + * a parameter. This function is useful for interpolating several vectors at + * the same time. * * @p intergridmap has to be initialized via InterGridMap::make_mapping * pointing from a source DoFHandler to a destination DoFHandler.