From: kanschat Date: Wed, 6 Nov 2013 10:25:28 +0000 (+0000) Subject: reformat documentation to longer lines X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e53ac94cbe6561d2bc8ea5b63f79f70af37b2943;p=dealii-svn.git reformat documentation to longer lines git-svn-id: https://svn.dealii.org/trunk@31560 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/include/deal.II/dofs/dof_tools.h b/deal.II/include/deal.II/dofs/dof_tools.h index 9b39197104..f1a02d0fe9 100644 --- a/deal.II/include/deal.II/dofs/dof_tools.h +++ b/deal.II/include/deal.II/dofs/dof_tools.h @@ -185,28 +185,22 @@ namespace GridTools {template struct PeriodicFacePair;} namespace DoFTools { /** - * The flags used in tables by certain - * make_*_pattern functions to - * describe whether two components of the - * solution couple in the bilinear forms - * corresponding to cell or face - * terms. An example of using these flags - * is shown in the introduction of - * step-46. - * - * In the descriptions of the individual - * elements below, remember that these - * flags are used as elements of tables - * of size FiniteElement::n_components - * times FiniteElement::n_components - * where each element indicates whether - * two components do or do not couple. + * The flags used in tables by certain make_*_pattern + * functions to describe whether two components of the solution + * couple in the bilinear forms corresponding to cell or face + * terms. An example of using these flags is shown in the + * introduction of step-46. + * + * In the descriptions of the individual elements below, remember + * that these flags are used as elements of tables of size + * FiniteElement::n_components times FiniteElement::n_components + * where each element indicates whether two components do or do not + * couple. */ enum Coupling { /** - * Two components do not - * couple. + * Two components do not couple. */ none, /** @@ -214,12 +208,9 @@ namespace DoFTools */ always, /** - * Two components couple only - * if their shape functions are - * both nonzero on a given - * face. This flag is only used - * when computing integrals over - * faces of cells. + * Two components couple only if their shape functions are both + * nonzero on a given face. This flag is only used when computing + * integrals over faces of cells. */ nonzero }; @@ -229,8 +220,7 @@ namespace DoFTools * @{ */ /** - * Maximal number of degrees of - * freedom on a cell. + * Maximal number of degrees of freedom on a cell. * * @relates DoFHandler */ @@ -239,8 +229,7 @@ namespace DoFTools max_dofs_per_cell (const DoFHandler &dh); /** - * Maximal number of degrees of - * freedom on a cell. + * Maximal number of degrees of freedom on a cell. * * @relates hp::DoFHandler */ @@ -250,13 +239,10 @@ namespace DoFTools /** - * Maximal number of degrees of - * freedom on a face. + * Maximal number of degrees of freedom on a face. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates DoFHandler */ @@ -265,13 +251,10 @@ namespace DoFTools max_dofs_per_face (const DoFHandler &dh); /** - * Maximal number of degrees of - * freedom on a face. + * Maximal number of degrees of freedom on a face. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates hp::DoFHandler */ @@ -280,13 +263,10 @@ namespace DoFTools max_dofs_per_face (const hp::DoFHandler &dh); /** - * Maximal number of degrees of - * freedom on a vertex. + * Maximal number of degrees of freedom on a vertex. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates DoFHandler */ @@ -295,13 +275,10 @@ namespace DoFTools max_dofs_per_vertex (const DoFHandler &dh); /** - * Maximal number of degrees of - * freedom on a vertex. + * Maximal number of degrees of freedom on a vertex. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates hp::DoFHandler */ @@ -310,14 +287,11 @@ namespace DoFTools max_dofs_per_vertex (const hp::DoFHandler &dh); /** - * Number of vector components in the - * finite element object used by this - * DoFHandler. + * Number of vector components in the finite element object used by + * this DoFHandler. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates DoFHandler */ @@ -326,14 +300,11 @@ namespace DoFTools n_components (const DoFHandler &dh); /** - * Number of vector components in the - * finite element object used by this - * DoFHandler. + * Number of vector components in the finite element object used by + * this DoFHandler. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates hp::DoFHandler */ @@ -342,14 +313,11 @@ namespace DoFTools n_components (const hp::DoFHandler &dh); /** - * Find out whether the FiniteElement - * used by this DoFHandler is primitive - * or not. + * Find out whether the FiniteElement used by this DoFHandler is + * primitive or not. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates DoFHandler */ @@ -358,14 +326,11 @@ namespace DoFTools fe_is_primitive (const DoFHandler &dh); /** - * Find out whether the FiniteElement - * used by this DoFHandler is primitive - * or not. + * Find out whether the FiniteElement used by this DoFHandler is + * primitive or not. * - * This function exists for both non-hp - * and hp DoFHandlers, to allow for a - * uniform interface to query this - * property. + * This function exists for both non-hp and hp DoFHandlers, to allow + * for a uniform interface to query this property. * * @relates hp::DoFHandler */ @@ -383,117 +348,65 @@ namespace DoFTools */ /** - * Locate non-zero entries of the - * system matrix. - * - * This function computes the - * possible positions of non-zero - * entries in the global system - * matrix. We assume that a - * certain finite element basis - * function is non-zero on a cell - * only if its degree of freedom - * is associated with the - * interior, a face, an edge or a - * vertex of this cell. As a - * result, the matrix entry - * between two basis functions - * can be non-zero only if they - * correspond to degrees of - * freedom of at least one common - * cell. Therefore, - * @p make_sparsity_pattern just - * loops over all cells and - * enters all couplings local to - * that cell. As the generation - * of the sparsity pattern is - * irrespective of the equation - * which is solved later on, the - * resulting sparsity pattern is - * symmetric. - * - * Remember using - * SparsityPattern::compress() - * after generating the pattern. - * - * The actual type of the - * sparsity pattern may be - * SparsityPattern, - * CompressedSparsityPattern, - * BlockSparsityPattern, + * Locate non-zero entries of the system matrix. + * + * This function computes the possible positions of non-zero entries + * in the global system matrix. We assume that a certain finite + * element basis function is non-zero on a cell only if its degree + * of freedom is associated with the interior, a face, an edge or a + * vertex of this cell. As a result, the matrix entry between two + * basis functions can be non-zero only if they correspond to + * degrees of freedom of at least one common cell. Therefore, @p + * make_sparsity_pattern just loops over all cells and enters all + * couplings local to that cell. As the generation of the sparsity + * pattern is irrespective of the equation which is solved later on, + * the resulting sparsity pattern is symmetric. + * + * Remember using SparsityPattern::compress() after generating the + * pattern. + * + * The actual type of the sparsity pattern may be SparsityPattern, + * CompressedSparsityPattern, BlockSparsityPattern, * BlockCompressedSparsityPattern, * BlockCompressedSetSparsityPattern, - * BlockCompressedSimpleSparsityPattern, - * or any other class that - * satisfies similar - * requirements. It is assumed - * that the size of the sparsity - * pattern matches the number of - * degrees of freedom and that - * enough unused nonzero entries - * are left to fill the sparsity - * pattern. The nonzero entries - * generated by this function are - * overlaid to possible previous - * content of the object, that is - * previously added entries are - * not deleted. - * - * Since this process is purely local, - * the sparsity pattern does not provide - * for entries introduced by the - * elimination of hanging nodes. They - * have to be taken care of by a call to - * ConstraintMatrix::condense() - * afterwards. - * - * Alternatively, the constraints on - * degrees of freedom can already be - * taken into account at the time of - * creating the sparsity pattern. For - * this, pass the ConstraintMatrix object - * as the third argument to the current - * function. No call to - * ConstraintMatrix::condense() is then - * necessary. This process is explained - * in step-27. - * - * In case the constraints are - * already taken care of in this - * function, it is possible to - * neglect off-diagonal entries - * in the sparsity pattern. When - * using - * ConstraintMatrix::distribute_local_to_global - * during assembling, no entries - * will ever be written into - * these matrix position, so that - * one can save some computing - * time in matrix-vector products - * by not even creating these - * elements. In that case, the - * variable - * keep_constrained_dofs - * needs to be set to - * false. - * - * If the @p subdomain_id parameter is - * given, the sparsity pattern is built - * only on cells that have a subdomain_id - * equal to the given argument. This is - * useful in parallel contexts where the - * matrix and sparsity pattern (for - * example a - * TrilinosWrappers::SparsityPattern) may - * be distributed and not every MPI - * process needs to build the entire - * sparsity pattern; in that case, it is - * sufficient if every process only - * builds that part of the sparsity - * pattern that corresponds to the - * subdomain_id for which it is - * responsible. This feature is - * used in step-32. + * BlockCompressedSimpleSparsityPattern, or any other class that + * satisfies similar requirements. It is assumed that the size of + * the sparsity pattern matches the number of degrees of freedom and + * that enough unused nonzero entries are left to fill the sparsity + * pattern. The nonzero entries generated by this function are + * overlaid to possible previous content of the object, that is + * previously added entries are not deleted. + * + * Since this process is purely local, the sparsity pattern does not + * provide for entries introduced by the elimination of hanging + * nodes. They have to be taken care of by a call to + * ConstraintMatrix::condense() afterwards. + * + * Alternatively, the constraints on degrees of freedom can already + * be taken into account at the time of creating the sparsity + * pattern. For this, pass the ConstraintMatrix object as the third + * argument to the current function. No call to + * ConstraintMatrix::condense() is then necessary. This process is + * explained in step-27. + * + * In case the constraints are already taken care of in this + * function, it is possible to neglect off-diagonal entries in the + * sparsity pattern. When using + * ConstraintMatrix::distribute_local_to_global during assembling, + * no entries will ever be written into these matrix position, so + * that one can save some computing time in matrix-vector products + * by not even creating these elements. In that case, the variable + * keep_constrained_dofs needs to be set to false. + * + * If the @p subdomain_id parameter is given, the sparsity pattern + * is built only on cells that have a subdomain_id equal to the + * given argument. This is useful in parallel contexts where the + * matrix and sparsity pattern (for example a + * TrilinosWrappers::SparsityPattern) may be distributed and not + * every MPI process needs to build the entire sparsity pattern; in + * that case, it is sufficient if every process only builds that + * part of the sparsity pattern that corresponds to the subdomain_id + * for which it is responsible. This feature is used in step-32. * * @ingroup constraints */ @@ -506,30 +419,22 @@ namespace DoFTools const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id); /** - * Locate non-zero entries for - * vector valued finite elements. - * This function does mostly the - * same as the previous - * @p make_sparsity_pattern, but - * it is specialized for vector - * finite elements and allows to - * specify which variables couple - * in which equation. For - * example, if wanted to solve - * the Stokes equations, + * Locate non-zero entries for vector valued finite elements. This + * function does mostly the same as the previous + * make_sparsity_pattern(), but it is specialized for vector finite + * elements and allows to specify which variables couple in which + * equation. For example, if wanted to solve the Stokes equations, + * * @f{align*} * -\Delta \mathbf u + \nabla p &= 0,\\ * \text{div}\ u &= 0 * @f} - * in two space dimensions, - * using stable Q2/Q1 mixed - * elements (using the FESystem - * class), then you don't want - * all degrees of freedom to - * couple in each equation. You - * rather may want to give the - * following pattern of - * couplings: + * + * in two space dimensions, using stable Q2/Q1 mixed elements (using + * the FESystem class), then you don't want all degrees of freedom + * to couple in each equation. You rather may want to give the + * following pattern of couplings: + * * @f[ * \left[ * \begin{array}{ccc} @@ -539,122 +444,67 @@ namespace DoFTools * \end{array} * \right] * @f] - * where "1" indicates that two - * variables (i.e. components of - * the FESystem) couple in the - * respective equation, and a "0" - * means no coupling, in which - * case it is not necessary to - * allocate space in the matrix - * structure. Obviously, the mask - * refers to components of the - * composed FESystem, rather - * than to the degrees of freedom + * + * where "1" indicates that two variables (i.e. components of the + * FESystem) couple in the respective equation, and a "0" means no + * coupling, in which case it is not necessary to allocate space in + * the matrix structure. Obviously, the mask refers to components of + * the composed FESystem, rather than to the degrees of freedom * contained in there. * - * This function is designed to - * accept a coupling pattern, like the one - * shown above, through the - * @p couplings parameter, which - * contains values of type #Coupling. It - * builds the matrix structure - * just like the previous - * function, but does not create - * matrix elements if not - * specified by the coupling pattern. If the - * couplings are symmetric, then so - * will be the resulting sparsity + * This function is designed to accept a coupling pattern, like the + * one shown above, through the @p couplings parameter, which + * contains values of type #Coupling. It builds the matrix structure + * just like the previous function, but does not create matrix + * elements if not specified by the coupling pattern. If the + * couplings are symmetric, then so will be the resulting sparsity * pattern. * - * The actual type of the - * sparsity pattern may be - * SparsityPattern, - * CompressedSparsityPattern, - * BlockSparsityPattern, + * The actual type of the sparsity pattern may be SparsityPattern, + * CompressedSparsityPattern, BlockSparsityPattern, * BlockCompressedSparsityPattern, - * BlockCompressedSetSparsityPattern, - * or any other class that - * satisfies similar - * requirements. - * - * There is a complication if - * some or all of the shape - * functions of the finite - * element in use are non-zero in - * more than one component (in - * deal.II speak: they are - * non-primitive). In this case, - * the coupling element - * correspoding to the first - * non-zero component is taken - * and additional ones for this - * component are ignored. - * - * Not implemented for - * hp::DoFHandler. + * BlockCompressedSetSparsityPattern, or any other class that + * satisfies similar requirements. + * + * There is a complication if some or all of the shape functions of + * the finite element in use are non-zero in more than one component + * (in deal.II speak: they are non-primitive). In this case, the + * coupling element correspoding to the first non-zero component is + * taken and additional ones for this component are ignored. * - * As mentioned before, the - * creation of the sparsity - * pattern is a purely local - * process and the sparsity - * pattern does not provide for - * entries introduced by the - * elimination of hanging - * nodes. They have to be taken - * care of by a call to - * ConstraintMatrix::condense() - * afterwards. - * - * Alternatively, the constraints - * on degrees of freedom can - * already be taken into account - * at the time of creating the - * sparsity pattern. For this, - * pass the ConstraintMatrix - * object as the third argument - * to the current function. No - * call to - * ConstraintMatrix::condense() - * is then necessary. This - * process is explained in @ref - * step_27 "step-27". - * - * In case the constraints are - * already taken care of in this - * function, it is possible to - * neglect off-diagonal entries - * in the sparsity pattern. When - * using - * ConstraintMatrix::distribute_local_to_global - * during assembling, no entries - * will ever be written into - * these matrix position, so that - * one can save some computing - * time in matrix-vector products - * by not even creating these - * elements. In that case, the - * variable - * keep_constrained_dofs - * needs to be set to - * false. - * - * If the @p subdomain_id parameter is - * given, the sparsity pattern is built - * only on cells that have a subdomain_id - * equal to the given argument. This is - * useful in parallel contexts where the - * matrix and sparsity pattern (for - * example a - * TrilinosWrappers::SparsityPattern) may - * be distributed and not every MPI - * process needs to build the entire - * sparsity pattern; in that case, it is - * sufficient if every process only - * builds that part of the sparsity - * pattern that corresponds to the - * subdomain_id for which it is - * responsible. This feature is - * used in step-32. + * @todo Not implemented for hp::DoFHandler. + * + * As mentioned before, the creation of the sparsity pattern is a + * purely local process and the sparsity pattern does not provide + * for entries introduced by the elimination of hanging nodes. They + * have to be taken care of by a call to + * ConstraintMatrix::condense() afterwards. + * + * Alternatively, the constraints on degrees of freedom can already + * be taken into account at the time of creating the sparsity + * pattern. For this, pass the ConstraintMatrix object as the third + * argument to the current function. No call to + * ConstraintMatrix::condense() is then necessary. This process is + * explained in @ref step_27 "step-27". + * + * In case the constraints are already taken care of in this + * function, it is possible to neglect off-diagonal entries in the + * sparsity pattern. When using + * ConstraintMatrix::distribute_local_to_global during assembling, + * no entries will ever be written into these matrix position, so + * that one can save some computing time in matrix-vector products + * by not even creating these elements. In that case, the variable + * keep_constrained_dofs needs to be set to false. + * + * If the @p subdomain_id parameter is given, the sparsity pattern + * is built only on cells that have a subdomain_id equal to the + * given argument. This is useful in parallel contexts where the + * matrix and sparsity pattern (for example a + * TrilinosWrappers::SparsityPattern) may be distributed and not + * every MPI process needs to build the entire sparsity pattern; in + * that case, it is sufficient if every process only builds that + * part of the sparsity pattern that corresponds to the subdomain_id + * for which it is responsible. This feature is used in step-32. * * @ingroup constraints */ @@ -668,15 +518,10 @@ namespace DoFTools const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id); /** - * @deprecated This is the old - * form of the previous - * function. It generates a table - * of DoFTools::Coupling values - * (where a true - * value in the mask is - * translated into a - * Coupling::always value in the - * table) and calls the function + * @deprecated This is the old form of the previous function. It + * generates a table of DoFTools::Coupling values (where a + * true value in the mask is translated into a + * Coupling::always value in the table) and calls the function * above. */ template @@ -686,37 +531,25 @@ namespace DoFTools SparsityPattern &sparsity_pattern) DEAL_II_DEPRECATED; /** - * Construct a sparsity pattern that - * allows coupling degrees of freedom on - * two different but related meshes. - * - * The idea is that if the two given - * DoFHandler objects correspond to two - * different meshes (and potentially to - * different finite elements used on - * these cells), but that if the two - * triangulations they are based on are - * derived from the same coarse mesh - * through hierarchical refinement, then - * one may set up a problem where one - * would like to test shape functions - * from one mesh against the shape - * functions from another mesh. In - * particular, this means that shape - * functions from a cell on the first - * mesh are tested against those on the - * second cell that are located on the - * corresponding cell; this - * correspondence is something that the - * IntergridMap class can determine. - * - * This function then constructs a - * sparsity pattern for which the degrees - * of freedom that represent the rows - * come from the first given DoFHandler, - * whereas the ones that correspond to - * columns come from the second - * DoFHandler. + * Construct a sparsity pattern that allows coupling degrees of + * freedom on two different but related meshes. + * + * The idea is that if the two given DoFHandler objects correspond + * to two different meshes (and potentially to different finite + * elements used on these cells), but that if the two triangulations + * they are based on are derived from the same coarse mesh through + * hierarchical refinement, then one may set up a problem where one + * would like to test shape functions from one mesh against the + * shape functions from another mesh. In particular, this means that + * shape functions from a cell on the first mesh are tested against + * those on the second cell that are located on the corresponding + * cell; this correspondence is something that the IntergridMap + * class can determine. + * + * This function then constructs a sparsity pattern for which the + * degrees of freedom that represent the rows come from the first + * given DoFHandler, whereas the ones that correspond to columns + * come from the second DoFHandler. */ template void @@ -725,21 +558,15 @@ namespace DoFTools SparsityPattern &sparsity); /** - * Create the sparsity pattern for - * boundary matrices. See the general - * documentation of this class for more - * information. + * Create the sparsity pattern for boundary matrices. See the + * general documentation of this class for more information. * - * The actual type of the sparsity - * pattern may be SparsityPattern, - * CompressedSparsityPattern, - * BlockSparsityPattern, + * The actual type of the sparsity pattern may be SparsityPattern, + * CompressedSparsityPattern, BlockSparsityPattern, * BlockCompressedSparsityPattern, - * BlockCompressedSetSparsityPattern, or - * any other class that satisfies similar - * requirements. It is assumed that the - * size of the sparsity pattern is - * already correct. + * BlockCompressedSetSparsityPattern, or any other class that + * satisfies similar requirements. It is assumed that the size of + * the sparsity pattern is already correct. */ template void @@ -748,34 +575,22 @@ namespace DoFTools SparsityPattern &sparsity_pattern); /** - * Write the sparsity structure of the - * matrix composed of the basis functions - * on the boundary into the - * matrix structure. In contrast to the - * previous function, only those parts - * of the boundary are considered of which - * the boundary indicator is listed in the - * set of numbers passed to this function. - * - * In fact, rather than a @p set - * of boundary indicators, a - * @p map needs to be passed, - * since most of the functions - * handling with boundary - * indicators take a mapping of - * boundary indicators and the - * respective boundary - * functions. The boundary - * function, however, is ignored - * in this function. If you have - * no functions at hand, but only - * the boundary indicators, set - * the function pointers to null + * Write the sparsity structure of the matrix composed of the basis + * functions on the boundary into the matrix structure. In contrast + * to the previous function, only those parts of the boundary are + * considered of which the boundary indicator is listed in the set + * of numbers passed to this function. + * + * In fact, rather than a @p set of boundary indicators, a @p map + * needs to be passed, since most of the functions handling with + * boundary indicators take a mapping of boundary indicators and the + * respective boundary functions. The boundary function, however, is + * ignored in this function. If you have no functions at hand, but + * only the boundary indicators, set the function pointers to null * pointers. * - * For the type of the sparsity - * pattern, the same holds as - * said above. + * For the type of the sparsity pattern, the same holds as said + * above. */ template void @@ -785,20 +600,12 @@ namespace DoFTools SparsityPattern &sparsity); /** - * Generate sparsity pattern for - * fluxes, i.e. formulations of - * the discrete problem with - * discontinuous elements which - * couple across faces of cells. - * This is a replacement of the - * function - * @p make_sparsity_pattern for - * discontinuous methods. Since - * the fluxes include couplings - * between neighboring elements, - * the normal couplings and these - * extra matrix entries are - * considered. + * Generate sparsity pattern for fluxes, i.e. formulations of the + * discrete problem with discontinuous elements which couple across + * faces of cells. This is a replacement of the function @p + * make_sparsity_pattern for discontinuous methods. Since the fluxes + * include couplings between neighboring elements, the normal + * couplings and these extra matrix entries are considered. */ template void @@ -806,13 +613,9 @@ namespace DoFTools SparsityPattern &sparsity_pattern); /** - * This function does the same as - * the other with the same name, - * but it gets a ConstraintMatrix - * additionally. - * This is for the case where you - * have fluxes but constraints as - * well. + * This function does the same as the other with the same name, but + * it gets a ConstraintMatrix additionally. This is for the case + * where you have fluxes but constraints as well. * * @ingroup constraints */ @@ -825,24 +628,16 @@ namespace DoFTools const types::subdomain_id subdomain_id = numbers::invalid_unsigned_int); /** - * This function does the same as - * the other with the same name, - * but it gets two additional - * coefficient matrices. A matrix - * entry will only be generated - * for two basis functions, if - * there is a non-zero entry - * linking their associated - * components in the coefficient + * This function does the same as the other with the same name, but + * it gets two additional coefficient matrices. A matrix entry will + * only be generated for two basis functions, if there is a non-zero + * entry linking their associated components in the coefficient * matrix. * - * There is one matrix for - * couplings in a cell and one - * for the couplings occuring in - * fluxes. + * There is one matrix for couplings in a cell and one for the + * couplings occuring in fluxes. * - * Not implemented for - * hp::DoFHandler. + * @todo Not implemented for hp::DoFHandler. */ template void @@ -858,74 +653,43 @@ namespace DoFTools */ /** - * Compute the constraints resulting from - * the presence of hanging nodes. Hanging - * nodes are best explained using a small - * picture: + * Compute the constraints resulting from the presence of hanging + * nodes. Hanging nodes are best explained using a small picture: * * @image html hanging_nodes.png * - * In order to make a finite element - * function globally continuous, we have - * to make sure that the dark red nodes - * have values that are compatible with - * the adjacent yellow nodes, so that the - * function has no jump when coming from - * the small cells to the large one at - * the top right. We therefore have to - * add conditions that constrain those - * "hanging nodes". - * - * The object into - * which these are inserted is - * later used to condense the - * global system matrix and right - * hand side, and to extend the - * solution vectors from the true - * degrees of freedom also to the - * constraint nodes. This - * function is explained in - * detail in the @ref step_6 - * "step-6" tutorial program and - * is used in almost all - * following programs as well. - * - * This function does not clear - * the constraint matrix object - * before use, in order to allow - * adding constraints from - * different sources to the same - * object. You therefore need to - * make sure it contains only - * constraints you still want; - * otherwise call the - * ConstraintMatrix::clear() - * function. Likewise, this - * function does not close the - * object since you may want to - * enter other constraints later - * on yourself. - * - * In the hp-case, i.e. when the - * argument is of type - * hp::DoFHandler, we consider - * constraints due to different - * finite elements used on two - * sides of a face between cells - * as hanging nodes as well. In - * other words, for hp finite - * elements, this function - * computes all constraints due - * to differing mesh sizes (h) or - * polynomial degrees (p) between - * adjacent cells. - * - * The template argument (and by - * consequence the type of the - * first argument to this - * function) can be either a - * ::DoFHandler, hp::DoFHandler, - * or MGDoFHandler. + * In order to make a finite element function globally continuous, + * we have to make sure that the dark red nodes have values that are + * compatible with the adjacent yellow nodes, so that the function + * has no jump when coming from the small cells to the large one at + * the top right. We therefore have to add conditions that constrain + * those "hanging nodes". + * + * The object into which these are inserted is later used to + * condense the global system matrix and right hand side, and to + * extend the solution vectors from the true degrees of freedom also + * to the constraint nodes. This function is explained in detail in + * the @ref step_6 "step-6" tutorial program and is used in almost + * all following programs as well. + * + * This function does not clear the constraint matrix object before + * use, in order to allow adding constraints from different sources + * to the same object. You therefore need to make sure it contains + * only constraints you still want; otherwise call the + * ConstraintMatrix::clear() function. Likewise, this function does + * not close the object since you may want to enter other + * constraints later on yourself. + * + * In the hp-case, i.e. when the argument is of type hp::DoFHandler, + * we consider constraints due to different finite elements used on + * two sides of a face between cells as hanging nodes as well. In + * other words, for hp finite elements, this function computes all + * constraints due to differing mesh sizes (h) or polynomial degrees + * (p) between adjacent cells. + * + * The template argument (and by consequence the type of the first + * argument to this function) can be either ::DoFHandler or + * hp::DoFHandler. * * @ingroup constraints */ @@ -1270,58 +1034,35 @@ namespace DoFTools /** - * Take a vector of values which live on - * cells (e.g. an error per cell) and - * distribute it to the dofs in such a - * way that a finite element field - * results, which can then be further - * processed, e.g. for output. You should - * note that the resulting field will not - * be continuous at hanging nodes. This - * can, however, easily be arranged by - * calling the appropriate @p distribute - * function of a ConstraintMatrix - * object created for this - * DoFHandler object, after the - * vector has been fully assembled. - * - * It is assumed that the number - * of elements in @p cell_data - * equals the number of active - * cells and that the number of - * elements in @p dof_data equals - * dof_handler.n_dofs(). - * - * Note that the input vector may - * be a vector of any data type - * as long as it is convertible - * to @p double. The output - * vector, being a data vector on - * a DoF handler, always consists of - * elements of type @p double. - * - * In case the finite element - * used by this DoFHandler - * consists of more than one - * component, you need to specify - * which component in the output - * vector should be used to store - * the finite element field in; - * the default is zero (no other - * value is allowed if the finite - * element consists only of one - * component). All other - * components of the vector - * remain untouched, i.e. their - * contents are not changed. - * - * This function cannot be used - * if the finite element in use - * has shape functions that are - * non-zero in more than one - * vector component (in deal.II - * speak: they are - * non-primitive). + * Take a vector of values which live on cells (e.g. an error per + * cell) and distribute it to the dofs in such a way that a finite + * element field results, which can then be further processed, + * e.g. for output. You should note that the resulting field will + * not be continuous at hanging nodes. This can, however, easily be + * arranged by calling the appropriate @p distribute function of a + * ConstraintMatrix object created for this DoFHandler object, after + * the vector has been fully assembled. + * + * It is assumed that the number of elements in @p cell_data equals + * the number of active cells and that the number of elements in @p + * dof_data equals dof_handler.n_dofs(). + * + * Note that the input vector may be a vector of any data type as + * long as it is convertible to @p double. The output vector, being + * a data vector on a DoF handler, always consists of elements of + * type @p double. + * + * In case the finite element used by this DoFHandler consists of + * more than one component, you need to specify which component in + * the output vector should be used to store the finite element + * field in; the default is zero (no other value is allowed if the + * finite element consists only of one component). All other + * components of the vector remain untouched, i.e. their contents + * are not changed. + * + * This function cannot be used if the finite element in use has + * shape functions that are non-zero in more than one vector + * component (in deal.II speak: they are non-primitive). */ template void @@ -1331,50 +1072,30 @@ namespace DoFTools const unsigned int component = 0); /** - * Extract the indices of the - * degrees of freedom belonging - * to certain vector components - * of - * a vector-valued finite - * element. The @p component_mask - * defines which - * components or blocks of an - * FESystem are to be extracted - * from the DoFHandler @p - * dof. The entries in the output array @p - * selected_dofs corresponding to - * degrees of freedom belonging - * to these components are then - * flagged @p true, while all - * others are set to @p false. - * - * The size of @p component_mask must - * be compatible with the number of components - * in the FiniteElement - * used by @p dof. The size of - * @p selected_dofs must equal - * DoFHandler::n_dofs(). Previous - * contents of this array are - * overwritten. + * Extract the indices of the degrees of freedom belonging to + * certain vector components of a vector-valued finite element. The + * @p component_mask defines which components or blocks of an + * FESystem are to be extracted from the DoFHandler @p dof. The + * entries in the output array @p selected_dofs corresponding to + * degrees of freedom belonging to these components are then flagged + * @p true, while all others are set to @p false. + * + * The size of @p component_mask must be compatible with the number + * of components in the FiniteElement used by @p dof. The size of @p + * selected_dofs must equal DoFHandler::n_dofs(). Previous contents + * of this array are overwritten. * - * If the finite element under - * consideration is not primitive, i.e., - * some or all of its shape functions are - * non-zero in more than one vector - * component (which holds, for example, for - * FE_Nedelec or FE_RaviartThomas - * elements), then shape functions cannot - * be associated with a single vector - * component. In this case, if one - * shape vector component of this element - * is flagged in @p component_mask (see - * @ref GlossComponentMask), then this is - * equivalent to selecting all - * vector components corresponding to this - * non-primitive base element. - * - * @note If the @p blocks argument is - * true, + * If the finite element under consideration is not primitive, i.e., + * some or all of its shape functions are non-zero in more than one + * vector component (which holds, for example, for FE_Nedelec or + * FE_RaviartThomas elements), then shape functions cannot be + * associated with a single vector component. In this case, if + * one shape vector component of this element is flagged in + * @p component_mask (see @ref GlossComponentMask), then this is + * equivalent to selecting all vector components + * corresponding to this non-primitive base element. + * + * @note If the @p blocks argument is true, */ template void @@ -1383,8 +1104,7 @@ namespace DoFTools std::vector &selected_dofs); /** - * The same function as above, - * but for a hp::DoFHandler. + * The same function as above, but for a hp::DoFHandler. */ template void @@ -1412,8 +1132,7 @@ namespace DoFTools std::vector &selected_dofs); /** - * The same function as above, - * but for a hp::DoFHandler. + * The same function as above, but for a hp::DoFHandler. */ template void @@ -1422,9 +1141,8 @@ namespace DoFTools std::vector &selected_dofs); /** - * Do the same thing as the corresponding - * extract_dofs() function for one level - * of a multi-grid DoF numbering. + * Do the same thing as the corresponding extract_dofs() function + * for one level of a multi-grid DoF numbering. */ template void @@ -1434,9 +1152,8 @@ namespace DoFTools std::vector &selected_dofs); /** - * Do the same thing as the corresponding - * extract_dofs() function for one level - * of a multi-grid DoF numbering. + * Do the same thing as the corresponding extract_dofs() function + * for one level of a multi-grid DoF numbering. */ template void @@ -1446,66 +1163,38 @@ namespace DoFTools std::vector &selected_dofs); /** - * Extract all degrees of freedom - * which are at the boundary and - * belong to specified components - * of the solution. The function - * returns its results in the - * last non-default-valued - * parameter which contains - * @p true if a degree of - * freedom is at the boundary and - * belongs to one of the selected - * components, and @p false + * Extract all degrees of freedom which are at the boundary and + * belong to specified components of the solution. The function + * returns its results in the last non-default-valued parameter + * which contains @p true if a degree of freedom is at the boundary + * and belongs to one of the selected components, and @p false * otherwise. The function is used in step-15. * - * By specifying the - * @p boundary_indicator - * variable, you can select which - * boundary indicators the faces - * have to have on which the - * degrees of freedom are located - * that shall be extracted. If it - * is an empty list, then all - * boundary indicators are - * accepted. - * - * The size of @p component_mask (see @ref GlossComponentMask) - * shall equal the number of - * components in the finite - * element used by @p dof. The - * size of @p selected_dofs shall - * equal - * dof_handler.n_dofs(). Previous - * contents of this array or + * By specifying the @p boundary_indicator variable, you can select + * which boundary indicators the faces have to have on which the + * degrees of freedom are located that shall be extracted. If it is + * an empty list, then all boundary indicators are accepted. + * + * The size of @p component_mask (see @ref GlossComponentMask) shall + * equal the number of components in the finite element used by @p + * dof. The size of @p selected_dofs shall equal + * dof_handler.n_dofs(). Previous contents of this array or * overwritten. * - * Using the usual convention, if - * a shape function is non-zero - * in more than one component - * (i.e. it is non-primitive), - * then the element in the - * component mask is used that - * corresponds to the first - * non-zero components. Elements - * in the mask corresponding to + * Using the usual convention, if a shape function is non-zero in + * more than one component (i.e. it is non-primitive), then the + * element in the component mask is used that corresponds to the + * first non-zero components. Elements in the mask corresponding to * later components are ignored. * - * @note This function will not work - * for DoFHandler objects that are - * built on a - * parallel::distributed::Triangulation - * object. The reasons is that the - * output argument @p selected_dofs - * has to have a length equal to all - * global degrees of freedom. - * Consequently, this does not scale - * to very large problems. If you - * need the functionality of this - * function for parallel triangulations, - * then you need to use the other - * DoFTools::extract_boundary_dofs - * function. + * @note This function will not work for DoFHandler objects that are + * built on a parallel::distributed::Triangulation object. The + * reasons is that the output argument @p selected_dofs has to have + * a length equal to all global degrees of freedom. + * Consequently, this does not scale to very large problems. If you + * need the functionality of this function for parallel + * triangulations, then you need to use the other + * DoFTools::extract_boundary_dofs function. * * @param dof_handler The object that describes which degrees of freedom * live on which cell @@ -1572,34 +1261,19 @@ namespace DoFTools const std::set &boundary_indicators = std::set()); /** - * This function is similar to - * the extract_boundary_dofs() - * function but it extracts those - * degrees of freedom whose shape - * functions are nonzero on at - * least part of the selected - * boundary. For continuous - * elements, this is exactly the - * set of shape functions whose - * degrees of freedom are defined - * on boundary faces. On the - * other hand, if the finite - * element in used is a - * discontinuous element, all - * degrees of freedom are defined - * in the inside of cells and - * consequently none would be - * boundary degrees of - * freedom. Several of those - * would have shape functions - * that are nonzero on the - * boundary, however. This - * function therefore extracts - * all those for which the - * FiniteElement::has_support_on_face - * function says that it is - * nonzero on any face on one of - * the selected boundary parts. + * This function is similar to the extract_boundary_dofs() function + * but it extracts those degrees of freedom whose shape functions + * are nonzero on at least part of the selected boundary. For + * continuous elements, this is exactly the set of shape functions + * whose degrees of freedom are defined on boundary faces. On the + * other hand, if the finite element in used is a discontinuous + * element, all degrees of freedom are defined in the inside of + * cells and consequently none would be boundary degrees of + * freedom. Several of those would have shape functions that are + * nonzero on the boundary, however. This function therefore + * extracts all those for which the + * FiniteElement::has_support_on_face function says that it is + * nonzero on any face on one of the selected boundary parts. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -1616,15 +1290,11 @@ namespace DoFTools */ /** - * Select all dofs that will be - * constrained by interface - * constraints, i.e. all hanging - * nodes. + * Select all dofs that will be constrained by interface + * constraints, i.e. all hanging nodes. * - * The size of @p selected_dofs - * shall equal - * dof_handler.n_dofs(). Previous - * contents of this array or + * The size of @p selected_dofs shall equal + * dof_handler.n_dofs(). Previous contents of this array or * overwritten. */ template @@ -1638,22 +1308,13 @@ namespace DoFTools * @{ */ /** - * Flag all those degrees of - * freedom which are on cells - * with the given subdomain - * id. Note that DoFs on faces - * can belong to cells with - * differing subdomain ids, so - * the sets of flagged degrees of - * freedom are not mutually - * exclusive for different - * subdomain ids. - * - * If you want to get a unique - * association of degree of freedom with - * subdomains, use the - * @p get_subdomain_association - * function. + * Flag all those degrees of freedom which are on cells with the + * given subdomain id. Note that DoFs on faces can belong to cells + * with differing subdomain ids, so the sets of flagged degrees of + * freedom are not mutually exclusive for different subdomain ids. + * + * If you want to get a unique association of degree of freedom with + * subdomains, use the @p get_subdomain_association function. */ template void @@ -1663,15 +1324,10 @@ namespace DoFTools /** - * Extract the set of global DoF - * indices that are owned by the - * current processor. For regular - * DoFHandler objects, this set - * is the complete set with all - * DoF indices. In either case, - * it equals what - * DoFHandler::locally_owned_dofs() - * returns. + * Extract the set of global DoF indices that are owned by the + * current processor. For regular DoFHandler objects, this set is + * the complete set with all DoF indices. In either case, it equals + * what DoFHandler::locally_owned_dofs() returns. */ template void @@ -1680,32 +1336,19 @@ namespace DoFTools /** - * Extract the set of global DoF - * indices that are active on the - * current DoFHandler. For - * regular DoFHandlers, these are - * all DoF indices, but for - * DoFHandler objects built on - * parallel::distributed::Triangulation - * this set is a superset of - * DoFHandler::locally_owned_dofs() - * and contains all DoF indices - * that live on all locally owned - * cells (including on the - * interface to ghost - * cells). However, it does not - * contain the DoF indices that - * are exclusively defined on - * ghost or artificial cells (see - * @ref GlossArtificialCell "the - * glossary"). - * - * The degrees of freedom identified by - * this function equal those obtained - * from the - * dof_indices_with_subdomain_association() - * function when called with the locally - * owned subdomain id. + * Extract the set of global DoF indices that are active on the + * current DoFHandler. For regular DoFHandlers, these are all DoF + * indices, but for DoFHandler objects built on + * parallel::distributed::Triangulation this set is a superset of + * DoFHandler::locally_owned_dofs() and contains all DoF indices + * that live on all locally owned cells (including on the interface + * to ghost cells). However, it does not contain the DoF indices + * that are exclusively defined on ghost or artificial cells (see + * @ref GlossArtificialCell "the glossary"). + * + * The degrees of freedom identified by this function equal those + * obtained from the dof_indices_with_subdomain_association() + * function when called with the locally owned subdomain id. */ template void @@ -1713,20 +1356,13 @@ namespace DoFTools IndexSet &dof_set); /** - * Extract the set of global DoF - * indices that are active on the - * current DoFHandler. For - * regular DoFHandlers, these are - * all DoF indices, but for - * DoFHandler objects built on - * parallel::distributed::Triangulation - * this set is the union of - * DoFHandler::locally_owned_dofs() - * and the DoF indices on all - * ghost cells. In essence, it is - * the DoF indices on all cells - * that are not artificial (see - * @ref GlossArtificialCell "the glossary"). + * Extract the set of global DoF indices that are active on the + * current DoFHandler. For regular DoFHandlers, these are all DoF + * indices, but for DoFHandler objects built on + * parallel::distributed::Triangulation this set is the union of + * DoFHandler::locally_owned_dofs() and the DoF indices on all ghost + * cells. In essence, it is the DoF indices on all cells that are + * not artificial (see @ref GlossArtificialCell "the glossary"). */ template void @@ -1734,57 +1370,36 @@ namespace DoFTools IndexSet &dof_set); /** - * For each DoF, return in the output - * array to which subdomain (as given by - * the cell->subdomain_id() function) - * it belongs. The output array is - * supposed to have the right size + * For each DoF, return in the output array to which subdomain (as + * given by the cell->subdomain_id() function) it + * belongs. The output array is supposed to have the right size * already when calling this function. * - * Note that degrees of freedom - * associated with faces, edges, and - * vertices may be associated with - * multiple subdomains if they are - * sitting on partition boundaries. In - * these cases, we put them into one of - * the associated partitions in an - * undefined way. This may sometimes lead - * to different numbers of degrees of - * freedom in partitions, even if the - * number of cells is perfectly - * equidistributed. While this is - * regrettable, it is not a problem in - * practice since the number of degrees - * of freedom on partition boundaries is - * asymptotically vanishing as we refine - * the mesh as long as the number of - * partitions is kept constant. - * - * This function returns the association - * of each DoF with one subdomain. If you - * are looking for the association of - * each @em cell with a subdomain, either - * query the - * cell->subdomain_id() - * function, or use the - * GridTools::get_subdomain_association - * function. - * - * Note that this function is of - * questionable use for DoFHandler objects built on - * parallel::distributed::Triangulation - * since in that case ownership of - * individual degrees of freedom by MPI - * processes is controlled by the DoF - * handler object, not based on some - * geometric algorithm in conjunction - * with subdomain id. In particular, the - * degrees of freedom identified by the - * functions in this namespace as - * associated with a subdomain are not - * the same the - * DoFHandler class - * identifies as those it owns. + * Note that degrees of freedom associated with faces, edges, and + * vertices may be associated with multiple subdomains if they are + * sitting on partition boundaries. In these cases, we put them into + * one of the associated partitions in an undefined way. This may + * sometimes lead to different numbers of degrees of freedom in + * partitions, even if the number of cells is perfectly + * equidistributed. While this is regrettable, it is not a problem + * in practice since the number of degrees of freedom on partition + * boundaries is asymptotically vanishing as we refine the mesh as + * long as the number of partitions is kept constant. + * + * This function returns the association of each DoF with one + * subdomain. If you are looking for the association of each @em + * cell with a subdomain, either query the + * cell->subdomain_id() function, or use the + * GridTools::get_subdomain_association function. + * + * Note that this function is of questionable use for DoFHandler + * objects built on parallel::distributed::Triangulation since in + * that case ownership of individual degrees of freedom by MPI + * processes is controlled by the DoF handler object, not based on + * some geometric algorithm in conjunction with subdomain id. In + * particular, the degrees of freedom identified by the functions in + * this namespace as associated with a subdomain are not the same + * the DoFHandler class identifies as those it owns. */ template void @@ -1792,43 +1407,31 @@ namespace DoFTools std::vector &subdomain); /** - * Count how many degrees of freedom are - * uniquely associated with the given - * @p subdomain index. + * Count how many degrees of freedom are uniquely associated with + * the given @p subdomain index. * - * Note that there may be rare cases - * where cells with the given @p - * subdomain index exist, but none of its - * degrees of freedom are actually - * associated with it. In that case, the - * returned value will be zero. + * Note that there may be rare cases where cells with the given @p + * subdomain index exist, but none of its degrees of freedom are + * actually associated with it. In that case, the returned value + * will be zero. * - * This function will generate an - * exception if there are no cells with - * the given @p subdomain index. + * This function will generate an exception if there are no cells + * with the given @p subdomain index. * - * This function returns the number of - * DoFs associated with one subdomain. If - * you are looking for the association of - * @em cells with this subdomain, use the + * This function returns the number of DoFs associated with one + * subdomain. If you are looking for the association of @em cells + * with this subdomain, use the * GridTools::count_cells_with_subdomain_association * function. * - * Note that this function is of - * questionable use for DoFHandler objects built on - * parallel::distributed::Triangulation - * since in that case ownership of - * individual degrees of freedom by MPI - * processes is controlled by the DoF - * handler object, not based on some - * geometric algorithm in conjunction - * with subdomain id. In particular, the - * degrees of freedom identified by the - * functions in this namespace as - * associated with a subdomain are not - * the same the - * DoFHandler class - * identifies as those it owns. + * Note that this function is of questionable use for DoFHandler + * objects built on parallel::distributed::Triangulation since in + * that case ownership of individual degrees of freedom by MPI + * processes is controlled by the DoF handler object, not based on + * some geometric algorithm in conjunction with subdomain id. In + * particular, the degrees of freedom identified by the functions in + * this namespace as associated with a subdomain are not the same + * the DoFHandler class identifies as those it owns. */ template unsigned int @@ -1836,36 +1439,24 @@ namespace DoFTools const types::subdomain_id subdomain); /** - * Count how many degrees of freedom are - * uniquely associated with the given - * @p subdomain index. - * - * This function does what the previous - * one does except that it splits the - * result among the vector components of - * the finite element in use by the - * DoFHandler object. The last argument - * (which must have a length equal to the - * number of vector components) will - * therefore store how many degrees of - * freedom of each vector component are - * associated with the given subdomain. - * - * Note that this function is of - * questionable use for DoFHandler objects built on - * parallel::distributed::Triangulation - * since in that case ownership of - * individual degrees of freedom by MPI - * processes is controlled by the DoF - * handler object, not based on some - * geometric algorithm in conjunction - * with subdomain id. In particular, the - * degrees of freedom identified by the - * functions in this namespace as - * associated with a subdomain are not - * the same the - * DoFHandler class - * identifies as those it owns. + * Count how many degrees of freedom are uniquely associated with + * the given @p subdomain index. + * + * This function does what the previous one does except that it + * splits the result among the vector components of the finite + * element in use by the DoFHandler object. The last argument (which + * must have a length equal to the number of vector components) will + * therefore store how many degrees of freedom of each vector + * component are associated with the given subdomain. + * + * Note that this function is of questionable use for DoFHandler + * objects built on parallel::distributed::Triangulation since in + * that case ownership of individual degrees of freedom by MPI + * processes is controlled by the DoF handler object, not based on + * some geometric algorithm in conjunction with subdomain id. In + * particular, the degrees of freedom identified by the functions in + * this namespace as associated with a subdomain are not the same + * the DoFHandler class identifies as those it owns. */ template void @@ -1874,40 +1465,26 @@ namespace DoFTools std::vector &n_dofs_on_subdomain); /** - * Return a set of indices that denotes - * the degrees of freedom that live on - * the given subdomain, i.e. that are on - * cells owned by the current - * processor. Note that this includes the - * ones that this subdomain "owns" - * (i.e. the ones for which - * get_subdomain_association() returns a - * value equal to the subdomain given - * here and that are selected by the - * extract_locally_owned() function) but - * also all of those that sit on the - * boundary between the given subdomain - * and other subdomain. In essence, - * degrees of freedom that sit on - * boundaries between subdomain will be - * in the index sets returned by this + * Return a set of indices that denotes the degrees of freedom that + * live on the given subdomain, i.e. that are on cells owned by the + * current processor. Note that this includes the ones that this + * subdomain "owns" (i.e. the ones for which + * get_subdomain_association() returns a value equal to the + * subdomain given here and that are selected by the + * extract_locally_owned() function) but also all of those that sit + * on the boundary between the given subdomain and other + * subdomain. In essence, degrees of freedom that sit on boundaries + * between subdomain will be in the index sets returned by this * function for more than one subdomain. * - * Note that this function is of - * questionable use for DoFHandler objects built on - * parallel::distributed::Triangulation - * since in that case ownership of - * individual degrees of freedom by MPI - * processes is controlled by the DoF - * handler object, not based on some - * geometric algorithm in conjunction - * with subdomain id. In particular, the - * degrees of freedom identified by the - * functions in this namespace as - * associated with a subdomain are not - * the same the - * DoFHandler class - * identifies as those it owns. + * Note that this function is of questionable use for DoFHandler + * objects built on parallel::distributed::Triangulation since in + * that case ownership of individual degrees of freedom by MPI + * processes is controlled by the DoF handler object, not based on + * some geometric algorithm in conjunction with subdomain id. In + * particular, the degrees of freedom identified by the functions in + * this namespace as associated with a subdomain are not the same + * the DoFHandler class identifies as those it owns. */ template IndexSet @@ -1917,37 +1494,24 @@ namespace DoFTools /** * @name Dof indices for patches * - * Create structures containing a - * large set of degrees of freedom - * for small patches of cells. The - * resulting objects can be used in - * RelaxationBlockSOR and related - * classes to implement Schwarz - * preconditioners and smoothers, - * where the subdomains consist of + * Create structures containing a large set of degrees of freedom + * for small patches of cells. The resulting objects can be used in + * RelaxationBlockSOR and related classes to implement Schwarz + * preconditioners and smoothers, where the subdomains consist of * small numbers of cells only. */ //@{ /** - * Create an incidence matrix that - * for every cell on a given level - * of a multilevel DoFHandler flags - * which degrees of freedom are - * associated with the - * corresponding cell. This data - * structure is matrix with as many - * rows as there are cells on a - * given level, as many rows as - * there are degrees of freedom on - * this level, and entries that are - * either true or false. This data - * structure is conveniently - * represented by a SparsityPattern - * object. - * - * @note The ordering of rows - * (cells) follows the ordering of - * the standard cell iterators. + * Create an incidence matrix that for every cell on a given level + * of a multilevel DoFHandler flags which degrees of freedom are + * associated with the corresponding cell. This data structure is + * matrix with as many rows as there are cells on a given level, as + * many rows as there are degrees of freedom on this level, and + * entries that are either true or false. This data structure is + * conveniently represented by a SparsityPattern object. + * + * @note The ordering of rows (cells) follows the ordering of the + * standard cell iterators. */ template void make_cell_patches(Sparsity &block_list, @@ -1957,73 +1521,45 @@ namespace DoFTools types::global_dof_index offset = 0); /** - * Create an incidence matrix that - * for every vertex on a given level - * of a multilevel DoFHandler flags - * which degrees of freedom are - * associated with the - * adjacent cells. This data - * structure is matrix with as many - * rows as there are vertices on a - * given level, as many rows as - * there are degrees of freedom on - * this level, and entries that are - * either true or false. This data - * structure is conveniently - * represented by a SparsityPattern - * object. - * The sparsity pattern - * may be empty when entering this - * function and will be - * reinitialized to the correct - * size. - * - * The function has some boolean - * arguments (listed below) - * controlling details of the - * generated patches. The default - * settings are those for - * Arnold-Falk-Winther type - * smoothers for divergence and - * curl conforming finite elements - * with essential boundary - * conditions. Other applications - * are possible, in particular - * changing - * boundary_patches for - * non-essential boundary conditions. - * - * @arg block_list: the - * SparsityPattern into which the + * Create an incidence matrix that for every vertex on a given level + * of a multilevel DoFHandler flags which degrees of freedom are + * associated with the adjacent cells. This data structure is matrix + * with as many rows as there are vertices on a given level, as many + * rows as there are degrees of freedom on this level, and entries + * that are either true or false. This data structure is + * conveniently represented by a SparsityPattern object. The + * sparsity pattern may be empty when entering this function and + * will be reinitialized to the correct size. + * + * The function has some boolean arguments (listed below) + * controlling details of the generated patches. The default + * settings are those for Arnold-Falk-Winther type smoothers for + * divergence and curl conforming finite elements with essential + * boundary conditions. Other applications are possible, in + * particular changing boundary_patches for non-essential + * boundary conditions. + * + * @arg block_list: the SparsityPattern into which the * patches will be stored. - * @arg dof_handler: The - * multilevel dof handler - * providing the topology operated - * on. - * @arg - * interior_dofs_only: - * for each patch of cells around - * a vertex, collect only the - * interior degrees of freedom of - * the patch and disregard those - * on the boundary of the - * patch. This is for instance the - * setting for smoothers of - * Arnold-Falk-Winther type. - * @arg boundary_patches: - * include patches around vertices - * at the boundary of the - * domain. If not, only patches - * around interior vertices will - * be generated. - * @arg - * level_boundary_patches: - * same for refinement edges + * + * @arg dof_handler: The multilevel dof handler providing + * the topology operated on. + * + * @arg interior_dofs_only: for each patch of cells around + * a vertex, collect only the interior degrees of freedom of the + * patch and disregard those on the boundary of the patch. This is + * for instance the setting for smoothers of Arnold-Falk-Winther + * type. + * + * @arg boundary_patches: include patches around vertices + * at the boundary of the domain. If not, only patches around + * interior vertices will be generated. + * + * @arg level_boundary_patches: same for refinement edges * towards coarser cells. - * @arg - * single_cell_patches: - * if not true, patches containing - * a single cell are eliminated. + * + * @arg single_cell_patches: if not true, patches + * containing a single cell are eliminated. */ template void make_vertex_patches(SparsityPattern &block_list, @@ -2035,71 +1571,42 @@ namespace DoFTools const bool single_cell_patches = false); /** - * Create an incidence matrix that - * for every cell on a given level - * of a multilevel DoFHandler flags - * which degrees of freedom are - * associated with children of this - * cell. This data - * structure is conveniently - * represented by a SparsityPattern - * object. - - * Create a sparsity pattern which - * in each row lists the degrees of - * freedom associated to the - * cells which are the children of - * the same cell. The - * sparsity pattern may be empty - * when entering this function and - * will be reinitialized to the - * correct size. - * - * The function has some boolean - * arguments (lsited below) - * controlling details of the - * generated patches. The default - * settings are those for - * Arnold-Falk-Winther type - * smoothers for divergence and - * curl conforming finite elements - * with essential boundary - * conditions. Other applications - * are possible, in particular - * changing - * boundary_dofs for - * non-essential boundary - * conditions. - * - * Since the patches are defined - * through refinement, th - * - * @arg block_list: the - * SparsityPattern into which the + * Create an incidence matrix that for every cell on a given level + * of a multilevel DoFHandler flags which degrees of freedom are + * associated with children of this cell. This data structure is + * conveniently represented by a SparsityPattern object. + + * Create a sparsity pattern which in each row lists the degrees of + * freedom associated to the cells which are the children of the + * same cell. The sparsity pattern may be empty when entering this + * function and will be reinitialized to the correct size. + * + * The function has some boolean arguments (listed below) + * controlling details of the generated patches. The default + * settings are those for Arnold-Falk-Winther type smoothers for + * divergence and curl conforming finite elements with essential + * boundary conditions. Other applications are possible, in + * particular changing boundary_dofs for non-essential + * boundary conditions. + * + * Since the patches are defined through refinement, th + * + * @arg block_list: the SparsityPattern into which the * patches will be stored. - * @arg dof_handler: The - * multilevel dof handler - * providing the topology operated - * on. - * @arg - * interior_dofs_only: - * for each patch of cells around - * a vertex, collect only the - * interior degrees of freedom of - * the patch and disregard those - * on the boundary of the - * patch. This is for instance the - * setting for smoothers of - * Arnold-Falk-Winther type. - * @arg boundary_dofs: - * include degrees of freedom, - * which would have excluded by - * interior_dofs_only, - * but are lying on the boundary - * of the domain, and thus need - * smoothing. This parameter has - * no effect if - * interior_dofs_only is false. + * + * @arg dof_handler: The multilevel dof handler providing + * the topology operated on. + * + * @arg interior_dofs_only: for each patch of cells around + * a vertex, collect only the interior degrees of freedom of the + * patch and disregard those on the boundary of the patch. This is + * for instance the setting for smoothers of Arnold-Falk-Winther + * type. + * + * @arg boundary_dofs: include degrees of freedom, which + * would have excluded by interior_dofs_only, but are lying + * on the boundary of the domain, and thus need smoothing. This + * parameter has no effect if interior_dofs_only is false. */ template void make_child_patches(SparsityPattern &block_list, @@ -2109,30 +1616,23 @@ namespace DoFTools const bool boundary_dofs = false); /** - * Create a block list with only a - * single patch, which in turn - * contains all degrees of freedom - * on the given level. + * Create a block list with only a single patch, which in turn + * contains all degrees of freedom on the given level. * - * This function is mostly a - * closure on level 0 for functions - * like make_child_patches() and - * make_vertex_patches(), which may - * produce an empty patch list. + * This function is mostly a closure on level 0 for functions like + * make_child_patches() and make_vertex_patches(), which may produce + * an empty patch list. * - * @arg block_list: the - * SparsityPattern into which the + * @arg block_list: the SparsityPattern into which the * patches will be stored. - * @arg dof_handler: The - * multilevel dof handler - * providing the topology operated - * on. - * @arg level The grid - * level used for building the list. - * @arg - * interior_dofs_only: - * if true, exclude degrees of freedom on - * the boundary of the domain. + * + * @arg dof_handler: The multilevel dof handler providing + * the topology operated on. + * + * @arg level The grid level used for building the list. + * + * @arg interior_dofs_only: if true, exclude degrees of + * freedom on the boundary of the domain. */ template void make_single_patch(SparsityPattern &block_list, @@ -2142,49 +1642,32 @@ namespace DoFTools //@} /** - * Extract a vector that represents the - * constant modes of the DoFHandler for the - * components chosen by - * component_mask (see @ref - * GlossComponentMask). The constant modes - * on a discretization are the null space - * of a Laplace operator on the selected - * components with Neumann boundary - * conditions applied. The null space is a - * necessary ingredient for obtaining a - * good AMG preconditioner when using the - * class TrilinosWrappers::PreconditionAMG. - * Since the ML AMG package only works on - * algebraic properties of the respective - * matrix, it has no chance to detect - * whether the matrix comes from a scalar - * or a vector valued problem. However, a - * near null space supplies exactly the - * needed information about these - * components. The null space will consist - * of as many vectors as there are true - * arguments in component_mask - * (see @ref GlossComponentMask), each of - * which will be one in one vector - * component and zero in all others. We - * store this object in a vector of - * vectors, where the outer vector is of - * the size of the number of selected - * components, and each inner vector has as - * many components as there are (locally - * owned) degrees of freedom in the - * selected components. Note that any - * matrix associated with this null space - * must have been constructed using the - * same component_mask argument, - * since the numbering of DoFs is done - * relative to the selected dofs, not to - * all dofs. - * - * The main reason for this - * program is the use of the - * null space with the - * AMG preconditioner. + * Extract a vector that represents the constant modes of the + * DoFHandler for the components chosen by component_mask + * (see @ref GlossComponentMask). The constant modes on a + * discretization are the null space of a Laplace operator on the + * selected components with Neumann boundary conditions applied. The + * null space is a necessary ingredient for obtaining a good AMG + * preconditioner when using the class + * TrilinosWrappers::PreconditionAMG. Since the ML AMG package only + * works on algebraic properties of the respective matrix, it has no + * chance to detect whether the matrix comes from a scalar or a + * vector valued problem. However, a near null space supplies + * exactly the needed information about these components. The null + * space will consist of as many vectors as there are true arguments + * in component_mask (see @ref GlossComponentMask), each of + * which will be one in one vector component and zero in all + * others. We store this object in a vector of vectors, where the + * outer vector is of the size of the number of selected components, + * and each inner vector has as many components as there are + * (locally owned) degrees of freedom in the selected + * components. Note that any matrix associated with this null space + * must have been constructed using the same component_mask + * argument, since the numbering of DoFs is done relative to the + * selected dofs, not to all dofs. + * + * The main reason for this program is the use of the null space + * with the AMG preconditioner. */ template void @@ -2193,18 +1676,14 @@ namespace DoFTools std::vector > &constant_modes); /** - * For each active cell of a DoFHandler - * or hp::DoFHandler, extract the active - * finite element index and fill the - * vector given as second argument. This - * vector is assumed to have as many - * entries as there are active cells. + * For each active cell of a DoFHandler or hp::DoFHandler, extract + * the active finite element index and fill the vector given as + * second argument. This vector is assumed to have as many entries + * as there are active cells. * - * For non-hp DoFHandler objects given as - * first argument, the returned vector - * will consist of only zeros, indicating - * that all cells use the same finite - * element. For a hp::DoFHandler, the + * For non-hp DoFHandler objects given as first argument, the + * returned vector will consist of only zeros, indicating that all + * cells use the same finite element. For a hp::DoFHandler, the * values may be different, though. */ template @@ -2213,81 +1692,42 @@ namespace DoFTools std::vector &active_fe_indices); /** - * Count how many degrees of - * freedom out of the total - * number belong to each - * component. If the number of - * components the finite element - * has is one (i.e. you only have - * one scalar variable), then the - * number in this component - * obviously equals the total - * number of degrees of - * freedom. Otherwise, the sum of - * the DoFs in all the components - * needs to equal the total - * number. - * - * However, the last statement - * does not hold true if the - * finite element is not - * primitive, i.e. some or all of - * its shape functions are - * non-zero in more than one - * vector component. This - * applies, for example, to the - * Nedelec or Raviart-Thomas - * elements. In this case, a - * degree of freedom is counted - * in each component in which it - * is non-zero, so that the sum - * mentioned above is greater - * than the total number of - * degrees of freedom. - * - * This behavior can be switched - * off by the optional parameter - * vector_valued_once. If - * this is true, the - * number of components of a - * nonprimitive vector valued - * element is collected only in - * the first component. All other - * components will have a count - * of zero. - * - * The additional optional - * argument @p target_component - * allows for a re-sorting and - * grouping of components. To - * this end, it contains for each - * component the component number - * it shall be counted as. Having - * the same number entered - * several times sums up several - * components as the same. One of - * the applications of this - * argument is when you want to - * form block matrices and - * vectors, but want to pack - * several components into the - * same block (for example, when - * you have @p dim velocities - * and one pressure, to put all - * velocities into one block, and - * the pressure into another). - * - * The result is returned in @p - * dofs_per_component. Note that - * the size of @p - * dofs_per_component needs to be - * enough to hold all the indices - * specified in @p - * target_component. If this is - * not the case, an assertion is - * thrown. The indices not - * targeted by target_components - * are left untouched. + * Count how many degrees of freedom out of the total number belong + * to each component. If the number of components the finite element + * has is one (i.e. you only have one scalar variable), then the + * number in this component obviously equals the total number of + * degrees of freedom. Otherwise, the sum of the DoFs in all the + * components needs to equal the total number. + * + * However, the last statement does not hold true if the finite + * element is not primitive, i.e. some or all of its shape functions + * are non-zero in more than one vector component. This applies, for + * example, to the Nedelec or Raviart-Thomas elements. In this case, + * a degree of freedom is counted in each component in which it is + * non-zero, so that the sum mentioned above is greater than the + * total number of degrees of freedom. + * + * This behavior can be switched off by the optional parameter + * vector_valued_once. If this is true, the number + * of components of a nonprimitive vector valued element is + * collected only in the first component. All other components will + * have a count of zero. + * + * The additional optional argument @p target_component allows for a + * re-sorting and grouping of components. To this end, it contains + * for each component the component number it shall be counted + * as. Having the same number entered several times sums up several + * components as the same. One of the applications of this argument + * is when you want to form block matrices and vectors, but want to + * pack several components into the same block (for example, when + * you have @p dim velocities and one pressure, to put all + * velocities into one block, and the pressure into another). + * + * The result is returned in @p dofs_per_component. Note that the + * size of @p dofs_per_component needs to be enough to hold all the + * indices specified in @p target_component. If this is not the + * case, an assertion is thrown. The indices not targeted by + * target_components are left untouched. */ template void @@ -2298,35 +1738,20 @@ namespace DoFTools = std::vector()); /** - * Count the degrees of freedom - * in each block. This function - * is similar to - * count_dofs_per_component(), - * with the difference that the - * counting is done by - * blocks. See @ref GlossBlock - * "blocks" in the glossary for - * details. Again the vectors are - * assumed to have the correct - * size before calling this - * function. If this is not the + * Count the degrees of freedom in each block. This function is + * similar to count_dofs_per_component(), with the difference that + * the counting is done by blocks. See @ref GlossBlock "blocks" in + * the glossary for details. Again the vectors are assumed to have + * the correct size before calling this function. If this is not the * case, an assertion is thrown. * - * This function is used in the - * step-22, - * step-31, and - * step-32 tutorial - * programs. - * - * @pre The dofs_per_block - * variable has as many - * components as the finite - * element used by the - * dof_handler argument has - * blocks, or alternatively as - * many blocks as are enumerated - * in the target_blocks argument - * if given. + * This function is used in the step-22, step-31, and step-32 + * tutorial programs. + * + * @pre The dofs_per_block variable has as many components as the + * finite element used by the dof_handler argument has blocks, or + * alternatively as many blocks as are enumerated in the + * target_blocks argument if given. */ template void @@ -2336,11 +1761,8 @@ namespace DoFTools = std::vector()); /** - * @deprecated See the previous - * function with the same name - * for a description. This - * function exists for - * compatibility with older + * @deprecated See the previous function with the same name for a + * description. This function exists for compatibility with older * versions only. */ template @@ -2350,218 +1772,102 @@ namespace DoFTools std::vector target_component) DEAL_II_DEPRECATED; /** - * This function can be used when - * different variables shall be - * discretized on different - * grids, where one grid is - * coarser than the other. This - * idea might seem nonsensical at - * first, but has reasonable - * applications in inverse - * (parameter estimation) - * problems, where there might - * not be enough information to - * recover the parameter on the - * same grid as the state - * variable; furthermore, the - * smoothness properties of state - * variable and parameter might - * not be too much related, so - * using different grids might be - * an alternative to using - * stronger regularization of the + * This function can be used when different variables shall be + * discretized on different grids, where one grid is coarser than + * the other. This idea might seem nonsensical at first, but has + * reasonable applications in inverse (parameter estimation) + * problems, where there might not be enough information to recover + * the parameter on the same grid as the state variable; + * furthermore, the smoothness properties of state variable and + * parameter might not be too much related, so using different grids + * might be an alternative to using stronger regularization of the * problem. * - * The basic idea of this - * function is explained in the - * following. Let us, for - * convenience, denote by - * ``parameter grid'' the coarser - * of the two grids, and by - * ``state grid'' the finer of - * the two. We furthermore assume - * that the finer grid can be - * obtained by refinement of the - * coarser one, i.e. the fine - * grid is at least as much - * refined as the coarse grid at - * each point of the - * domain. Then, each shape - * function on the coarse grid - * can be represented as a linear - * combination of shape functions - * on the fine grid (assuming - * identical ansatz - * spaces). Thus, if we - * discretize as usual, using - * shape functions on the fine - * grid, we can consider the - * restriction that the parameter - * variable shall in fact be - * discretized by shape functions - * on the coarse grid as a - * constraint. These constraints - * are linear and happen to have - * the form managed by the - * ``ConstraintMatrix'' class. - * - * The construction of these - * constraints is done as - * follows: for each of the - * degrees of freedom (i.e. shape - * functions) on the coarse grid, - * we compute its representation - * on the fine grid, i.e. how the - * linear combination of shape - * functions on the fine grid - * looks like that resembles the - * shape function on the coarse - * grid. From this information, - * we can then compute the - * constraints which have to hold - * if a solution of a linear - * equation on the fine grid - * shall be representable on the - * coarse grid. The exact - * algorithm how these - * constraints can be computed is - * rather complicated and is best - * understood by reading the - * source code, which contains - * many comments. - * - * Before explaining the use of - * this function, we would like - * to state that the total number - * of degrees of freedom used for - * the discretization is not - * reduced by the use of this - * function, i.e. even though we - * discretize one variable on a - * coarser grid, the total number - * of degrees of freedom is that - * of the fine grid. This seems - * to be counter-productive, - * since it does not give us a - * benefit from using a coarser - * grid. The reason why it may be - * useful to choose this approach - * nonetheless is three-fold: - * first, as stated above, there - * might not be enough - * information to recover a - * parameter on a fine grid, - * i.e. we chose to discretize it - * on the coarse grid not to save - * DoFs, but for other - * reasons. Second, the - * ``ConstraintMatrix'' includes - * the constraints into the - * linear system of equations, by - * which constrained nodes become - * dummy nodes; we may therefore - * exclude them from the linear - * algebra, for example by - * sorting them to the back of - * the DoF numbers and simply - * calling the solver for the - * upper left block of the matrix - * which works on the - * non-constrained nodes only, - * thus actually realizing the - * savings in numerical effort - * from the reduced number of - * actual degrees of freedom. The - * third reason is that for some - * or other reason we have chosen - * to use two different grids, it - * may be actually quite - * difficult to write a function - * that assembles the system - * matrix for finite element - * spaces on different grids; - * using the approach of - * constraints as with this - * function allows to use - * standard techniques when - * discretizing on only one grid - * (the finer one) without having - * to take care of the fact that - * one or several of the variable - * actually belong to different - * grids. - * - * The use of this function is as - * follows: it accepts as - * parameters two DoF Handlers, - * the first of which refers to - * the coarse grid and the second - * of which is the fine grid. On - * both, a finite element is - * represented by the DoF handler - * objects, which will usually - * have several components, which - * may belong to different finite - * elements. The second and - * fourth parameter of this - * function therefore state which - * variable on the coarse grid - * shall be used to restrict the - * stated component on the fine - * grid. Of course, the finite - * elements used for the - * respective components on the - * two grids need to be the - * same. An example may clarify - * this: consider the parameter - * estimation mentioned briefly - * above; there, on the fine grid - * the whole discretization is - * done, thus the variables are - * ``u'', ``q'', and the Lagrange - * multiplier ``lambda'', which - * are discretized using - * continuous linear, piecewise - * constant discontinuous, and - * continuous linear elements, - * respectively. Only the - * parameter ``q'' shall be - * represented on the coarse - * grid, thus the DoFHandler - * object on the coarse grid - * represents only one variable, - * discretized using piecewise - * constant discontinuous - * elements. Then, the parameter - * denoting the component on the - * coarse grid would be zero (the - * only possible choice, since - * the variable on the coarse - * grid is scalar), and one on - * the fine grid (corresponding - * to the variable ``q''; zero - * would be ``u'', two would be - * ``lambda''). Furthermore, an - * object of type IntergridMap - * is needed; this could in - * principle be generated by the - * function itself from the two - * DoFHandler objects, but since - * it is probably available - * anyway in programs that use - * this function, we shall use it - * instead of re-generating - * it. Finally, the computed - * constraints are entered into a - * variable of type - * ConstraintMatrix; the - * constraints are added, - * i.e. previous contents which - * may have, for example, be - * obtained from hanging nodes, - * are not deleted, so that you - * only need one object of this - * type. + * The basic idea of this function is explained in the + * following. Let us, for convenience, denote by ``parameter grid'' + * the coarser of the two grids, and by ``state grid'' the finer of + * the two. We furthermore assume that the finer grid can be + * obtained by refinement of the coarser one, i.e. the fine grid is + * at least as much refined as the coarse grid at each point of the + * domain. Then, each shape function on the coarse grid can be + * represented as a linear combination of shape functions on the + * fine grid (assuming identical ansatz spaces). Thus, if we + * discretize as usual, using shape functions on the fine grid, we + * can consider the restriction that the parameter variable shall in + * fact be discretized by shape functions on the coarse grid as a + * constraint. These constraints are linear and happen to have the + * form managed by the ``ConstraintMatrix'' class. + * + * The construction of these constraints is done as follows: for + * each of the degrees of freedom (i.e. shape functions) on the + * coarse grid, we compute its representation on the fine grid, + * i.e. how the linear combination of shape functions on the fine + * grid looks like that resembles the shape function on the coarse + * grid. From this information, we can then compute the constraints + * which have to hold if a solution of a linear equation on the fine + * grid shall be representable on the coarse grid. The exact + * algorithm how these constraints can be computed is rather + * complicated and is best understood by reading the source code, + * which contains many comments. + * + * Before explaining the use of this function, we would like to + * state that the total number of degrees of freedom used for the + * discretization is not reduced by the use of this function, + * i.e. even though we discretize one variable on a coarser grid, + * the total number of degrees of freedom is that of the fine + * grid. This seems to be counter-productive, since it does not give + * us a benefit from using a coarser grid. The reason why it may be + * useful to choose this approach nonetheless is three-fold: first, + * as stated above, there might not be enough information to recover + * a parameter on a fine grid, i.e. we chose to discretize it on the + * coarse grid not to save DoFs, but for other reasons. Second, the + * ``ConstraintMatrix'' includes the constraints into the linear + * system of equations, by which constrained nodes become dummy + * nodes; we may therefore exclude them from the linear algebra, for + * example by sorting them to the back of the DoF numbers and simply + * calling the solver for the upper left block of the matrix which + * works on the non-constrained nodes only, thus actually realizing + * the savings in numerical effort from the reduced number of actual + * degrees of freedom. The third reason is that for some or other + * reason we have chosen to use two different grids, it may be + * actually quite difficult to write a function that assembles the + * system matrix for finite element spaces on different grids; using + * the approach of constraints as with this function allows to use + * standard techniques when discretizing on only one grid (the finer + * one) without having to take care of the fact that one or several + * of the variable actually belong to different grids. + * + * The use of this function is as follows: it accepts as parameters + * two DoF Handlers, the first of which refers to the coarse grid + * and the second of which is the fine grid. On both, a finite + * element is represented by the DoF handler objects, which will + * usually have several components, which may belong to different + * finite elements. The second and fourth parameter of this function + * therefore state which variable on the coarse grid shall be used + * to restrict the stated component on the fine grid. Of course, the + * finite elements used for the respective components on the two + * grids need to be the same. An example may clarify this: consider + * the parameter estimation mentioned briefly above; there, on the + * fine grid the whole discretization is done, thus the variables + * are ``u'', ``q'', and the Lagrange multiplier ``lambda'', which + * are discretized using continuous linear, piecewise constant + * discontinuous, and continuous linear elements, respectively. Only + * the parameter ``q'' shall be represented on the coarse grid, thus + * the DoFHandler object on the coarse grid represents only one + * variable, discretized using piecewise constant discontinuous + * elements. Then, the parameter denoting the component on the + * coarse grid would be zero (the only possible choice, since the + * variable on the coarse grid is scalar), and one on the fine grid + * (corresponding to the variable ``q''; zero would be ``u'', two + * would be ``lambda''). Furthermore, an object of type IntergridMap + * is needed; this could in principle be generated by the function + * itself from the two DoFHandler objects, but since it is probably + * available anyway in programs that use this function, we shall use + * it instead of re-generating it. Finally, the computed constraints + * are entered into a variable of type ConstraintMatrix; the + * constraints are added, i.e. previous contents which may have, for + * example, be obtained from hanging nodes, are not deleted, so that + * you only need one object of this type. */ template void @@ -2574,26 +1880,16 @@ namespace DoFTools /** - * This function generates a - * matrix such that when a vector - * of data with as many elements - * as there are degrees of - * freedom of this component on - * the coarse grid is multiplied - * to this matrix, we obtain a - * vector with as many elements - * are there are global degrees - * of freedom on the fine - * grid. All the elements of the - * other components of the finite - * element fields on the fine - * grid are not touched. - * - * The output of this function is - * a compressed format that can - * be given to the @p reinit - * functions of the - * SparsityPattern ad + * This function generates a matrix such that when a vector of data + * with as many elements as there are degrees of freedom of this + * component on the coarse grid is multiplied to this matrix, we + * obtain a vector with as many elements are there are global + * degrees of freedom on the fine grid. All the elements of the + * other components of the finite element fields on the fine grid + * are not touched. + * + * The output of this function is a compressed format that can be + * given to the @p reinit functions of the SparsityPattern ad * SparseMatrix classes. */ template @@ -2606,31 +1902,18 @@ namespace DoFTools std::vector > &transfer_representation); /** - * Create a mapping from degree - * of freedom indices to the - * index of that degree of - * freedom on the boundary. After - * this operation, mapping[dof] - * gives the index of the - * degree of freedom with global - * number @p dof in the list of - * degrees of freedom on the - * boundary. If the degree of - * freedom requested is not on - * the boundary, the value of - * mapping[dof] is - * @p invalid_dof_index. This - * function is mainly used when - * setting up matrices and - * vectors on the boundary from - * the trial functions, which - * have global numbers, while the - * matrices and vectors use - * numbers of the trial functions - * local to the boundary. - * - * Prior content of @p mapping - * is deleted. + * Create a mapping from degree of freedom indices to the index of + * that degree of freedom on the boundary. After this operation, + * mapping[dof] gives the index of the degree of freedom + * with global number @p dof in the list of degrees of freedom on + * the boundary. If the degree of freedom requested is not on the + * boundary, the value of mapping[dof] is @p + * invalid_dof_index. This function is mainly used when setting up + * matrices and vectors on the boundary from the trial functions, + * which have global numbers, while the matrices and vectors use + * numbers of the trial functions local to the boundary. + * + * Prior content of @p mapping is deleted. */ template void @@ -2638,15 +1921,11 @@ namespace DoFTools std::vector &mapping); /** - * Same as the previous function, - * except that only those parts - * of the boundary are considered - * for which the boundary - * indicator is listed in the - * second argument. + * Same as the previous function, except that only those parts of + * the boundary are considered for which the boundary indicator is + * listed in the second argument. * - * See the general doc of this - * class for more information. + * See the general doc of this class for more information. * * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" */ @@ -2657,33 +1936,22 @@ namespace DoFTools std::vector &mapping); /** - * Return a list of support - * points (see this - * @ref GlossSupport "glossary entry") - * for all the degrees of - * freedom handled by this DoF - * handler object. This function, - * of course, only works if the - * finite element object used by - * the DoF handler object - * actually provides support - * points, i.e. no edge elements - * or the like. Otherwise, an - * exception is thrown. - * - * @pre The given array must have a - * length of as many elements as + * Return a list of support points (see this @ref GlossSupport + * "glossary entry") for all the degrees of freedom handled by this + * DoF handler object. This function, of course, only works if the + * finite element object used by the DoF handler object actually + * provides support points, i.e. no edge elements or the + * like. Otherwise, an exception is thrown. + * + * @pre The given array must have a length of as many elements as * there are degrees of freedom. * - * @note The precondition to this function - * that the output argument needs to have - * size equal to the total number of degrees - * of freedom makes this function - * unsuitable for the case that the given - * DoFHandler object derives from a - * parallel::distributed::Triangulation object. - * Consequently, this function will produce an - * error if called with such a DoFHandler. + * @note The precondition to this function that the output argument + * needs to have size equal to the total number of degrees of + * freedom makes this function unsuitable for the case that the + * given DoFHandler object derives from a + * parallel::distributed::Triangulation object. Consequently, this + * function will produce an error if called with such a DoFHandler. */ template void @@ -2745,33 +2013,20 @@ namespace DoFTools /** - * This is the opposite function - * to the one above. It generates - * a map where the keys are the - * support points of the degrees - * of freedom, while the values - * are the DoF indices. For a definition - * of support points, see this - * @ref GlossSupport "glossary entry". - * - * Since there is no natural - * order in the space of points - * (except for the 1d case), you - * have to provide a map with an - * explicitly specified - * comparator object. This - * function is therefore - * templatized on the comparator - * object. Previous content of - * the map object is deleted in - * this function. - * - * Just as with the function - * above, it is assumed that the - * finite element in use here - * actually supports the notion - * of support points of all its - * components. + * This is the opposite function to the one above. It generates a + * map where the keys are the support points of the degrees of + * freedom, while the values are the DoF indices. For a definition + * of support points, see this @ref GlossSupport "glossary entry". + * + * Since there is no natural order in the space of points (except + * for the 1d case), you have to provide a map with an explicitly + * specified comparator object. This function is therefore + * templatized on the comparator object. Previous content of the map + * object is deleted in this function. + * + * Just as with the function above, it is assumed that the finite + * element in use here actually supports the notion of support + * points of all its components. */ template void @@ -2780,19 +2035,13 @@ namespace DoFTools std::map, types::global_dof_index, Comp> &point_to_index_map); /** - * Map a coupling table from the - * user friendly organization by - * components to the organization - * by blocks. Specializations of - * this function for DoFHandler - * and hp::DoFHandler are - * required due to the different - * results of their finite - * element access. + * Map a coupling table from the user friendly organization by + * components to the organization by blocks. Specializations of this + * function for DoFHandler and hp::DoFHandler are required due to + * the different results of their finite element access. * - * The return vector will be - * initialized to the correct - * length inside this function. + * The return vector will be initialized to the correct length + * inside this function. */ template void @@ -2801,16 +2050,14 @@ namespace DoFTools std::vector > &tables_by_block); /** - * Make a constraint matrix for the - * constraints that result from zero - * boundary values on the given boundary indicator. + * Make a constraint matrix for the constraints that result from + * zero boundary values on the given boundary indicator. * - * This function constrains all - * degrees of freedom on the given part of the - * boundary. + * This function constrains all degrees of freedom on the given part + * of the boundary. * - * A variant of this function with different arguments is used - * in step-36. + * A variant of this function with different arguments is used in + * step-36. * * @param dof The DoFHandler to work on. * @param boundary_indicator The indicator of that part of the boundary @@ -2867,19 +2114,13 @@ namespace DoFTools /** - * Map a coupling table from the - * user friendly organization by - * components to the organization - * by blocks. Specializations of - * this function for DoFHandler - * and hp::DoFHandler are - * required due to the different - * results of their finite - * element access. + * Map a coupling table from the user friendly organization by + * components to the organization by blocks. Specializations of this + * function for DoFHandler and hp::DoFHandler are required due to + * the different results of their finite element access. * - * The return vector will be - * initialized to the correct - * length inside this function. + * The return vector will be initialized to the correct length + * inside this function. */ template void @@ -2888,12 +2129,10 @@ namespace DoFTools std::vector > &tables_by_block); /** - * Given a finite element and a table how - * the vector components of it couple - * with each other, compute and return a - * table that describes how the - * individual shape functions couple with - * each other. + * Given a finite element and a table how the vector components of + * it couple with each other, compute and return a table that + * describes how the individual shape functions couple with each + * other. */ template Table<2,Coupling> @@ -2901,40 +2140,45 @@ namespace DoFTools const Table<2,Coupling> &component_couplings); /** - * Same function as above for a - * collection of finite elements, + * Same function as above for a collection of finite elements, * returning a collection of tables. * - * The function currently treats - * DoFTools::Couplings::nonzero the same - * as DoFTools::Couplings::always . + * The function currently treats DoFTools::Couplings::nonzero the + * same as DoFTools::Couplings::always . */ template std::vector > dof_couplings_from_component_couplings (const hp::FECollection &fe, const Table<2,Coupling> &component_couplings); /** - * Exception + * @todo Write description + * * @ingroup Exceptions */ DeclException0 (ExcFiniteElementsDontMatch); /** - * Exception + * @todo Write description + * * @ingroup Exceptions */ DeclException0 (ExcGridNotCoarser); /** + * @todo Write description + * * Exception * @ingroup Exceptions */ DeclException0 (ExcGridsDontMatch); /** - * Exception + * The ::DoFHandler or hp::DoFHandler was not initialized with a + * finite element. Please call DoFHandler::distribute_dofs() etc. first. + * * @ingroup Exceptions */ DeclException0 (ExcNoFESelected); /** - * Exception + * @todo Write description + * * @ingroup Exceptions */ DeclException0 (ExcInvalidBoundaryIndicator);