From: Timo Heister Date: Fri, 24 Oct 2014 13:01:28 +0000 (-0400) Subject: wrap comments X-Git-Tag: v8.2.0-rc1~97^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b3344e90531c5c591a660a55194256afe3dddd71;p=dealii.git wrap comments --- diff --git a/include/deal.II/numerics/vector_tools.h b/include/deal.II/numerics/vector_tools.h index afabd7a945..feb076e25c 100644 --- a/include/deal.II/numerics/vector_tools.h +++ b/include/deal.II/numerics/vector_tools.h @@ -53,277 +53,260 @@ class ConstraintMatrix; //TODO: Move documentation of functions to the functions! /** - * Provide a namespace which offers some operations on vectors. Among - * these are assembling of standard vectors, integration of the - * difference of a finite element solution and a continuous function, - * interpolations and projections of continuous functions to the - * finite element space and other operations. + * Provide a namespace which offers some operations on vectors. Among these + * are assembling of standard vectors, integration of the difference of a + * finite element solution and a continuous function, interpolations and + * projections of continuous functions to the finite element space and other + * operations. * - * @note There exist two versions of almost each function. One with a - * Mapping argument and one without. If a code uses a mapping - * different from MappingQ1 the functions with mapping argument - * should be used. Code that uses only MappingQ1 may also use the - * functions without Mapping argument. Each of these latter functions - * create a MappingQ1 object and just call the respective functions - * with that object as mapping argument. The functions without Mapping - * argument still exist to ensure backward compatibility. Nevertheless - * it is advised to change the user's codes to store a specific - * Mapping object and to use the functions that take this Mapping - * object as argument. This gives the possibility to easily extend the - * user codes to work also on mappings of higher degree, this just by - * exchanging MappingQ1 by, for example, a MappingQ or another Mapping - * object of interest. + * @note There exist two versions of almost each function. One with a Mapping + * argument and one without. If a code uses a mapping different from MappingQ1 + * the functions with mapping argument should be used. Code that uses + * only MappingQ1 may also use the functions without Mapping argument. Each of + * these latter functions create a MappingQ1 object and just call the + * respective functions with that object as mapping argument. The functions + * without Mapping argument still exist to ensure backward compatibility. + * Nevertheless it is advised to change the user's codes to store a specific + * Mapping object and to use the functions that take this Mapping object as + * argument. This gives the possibility to easily extend the user codes to + * work also on mappings of higher degree, this just by exchanging MappingQ1 + * by, for example, a MappingQ or another Mapping object of interest. * *

Description of operations

* * This collection of methods offers the following operations: * * - * All functions use the finite element given to the DoFHandler object the last - * time that the degrees of freedom were distributed over the triangulation. Also, - * if access to an object describing the exact form of the boundary is needed, the - * pointer stored within the triangulation object is accessed. + * All functions use the finite element given to the DoFHandler object the + * last time that the degrees of freedom were distributed over the + * triangulation. Also, if access to an object describing the exact form of + * the boundary is needed, the pointer stored within the triangulation object + * is accessed. * * @note Instantiations for this template are provided for some vector types, * in particular Vector<float>, Vector<double>, @@ -332,55 +315,39 @@ class ConstraintMatrix; * the manual). * * @ingroup numerics - * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat, 1998, 1999, 2000, 2001 + * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat, 1998, 1999, 2000, + * 2001 */ namespace VectorTools { /** - * Denote which norm/integral is - * to be computed by the - * integrate_difference() - * function of this class. The - * following possibilities are - * implemented: + * Denote which norm/integral is to be computed by the + * integrate_difference() function of this class. The following + * possibilities are implemented: */ enum NormType { /** - * The function or - * difference of functions - * is integrated on each - * cell. + * The function or difference of functions is integrated on each cell. */ mean, /** - * The absolute value of - * the function is - * integrated. + * The absolute value of the function is integrated. */ L1_norm, /** - * The square of the - * function is integrated - * and the the square root - * of the result is - * computed on each cell. + * The square of the function is integrated and the the square root of the + * result is computed on each cell. */ L2_norm, /** - * The absolute value to - * the pth power is - * integrated and the pth - * root is computed on each - * cell. The exponent - * p is the last - * parameter of the - * function. + * The absolute value to the pth power is integrated and the pth + * root is computed on each cell. The exponent p is the last + * parameter of the function. */ Lp_norm, /** - * The maximum absolute - * value of the function. + * The maximum absolute value of the function. */ Linfty_norm, /** @@ -388,9 +355,7 @@ namespace VectorTools */ H1_seminorm, /** - * The square of this norm - * is the square of the - * #L2_norm plus the square + * The square of this norm is the square of the #L2_norm plus the square * of the #H1_seminorm. */ H1_norm, @@ -399,8 +364,7 @@ namespace VectorTools */ W1p_seminorm, /** - * same as #H1_norm for - * Lp. + * same as #H1_norm for Lp. */ W1p_norm, /** @@ -408,8 +372,7 @@ namespace VectorTools */ W1infty_seminorm, /** - * same as #H1_norm for - * Linfty. + * same as #H1_norm for Linfty. */ W1infty_norm @@ -419,36 +382,23 @@ namespace VectorTools */ //@{ /** - * Compute the interpolation of - * @p function at the support - * points to the finite element - * space described by the Triangulation - * and FiniteElement object with which - * the given DoFHandler argument is - * initialized. It is assumed that the - * number of components of - * @p function matches that of - * the finite element used by - * @p dof. - * - * Note that you may have to call - * hanging_nodes.distribute(vec) - * with the hanging nodes from - * space @p dof afterwards, to - * make the result continuous - * again. - * - * The template argument DH - * may either be of type DoFHandler or + * Compute the interpolation of @p function at the support points to the + * finite element space described by the Triangulation and FiniteElement + * object with which the given DoFHandler argument is initialized. It is + * assumed that the number of components of @p function matches that of the + * finite element used by @p dof. + * + * Note that you may have to call hanging_nodes.distribute(vec) + * with the hanging nodes from space @p dof afterwards, to make the result + * continuous again. + * + * The template argument DH may either be of type DoFHandler or * hp::DoFHandler. * - * See the general documentation - * of this class for further - * information. + * See the general documentation of this class for further information. * - * @todo The @p mapping argument should be - * replaced by a hp::MappingCollection in - * case of a hp::DoFHandler. + * @todo The @p mapping argument should be replaced by a + * hp::MappingCollection in case of a hp::DoFHandler. */ template class DH> void interpolate (const Mapping &mapping, @@ -457,8 +407,7 @@ namespace VectorTools VECTOR &vec); /** - * Calls the @p interpolate() - * function above with + * Calls the @p interpolate() function above with * mapping=MappingQ1@@(). */ template @@ -467,31 +416,19 @@ namespace VectorTools VECTOR &vec); /** - * Interpolate different finite - * element spaces. The - * interpolation of vector - * @p data_1 is executed from the - * FE space represented by - * @p dof_1 to the vector @p data_2 - * on FE space @p dof_2. The - * interpolation on each cell is - * represented by the matrix - * @p transfer. Curved boundaries - * are neglected so far. - * - * Note that you may have to call - * hanging_nodes.distribute(data_2) - * with the hanging nodes from - * space @p dof_2 afterwards, to - * make the result continuous - * again. - * - * @note Instantiations for this template - * are provided for some vector types - * (see the general documentation of the - * class), but only the same vector for - * InVector and OutVector. Other - * combinations must be instantiated by + * Interpolate different finite element spaces. The interpolation of vector + * @p data_1 is executed from the FE space represented by @p dof_1 to the + * vector @p data_2 on FE space @p dof_2. The interpolation on each cell is + * represented by the matrix @p transfer. Curved boundaries are neglected so + * far. + * + * Note that you may have to call hanging_nodes.distribute(data_2) + * with the hanging nodes from space @p dof_2 afterwards, to make the result + * continuous again. + * + * @note Instantiations for this template are provided for some vector types + * (see the general documentation of the class), but only the same vector + * for InVector and OutVector. Other combinations must be instantiated by * hand. */ template @@ -502,61 +439,46 @@ namespace VectorTools OutVector &data_2); /** - * This function is a kind of generalization or modification - * of the very first interpolate() - * function in the series. - * It interpolations a set of functions onto the finite element space - * given by the DoFHandler argument where the determination which function - * to use is made based on the material id (see @ref GlossMaterialId) of - * each cell. - * - * @param mapping - The mapping to use to determine the location - * of support points at which the functions - * are to be evaluated. - * @param dof - DoFHandler initialized with Triangulation - * and - * FiniteElement - * objects, - * @param function_map - std::map reflecting the correspondence - * between material ids and functions, + * This function is a kind of generalization or modification of the very + * first interpolate() function in the series. It interpolations a set of + * functions onto the finite element space given by the DoFHandler argument + * where the determination which function to use is made based on the + * material id (see @ref GlossMaterialId) of each cell. + * + * @param mapping - The mapping to use to determine the location of + * support points at which the functions are to be evaluated. + * @param dof_handler - DoFHandler initialized with Triangulation and + * FiniteElement objects, + * @param function_map - std::map reflecting the correspondence between + * material ids and functions, * @param dst - global FE vector at the support points, * @param component_mask - mask of components that shall be interpolated * - * @note If a material id of some group of cells - * is missed in @p function_map, then @p dst will - * not be updated in the respective degrees of freedom - * of the output vector - * For example, if @p dst was successfully - * initialized to capture the degrees of freedom of the @p dof_handler - * of the problem with all zeros in it, - * then those zeros which correspond to - * the missed material ids will still remain - * in @p dst even after calling this function. + * @note If a material id of some group of cells is missed in @p + * function_map, then @p dst will not be updated in the respective degrees + * of freedom of the output vector For example, if @p dst was successfully + * initialized to capture the degrees of freedom of the @p dof_handler of + * the problem with all zeros in it, then those zeros which correspond to + * the missed material ids will still remain in @p dst even after calling + * this function. * * @note Degrees of freedom located on faces between cells of different - * material ids will get their value by that cell which was called - * last in the respective loop over cells implemented - * in this function. - * Since this process is kind of arbitrary, - * you cannot control it. - * However, if you want to have control over the order in which cells are visited, - * let us take a look at the following example: Let @p u be a variable of interest - * which is approximated by some CG finite element. - * Let @p 0, @p 1 and @p 2 be material ids - * of cells on the triangulation. - * Let 0: 0.0, 1: 1.0, 2: 2.0 - * be the whole @p function_map that you want to pass to - * this function, where @p key is a material id and - * @p value is a value of @p u. - * By using the whole @p function_map you do not really know - * which values will be assigned to the face DoFs. - * On the other hand, if you split the whole @p function_map - * into three smaller independent objects - * 0: 0.0 and 1: 1.0 and 2: 2.0 - * and make three distinct calls of this function passing each - * of these objects separately (the order depends on what you want - * to get between cells), then each subsequent call will rewrite - * the intercell @p dofs of the previous one. + * material ids will get their value by that cell which was called last in + * the respective loop over cells implemented in this function. Since this + * process is kind of arbitrary, you cannot control it. However, if you want + * to have control over the order in which cells are visited, let us take a + * look at the following example: Let @p u be a variable of interest which + * is approximated by some CG finite element. Let @p 0, @p 1 and @p 2 be + * material ids of cells on the triangulation. Let 0: 0.0, 1: 1.0, 2: 2.0 be + * the whole @p function_map that you want to pass to this function, where + * @p key is a material id and @p value is a value of @p u. By using the + * whole @p function_map you do not really know which values will be + * assigned to the face DoFs. On the other hand, if you split the whole @p + * function_map into three smaller independent objects 0: 0.0 and 1: 1.0 and + * 2: 2.0 and make three distinct calls of this function passing each of + * these objects separately (the order depends on what you want to get + * between cells), then each subsequent call will rewrite the intercell @p + * dofs of the previous one. * * @author Valentin Zingan, 2013 */ @@ -569,40 +491,23 @@ namespace VectorTools const ComponentMask &component_mask = ComponentMask()); /** - * Gives 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. - * - * Note that for continuous - * elements on grids with hanging - * nodes (i.e. locally refined - * grids) this function does not - * give the expected output. - * Indeed, the resulting output - * vector does not necessarily - * respect continuity - * requirements at hanging nodes, - * due to local cellwise + * Gives 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. + * + * Note that for continuous elements on grids with hanging nodes (i.e. + * locally refined grids) this function does not give the expected output. + * Indeed, the resulting output vector does not necessarily respect + * continuity requirements at hanging nodes, due to local cellwise * interpolation. * - * For this case (continuous - * elements on grids with hanging - * nodes), please use the - * interpolate_to_different_mesh - * function with an additional - * ConstraintMatrix argument, - * see below, or make the field - * conforming yourself by calling the - * @p ConstraintsMatrix::distribute - * function of your hanging node - * constraints object. + * For this case (continuous elements on grids with hanging nodes), please + * use the interpolate_to_different_mesh function with an additional + * ConstraintMatrix argument, see below, or make the field conforming + * yourself by calling the @p ConstraintsMatrix::distribute function of your + * hanging node constraints object. */ template class DH, @@ -614,29 +519,17 @@ namespace VectorTools VECTOR &u2); /** - * Gives 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. - * - * @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. + * Gives 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. + * + * @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. */ template class DH, @@ -650,17 +543,11 @@ namespace VectorTools /** - * The same function as above, but - * takes an InterGridMap object - * directly as a parameter. Useful - * for interpolating several vectors - * at the same time. + * The same function as above, but takes an InterGridMap object directly as + * a parameter. 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. + * @p intergridmap has to be initialized via InterGridMap::make_mapping + * pointing from a source DoFHandler to a destination DoFHandler. */ template class DH, @@ -672,42 +559,24 @@ namespace VectorTools VECTOR &u2); /** - * Compute the projection of - * @p function to the finite element space. - * - * By default, projection to the boundary - * and enforcement of zero boundary values - * are disabled. The ordering of arguments - * to this function is such that you need - * not give a second quadrature formula if - * you don't want to project to the - * boundary first, but that you must if you - * want to do so. - * - * This function needs the mass - * matrix of the finite element - * space on the present grid. To - * this end, the mass matrix is - * assembled exactly using - * MatrixTools::create_mass_matrix. This - * function performs numerical - * quadrature using the given - * quadrature rule; you should - * therefore make sure that the - * given quadrature formula is - * also sufficient for the - * integration of the mass - * matrix. - * - * See the general documentation of this - * class for further information. - * - * In 1d, the default value of - * the boundary quadrature - * formula is an invalid object - * since integration on the - * boundary doesn't happen in - * 1d. + * Compute the projection of @p function to the finite element space. + * + * By default, projection to the boundary and enforcement of zero boundary + * values are disabled. The ordering of arguments to this function is such + * that you need not give a second quadrature formula if you don't want to + * project to the boundary first, but that you must if you want to do so. + * + * This function needs the mass matrix of the finite element space on the + * present grid. To this end, the mass matrix is assembled exactly using + * MatrixTools::create_mass_matrix. This function performs numerical + * quadrature using the given quadrature rule; you should therefore make + * sure that the given quadrature formula is also sufficient for the + * integration of the mass matrix. + * + * See the general documentation of this class for further information. + * + * In 1d, the default value of the boundary quadrature formula is an invalid + * object since integration on the boundary doesn't happen in 1d. */ template void project (const Mapping &mapping, @@ -723,8 +592,7 @@ namespace VectorTools const bool project_to_boundary_first = false); /** - * Calls the project() - * function above, with + * Calls the project() function above, with * mapping=MappingQ1@(). */ template @@ -757,8 +625,7 @@ namespace VectorTools const bool project_to_boundary_first = false); /** - * Calls the project() - * function above, with a collection of + * Calls the project() function above, with a collection of * MappingQ1@() objects. */ template @@ -774,89 +641,51 @@ namespace VectorTools const bool project_to_boundary_first = false); /** - * Compute Dirichlet boundary - * conditions. This function makes up 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. If the - * @p boundary_values object contained - * values before, the new ones - * are added, or the old ones - * overwritten if a node of the - * boundary part to be used - * was already in the - * map of 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_indicator of the - * face. numbers::internal_face_boundary_id - * is an illegal value for this key since - * it is reserved for interior faces. - * - * 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 than one - * component (in deal.II speak: - * they are non-primitive), then - * these components can presently - * not be used for interpolating - * boundary values. 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 class for more - * information. + * Compute Dirichlet boundary conditions. This function makes up 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. If the @p boundary_values object contained values before, the + * new ones are added, or the old ones overwritten if a node of the boundary + * part to be used was already in the map of 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_indicator of + * the face. numbers::internal_face_boundary_id is an illegal value for + * this key since it is reserved for interior faces. + * + * 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 + * than one component (in deal.II speak: they are non-primitive), then these + * components can presently not be used for interpolating boundary values. + * 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 class for more information. */ template void @@ -867,8 +696,8 @@ namespace VectorTools const ComponentMask &component_mask = ComponentMask()); /** - * Like the previous function, but take a mapping collection to go with - * the hp::DoFHandler object. + * Like the previous function, but take a mapping collection to go with the + * hp::DoFHandler object. */ template void @@ -879,13 +708,10 @@ 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. + * 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. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -899,13 +725,10 @@ namespace VectorTools const ComponentMask &component_mask = ComponentMask()); /** - * Calls the other - * 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. + * Calls the other 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" */ @@ -919,13 +742,10 @@ namespace VectorTools /** - * Calls the other - * 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. + * Calls the other 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 @@ -936,97 +756,61 @@ namespace VectorTools /** - * Insert the (algebraic) constraints due - * to Dirichlet boundary conditions into - * a ConstraintMatrix @p - * constraints. 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. - * - * @note When combining adaptively - * refined meshes with hanging node - * constraints and boundary conditions - * like from the current function within - * one ConstraintMatrix object, the - * hanging node constraints should always - * 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 parameter @p boundary_component - * corresponds to the number @p + * Insert the (algebraic) constraints due to Dirichlet boundary conditions + * into a ConstraintMatrix @p constraints. 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. + * + * @note When combining adaptively refined meshes with hanging node + * constraints and boundary conditions like from the current function within + * one ConstraintMatrix object, the hanging node constraints should always + * 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 parameter @p boundary_component corresponds to the number @p * boundary_indicator of the face. * - * 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 - * than one component (in deal.II - * speak: they are non-primitive), then - * these components can presently not - * be used for interpolating boundary - * values. 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 class for more - * information. + * 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 + * than one component (in deal.II speak: they are non-primitive), then these + * components can presently not be used for interpolating boundary values. + * 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 class for more information. * * @ingroup constraints */ @@ -1039,13 +823,10 @@ 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. + * 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. * * @ingroup constraints * @@ -1061,13 +842,10 @@ namespace VectorTools const ComponentMask &component_mask = ComponentMask()); /** - * Calls the other - * 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. + * Calls the other 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 * @@ -1083,13 +861,10 @@ namespace VectorTools /** - * Calls the other - * 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. + * Calls the other 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 */ @@ -1102,51 +877,48 @@ namespace VectorTools /** - * 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 \in V_h$ (where $V_h$ is the finite element space represented - * by the DoFHandler argument of this function) so that - * @f{align*} - * \int_{\Gamma} \varphi_i u_h = \sum_{k \in {\cal K}} \int_{\Gamma_k} \varphi_i f_k, - * \qquad \forall \varphi_i \in V_h - * @f} - * where $\Gamma = \bigcup_{k \in {\cal K}} \Gamma_k$, $\Gamma_k \subset \partial\Omega$, - * $\cal K$ is the set of indices and $f_k$ the corresponding boundary functions - * represented in the function map argument @p boundary_values to this - * function, and the integrals are evaluated by quadrature. This problem has a - * non-unique solution in the interior, but it is well defined for the degrees - * of freedom on the part of the boundary, $\Gamma$, for which we do the - * integration. The values of $u_h|_\Gamma$, i.e., the nodal values of the degrees - * of freedom of this function along the boundary, are then what is computed by - * this function. - * - * @param mapping The mapping that will be used in the transformations necessary to - * integrate along the boundary. - * @param dof The DoFHandler that describes the finite element space and the numbering - * of degrees of freedom. - * @param boundary_functions A map from boundary indicators to pointers to functions - * that describe the desired values on those parts of the boundary marked - * with this boundary indicator (see @ref GlossBoundaryIndicator "Boundary indicator"). - * The projection happens on only those parts of the boundary whose indicators - * are represented in this map. - * @param q The face quadrature used in the integration necessary to compute the - * mass matrix and right hand side of the projection. - * @param boundary_values The result of this function. It is a map containing - * all indices of degrees of freedom at the boundary (as covered by the - * boundary parts in @p boundary_functions) and the computed - * dof value for this degree of freedom. If @p boundary_values contained - * values before, the new ones are added, or the old ones overwritten if - * a node of the boundary part to be projected on was already in this - * map. - * @param component_mapping It is sometimes convenient to project a vector-valued - * function onto only parts of a finite element space (for example, to project - * a function with dim components onto the velocity components of a - * dim+1 component DoFHandler for a Stokes problem). To allow for - * this, this argument allows components to be remapped. If the vector is not - * empty, it has to have one entry for each vector component of the finite element - * used in @p dof. This entry is the component number in @p boundary_functions - * that should be used for this component in @p dof. By default, no remapping is - * applied. + * 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 + * \in V_h$ (where $V_h$ is the finite element space represented by the + * DoFHandler argument of this function) so that @f{align*} \int_{\Gamma} + * \varphi_i u_h = \sum_{k \in {\cal K}} \int_{\Gamma_k} \varphi_i f_k, + * \qquad \forall \varphi_i \in V_h @f} where $\Gamma = \bigcup_{k \in {\cal + * K}} \Gamma_k$, $\Gamma_k \subset \partial\Omega$, $\cal K$ is the set of + * indices and $f_k$ the corresponding boundary functions represented in the + * function map argument @p boundary_values to this function, and the + * integrals are evaluated by quadrature. This problem has a non-unique + * solution in the interior, but it is well defined for the degrees of + * freedom on the part of the boundary, $\Gamma$, for which we do the + * integration. The values of $u_h|_\Gamma$, i.e., the nodal values of the + * degrees of freedom of this function along the boundary, are then what is + * computed by this function. + * + * @param mapping The mapping that will be used in the transformations + * necessary to integrate along the boundary. + * @param dof The DoFHandler that describes the finite element space and the + * numbering of degrees of freedom. + * @param boundary_functions A map from boundary indicators to pointers to + * functions that describe the desired values on those parts of the boundary + * marked with this boundary indicator (see @ref GlossBoundaryIndicator + * "Boundary indicator"). The projection happens on only those parts of the + * boundary whose indicators are represented in this map. + * @param q The face quadrature used in the integration necessary to compute + * the mass matrix and right hand side of the projection. + * @param boundary_values The result of this function. It is a map + * containing all indices of degrees of freedom at the boundary (as covered + * by the boundary parts in @p boundary_functions) and the computed dof + * value for this degree of freedom. If @p boundary_values contained values + * before, the new ones are added, or the old ones overwritten if a node of + * the boundary part to be projected on was already in this map. + * @param component_mapping It is sometimes convenient to project a vector- + * valued function onto only parts of a finite element space (for example, + * to project a function with dim components onto the velocity + * components of a dim+1 component DoFHandler for a Stokes + * problem). To allow for this, this argument allows components to be + * remapped. If the vector is not empty, it has to have one entry for each + * vector component of the finite element used in @p dof. This entry is the + * component number in @p boundary_functions that should be used for this + * component in @p dof. By default, no remapping is applied. */ template void project_boundary_values (const Mapping &mapping, @@ -1157,8 +929,7 @@ namespace VectorTools std::vector component_mapping = std::vector()); /** - * Calls the project_boundary_values() - * function, see above, with + * Calls the project_boundary_values() function, see above, with * mapping=MappingQ1@(). */ template @@ -1180,8 +951,7 @@ namespace VectorTools std::vector component_mapping = std::vector()); /** - * Calls the project_boundary_values() - * function, see above, with + * Calls the project_boundary_values() function, see above, with * mapping=MappingQ1@(). */ template @@ -1192,64 +962,38 @@ namespace VectorTools std::vector component_mapping = std::vector()); /** - * Project a function to the boundary of - * the domain, using the given quadrature - * formula for the faces. 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 resulting from the - * projection operation. 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. + * Project a function to the boundary of the domain, using the given + * quadrature formula for the faces. 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 resulting from the projection operation. 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. + * + * @note When combining adaptively refined meshes with hanging node + * constraints and boundary conditions like from the current function within + * one ConstraintMatrix object, the hanging node constraints should always + * 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 . * - * @note When combining adaptively - * refined meshes with hanging node - * constraints and boundary conditions - * like from the current function within - * one ConstraintMatrix object, the - * hanging node constraints should always - * 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 . - * - * If @p component_mapping is empty, it - * is assumed that the number of - * components of @p boundary_function - * matches that of the finite element + * If @p component_mapping is empty, it is assumed that the number of + * components of @p boundary_function matches that of the finite element * used by @p dof. * - * In 1d, projection equals - * interpolation. Therefore, - * interpolate_boundary_values is - * called. - * - * @arg @p component_mapping: if the - * components in @p boundary_functions - * and @p dof do not coincide, this - * vector allows them to be - * remapped. If the vector is not - * empty, it has to have one entry for - * each component in @p dof. This entry - * is the component number in @p - * boundary_functions that should be - * used for this component in @p - * dof. By default, no remapping is + * In 1d, projection equals interpolation. Therefore, + * interpolate_boundary_values is called. + * + * @arg @p component_mapping: if the components in @p boundary_functions and + * @p dof do not coincide, this vector allows them to be remapped. If the + * vector is not empty, it has to have one entry for each component in @p + * dof. This entry is the component number in @p boundary_functions that + * should be used for this component in @p dof. By default, no remapping is * applied. * * @ingroup constraints @@ -1263,8 +1007,7 @@ namespace VectorTools std::vector component_mapping = std::vector()); /** - * Calls the project_boundary_values() - * function, see above, with + * Calls the project_boundary_values() function, see above, with * mapping=MappingQ1@(). * * @ingroup constraints @@ -1278,81 +1021,52 @@ namespace VectorTools /** - * Compute constraints that correspond to - * boundary conditions of the form - * $\vec{n}\times\vec{u}=\vec{n}\times\vec{f}$, - * i.e. the tangential components of $u$ - * and $f$ shall coincide. - * - * If the ConstraintMatrix @p constraints - * contained values or other - * constraints before, the new ones are - * added or the old ones overwritten, - * if a node of the boundary part to be - * used was already in the list of - * constraints. This is handled by - * using inhomogeneous constraints. Please - * note that when combining adaptive meshes - * and this kind of constraints, the - * Dirichlet conditions should be set - * first, and then completed by hanging - * node constraints, in order to make sure - * that the discretization remains - * consistent. See the discussion on - * conflicting constraints in the + * Compute constraints that correspond to boundary conditions of the form + * $\vec{n}\times\vec{u}=\vec{n}\times\vec{f}$, i.e. the tangential + * components of $u$ and $f$ shall coincide. + * + * If the ConstraintMatrix @p constraints contained values or other + * constraints before, the new ones are added or the old ones overwritten, + * if a node of the boundary part to be used was already in the list of + * constraints. This is handled by using inhomogeneous constraints. Please + * note that when combining adaptive meshes and this kind of constraints, + * the Dirichlet conditions should be set first, and then completed by + * hanging node constraints, in order to make sure that the discretization + * remains consistent. See the discussion on conflicting constraints in the * module on @ref constraints . * - * This function is explicitly written to - * use with the FE_Nedelec elements. Thus - * it throws an exception, if it is - * called with other finite elements. - * - * The second argument of this function - * denotes the first vector component in - * the finite element that corresponds to - * the vector function that you want to - * constrain. For example, if we want to - * solve Maxwell's equations in 3d and the - * finite element has components - * $(E_x,E_y,E_z,B_x,B_y,B_z)$ and we want - * the boundary conditions - * $\vec{n}\times\vec{B}=\vec{n}\times\vec{f}$, - * then @p first_vector_component would - * be 3. Vectors are implicitly assumed to - * have exactly dim components - * that are ordered in the same way as we - * usually order the coordinate directions, - * i.e. $x$-, $y$-, and finally + * This function is explicitly written to use with the FE_Nedelec elements. + * Thus it throws an exception, if it is called with other finite elements. + * + * The second argument of this function denotes the first vector component + * in the finite element that corresponds to the vector function that you + * want to constrain. For example, if we want to solve Maxwell's equations + * in 3d and the finite element has components $(E_x,E_y,E_z,B_x,B_y,B_z)$ + * and we want the boundary conditions + * $\vec{n}\times\vec{B}=\vec{n}\times\vec{f}$, then @p + * first_vector_component would be 3. Vectors are implicitly assumed to have + * exactly dim components that are ordered in the same way as + * we usually order the coordinate directions, i.e. $x$-, $y$-, and finally * $z$-component. * - * 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 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 last argument is denoted to compute - * the normal vector $\vec{n}$ at the - * boundary points. + * The last argument is denoted to compute the normal vector $\vec{n}$ at + * the boundary points. * *

Computing constraints

* - * To compute the constraints we use - * projection-based interpolation as proposed - * in Solin, Segeth and Dolezel - * (Higher order finite elements, Chapman&Hall, - * 2004) on every face located at the - * boundary. - * - * First one projects $\vec{f}$ on the - * lowest-order edge shape functions. Then the - * remaining part $(I-P_0)\vec{f}$ of the - * function is projected on the remaining - * higher-order edge shape functions. In the - * last step we project $(I-P_0-P_e)\vec{f}$ - * on the bubble shape functions defined on - * the face. + * To compute the constraints we use projection-based interpolation as + * proposed in Solin, Segeth and Dolezel (Higher order finite elements, + * Chapman&Hall, 2004) on every face located at the boundary. + * + * First one projects $\vec{f}$ on the lowest-order edge shape functions. + * Then the remaining part $(I-P_0)\vec{f}$ of the function is projected on + * the remaining higher-order edge shape functions. In the last step we + * project $(I-P_0-P_e)\vec{f}$ on the bubble shape functions defined on the + * face. * * @ingroup constraints * @@ -1383,67 +1097,44 @@ namespace VectorTools /** - * Compute constraints that correspond to - * boundary conditions of the form - * $\vec{n}^T\vec{u}=\vec{n}^T\vec{f}$, - * i.e. the normal components of the solution $u$ - * and a given $f$ shall coincide. The function $f$ is given by @p boundary_function and - * the resulting constraints are added to @p constraints for faces with boundary indicator - * @p boundary_component. - * - * This function is explicitly written to - * use with the FE_RaviartThomas elements. - * Thus it throws an exception, if it is - * called with other finite elements. - * - * If the ConstraintMatrix @p constraints - * contained values or other - * constraints before, the new ones are - * added or the old ones overwritten, - * if a node of the boundary part to be - * used was already in the list of - * constraints. This is handled by - * using inhomogeneous constraints. Please - * note that when combining adaptive meshes - * and this kind of constraints, the - * Dirichlet conditions should be set - * first, and then completed by hanging - * node constraints, in order to make sure - * that the discretization remains - * consistent. See the discussion on - * conflicting constraints in the + * Compute constraints that correspond to boundary conditions of the form + * $\vec{n}^T\vec{u}=\vec{n}^T\vec{f}$, i.e. the normal components of the + * solution $u$ and a given $f$ shall coincide. The function $f$ is given by + * @p boundary_function and the resulting constraints are added to @p + * constraints for faces with boundary indicator @p boundary_component. + * + * This function is explicitly written to use with the FE_RaviartThomas + * elements. Thus it throws an exception, if it is called with other finite + * elements. + * + * If the ConstraintMatrix @p constraints contained values or other + * constraints before, the new ones are added or the old ones overwritten, + * if a node of the boundary part to be used was already in the list of + * constraints. This is handled by using inhomogeneous constraints. Please + * note that when combining adaptive meshes and this kind of constraints, + * the Dirichlet conditions should be set first, and then completed by + * hanging node constraints, in order to make sure that the discretization + * remains consistent. See the discussion on conflicting constraints in the * module on @ref constraints . * - * The argument @p first_vector_component - * denotes the first vector component in - * the finite element that corresponds to - * the vector function $\vec{u}$ that you want to - * constrain. Vectors are implicitly - * assumed to have exactly - * dim components that are - * ordered in the same way as we - * usually order the coordinate directions, - * i.e., $x$-, $y$-, and finally + * The argument @p first_vector_component denotes the first vector component + * in the finite element that corresponds to the vector function $\vec{u}$ + * that you want to constrain. Vectors are implicitly assumed to have + * exactly dim components that are ordered in the same way as + * we usually order the coordinate directions, i.e., $x$-, $y$-, and finally * $z$-component. * - * The parameter @p boundary_component - * corresponds to the - * @p boundary_indicator of the faces where the boundary conditions are applied. - * numbers::internal_face_boundary_id - * is an illegal value, since it is - * reserved for interior faces. - * The @p mapping is used to compute - * the normal vector $\vec{n}$ at the - * boundary points. + * The parameter @p boundary_component corresponds to the @p + * boundary_indicator of the faces where the boundary conditions are + * applied. numbers::internal_face_boundary_id is an illegal value, since it + * is reserved for interior faces. The @p mapping is used to compute the + * normal vector $\vec{n}$ at the boundary points. * *

Computing constraints

* - * To compute the constraints we use - * interpolation operator proposed - * in Brezzi, Fortin (Mixed and Hybrid - * (Finite Element Methods, Springer, - * 1991) on every face located at the - * boundary. + * To compute the constraints we use interpolation operator proposed in + * Brezzi, Fortin (Mixed and Hybrid (Finite Element Methods, Springer, 1991) + * on every face located at the boundary. * * @ingroup constraints * @@ -1482,10 +1173,10 @@ namespace VectorTools * and corresponding value, we here create a list of constraints that are * written into a ConstraintMatrix. This object may already have some * content, for example from hanging node constraints, that remains - * untouched. These constraints have to be applied to the linear system - * like any other such constraints, i.e. you have to condense the linear - * system with the constraints before solving, and you have to distribute - * the solution vector afterwards. + * untouched. These constraints have to be applied to the linear system like + * any other such constraints, i.e. you have to condense the linear system + * with the constraints before solving, and you have to distribute the + * solution vector afterwards. * * The use of this function is explained in more detail in step-31. It * doesn't make much sense in 1d, so the function throws an exception in @@ -1499,10 +1190,11 @@ namespace VectorTools * Maxwell equations in 3d and the finite element has components * $(E_x,E_y,E_z,B_x,B_y,B_z)$ and we want the boundary condition $\vec * B\cdot \vec n=\vec B_\Gamma\cdot \vec n$, then @p first_vector_component - * would be 3. Vectors are implicitly assumed to have exactly dim - * components that are ordered in the same way as we usually order the - * coordinate directions, i.e. $x$-, $y$-, and finally $z$-component. The - * function assumes, but can't check, that the vector components in the range + * would be 3. Vectors are implicitly assumed to have exactly + * dim components that are ordered in the same way as we + * usually order the coordinate directions, i.e. $x$-, $y$-, and finally + * $z$-component. The function assumes, but can't check, that the vector + * components in the range * [first_vector_component,first_vector_component+dim) come * from the same base finite element. For example, in the Stokes example * above, it would not make sense to use a @@ -1516,8 +1208,7 @@ namespace VectorTools * boundary condition is to be enforced. Note that, as explained below, this * is one of the few functions where it makes a difference where we call the * function multiple times with only one boundary indicator, or whether we - * call the function once with the whole set of boundary indicators at - * once. + * call the function once with the whole set of boundary indicators at once. * * The forth parameter describes the boundary function that is used for * computing these constraints. @@ -1540,21 +1231,24 @@ namespace VectorTools * * Computing these constraints requires some smarts. The main question * revolves around the question what the normal vector is. Consider the - * following situation:

@image html no_normal_flux_1.png + * following situation: + * + *

+ * @image html no_normal_flux_1.png *

* - * Here, we have two cells that use a bilinear mapping - * (i.e. MappingQ1). Consequently, for each of the cells, the normal vector - * is perpendicular to the straight edge. If the two edges at the top and - * right are meant to approximate a curved boundary (as indicated by the - * dashed line), then neither of the two computed normal vectors are equal - * to the exact normal vector (though they approximate it as the mesh is - * refined further). What is worse, if we constrain $\vec u \cdot \vec n= - * \vec u_\Gamma \cdot \vec n$ at the common vertex with the normal vector - * from both cells, then we constrain the vector $\vec u$ with respect to - * two linearly independent vectors; consequently, the constraint would be - * $\vec u=\vec u_\Gamma$ at this point (i.e. all components of the - * vector), which is not what we wanted. + * Here, we have two cells that use a bilinear mapping (i.e. MappingQ1). + * Consequently, for each of the cells, the normal vector is perpendicular + * to the straight edge. If the two edges at the top and right are meant to + * approximate a curved boundary (as indicated by the dashed line), then + * neither of the two computed normal vectors are equal to the exact normal + * vector (though they approximate it as the mesh is refined further). What + * is worse, if we constrain $\vec u \cdot \vec n= \vec u_\Gamma \cdot \vec + * n$ at the common vertex with the normal vector from both cells, then we + * constrain the vector $\vec u$ with respect to two linearly independent + * vectors; consequently, the constraint would be $\vec u=\vec u_\Gamma$ at + * this point (i.e. all components of the vector), which is not what + * we wanted. * * To deal with this situation, the algorithm works in the following way: at * each point where we want to constrain $\vec u$, we first collect all @@ -1639,19 +1333,19 @@ namespace VectorTools * There are cases where one cell contributes two tangential directions and * another one only one; for example, this would happen if both top and * front faces of the left cell belong to the boundary selected whereas only - * the top face of the right cell belongs to it, maybe indicating the the entire - * front part of the domain is a smooth manifold whereas the top really forms - * two separate manifolds that meet in a ridge, and that normal-flux boundary - * conditions are only desired on the front manifold and the right one on top. - * In cases like these, it's difficult to define what should happen. The - * current implementation simply ignores the one contribution from the - * cell that only contributes one normal vector. In the example shown, this - * is acceptable because the normal vector for the front face of the left - * cell is the same as the normal vector provided by the front face of - * the right cell (the surface is planar) but it would be a problem if the - * front manifold would be curved. Regardless, it is unclear how one would - * proceed in this case and ignoring the single cell is likely the best - * one can do. + * the top face of the right cell belongs to it, maybe indicating the the + * entire front part of the domain is a smooth manifold whereas the top + * really forms two separate manifolds that meet in a ridge, and that + * normal-flux boundary conditions are only desired on the front manifold + * and the right one on top. In cases like these, it's difficult to define + * what should happen. The current implementation simply ignores the one + * contribution from the cell that only contributes one normal vector. In + * the example shown, this is acceptable because the normal vector for the + * front face of the left cell is the same as the normal vector provided by + * the front face of the right cell (the surface is planar) but it would be + * a problem if the front manifold would be curved. Regardless, it is + * unclear how one would proceed in this case and ignoring the single cell + * is likely the best one can do. * * *

Results

@@ -1743,13 +1437,10 @@ namespace VectorTools //@{ /** - * Create a right hand side - * vector. Prior content of the - * given @p rhs_vector vector is - * deleted. + * Create a right hand side vector. Prior content of the given @p rhs_vector + * vector is deleted. * - * See the general documentation of this - * class for further information. + * See the general documentation of this class for further information. */ template void create_right_hand_side (const Mapping &mapping, @@ -1759,8 +1450,7 @@ namespace VectorTools Vector &rhs_vector); /** - * Calls the create_right_hand_side() - * function, see above, with + * Calls the create_right_hand_side() function, see above, with * mapping=MappingQ1@(). */ template @@ -1770,8 +1460,7 @@ namespace VectorTools Vector &rhs_vector); /** - * Like the previous set of functions, - * but for hp objects. + * Like the previous set of functions, but for hp objects. */ template void create_right_hand_side (const hp::MappingCollection &mapping, @@ -1781,8 +1470,7 @@ namespace VectorTools Vector &rhs_vector); /** - * Like the previous set of functions, - * but for hp objects. + * Like the previous set of functions, but for hp objects. */ template void create_right_hand_side (const hp::DoFHandler &dof, @@ -1791,16 +1479,12 @@ namespace VectorTools Vector &rhs_vector); /** - * Create a right hand side - * vector for a point source at point @p p. In other words, it creates - * a vector $F$ so that - * $F_i = \int_\Omega \delta(x-p) \phi_i(x) dx$. - * Prior content of the - * given @p rhs_vector vector is - * deleted. + * Create a right hand side vector for a point source at point @p p. In + * other words, it creates a vector $F$ so that $F_i = \int_\Omega + * \delta(x-p) \phi_i(x) dx$. Prior content of the given @p rhs_vector + * vector is deleted. * - * See the general documentation of this - * class for further information. + * See the general documentation of this class for further information. */ template void create_point_source_vector(const Mapping &mapping, @@ -1809,8 +1493,7 @@ namespace VectorTools Vector &rhs_vector); /** - * Calls the create_point_source_vector() - * function, see above, with + * Calls the create_point_source_vector() function, see above, with * mapping=MappingQ1@(). */ template @@ -1819,8 +1502,7 @@ namespace VectorTools Vector &rhs_vector); /** - * Like the previous set of functions, - * but for hp objects. + * Like the previous set of functions, but for hp objects. */ template void create_point_source_vector(const hp::MappingCollection &mapping, @@ -1829,14 +1511,10 @@ namespace VectorTools Vector &rhs_vector); /** - * Like the previous set of functions, - * but for hp objects. The function uses - * the default Q1 mapping object. Note - * that if your hp::DoFHandler uses any - * active fe index other than zero, then - * you need to call the function above - * that provides a mapping object for - * each active fe index. + * Like the previous set of functions, but for hp objects. The function uses + * the default Q1 mapping object. Note that if your hp::DoFHandler uses any + * active fe index other than zero, then you need to call the function above + * that provides a mapping object for each active fe index. */ template void create_point_source_vector(const hp::DoFHandler &dof, @@ -1844,24 +1522,21 @@ namespace VectorTools Vector &rhs_vector); /** - * Create a right hand side - * vector for a point source at point @p p. This variation of the function - * is meant for vector-valued problems with exactly dim components (it will - * also work for problems with more than dim components, and in this case - * simply consider only the first dim components of the shape functions). - * It computes a right hand side that corresponds to a forcing function that - * is equal to a delta function times a given direction. - * In other words, it creates a vector $F$ so that - * $F_i = \int_\Omega [\mathbf d \delta(x-p)] \cdot \phi_i(x) dx$. - * Note here that $\phi_i$ is a vector-valued function. $\mathbf d$ is - * the given direction of the source term $\mathbf d \delta(x-p)$ and - * corresponds to the @p direction argument to be passed to this function. + * Create a right hand side vector for a point source at point @p p. This + * variation of the function is meant for vector-valued problems with + * exactly dim components (it will also work for problems with more than dim + * components, and in this case simply consider only the first dim + * components of the shape functions). It computes a right hand side that + * corresponds to a forcing function that is equal to a delta function times + * a given direction. In other words, it creates a vector $F$ so that $F_i = + * \int_\Omega [\mathbf d \delta(x-p)] \cdot \phi_i(x) dx$. Note here that + * $\phi_i$ is a vector-valued function. $\mathbf d$ is the given direction + * of the source term $\mathbf d \delta(x-p)$ and corresponds to the @p + * direction argument to be passed to this function. * - * Prior content of the given @p rhs_vector vector is - * deleted. + * Prior content of the given @p rhs_vector vector is deleted. * - * See the general documentation of this - * class for further information. + * See the general documentation of this class for further information. */ template void create_point_source_vector(const Mapping &mapping, @@ -1871,10 +1546,8 @@ namespace VectorTools Vector &rhs_vector); /** - * Calls the create_point_source_vector() - * function for vector-valued finite elements, - * see above, with - * mapping=MappingQ1@(). + * Calls the create_point_source_vector() function for vector-valued finite + * elements, see above, with mapping=MappingQ1@(). */ template void create_point_source_vector(const DoFHandler &dof, @@ -1883,8 +1556,7 @@ namespace VectorTools Vector &rhs_vector); /** - * Like the previous set of functions, - * but for hp objects. + * Like the previous set of functions, but for hp objects. */ template void create_point_source_vector(const hp::MappingCollection &mapping, @@ -1894,14 +1566,10 @@ namespace VectorTools Vector &rhs_vector); /** - * Like the previous set of functions, - * but for hp objects. The function uses - * the default Q1 mapping object. Note - * that if your hp::DoFHandler uses any - * active fe index other than zero, then - * you need to call the function above - * that provides a mapping object for - * each active fe index. + * Like the previous set of functions, but for hp objects. The function uses + * the default Q1 mapping object. Note that if your hp::DoFHandler uses any + * active fe index other than zero, then you need to call the function above + * that provides a mapping object for each active fe index. */ template void create_point_source_vector(const hp::DoFHandler &dof, @@ -1910,14 +1578,10 @@ namespace VectorTools Vector &rhs_vector); /** - * Create a right hand side - * vector from boundary - * forces. Prior content of the - * given @p rhs_vector vector is - * deleted. + * Create a right hand side vector from boundary forces. Prior content of + * the given @p rhs_vector vector is deleted. * - * See the general documentation of this - * class for further information. + * See the general documentation of this class for further information. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -1930,9 +1594,7 @@ namespace VectorTools const std::set &boundary_indicators = std::set()); /** - * Calls the - * create_boundary_right_hand_side() - * function, see above, with + * Calls the create_boundary_right_hand_side() function, see above, with * mapping=MappingQ1@(). * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" @@ -1945,8 +1607,7 @@ namespace VectorTools const std::set &boundary_indicators = std::set()); /** - * Same as the set of functions above, - * but for hp objects. + * Same as the set of functions above, but for hp objects. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -1959,14 +1620,9 @@ namespace VectorTools const std::set &boundary_indicators = std::set()); /** - * Calls the - * create_boundary_right_hand_side() - * function, see above, with a - * single Q1 mapping as - * collection. This function - * therefore will only work if - * the only active fe index in - * use is zero. + * Calls the create_boundary_right_hand_side() function, see above, with a + * single Q1 mapping as collection. This function therefore will only work + * if the only active fe index in use is zero. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -1979,87 +1635,78 @@ namespace VectorTools //@} /** - * @name Evaluation of functions - * and errors + * @name Evaluation of functions and errors */ //@{ /** * Compute the error of the finite element solution. Integrate the - * difference between a reference function which is given as a - * continuous function object, and a finite element function. The - * result of this function is the vector @p difference that contains - * one value per active cell $K$ of the triangulation. Each of the values - * of this vector $d$ equals - * @f{align*} - * d_K = \| u-u_h \|_X - * @f} - * where $X$ denotes the norm chosen and $u$ represents the exact solution. - * - * It is assumed that the number of components of the function - * @p exact_solution matches that of the finite element used by @p dof. + * difference between a reference function which is given as a continuous + * function object, and a finite element function. The result of this + * function is the vector @p difference that contains one value per active + * cell $K$ of the triangulation. Each of the values of this vector $d$ + * equals @f{align*} d_K = \| u-u_h \|_X @f} where $X$ denotes the norm + * chosen and $u$ represents the exact solution. + * + * It is assumed that the number of components of the function @p + * exact_solution matches that of the finite element used by @p dof. * * @param[in] mapping The mapping that is used when integrating the - * difference $u-u_h$. - * @param[in] dof The DoFHandler object that describes the finite - * element space in which the solution vector lives. + * difference $u-u_h$. + * @param[in] dof The DoFHandler object that describes the finite element + * space in which the solution vector lives. * @param[in] fe_function A vector with nodal values representing the - * numerical approximation $u_h$. This vector needs to correspond - * to the finite element space represented by @p dof . + * numerical approximation $u_h$. This vector needs to correspond to the + * finite element space represented by @p dof. * @param[in] exact_solution The exact solution that is used to compute * the error. * @param[out] difference The vector of values $d_K$ computed as above. * @param[in] q The quadrature formula used to approximate the integral - * shown above. Note that some quadrature formulas are more useful - * than other in integrating $u-u_h$. For example, it is known that - * the $Q_1$ approximation $u_h$ to the exact solution $u$ of a Laplace - * equation is particularly accurate (in fact, superconvergent, i.e. - * accurate to higher order) at the 4 Gauss points of a cell in 2d - * (or 8 points in 3d) that correspond to a QGauss(2) object. Consequently, - * because a QGauss(2) formula only evaluates the two solutions at these - * particular points, choosing this quadrature formula may indicate an error - * far smaller than it actually is. + * shown above. Note that some quadrature formulas are more useful than + * other in integrating $u-u_h$. For example, it is known that the $Q_1$ + * approximation $u_h$ to the exact solution $u$ of a Laplace equation is + * particularly accurate (in fact, superconvergent, i.e. accurate to higher + * order) at the 4 Gauss points of a cell in 2d (or 8 points in 3d) that + * correspond to a QGauss(2) object. Consequently, because a QGauss(2) + * formula only evaluates the two solutions at these particular points, + * choosing this quadrature formula may indicate an error far smaller than + * it actually is. * @param[in] norm The norm $X$ shown above that should be computed. - * @param[in] weight The additional argument @p weight allows to evaluate weighted - * norms. The weight function may be scalar, establishing a weight - * in the domain for all components equally. This may be used, for - * instance, to only integrate over parts of the domain. The weight function - * may also be vector-valued, with as many components as the finite element: - * Then, different components get different weights. A typical application is when - * the error with respect to only one or a subset of the solution - * variables is to be computed, in which the other components would - * have weight values equal to zero. The ComponentSelectFunction - * class is particularly useful for this purpose as it provides - * such as "mask" weight.. - * The weight function is expected to be positive, but negative - * values are not filtered. By default, no weighting function is - * given, i.e. weight=1 in the whole domain for all vector - * components uniformly. + * @param[in] weight The additional argument @p weight allows to evaluate + * weighted norms. The weight function may be scalar, establishing a weight + * in the domain for all components equally. This may be used, for instance, + * to only integrate over parts of the domain. The weight function may also + * be vector-valued, with as many components as the finite element: Then, + * different components get different weights. A typical application is when + * the error with respect to only one or a subset of the solution variables + * is to be computed, in which the other components would have weight values + * equal to zero. The ComponentSelectFunction class is particularly useful + * for this purpose as it provides such as "mask" weight.. The weight + * function is expected to be positive, but negative values are not + * filtered. By default, no weighting function is given, i.e. weight=1 in + * the whole domain for all vector components uniformly. * @param[in] exponent This value denotes the $p$ used in computing - * $L^p$-norms and $W^{1,p}$-norms. The value is ignores if a @p norm - * other than NormType::Lp_norm or NormType::W1p_norm is chosen. + * $L^p$-norms and $W^{1,p}$-norms. The value is ignores if a @p norm other + * than NormType::Lp_norm or NormType::W1p_norm is chosen. * * - * See the general documentation of this - * class for more information. + * See the general documentation of this class for more information. * * @note If the integration here happens over the cells of a - * parallel::distribute::Triangulation object, then this function - * computes the vector elements $d_K$ for an output vector with as - * many cells as there are active cells of the triangulation object - * of the current processor. However, not all active cells are in - * fact locally owned: some may be ghost or artificial cells (see - * @ref GlossGhostCell "here" and @ref GlossArtificialCell - * "here"). The vector computed will, in the case of a distributed - * triangulation, contain zeros for cells that are not locally - * owned. As a consequence, in order to compute the global - * $L_2$ error (for example), the errors from different processors - * need to be combined, but this is simple because every processor - * only computes contributions for those cells of the global - * triangulation it locally owns (and these sets are, by definition, - * mutually disjoint). Consequently, the following piece of code - * computes the global $L_2$ error across multiple processors - * sharing a parallel::distribute::Triangulation: + * parallel::distribute::Triangulation object, then this function computes + * the vector elements $d_K$ for an output vector with as many cells as + * there are active cells of the triangulation object of the current + * processor. However, not all active cells are in fact locally owned: some + * may be ghost or artificial cells (see @ref GlossGhostCell "here" and @ref + * GlossArtificialCell "here"). The vector computed will, in the case of a + * distributed triangulation, contain zeros for cells that are not locally + * owned. As a consequence, in order to compute the global $L_2$ + * error (for example), the errors from different processors need to be + * combined, but this is simple because every processor only computes + * contributions for those cells of the global triangulation it locally owns + * (and these sets are, by definition, mutually disjoint). Consequently, the + * following piece of code computes the global $L_2$ error across multiple + * processors sharing a parallel::distribute::Triangulation: * @code * Vector local_errors (tria.n_active_cells()); * VectorTools::integrate_difference (mapping, dof, @@ -2071,14 +1718,12 @@ namespace VectorTools * const double total_global_error * = std::sqrt (Utilities::MPI::sum (total_local_error * total_local_error, MPI_COMM_WORLD)); * @endcode - * The squaring and taking the square root is necessary in order to - * compute the sum of squares of norms over all all cells in the definition - * of the $L_2$ norm: - * @f{align*} - * \textrm{error} = \sqrt{\sum_K \|u-u_h\|_{L_2(K)}^2} - * @f} - * Obviously, if you are interested in computing the $L_1$ norm of the - * error, the correct form of the last two lines would have been + * The squaring and taking the square root is necessary in order to compute + * the sum of squares of norms over all all cells in the definition of the + * $L_2$ norm: @f{align*} \textrm{error} = \sqrt{\sum_K + * \|u-u_h\|_{L_2(K)}^2} @f} Obviously, if you are interested in computing + * the $L_1$ norm of the error, the correct form of the last two lines would + * have been * @code * const double total_local_error = local_errors.l1_norm(); * const double total_global_error @@ -2087,12 +1732,9 @@ namespace VectorTools * instead, and similar considerations hold when computing the $L_\infty$ * norm of the error. * - * Instantiations for this template - * are provided for some vector types - * (see the general documentation of the - * class), but only for InVectors as in - * the documentation of the class, - * OutVector only Vector and + * Instantiations for this template are provided for some vector types (see + * the general documentation of the class), but only for InVectors as in the + * documentation of the class, OutVector only Vector and * Vector. */ template @@ -2107,8 +1749,7 @@ namespace VectorTools const double exponent = 2.); /** - * Calls the integrate_difference() - * function, see above, with + * Calls the integrate_difference() function, see above, with * mapping=MappingQ1@(). */ template @@ -2136,8 +1777,7 @@ namespace VectorTools const double exponent = 2.); /** - * Calls the integrate_difference() - * function, see above, with + * Calls the integrate_difference() function, see above, with * mapping=MappingQ1@(). */ template @@ -2151,25 +1791,16 @@ namespace VectorTools const double exponent = 2.); /** - * Point error evaluation. Find - * the first cell containing the - * given point and compute the - * difference of a (possibly - * vector-valued) finite element - * function and a continuous - * function (with as many vector - * components as the finite - * element) at this point. + * Point error evaluation. Find the first cell containing the given point + * and compute the difference of a (possibly vector-valued) finite element + * function and a continuous function (with as many vector components as the + * finite element) at this point. * - * This is a wrapper function - * using a Q1-mapping for cell - * boundaries to call the other - * point_difference() function. + * This is a wrapper function using a Q1-mapping for cell boundaries to call + * the other point_difference() function. * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. */ template void point_difference (const DoFHandler &dof, @@ -2179,26 +1810,16 @@ namespace VectorTools const Point &point); /** - * Point error evaluation. Find - * the first cell containing the - * given point and compute the - * difference of a (possibly - * vector-valued) finite element - * function and a continuous - * function (with as many vector - * components as the finite - * element) at this point. + * Point error evaluation. Find the first cell containing the given point + * and compute the difference of a (possibly vector-valued) finite element + * function and a continuous function (with as many vector components as the + * finite element) at this point. * - * Compared with the other - * function of the same name, - * this function uses an - * arbitrary mapping to evaluate - * the difference. + * Compared with the other function of the same name, this function uses an + * arbitrary mapping to evaluate the difference. * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. */ template void point_difference (const Mapping &mapping, @@ -2209,24 +1830,15 @@ namespace VectorTools const Point &point); /** - * Evaluate a possibly - * vector-valued finite element - * function defined by the given - * DoFHandler and nodal vector at - * the given point, and return - * the (vector) value of this - * function through the last - * argument. + * Evaluate a possibly vector-valued finite element function defined by the + * given DoFHandler and nodal vector at the given point, and return the + * (vector) value of this function through the last argument. * - * This is a wrapper function - * using a Q1-mapping for cell - * boundaries to call the other - * point_difference() function. + * This is a wrapper function using a Q1-mapping for cell boundaries to call + * the other point_difference() function. * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. */ template void @@ -2236,13 +1848,11 @@ namespace VectorTools Vector &value); /** - * Same as above for hp. - * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. - */ + * Same as above for hp. + * + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. + */ template void point_value (const hp::DoFHandler &dof, @@ -2251,27 +1861,18 @@ namespace VectorTools Vector &value); /** - * Evaluate a scalar finite - * element function defined by - * the given DoFHandler and nodal - * vector at the given point, and - * return the value of this + * Evaluate a scalar finite element function defined by the given DoFHandler + * and nodal vector at the given point, and return the value of this * function. * - * Compared with the other - * function of the same name, - * this is a wrapper function using - * a Q1-mapping for cells. + * Compared with the other function of the same name, this is a wrapper + * function using a Q1-mapping for cells. * - * This function is used in the - * "Possibilities for extensions" part of - * the results section of @ref step_3 - * "step-3". + * This function is used in the "Possibilities for extensions" part of the + * results section of @ref step_3 "step-3". * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. */ template double @@ -2280,13 +1881,11 @@ namespace VectorTools const Point &point); /** - * Same as above for hp. - * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. - */ + * Same as above for hp. + * + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. + */ template double point_value (const hp::DoFHandler &dof, @@ -2294,24 +1893,15 @@ namespace VectorTools const Point &point); /** - * Evaluate a possibly - * vector-valued finite element - * function defined by the given - * DoFHandler and nodal vector at - * the given point, and return - * the (vector) value of this - * function through the last - * argument. + * Evaluate a possibly vector-valued finite element function defined by the + * given DoFHandler and nodal vector at the given point, and return the + * (vector) value of this function through the last argument. * - * Compared with the other - * function of the same name, - * this function uses an arbitrary - * mapping to evaluate the difference. + * Compared with the other function of the same name, this function uses an + * arbitrary mapping to evaluate the difference. * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. */ template void @@ -2322,13 +1912,11 @@ namespace VectorTools Vector &value); /** - * Same as above for hp. - * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. - */ + * Same as above for hp. + * + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. + */ template void point_value (const hp::MappingCollection &mapping, @@ -2338,22 +1926,15 @@ namespace VectorTools Vector &value); /** - * Evaluate a scalar finite - * element function defined by - * the given DoFHandler and nodal - * vector at the given point, and - * return the value of this + * Evaluate a scalar finite element function defined by the given DoFHandler + * and nodal vector at the given point, and return the value of this * function. * - * Compared with the other - * function of the same name, - * this function uses an arbitrary - * mapping to evaluate the difference. + * Compared with the other function of the same name, this function uses an + * arbitrary mapping to evaluate the difference. * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. */ template double @@ -2363,13 +1944,11 @@ namespace VectorTools const Point &point); /** - * Same as above for hp. - * - * @note If the cell in which the point is found - * is not locally owned, an exception of type - * VectorTools::ExcPointNotAvailableHere - * is thrown. - */ + * Same as above for hp. + * + * @note If the cell in which the point is found is not locally owned, an + * exception of type VectorTools::ExcPointNotAvailableHere is thrown. + */ template double point_value (const hp::MappingCollection &mapping, @@ -2386,50 +1965,47 @@ namespace VectorTools /** * Subtract the (algebraic) mean value from a vector. * - * This function is most frequently used as a mean-value filter for - * Stokes: The pressure in Stokes' equations with only Dirichlet - * boundaries for the velocities is only determined up to a constant. - * This function allows to subtract the mean value of the pressure. It is - * usually called in a preconditioner and generates updates with mean - * value zero. The mean value is computed as the mean value of the - * degrees of freedom values as given by the input vector; they are not - * weighted by the area of cells, i.e. the mean is computed as $\sum_i - * v_i$, rather than as $\int_\Omega v(x) = \int_\Omega \sum_i v_i - * \phi_i(x)$. The latter can be obtained from the + * This function is most frequently used as a mean-value filter for Stokes: + * The pressure in Stokes' equations with only Dirichlet boundaries for the + * velocities is only determined up to a constant. This function allows to + * subtract the mean value of the pressure. It is usually called in a + * preconditioner and generates updates with mean value zero. The mean value + * is computed as the mean value of the degrees of freedom values as given + * by the input vector; they are not weighted by the area of cells, i.e. the + * mean is computed as $\sum_i v_i$, rather than as $\int_\Omega v(x) = + * \int_\Omega \sum_i v_i \phi_i(x)$. The latter can be obtained from the * VectorTools::compute_mean_function, however. * - * Apart from the vector @p v to operate on, this function takes a - * boolean mask @p p_select that has a true entry for every element of - * the vector for which the mean value shall be computed and later - * subtracted. The argument is used to denote which components of the - * solution vector correspond to the pressure, and avoid touching all - * other components of the vector, such as the velocity components. - * (Note, however, that the mask is not a @ref GlossComponentMask - * operating on the vector components of the finite element the solution - * vector @p v may be associated with; rather, it is a mask on the entire - * vector, without reference to what the vector elements mean.) - * - * The boolean mask @p p_select has an empty vector as default value, - * which will be interpreted as selecting all vector elements, hence, - * subtracting the algebraic mean value on the whole vector. This allows - * to call this function without a boolean mask if the whole vector - * should be processed. - * - * @note In the context of using this function to filter out the kernel - * of an operator (such as the null space of the Stokes operator that - * consists of the constant pressures), this function only makes sense - * for finite elements for which the null space indeed consists of the - * vector $(1,1,\ldots,1)^T$. This is the case for example for the usual - * Lagrange elements where the sum of all shape functions equals the - * function that is constant one. However, it is not true for some other - * functions: for example, for the FE_DGP element (another valid choice - * for the pressure in Stokes discretizations), the first shape function - * on each cell is constant while further elements are $L_2$ orthogonal - * to it (on the reference cell); consequently, the sum of all shape - * functions is not equal to one, and the vector that is associated with - * the constant mode is not equal to $(1,1,\ldots,1)^T$. For such - * elements, a different procedure has to be used when subtracting the - * mean value. + * Apart from the vector @p v to operate on, this function takes a boolean + * mask @p p_select that has a true entry for every element of the vector + * for which the mean value shall be computed and later subtracted. The + * argument is used to denote which components of the solution vector + * correspond to the pressure, and avoid touching all other components of + * the vector, such as the velocity components. (Note, however, that the + * mask is not a @ref GlossComponentMask operating on the vector components + * of the finite element the solution vector @p v may be associated with; + * rather, it is a mask on the entire vector, without reference to what the + * vector elements mean.) + * + * The boolean mask @p p_select has an empty vector as default value, which + * will be interpreted as selecting all vector elements, hence, subtracting + * the algebraic mean value on the whole vector. This allows to call this + * function without a boolean mask if the whole vector should be processed. + * + * @note In the context of using this function to filter out the kernel of + * an operator (such as the null space of the Stokes operator that consists + * of the constant pressures), this function only makes sense for finite + * elements for which the null space indeed consists of the vector + * $(1,1,\ldots,1)^T$. This is the case for example for the usual Lagrange + * elements where the sum of all shape functions equals the function that is + * constant one. However, it is not true for some other functions: for + * example, for the FE_DGP element (another valid choice for the pressure in + * Stokes discretizations), the first shape function on each cell is + * constant while further elements are $L_2$ orthogonal to it (on the + * reference cell); consequently, the sum of all shape functions is not + * equal to one, and the vector that is associated with the constant mode is + * not equal to $(1,1,\ldots,1)^T$. For such elements, a different procedure + * has to be used when subtracting the mean value. */ template void subtract_mean_value(VECTOR &v, @@ -2439,25 +2015,23 @@ namespace VectorTools /** * Compute the mean value of one component of the solution. * - * This function integrates the chosen component over the whole domain - * and returns the result, i.e. it computes $\int_\Omega [u_h(x)]_c \; - * dx$ where $c$ is the vector component and $u_h$ is the function - * representation of the nodal vector given as fourth argument. The - * integral is evaluated numerically using the quadrature formula given - * as third argument. + * This function integrates the chosen component over the whole domain and + * returns the result, i.e. it computes $\int_\Omega [u_h(x)]_c \; dx$ where + * $c$ is the vector component and $u_h$ is the function representation of + * the nodal vector given as fourth argument. The integral is evaluated + * numerically using the quadrature formula given as third argument. * - * This function is used in the "Possibilities for extensions" part of - * the results section of @ref step_3 "step-3". + * This function is used in the "Possibilities for extensions" part of the + * results section of @ref step_3 "step-3". * * @note The function is most often used when solving a problem whose * solution is only defined up to a constant, for example a pure Neumann * problem or the pressure in a Stokes or Navier-Stokes problem. In both * cases, subtracting the mean value as computed by the current function, * from the nodal vector does not generally yield the desired result of a - * finite element function with mean value zero. In fact, it only works - * for Lagrangian elements. For all other elements, you will need to - * compute the mean value and subtract it right inside the evaluation - * routine. + * finite element function with mean value zero. In fact, it only works for + * Lagrangian elements. For all other elements, you will need to compute the + * mean value and subtract it right inside the evaluation routine. */ template double compute_mean_value (const Mapping &mapping, @@ -2494,8 +2068,8 @@ namespace VectorTools DeclException0 (ExcNonInterpolatingFE); /** - * Exception - */ + * Exception + */ DeclException0 (ExcPointNotAvailableHere); }