From 4594642a799a9662d34a19413dd79c94ee795d5d Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 1 Jun 2012 08:59:26 +0000 Subject: [PATCH] Correct documentation. Provide a glossary entry and link to it. git-svn-id: https://svn.dealii.org/trunk@25589 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/doxygen/headers/glossary.h | 35 +++++++++++++++++++ deal.II/include/deal.II/dofs/dof_tools.h | 11 ++++-- .../deal.II/numerics/error_estimator.h | 4 ++- deal.II/include/deal.II/numerics/vectors.h | 15 +++++--- 4 files changed, 58 insertions(+), 7 deletions(-) diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h index 797fed3e12..71619f7051 100644 --- a/deal.II/doc/doxygen/headers/glossary.h +++ b/deal.II/doc/doxygen/headers/glossary.h @@ -269,6 +269,41 @@ * FiniteElement and FEValues classes. * * + *
@anchor GlossComponentMask Component mask
+ * + *
+ * When using vector-valued elements (see @ref vector_valued) to solve systems + * of equations, one frequently wants to restrict some operations to only certain + * solution variables. For example, when solving the Stokes equations, one may + * wish to only interpolate boundary values for the velocity components + * but not the pressure. In deal.II, this is typically done by passing functions + * a component mask. Component masks are always specified as a + * std::vector@, i.e., an array with as many entries as the + * finite element has components (e.g., in the Stokes case, there are + * dim+1 components) and where each entry is either true or false. + * In the example where we would like to interpolate boundary values only for + * the velocity components of the Stokes system, this component mask would then + * be [true, true, false] in 2d and [true, true, true, false] + * in 3d to indicate that no boundary values shall be set for the pressure variable + * (the last of the dim+1 vector components of the solution. + * + * There are many functions that take such component masks, for example + * DoFTools::make_zero_boundary_values, + * VectorTools::interpolate_boundary_values, + * KellyErrorEstimator::estimate, etc. In some cases, there are multiple + * functions with these names but only some of them have a component mask + * argument. + * + * Many of the functions that take a component mask accept a vector of length + * zero to indicate all components, i.e., as if the vector had the + * correct length and was filled with only true values. The reason + * is that the empty vector can be constructed in place using the code snippet + * std::vector@() and can thus be used as a default + * argument in function signatures. + *
+ * + * + * *
@anchor GlossCompress Compressing distributed * vectors and matrices
* diff --git a/deal.II/include/deal.II/dofs/dof_tools.h b/deal.II/include/deal.II/dofs/dof_tools.h index 2d33d4ad62..108b098e1a 100644 --- a/deal.II/include/deal.II/dofs/dof_tools.h +++ b/deal.II/include/deal.II/dofs/dof_tools.h @@ -985,7 +985,8 @@ namespace DoFTools * as being constrained. * * The flags in the last parameter, - * @p component_mask denote which + * @p component_mask (see @ref GlossComponentMask) + * denote which * components of the finite element space * shall be constrained with periodic * boundary conditions. If it is left as @@ -1063,7 +1064,8 @@ namespace DoFTools * marked as being constrained. * * The flags in the last parameter, - * @p component_mask denote which + * @p component_mask (see @ref GlossComponentMask) + * denote which * components of the finite element space * shall be constrained with periodic * boundary conditions. If it is left as @@ -2579,6 +2581,11 @@ namespace DoFTools * one of its nonzero components * is affected. * + * The last argument indicates which + * components of the solution + * vector should be constrained to zero + * (see @ref GlossComponentMask). + * * This function is used * in step-36, for * example. diff --git a/deal.II/include/deal.II/numerics/error_estimator.h b/deal.II/include/deal.II/numerics/error_estimator.h index 61ea08138a..ba847adb88 100644 --- a/deal.II/include/deal.II/numerics/error_estimator.h +++ b/deal.II/include/deal.II/numerics/error_estimator.h @@ -254,7 +254,9 @@ class KellyErrorEstimator * vector-valued. You then have * to set those entries to true * in the bit-vector - * @p component_mask for which the + * @p component_mask + * (see @ref GlossComponentMask) + * for which the * respective component is to be * used in the error * estimator. The default is to diff --git a/deal.II/include/deal.II/numerics/vectors.h b/deal.II/include/deal.II/numerics/vectors.h index 0852961cf7..5e81be2251 100644 --- a/deal.II/include/deal.II/numerics/vectors.h +++ b/deal.II/include/deal.II/numerics/vectors.h @@ -686,11 +686,16 @@ namespace VectorTools * map of boundary values. * * The parameter - * @p boundary_component - * corresponds to the number + * @p function_map argument + * 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. types::internal_face_boundary_id - * is an illegal value, since + * is an illegal value for this key since * it is reserved for interior faces. * * The flags in the last @@ -712,6 +717,7 @@ namespace VectorTools * boundary function will be used * for which the respective flag * was set in the component mask. + * See also @ref GlossComponentMask. * * It is assumed that the number * of components of the function @@ -844,7 +850,8 @@ namespace VectorTools * reserved for interior faces. * * The flags in the last parameter, @p - * component_mask denote which + * component_mask (see @ref GlossComponentMask) + * denote which * components of the finite element * space shall be interpolated. If it * is left as specified by the default -- 2.39.5