From be7248d3791318ba59e90604828c929bb54625b9 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Sat, 26 Jul 2014 17:05:04 -0500 Subject: [PATCH] Update the documentation of VectorTools::project_boundary_values(). This had apparently confused a user on the mailing list earlier today, so structure the documentation better. --- include/deal.II/numerics/vector_tools.h | 87 +++++++++++++------------ 1 file changed, 45 insertions(+), 42 deletions(-) diff --git a/include/deal.II/numerics/vector_tools.h b/include/deal.II/numerics/vector_tools.h index 0f15f4c978..5ca67a84f2 100644 --- a/include/deal.II/numerics/vector_tools.h +++ b/include/deal.II/numerics/vector_tools.h @@ -1103,48 +1103,51 @@ namespace VectorTools /** - * Project a function to the boundary - * of the domain, using the given - * quadrature formula for the faces. If - * the @p boundary_values contained - * values before, the new ones are - * added, or the old one overwritten if - * a node of the boundary part to be - * projected on already was in the - * variable. - * - * 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 boundary_values: the result - * of this function, 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. - * - * @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. + * 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 @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, -- 2.39.5