From: Niklas Fehn Date: Tue, 14 Mar 2023 14:35:40 +0000 (+0100) Subject: improve docu of VectorTools::interpolate_boundary_values() X-Git-Tag: v9.5.0-rc1~419^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0ba0aadd382694e0cdfdc5eadea3e96f85c92bbb;p=dealii.git improve docu of VectorTools::interpolate_boundary_values() --- diff --git a/include/deal.II/numerics/vector_tools_boundary.h b/include/deal.II/numerics/vector_tools_boundary.h index 572848dd6b..0fe6b4141e 100644 --- a/include/deal.II/numerics/vector_tools_boundary.h +++ b/include/deal.II/numerics/vector_tools_boundary.h @@ -52,19 +52,19 @@ namespace VectorTools * of Dirichlet boundary conditions. This function creates a map of * degrees of freedom subject to Dirichlet boundary conditions and the * corresponding values to be assigned to them, by interpolation around the - * boundary. For each degree of freedom at the boundary, if its index - * already exists in @p boundary_values then its boundary value will be - * overwritten, otherwise a new entry with proper index and boundary value - * for this degree of freedom will be inserted into @p boundary_values. + * boundary. For each degree of freedom at the boundary, its boundary value + * will be overwritten if its index already exists in @p boundary_values. + * Otherwise, a new entry with proper index and boundary value for this + * degree of freedom will be inserted into @p boundary_values. * * The parameter @p function_map provides a list of boundary indicators to * be handled by this function and corresponding boundary value functions. - * The keys of this map correspond to the number @p boundary_id of the face. + * The key of this map corresponds to the number @p boundary_id of the face. * numbers::internal_face_boundary_id is an illegal value for this key since * it is reserved for interior faces. For an example of how to use this * argument with a non-empty map, see the step-16 tutorial program. * - * The flags in the last parameter, @p component_mask denote which + * The flags in the last parameter, @p component_mask, denote which * components of the finite element space shall be interpolated. If it is * left as specified by the default value (i.e. an empty array), all * components are interpolated. If it is different from the default value, @@ -96,7 +96,15 @@ namespace VectorTools * Thus, the elements in the component mask corresponding to the components * of these non-primitive shape functions must be @p false. * - * See the general documentation of this namespace for more information. + * @note This function expects the same ComponentMask for all boundary + * indicators passed to this function. In case of multiple boundary + * indicators with different ComponentMask, this function needs to be called + * multiple times. For performance reasons, it might be reasonable to use + * the present function by grouping together all boundary indicators with + * the same ComponentMask. An alternative is to use one of the other + * functions with this name, which take only one boundary indicator with + * corresponding boundary function, to be called separately for every + * boundary indicator. * * @note When solving a partial differential equation with boundary * conditions $u|_{\partial\Omega}=g$ (or on *parts* of the boundary), @@ -135,6 +143,8 @@ namespace VectorTools * boundary. On the other hand, interpolation is only possible for * "nodal" finite element spaces (such as FE_Q, but not * FE_Q_Hierarchical), whereas the projection is always possible. + * + * See the general documentation of this namespace for more information. */ template void @@ -161,10 +171,20 @@ namespace VectorTools const ComponentMask &component_mask = ComponentMask()); /** - * Same function as above, but taking only one pair of boundary indicator - * and corresponding boundary function. The same comments apply as for the - * previous function, in particular about the use of the component mask and - * the requires size of the function object. + * Like the previous functions but without Mapping argument, using + * mapping=MappingQ@(1) internally. + */ + template + void + interpolate_boundary_values( + const DoFHandler &dof, + const std::map *> + & function_map, + std::map &boundary_values, + const ComponentMask &component_mask = ComponentMask()); + + /** + * Take only one boundary indicator with corresponding boundary function. * * @see * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" @@ -174,7 +194,7 @@ namespace VectorTools interpolate_boundary_values( const Mapping & mapping, const DoFHandler & dof, - const types::boundary_id boundary_component, + const types::boundary_id boundary_indicator, const Function & boundary_function, std::map &boundary_values, const ComponentMask &component_mask = ComponentMask()); @@ -188,16 +208,14 @@ namespace VectorTools interpolate_boundary_values( const hp::MappingCollection &mapping, const DoFHandler & dof, - const types::boundary_id boundary_component, + const types::boundary_id boundary_indicator, const Function & boundary_function, std::map & boundary_values, const ComponentMask &component_mask = ComponentMask()); /** - * Call the other interpolate_boundary_values() function, see above, with - * mapping=MappingQ@(1). The same comments - * apply as for the previous function, in particular about the use of the - * component mask and the requires size of the function object. + * Like the previous functions but without Mapping argument, using + * mapping=MappingQ@(1) internally. * * @see * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" @@ -206,53 +224,34 @@ namespace VectorTools void interpolate_boundary_values( const DoFHandler & dof, - const types::boundary_id boundary_component, + const types::boundary_id boundary_indicator, const Function & boundary_function, std::map &boundary_values, const ComponentMask &component_mask = ComponentMask()); - /** - * Call the other interpolate_boundary_values() function, see above, with - * mapping=MappingQ@(1). The same comments - * apply as for the previous function, in particular about the use of the - * component mask and the requires size of the function object. - */ - template - void - interpolate_boundary_values( - const DoFHandler &dof, - const std::map *> - & function_map, - std::map &boundary_values, - const ComponentMask &component_mask = ComponentMask()); - - /** * Insert the (algebraic) constraints due to Dirichlet boundary conditions - * into a AffineConstraints @p constraints. This function identifies the + * into an AffineConstraints object. This function identifies the * degrees of freedom subject to Dirichlet boundary conditions, adds them to * the list of constrained DoFs in @p constraints and sets the respective * inhomogeneity to the value interpolated around the boundary. If this * routine encounters a DoF that already is constrained (for instance by a * hanging node constraint, see below, or any other type of constraint, e.g. - * from periodic boundary conditions), the old setting of the constraint - * (dofs the entry is constrained to, inhomogeneities) is kept and nothing - * happens. + * from periodic boundary conditions), the old setting of the constraint is + * kept and nothing happens. * * @note When combining adaptively refined meshes with hanging node * constraints and boundary conditions like from the current function within * one AffineConstraints object, the hanging node constraints should always - * be set first, and then the boundary conditions since boundary conditions + * be set first and then the boundary conditions, since boundary conditions * are not set in the second operation on degrees of freedom that are * already constrained. This makes sure that the discretization remains * conforming as is needed. See the discussion on conflicting constraints in - * the module on - * @ref constraints. + * the module on @ref constraints. * - * This function is fundamentally equivalent to the ones above except that it - * puts its results into an AffineConstraint object rather than a `std::map`. - * See the functions above for more comments. + * TODO how to refer to interpolate_boundary_values() function with most + * detailed documentation (it appears on a different page in Doxygen)? * * @ingroup constraints */ @@ -269,6 +268,8 @@ namespace VectorTools /** * Like the previous function, but take a mapping collection to go with * DoFHandler objects with hp-capabilities. + * + * @ingroup constraints */ template void @@ -281,10 +282,22 @@ namespace VectorTools const ComponentMask & component_mask = ComponentMask()); /** - * Same function as above, but taking only one pair of boundary indicator - * and corresponding boundary function. The same comments apply as for the - * previous function, in particular about the use of the component mask and - * the requires size of the function object. + * Like the previous functions but without Mapping argument, using + * mapping=MappingQ@(1) internally. + * + * @ingroup constraints + */ + template + void + interpolate_boundary_values( + const DoFHandler &dof, + const std::map *> + & function_map, + AffineConstraints &constraints, + const ComponentMask & component_mask = ComponentMask()); + + /** + * Take only one boundary indicator with corresponding boundary function. * * @ingroup constraints * @@ -296,7 +309,7 @@ namespace VectorTools interpolate_boundary_values( const Mapping & mapping, const DoFHandler & dof, - const types::boundary_id boundary_component, + const types::boundary_id boundary_indicator, const Function &boundary_function, AffineConstraints & constraints, const ComponentMask & component_mask = ComponentMask()); @@ -304,22 +317,22 @@ namespace VectorTools /** * Like the previous function, but take a mapping collection to go with * DoFHandler objects with hp-capabilities. + * + * @ingroup constraints */ template void interpolate_boundary_values( const hp::MappingCollection &mapping, const DoFHandler & dof, - const types::boundary_id boundary_component, + const types::boundary_id boundary_indicator, const Function & boundary_function, AffineConstraints & constraints, const ComponentMask &component_mask = ComponentMask()); /** - * Call the other interpolate_boundary_values() function, see above, with - * mapping=MappingQ@(1). The same comments - * apply as for the previous function, in particular about the use of the - * component mask and the requires size of the function object. + * Like the previous functions but without Mapping argument, using + * mapping=MappingQ@(1) internally. * * @ingroup constraints * @@ -330,30 +343,12 @@ namespace VectorTools void interpolate_boundary_values( const DoFHandler & dof, - const types::boundary_id boundary_component, + const types::boundary_id boundary_indicator, const Function &boundary_function, AffineConstraints & constraints, const ComponentMask & component_mask = ComponentMask()); - /** - * Call the other interpolate_boundary_values() function, see above, with - * mapping=MappingQ@(1). The same comments - * apply as for the previous function, in particular about the use of the - * component mask and the requires size of the function object. - * - * @ingroup constraints - */ - template - void - interpolate_boundary_values( - const DoFHandler &dof, - const std::map *> - & function_map, - AffineConstraints &constraints, - const ComponentMask & component_mask = ComponentMask()); - - /** * Project a function or a set of functions to the boundary of the domain. * In other words, compute the solution of the following problem: Find $u_h