From f4103167fb0b3ac15d05056b098ebc5b89b10010 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 29 Apr 2013 14:42:42 +0000 Subject: [PATCH] Augment documentation to explain a common mistake. git-svn-id: https://svn.dealii.org/trunk@29397 0785d39b-7218-0410-832d-ea1e28bc413d --- .../include/deal.II/numerics/vector_tools.h | 121 ++++++++++++------ 1 file changed, 79 insertions(+), 42 deletions(-) diff --git a/deal.II/include/deal.II/numerics/vector_tools.h b/deal.II/include/deal.II/numerics/vector_tools.h index 4b72071289..6ab871a2c3 100644 --- a/deal.II/include/deal.II/numerics/vector_tools.h +++ b/deal.II/include/deal.II/numerics/vector_tools.h @@ -669,15 +669,15 @@ namespace VectorTools const bool project_to_boundary_first = false); /** - * Prepare Dirichlet boundary - * conditions. Make up the list + * Compute Dirichlet boundary + * conditions. This function makes up a map * of degrees of freedom subject * to Dirichlet boundary - * conditions and the values to + * conditions and the corresponding values to * be assigned to them, by * interpolation around the * boundary. If the - * @p boundary_values contained + * @p boundary_values object contained * values before, the new ones * are added, or the old ones * overwritten if a node of the @@ -717,13 +717,24 @@ namespace VectorTools * boundary function will be used * for which the respective flag * was set in the component mask. - * See also @ref GlossComponentMask. - * - * It is assumed that the number - * of components of the function - * in @p boundary_function matches that + * See also @ref GlossComponentMask. As an example, assume that you are + * solving the Stokes equations in 2d, with variables $(u,v,p)$ and that + * you only want to interpolate boundary values for the pressure, then + * the component mask should correspond to (true,true,false). + * + * @note Whether a component mask has been specified or not, the number + * of components of the functions + * in @p function_map must match that * of the finite element used by - * @p dof. + * @p dof. In other words, for the example above, you need to provide a + * Function object that has 3 components (the two velocities and the + * pressure), even though you are only + * interested in the first two of them. interpolate_boundary_values() + * will then call this function to obtain a vector of 3 values at each + * interpolation point but only take the first two and discard the third. + * In other words, you are free to return whatever you like in the third + * component of the vector returned by Function::vector_value, but the + * Function object must state that it has 3 components. * * If the finite element used has * shape functions that are @@ -739,7 +750,7 @@ namespace VectorTools * non-primitive shape functions * must be @p false. * - * See the general doc for more + * See the general documentation of this class for more * information. */ template @@ -755,9 +766,9 @@ namespace VectorTools * taking only one pair of * boundary indicator and * corresponding boundary - * function. Calls the other - * function with remapped - * arguments. + * 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. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -775,6 +786,9 @@ namespace VectorTools * interpolate_boundary_values() * function, see above, with * mapping=MappingQ1@(). + * 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. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -792,6 +806,9 @@ namespace VectorTools * interpolate_boundary_values() * function, see above, with * mapping=MappingQ1@(). + * 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 @@ -841,32 +858,44 @@ namespace VectorTools * The parameter @p boundary_component * corresponds to the number @p * boundary_indicator of the face. - * numbers::internal_face_boundary_id - * is an illegal value, since it is - * reserved for interior faces. * - * The flags in the last parameter, @p - * component_mask (see @ref GlossComponentMask) - * 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, - * it is assumed that the number of - * entries equals the number of - * components in the boundary functions - * and the finite element, and those - * components in the given boundary - * function will be used for which the - * respective flag was set in the - * component mask. - * - * It is assumed that the number of - * components of the function in @p - * boundary_function matches that of - * the finite element used by @p dof. + * 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, it is assumed that the + * number of entries equals the + * number of components in the + * boundary functions and the + * finite element, and those + * components in the given + * boundary function will be used + * for which the respective flag + * was set in the component mask. + * See also @ref GlossComponentMask. As an example, assume that you are + * solving the Stokes equations in 2d, with variables $(u,v,p)$ and that + * you only want to interpolate boundary values for the pressure, then + * the component mask should correspond to (true,true,false). + * + * @note Whether a component mask has been specified or not, the number + * of components of the functions + * in @p function_map must match that + * of the finite element used by + * @p dof. In other words, for the example above, you need to provide a + * Function object that has 3 components (the two velocities and the + * pressure), even though you are only + * interested in the first two of them. interpolate_boundary_values() + * will then call this function to obtain a vector of 3 values at each + * interpolation point but only take the first two and discard the third. + * In other words, you are free to return whatever you like in the third + * component of the vector returned by Function::vector_value, but the + * Function object must state that it has 3 components. * * If the finite element used has shape * functions that are non-zero in more @@ -879,7 +908,7 @@ namespace VectorTools * components of these non-primitive * shape functions must be @p false. * - * See the general doc for more + * See the general documentation of this class for more * information. * * @ingroup constraints @@ -896,8 +925,10 @@ namespace VectorTools * Same function as above, but taking * only one pair of boundary indicator * and corresponding boundary - * function. Calls the other function - * with remapped arguments. + * 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. * * @ingroup constraints * @@ -917,6 +948,9 @@ namespace VectorTools * interpolate_boundary_values() * function, see above, with * mapping=MappingQ1@(). + * 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 * @@ -936,6 +970,9 @@ namespace VectorTools * interpolate_boundary_values() * function, see above, with * mapping=MappingQ1@(). + * 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 */ -- 2.39.5