From: heister Date: Fri, 1 Mar 2013 18:53:04 +0000 (+0000) Subject: rewrap comments X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c5926c20429b5c82619aec7e9a7429d25e293d14;p=dealii-svn.git rewrap comments git-svn-id: https://svn.dealii.org/trunk@28703 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/include/deal.II/fe/fe_tools.h b/deal.II/include/deal.II/fe/fe_tools.h index ea93077ced..e15b23cfab 100644 --- a/deal.II/include/deal.II/fe/fe_tools.h +++ b/deal.II/include/deal.II/fe/fe_tools.h @@ -73,19 +73,12 @@ namespace PETScWrappers namespace FETools { /** - * A base class for factory - * objects creating finite - * elements of a given - * degree. Derived classes are - * called whenever one wants to - * have a transparent way to - * create a finite element - * object. - * - * This class is used in the - * FETools::get_fe_from_name() - * and FETools::add_fe_name() - * functions. + * A base class for factory objects creating finite elements of a given + * degree. Derived classes are called whenever one wants to have a + * transparent way to create a finite element object. + * + * This class is used in the FETools::get_fe_from_name() and + * FETools::add_fe_name() functions. * * @author Guido Kanschat, 2006 */ @@ -94,42 +87,32 @@ namespace FETools { public: /** - * Create a FiniteElement and - * return a pointer to it. + * Create a FiniteElement and return a pointer to it. */ virtual FiniteElement * get (const unsigned int degree) const = 0; /** - * Create a FiniteElement from a - * quadrature formula (currently only - * implemented for FE_Q) and return a - * pointer to it. + * Create a FiniteElement from a quadrature formula (currently only + * implemented for FE_Q) and return a pointer to it. */ virtual FiniteElement * get (const Quadrature<1> &quad) const = 0; /** - * Virtual destructor doing - * nothing but making the - * compiler happy. + * Virtual destructor doing nothing but making the compiler happy. */ virtual ~FEFactoryBase(); }; /** - * A concrete class for factory - * objects creating finite - * elements of a given degree. - * - * The class's get() function - * generates a finite element - * object of the type given as - * template argument, and with - * the degree (however the finite - * element class wishes to - * interpret this number) given - * as argument to get(). + * A concrete class for factory objects creating finite elements of a given + * degree. + * + * The class's get() function generates a finite element object of the type + * given as template argument, and with the degree (however the finite + * element class wishes to interpret this number) given as argument to + * get(). * * @author Guido Kanschat, 2006 */ @@ -138,46 +121,33 @@ namespace FETools { public: /** - * Create a FiniteElement and - * return a pointer to it. + * Create a FiniteElement and return a pointer to it. */ virtual FiniteElement * get (const unsigned int degree) const; /** - * Create a FiniteElement from a - * quadrature formula (currently only - * implemented for FE_Q) and return a - * pointer to it. + * Create a FiniteElement from a quadrature formula (currently only + * implemented for FE_Q) and return a pointer to it. */ virtual FiniteElement * get (const Quadrature<1> &quad) const; }; /** - * @warning In most cases, you - * will probably want to use + * @warning In most cases, you will probably want to use * compute_base_renumbering(). * - * Compute the vector required to - * renumber the dofs of a cell by - * component. Furthermore, - * compute the vector storing the - * start indices of each - * component in the local block - * vector. - * - * The second vector is organized - * such that there is a vector - * for each base element - * containing the start index for - * each component served by this - * base element. - * - * While the first vector is - * checked to have the correct - * size, the second one is - * reinitialized for convenience. + * Compute the vector required to renumber the dofs of a cell by + * component. Furthermore, compute the vector storing the start indices of + * each component in the local block vector. + * + * The second vector is organized such that there is a vector for each base + * element containing the start index for each component served by this base + * element. + * + * While the first vector is checked to have the correct size, the second + * one is reinitialized for convenience. */ template void compute_component_wise( @@ -186,22 +156,15 @@ namespace FETools std::vector > &start_indices); /** - * Compute the vector required to - * renumber the dofs of a cell by - * block. Furthermore, compute - * the vector storing either the - * start indices or the size of - * each local block vector. - * - * If the @p bool parameter is - * true, @p block_data is filled - * with the start indices of each - * local block. If it is false, - * then the block sizes are + * Compute the vector required to renumber the dofs of a cell by + * block. Furthermore, compute the vector storing either the start indices + * or the size of each local block vector. + * + * If the @p bool parameter is true, @p block_data is filled with the start + * indices of each local block. If it is false, then the block sizes are * returned. * - * @todo Which way does this - * vector map the numbers? + * @todo Which way does this vector map the numbers? */ template void compute_block_renumbering ( @@ -215,18 +178,13 @@ namespace FETools * @{ */ /** - * Gives the interpolation matrix - * that interpolates a @p fe1- - * function to a @p fe2-function on - * each cell. The interpolation_matrix - * needs to be of size - * (fe2.dofs_per_cell, fe1.dofs_per_cell). - * - * Note, that if the finite element - * space @p fe1 is a subset of - * the finite element space - * @p fe2 then the @p interpolation_matrix - * is an embedding matrix. + * Gives the interpolation matrix that interpolates a @p fe1- function to a + * @p fe2-function on each cell. The interpolation_matrix needs to be of + * size (fe2.dofs_per_cell, fe1.dofs_per_cell). + * + * Note, that if the finite element space @p fe1 is a subset of the finite + * element space @p fe2 then the @p interpolation_matrix is an embedding + * matrix. */ template void @@ -235,22 +193,15 @@ namespace FETools FullMatrix &interpolation_matrix); /** - * Gives the interpolation matrix - * that interpolates a @p fe1- - * function to a @p fe2-function, and - * interpolates this to a second - * @p fe1-function on - * each cell. The interpolation_matrix - * needs to be of size + * Gives the interpolation matrix that interpolates a @p fe1- function to a + * @p fe2-function, and interpolates this to a second @p fe1-function on + * each cell. The interpolation_matrix needs to be of size * (fe1.dofs_per_cell, fe1.dofs_per_cell). * - * Note, that this function only - * makes sense if the finite element - * space due to @p fe1 is not a subset of - * the finite element space due to - * @p fe2, as if it were a subset then - * the @p interpolation_matrix would be - * only the unit matrix. + * Note, that this function only makes sense if the finite element space due + * to @p fe1 is not a subset of the finite element space due to @p fe2, as + * if it were a subset then the @p interpolation_matrix would be only the + * unit matrix. */ template void @@ -259,21 +210,14 @@ namespace FETools FullMatrix &interpolation_matrix); /** - * Gives the unit matrix minus the - * back interpolation matrix. - * The @p difference_matrix - * needs to be of size - * (fe1.dofs_per_cell, fe1.dofs_per_cell). + * Gives the unit matrix minus the back interpolation matrix. The @p + * difference_matrix needs to be of size (fe1.dofs_per_cell, + * fe1.dofs_per_cell). * - * This function gives - * the matrix that transforms a - * @p fe1 function $z$ to $z-I_hz$ - * where $I_h$ denotes the interpolation - * operator from the @p fe1 space to - * the @p fe2 space. This matrix hence - * is useful to evaluate - * error-representations where $z$ - * denotes the dual solution. + * This function gives the matrix that transforms a @p fe1 function $z$ to + * $z-I_hz$ where $I_h$ denotes the interpolation operator from the @p fe1 + * space to the @p fe2 space. This matrix hence is useful to evaluate + * error-representations where $z$ denotes the dual solution. */ template void @@ -282,9 +226,7 @@ namespace FETools FullMatrix &difference_matrix); /** - * Compute the local - * $L^2$-projection matrix from - * fe1 to fe2. + * Compute the local $L^2$-projection matrix from fe1 to fe2. */ template void get_projection_matrix(const FiniteElement &fe1, @@ -292,123 +234,70 @@ namespace FETools FullMatrix &matrix); /** - * Compute the matrix of nodal - * values of a finite element - * applied to all its shape - * functions. - * - * This function is supposed to - * help building finite elements - * from polynomial spaces and - * should be called inside the - * constructor of an - * element. Applied to a - * completely initialized finite - * element, the result should be - * the unit matrix by definition - * of the node values. - * - * Using this matrix allows the - * construction of the basis of - * shape functions in two steps. + * Compute the matrix of nodal values of a finite element applied to all its + * shape functions. + * + * This function is supposed to help building finite elements from + * polynomial spaces and should be called inside the constructor of an + * element. Applied to a completely initialized finite element, the result + * should be the unit matrix by definition of the node values. + * + * Using this matrix allows the construction of the basis of shape functions + * in two steps. + * *
    * - *
  1. Define the space of shape - * functions using an arbitrary - * basis wj and - * compute the matrix M of - * node functionals - * Ni applied - * to these basis functions. - * - *
  2. Compute the basis - * vj of the - * finite element shape function - * space by applying - * M-1 to the - * basis wj. + *
  3. Define the space of shape functions using an arbitrary basis + * wj and compute the matrix M of node functionals + * Ni applied to these basis functions. + * + *
  4. Compute the basis vj of the finite element shape + * function space by applying M-1 to the basis + * wj. + * *
* - * @note The FiniteElement must - * provide generalized support - * points and and interpolation - * functions. + * @note The FiniteElement must provide generalized support points and and + * interpolation functions. */ template void compute_node_matrix(FullMatrix &M, const FiniteElement &fe); /** - * For all possible (isotropic - * and anisotropic) refinement - * cases compute the embedding - * matrices from a coarse cell to - * the child cells. Each column - * of the resulting matrices - * contains the representation of - * a coarse grid basis functon by - * the fine grid basis; the - * matrices are split such that - * there is one matrix for every - * child. - * - * This function computes the - * coarse grid function in a - * sufficiently large number of - * quadrature points and fits the - * fine grid functions using - * least squares - * approximation. Therefore, the - * use of this function is - * restricted to the case that - * the finite element spaces are - * actually nested. - * - * Note, that - * matrices[refinement_case-1][child] - * includes the embedding (or prolongation) - * matrix of child - * child for the - * RefinementCase - * refinement_case. Here, - * we use - * refinement_case-1 - * instead of - * refinement_case - * as for - * RefinementCase::no_refinement(=0) - * there are no prolongation - * matrices available. - * - * Typically this function is - * called by the various - * implementations of - * FiniteElement classes in order - * to fill the respective - * FiniteElement::prolongation + * For all possible (isotropic and anisotropic) refinement cases compute the + * embedding matrices from a coarse cell to the child cells. Each column of + * the resulting matrices contains the representation of a coarse grid basis + * functon by the fine grid basis; the matrices are split such that there is + * one matrix for every child. + * + * This function computes the coarse grid function in a sufficiently large + * number of quadrature points and fits the fine grid functions using least + * squares approximation. Therefore, the use of this function is restricted + * to the case that the finite element spaces are actually nested. + * + * Note, that matrices[refinement_case-1][child] includes the + * embedding (or prolongation) matrix of child child for the + * RefinementCase refinement_case. Here, we use + * refinement_case-1 instead of refinement_case as + * for RefinementCase::no_refinement(=0) there are no prolongation matrices + * available. + * + * Typically this function is called by the various implementations of + * FiniteElement classes in order to fill the respective + * FiniteElement::prolongation matrices. + * + * @param fe The finite element class for which we compute the embedding * matrices. * - * @param fe The finite element - * class for which we compute the - * embedding matrices. - * - * @param matrices A reference to - * RefinementCase::isotropic_refinement - * vectors of FullMatrix - * objects. Each vector - * corresponds to one - * RefinementCase @p - * refinement_case and is of the - * vector size - * GeometryInfo::n_children(refinement_case). This - * is the format used in - * FiniteElement, where we want - * to use this function mostly. - * - * @param isotropic_only Set - * to true if you only - * want to compute matrices for - * isotropic refinement. + * @param matrices A reference to RefinementCase::isotropic_refinement + * vectors of FullMatrix objects. Each vector corresponds to one + * RefinementCase @p refinement_case and is of the vector size + * GeometryInfo::n_children(refinement_case). This is the format used + * in FiniteElement, where we want to use this function mostly. + * + * @param isotropic_only Set to true if you only want to + * compute matrices for isotropic refinement. */ template void compute_embedding_matrices(const FiniteElement &fe, @@ -416,31 +305,17 @@ namespace FETools const bool isotropic_only = false); /** - * Compute the embedding matrices - * on faces needed for constraint - * matrices. + * Compute the embedding matrices on faces needed for constraint matrices. + * + * @param fe The finite element for which to compute these matrices. @param + * matrices An array of GeometryInfo::subfaces_per_face = + * 2dim-1 FullMatrix objects,holding the embedding matrix for + * each subface. @param face_coarse The number of the face on the coarse + * side of the face for which this is computed. @param face_fine The number + * of the face on the refined side of the face for which this is computed. * - * @param fe The finite element - * for which to compute these - * matrices. @param matrices An - * array of - * GeometryInfo::subfaces_per_face - * = 2dim-1 - * FullMatrix objects,holding the - * embedding matrix for each - * subface. @param face_coarse - * The number of the face on the - * coarse side of the face for - * which this is computed. - * @param face_fine The number of - * the face on the refined side - * of the face for which this is - * computed. - * - * @warning This function will be - * used in computing constraint - * matrices. It is not - * sufficiently tested yet. + * @warning This function will be used in computing constraint matrices. It + * is not sufficiently tested yet. */ template void @@ -450,57 +325,31 @@ namespace FETools const unsigned int face_fine); /** - * For all possible (isotropic - * and anisotropic) refinement - * cases compute the - * L2-projection - * matrices from the children to - * a coarse cell. - * - * Note, that - * matrices[refinement_case-1][child] - * includes the projection (or restriction) - * matrix of child - * child for the - * RefinementCase - * refinement_case. Here, - * we use - * refinement_case-1 - * instead of - * refinement_case - * as for - * RefinementCase::no_refinement(=0) - * there are no projection - * matrices available. - * - * Typically this function is - * called by the various - * implementations of - * FiniteElement classes in order - * to fill the respective - * FiniteElement::restriction - * matrices. + * For all possible (isotropic and anisotropic) refinement cases compute the + * L2-projection matrices from the children to a coarse + * cell. * - * @arg fe The finite element - * class for which we compute the - * projection matrices. @arg - * matrices A reference to - * RefinementCase::isotropic_refinement - * vectors of FullMatrix - * objects. Each vector - * corresponds to one - * RefinementCase @p - * refinement_case and is of the - * vector size - * GeometryInfo::n_children(refinement_case). This - * is the format used in - * FiniteElement, where we want - * to use this function mostly. - * - * @arg isotropic_only Set - * to true if you only - * want to compute matrices for - * isotropic refinement. + * Note, that matrices[refinement_case-1][child] includes the + * projection (or restriction) matrix of child child for the + * RefinementCase refinement_case. Here, we use + * refinement_case-1 instead of refinement_case as + * for RefinementCase::no_refinement(=0) there are no projection matrices + * available. + * + * Typically this function is called by the various implementations of + * FiniteElement classes in order to fill the respective + * FiniteElement::restriction matrices. + * + * @arg fe The finite element class for which we compute the projection + * matrices. @arg matrices A reference to + * RefinementCase::isotropic_refinement vectors of FullMatrix + * objects. Each vector corresponds to one RefinementCase @p refinement_case + * and is of the vector size + * GeometryInfo::n_children(refinement_case). This is the + * format used in FiniteElement, where we want to use this function mostly. + * + * @arg isotropic_only Set to true if you only want to compute + * matrices for isotropic refinement. */ template void compute_projection_matrices( @@ -509,165 +358,89 @@ namespace FETools const bool isotropic_only = false); /** - * Projects scalar data defined in - * quadrature points to a finite element + * Projects scalar data defined in quadrature points to a finite element * space on a single cell. * - * What this function does is the - * following: assume that there is scalar - * data uq, 0 <= q < - * Q:=quadrature.size() - * defined at the quadrature points of a - * cell, with the points defined by the - * given rhs_quadrature - * object. We may then want to ask for - * that finite element function (on a - * single cell) vh in - * the finite-dimensional space defined - * by the given FE object that is the - * projection of u in the - * following sense: - * - * Usually, the projection - * vh is that - * function that satisfies - * (vh,w)=(u,w) for - * all discrete test functions - * w. In the present case, we - * can't evaluate the right hand side, - * since u is only defined in - * the quadrature points given by - * rhs_quadrature, so we replace - * it by a quadrature - * approximation. Likewise, the left hand - * side is approximated using the - * lhs_quadrature object; if - * this quadrature object is chosen - * appropriately, then the integration of - * the left hand side can be done - * exactly, without any - * approximation. The use of different - * quadrature objects is necessary if the - * quadrature object for the right hand - * side has too few quadrature points -- - * for example, if data q is - * only defined at the cell center, then - * the corresponding one-point quadrature - * formula is obviously insufficient to - * approximate the scalar product on the - * left hand side by a definite form. - * - * After these quadrature approximations, - * we end up with a nodal representation - * Vh of - * vh that satisfies - * the following system of linear - * equations: M Vh = Q - * U, where - * Mij=(phi_i,phi_j) - * is the mass matrix approximated by - * lhs_quadrature, and - * Q is the matrix - * Qiq=phii(xq) - * wq where - * wq are quadrature - * weights; U is the vector of - * quadrature point data - * uq. - * - * In order to then get the nodal - * representation Vh - * of the projection of U, one - * computes Vh = X U, - * X=M-1 Q. The purpose - * of this function is to compute the - * matrix X and return it - * through the last argument of this + * What this function does is the following: assume that there is scalar + * data uq, 0 <= q < Q:=quadrature.size() defined at the + * quadrature points of a cell, with the points defined by the given + * rhs_quadrature object. We may then want to ask for that finite + * element function (on a single cell) vh in the + * finite-dimensional space defined by the given FE object that is the + * projection of u in the following sense: + * + * Usually, the projection vh is that function that + * satisfies (vh,w)=(u,w) for all discrete test + * functions w. In the present case, we can't evaluate the right + * hand side, since u is only defined in the quadrature points + * given by rhs_quadrature, so we replace it by a quadrature + * approximation. Likewise, the left hand side is approximated using the + * lhs_quadrature object; if this quadrature object is chosen + * appropriately, then the integration of the left hand side can be done + * exactly, without any approximation. The use of different quadrature + * objects is necessary if the quadrature object for the right hand side has + * too few quadrature points -- for example, if data q is only + * defined at the cell center, then the corresponding one-point quadrature + * formula is obviously insufficient to approximate the scalar product on + * the left hand side by a definite form. + * + * After these quadrature approximations, we end up with a nodal + * representation Vh of vh that + * satisfies the following system of linear equations: M Vh = + * Q U, where Mij=(phi_i,phi_j) is the mass matrix + * approximated by lhs_quadrature, and Q is the matrix + * Qiq=phii(xq) wq + * where wq are quadrature weights; U is the + * vector of quadrature point data uq. + * + * In order to then get the nodal representation Vh of + * the projection of U, one computes Vh = X U, + * X=M-1 Q. The purpose of this function is to compute the + * matrix X and return it through the last argument of this * function. * - * Note that this function presently only - * supports scalar data. An extension of - * the mass matrix is of course trivial, - * but one has to define the order of - * data in the vector U if it - * contains vector valued data in all + * Note that this function presently only supports scalar data. An extension + * of the mass matrix is of course trivial, but one has to define the order + * of data in the vector U if it contains vector valued data in all * quadrature points. * - * A use for this function is described - * in the introduction to the step-18 + * A use for this function is described in the introduction to the step-18 * example program. * - * The opposite of this function, - * interpolation of a finite element - * function onto quadrature points is - * essentially what the - * FEValues::get_function_values - * functions do; to make things a little - * simpler, the + * The opposite of this function, interpolation of a finite element function + * onto quadrature points is essentially what the + * FEValues::get_function_values functions do; to make things a + * little simpler, the * FETools::compute_interpolation_to_quadrature_points_matrix * provides the matrix form of this. * - * Note that this function works - * on a single cell, rather than - * an entire triangulation. In - * effect, it therefore doesn't - * matter if you use a continuous - * or discontinuous version of - * the finite element. - * - * It is worth noting that there - * are a few confusing cases of - * this function. The first one - * is that it really only makes - * sense to project onto a finite - * element that has at most as - * many degrees of freedom per - * cell as there are quadrature - * points; the projection of N - * quadrature point data into a - * space with M>N unknowns is - * well-defined, but often yields - * funny and non-intuitive - * results. Secondly, one would - * think that if the quadrature - * point data is defined in the - * support points of the finite - * element, i.e. the quadrature - * points of - * ths_quadrature equal - * fe.get_unit_support_points(), - * then the projection should be - * the identity, i.e. each degree - * of freedom of the finite - * element equals the value of - * the given data in the support - * point of the corresponding - * shape function. However, this - * is not generally the case: - * while the matrix Q in - * that case is the identity - * matrix, the mass matrix - * M is not equal to the - * identity matrix, except for - * the special case that the - * quadrature formula - * lhs_quadrature also - * has its quadrature points in - * the support points of the - * finite element. - * - * Finally, this function only defines a - * cell wise projection, while one - * frequently wants to apply it to all - * cells in a triangulation. However, if - * it is applied to one cell after the - * other, the results from later cells - * may overwrite nodal values computed - * already from previous cells if degrees - * of freedom live on the interfaces - * between cells. The function is - * therefore most useful for - * discontinuous elements. + * Note that this function works on a single cell, rather than an entire + * triangulation. In effect, it therefore doesn't matter if you use a + * continuous or discontinuous version of the finite element. + * + * It is worth noting that there are a few confusing cases of this + * function. The first one is that it really only makes sense to project + * onto a finite element that has at most as many degrees of freedom per + * cell as there are quadrature points; the projection of N quadrature point + * data into a space with M>N unknowns is well-defined, but often yields + * funny and non-intuitive results. Secondly, one would think that if the + * quadrature point data is defined in the support points of the finite + * element, i.e. the quadrature points of ths_quadrature equal + * fe.get_unit_support_points(), then the projection should be the + * identity, i.e. each degree of freedom of the finite element equals the + * value of the given data in the support point of the corresponding shape + * function. However, this is not generally the case: while the matrix + * Q in that case is the identity matrix, the mass matrix + * M is not equal to the identity matrix, except for the special + * case that the quadrature formula lhs_quadrature also has its + * quadrature points in the support points of the finite element. + * + * Finally, this function only defines a cell wise projection, while one + * frequently wants to apply it to all cells in a triangulation. However, if + * it is applied to one cell after the other, the results from later cells + * may overwrite nodal values computed already from previous cells if + * degrees of freedom live on the interfaces between cells. The function is + * therefore most useful for discontinuous elements. */ template void @@ -677,15 +450,11 @@ namespace FETools FullMatrix &X); /** - * Given a (scalar) local finite element - * function, compute the matrix that maps - * the vector of nodal values onto the - * vector of values of this function at - * quadrature points as given by the - * second argument. In a sense, this - * function does the opposite of the - * FETools::compute_projection_from_quadrature_points_matrix - * function. + * Given a (scalar) local finite element function, compute the matrix that + * maps the vector of nodal values onto the vector of values of this + * function at quadrature points as given by the second argument. In a + * sense, this function does the opposite of the + * FETools::compute_projection_from_quadrature_points_matrix function. */ template void @@ -694,30 +463,17 @@ namespace FETools FullMatrix &I_q); /** - * Computes the projection of tensorial - * (first-order tensor) - * data stored at the quadrature points - * @p vector_of_tensors_at_qp - * to data @p vector_of_tensors_at_nodes - * at the support points of the cell. - * The data in - * @p vector_of_tensors_at_qp - * is ordered sequentially following the - * quadrature point numbering. - * The size of - * @p vector_of_tensors_at_qp - * must correspond to the number of columns - * of @p projection_matrix. - * The size of @p vector_of_tensors_at_nodes - * must correspond to the number of rows of - * @p vector_of_tensors_at_nodes . - * The projection matrix - * @p projection_matrix desribes the - * projection of scalar data from the - * quadrature points and can be obtained - * from the - * FETools::compute_projection_from_quadrature_points_matrix - * function. + * Computes the projection of tensorial (first-order tensor) data stored at + * the quadrature points @p vector_of_tensors_at_qp to data @p + * vector_of_tensors_at_nodes at the support points of the cell. The data + * in @p vector_of_tensors_at_qp is ordered sequentially following the + * quadrature point numbering. The size of @p vector_of_tensors_at_qp must + * correspond to the number of columns of @p projection_matrix. The size of + * @p vector_of_tensors_at_nodes must correspond to the number of rows of @p + * vector_of_tensors_at_nodes . The projection matrix @p projection_matrix + * desribes the projection of scalar data from the quadrature points and can + * be obtained from the + * FETools::compute_projection_from_quadrature_points_matrix function. */ template void @@ -729,8 +485,7 @@ namespace FETools /** - * same as last function but for a - * @p SymmetricTensor . + * same as last function but for a @p SymmetricTensor . */ template void @@ -744,14 +499,12 @@ namespace FETools /** * This method implements the - * FETools::compute_projection_from_quadrature_points_matrix - * method for faces of a mesh. - * The matrix that it returns, X, is face specific - * and its size is fe.dofs_per_cell by - * rhs_quadrature.size(). - * The dimension, dim must be larger than 1 for this class, - * since Quadrature objects are required. See the - * documentation on the Quadrature class for more information. + * FETools::compute_projection_from_quadrature_points_matrix method for + * faces of a mesh. The matrix that it returns, X, is face specific and its + * size is fe.dofs_per_cell by rhs_quadrature.size(). The dimension, dim + * must be larger than 1 for this class, since Quadrature objects are + * required. See the documentation on the Quadrature class for more + * information. */ template void @@ -770,61 +523,32 @@ namespace FETools */ //@{ /** - * Gives the interpolation of a the - * @p dof1-function @p u1 to a - * @p dof2-function @p u2. @p dof1 and - * @p dof2 need to be DoFHandlers - * based on the same triangulation. - * - * If the elements @p fe1 and @p fe2 - * are either both continuous or - * both discontinuous then this - * interpolation is the usual point - * interpolation. The same is true - * if @p fe1 is a continuous and - * @p fe2 is a discontinuous finite - * element. For the case that @p fe1 - * is a discontinuous and @p fe2 is - * a continuous finite element - * there is no point interpolation - * defined at the discontinuities. - * Therefore the meanvalue is taken - * at the DoF values on the - * discontinuities. - * - * Note that for continuous - * elements on grids with hanging - * nodes (i.e. locally refined - * grids) this function does not - * give the expected output. - * Indeed, the resulting output - * vector does not necessarily - * respect continuity - * requirements at hanging nodes: - * if, for example, you are - * interpolating a Q2 field to a - * Q1 field, then at hanging - * nodes the output field will - * have the function value of the - * input field, which however is - * not usually the mean value of - * the two adjacent nodes. It is - * thus not part of the Q1 - * function space on the whole - * triangulation, although it is - * of course Q1 on each cell. - * - * For this case (continuous - * elements on grids with hanging - * nodes), please use the - * @p interpolate function with - * an additional - * @p ConstraintMatrix argument, - * see below, or make the field - * conforming yourself by calling - * the @p distribute function of - * your hanging node constraints - * object. + * Gives the interpolation of a the @p dof1-function @p u1 to a @p + * dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers based on + * the same triangulation. + * + * If the elements @p fe1 and @p fe2 are either both continuous or both + * discontinuous then this interpolation is the usual point + * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a + * discontinuous finite element. For the case that @p fe1 is a discontinuous + * and @p fe2 is a continuous finite element there is no point interpolation + * defined at the discontinuities. Therefore the meanvalue is taken at the + * DoF values on the discontinuities. + * + * Note that for continuous elements on grids with hanging nodes + * (i.e. locally refined grids) this function does not give the expected + * output. Indeed, the resulting output vector does not necessarily respect + * continuity requirements at hanging nodes: if, for example, you are + * interpolating a Q2 field to a Q1 field, then at hanging nodes the output + * field will have the function value of the input field, which however is + * not usually the mean value of the two adjacent nodes. It is thus not part + * of the Q1 function space on the whole triangulation, although it is of + * course Q1 on each cell. + * + * For this case (continuous elements on grids with hanging nodes), please + * use the @p interpolate function with an additional @p ConstraintMatrix + * argument, see below, or make the field conforming yourself by calling the + * @p distribute function of your hanging node constraints object. */ template class DH1, @@ -837,37 +561,20 @@ namespace FETools OutVector &u2); /** - * Gives the interpolation of a - * the @p dof1-function @p u1 to - * a @p dof2-function @p u2. @p - * dof1 and @p dof2 need to be - * DoFHandlers (or - * hp::DoFHandlers) based on the - * same triangulation. @p - * constraints is a hanging node - * constraints object - * corresponding to @p dof2. This - * object is particular important - * when interpolating onto - * continuous elements on grids - * with hanging nodes (locally - * refined grids). - * - * If the elements @p fe1 and @p fe2 - * are either both continuous or - * both discontinuous then this - * interpolation is the usual point - * interpolation. The same is true - * if @p fe1 is a continuous and - * @p fe2 is a discontinuous finite - * element. For the case that @p fe1 - * is a discontinuous and @p fe2 is - * a continuous finite element - * there is no point interpolation - * defined at the discontinuities. - * Therefore the meanvalue is taken - * at the DoF values on the - * discontinuities. + * Gives the interpolation of a the @p dof1-function @p u1 to a @p + * dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers (or + * hp::DoFHandlers) based on the same triangulation. @p constraints is a + * hanging node constraints object corresponding to @p dof2. This object is + * particular important when interpolating onto continuous elements on grids + * with hanging nodes (locally refined grids). + * + * If the elements @p fe1 and @p fe2 are either both continuous or both + * discontinuous then this interpolation is the usual point + * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a + * discontinuous finite element. For the case that @p fe1 is a discontinuous + * and @p fe2 is a continuous finite element there is no point interpolation + * defined at the discontinuities. Therefore the meanvalue is taken at the + * DoF values on the discontinuities. */ template class DH1, @@ -880,30 +587,17 @@ namespace FETools OutVector &u2); /** - * Gives the interpolation of the - * @p fe1-function @p u1 to a - * @p fe2-function, and - * interpolates this to a second - * @p fe1-function named - * @p u1_interpolated. - * - * Note, that this function does - * not work on continuous - * elements at hanging nodes. For - * that case use the - * @p back_interpolate function, - * below, that takes an - * additional - * @p ConstraintMatrix object. - * - * Furthermore note, that for the - * specific case when the finite - * element space corresponding to - * @p fe1 is a subset of the - * finite element space - * corresponding to @p fe2, this - * function is simply an identity - * mapping. + * Gives the interpolation of the @p fe1-function @p u1 to a @p + * fe2-function, and interpolates this to a second @p fe1-function named @p + * u1_interpolated. + * + * Note, that this function does not work on continuous elements at hanging + * nodes. For that case use the @p back_interpolate function, below, that + * takes an additional @p ConstraintMatrix object. + * + * Furthermore note, that for the specific case when the finite element + * space corresponding to @p fe1 is a subset of the finite element space + * corresponding to @p fe2, this function is simply an identity mapping. */ template void back_interpolate (const DoFHandler &dof1, @@ -912,10 +606,8 @@ namespace FETools OutVector &u1_interpolated); /** - * Same as last function, except - * that the dof handler objects - * might be of type - * @p hp::DoFHandler. + * Same as last function, except that the dof handler objects might be of + * type @p hp::DoFHandler. */ template class DH, @@ -926,31 +618,17 @@ namespace FETools OutVector &u1_interpolated); /** - * Gives the interpolation of the - * @p dof1-function @p u1 to a - * @p dof2-function, and - * interpolates this to a second - * @p dof1-function named - * @p u1_interpolated. - * @p constraints1 and - * @p constraints2 are the - * hanging node constraints - * corresponding to @p dof1 and - * @p dof2, respectively. These - * objects are particular - * important when continuous - * elements on grids with hanging - * nodes (locally refined grids) - * are involved. - * - * Furthermore note, that for the - * specific case when the finite - * element space corresponding to - * @p dof1 is a subset of the - * finite element space - * corresponding to @p dof2, this - * function is simply an identity - * mapping. + * Gives the interpolation of the @p dof1-function @p u1 to a @p + * dof2-function, and interpolates this to a second @p dof1-function named + * @p u1_interpolated. @p constraints1 and @p constraints2 are the hanging + * node constraints corresponding to @p dof1 and @p dof2, + * respectively. These objects are particular important when continuous + * elements on grids with hanging nodes (locally refined grids) are + * involved. + * + * Furthermore note, that for the specific case when the finite element + * space corresponding to @p dof1 is a subset of the finite element space + * corresponding to @p dof2, this function is simply an identity mapping. */ template void back_interpolate (const DoFHandler &dof1, @@ -961,20 +639,13 @@ namespace FETools OutVector &u1_interpolated); /** - * Gives $(Id-I_h)z_1$ for a given - * @p dof1-function $z_1$, where $I_h$ - * is the interpolation from @p fe1 - * to @p fe2. The result $(Id-I_h)z_1$ is + * Gives $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is + * the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is * written into @p z1_difference. * - * Note, that this function does - * not work for continuous - * elements at hanging nodes. For - * that case use the - * @p interpolation_difference - * function, below, that takes an - * additional - * @p ConstraintMatrix object. + * Note, that this function does not work for continuous elements at hanging + * nodes. For that case use the @p interpolation_difference function, below, + * that takes an additional @p ConstraintMatrix object. */ template void interpolation_difference(const DoFHandler &dof1, @@ -983,21 +654,13 @@ namespace FETools OutVector &z1_difference); /** - * Gives $(Id-I_h)z_1$ for a given - * @p dof1-function $z_1$, where $I_h$ - * is the interpolation from @p fe1 - * to @p fe2. The result $(Id-I_h)z_1$ is - * written into @p z1_difference. - * @p constraints1 and - * @p constraints2 are the - * hanging node constraints - * corresponding to @p dof1 and - * @p dof2, respectively. These - * objects are particular - * important when continuous - * elements on grids with hanging - * nodes (locally refined grids) - * are involved. + * Gives $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is + * the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is + * written into @p z1_difference. @p constraints1 and @p constraints2 are + * the hanging node constraints corresponding to @p dof1 and @p dof2, + * respectively. These objects are particular important when continuous + * elements on grids with hanging nodes (locally refined grids) are + * involved. * * For parallel computations with PETSc, supply @p z1 with ghost elements * and @p z1_difference without ghost elements. @@ -1013,18 +676,12 @@ namespace FETools /** - * $L^2$ projection for - * discontinuous - * elements. Operates the same - * direction as interpolate. - * - * The global projection can be - * computed by local matrices if - * the finite element spaces are - * discontinuous. With continuous - * elements, this is impossible, - * since a global mass matrix - * must be inverted. + * $L^2$ projection for discontinuous elements. Operates the same direction + * as interpolate. + * + * The global projection can be computed by local matrices if the finite + * element spaces are discontinuous. With continuous elements, this is + * impossible, since a global mass matrix must be inverted. */ template void project_dg (const DoFHandler &dof1, @@ -1033,39 +690,23 @@ namespace FETools OutVector &u2); /** - * Gives the patchwise - * extrapolation of a @p dof1 - * function @p z1 to a @p dof2 - * function @p z2. @p dof1 and - * @p dof2 need to be DoFHandler - * based on the same triangulation. - * - * This function is interesting - * for e.g. extrapolating - * patchwise a piecewise linear - * solution to a piecewise - * quadratic solution. - * - * Note that the resulting field - * does not satisfy continuity - * requirements of the given - * finite elements. - * - * When you use continuous - * elements on grids with hanging - * nodes, please use the - * @p extrapolate function with - * an additional - * ConstraintMatrix argument, + * Gives the patchwise extrapolation of a @p dof1 function @p z1 to a @p + * dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler based on + * the same triangulation. + * + * This function is interesting for e.g. extrapolating patchwise a piecewise + * linear solution to a piecewise quadratic solution. + * + * Note that the resulting field does not satisfy continuity requirements of + * the given finite elements. + * + * When you use continuous elements on grids with hanging nodes, please use + * the @p extrapolate function with an additional ConstraintMatrix argument, * see below. * - * Since this function operates - * on patches of cells, it is - * required that the underlying - * grid is refined at least once - * for every coarse grid cell. If - * this is not the case, an - * exception will be raised. + * Since this function operates on patches of cells, it is required that the + * underlying grid is refined at least once for every coarse grid cell. If + * this is not the case, an exception will be raised. */ template void extrapolate (const DoFHandler &dof1, @@ -1074,24 +715,14 @@ namespace FETools OutVector &z2); /** - * Gives the patchwise - * extrapolation of a @p dof1 - * function @p z1 to a @p dof2 - * function @p z2. @p dof1 and - * @p dof2 need to be DoFHandler - * based on the same triangulation. - * @p constraints is a hanging - * node constraints object - * corresponding to - * @p dof2. This object is - * particular important when - * interpolating onto continuous - * elements on grids with hanging - * nodes (locally refined grids). - * - * Otherwise, the same holds as - * for the other @p extrapolate - * function. + * Gives the patchwise extrapolation of a @p dof1 function @p z1 to a @p + * dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler based on + * the same triangulation. @p constraints is a hanging node constraints + * object corresponding to @p dof2. This object is particular important when + * interpolating onto continuous elements on grids with hanging nodes + * (locally refined grids). + * + * Otherwise, the same holds as for the other @p extrapolate function. */ template void extrapolate (const DoFHandler &dof1, @@ -1101,54 +732,27 @@ namespace FETools OutVector &z2); //@} /** - * The numbering of the degrees - * of freedom in continuous finite - * elements is hierarchic, - * i.e. in such a way that we - * first number the vertex dofs, - * in the order of the vertices - * as defined by the - * triangulation, then the line - * dofs in the order and - * respecting the direction of - * the lines, then the dofs on - * quads, etc. However, we could - * have, as well, numbered them - * in a lexicographic way, - * i.e. with indices first - * running in x-direction, then - * in y-direction and finally in - * z-direction. Discontinuous - * elements of class FE_DGQ() - * are numbered in this way, for - * example. - * - * This function constructs a - * table which lexicographic - * index each degree of freedom - * in the hierarchic numbering - * would have. It operates on the - * continuous finite element - * given as first argument, and - * outputs the lexicographic - * indices in the second. - * - * Note that since this function - * uses specifics of the - * continuous finite elements, it - * can only operate on - * FiniteElementData objects - * inherent in FE_Q(). However, - * this function does not take a - * FE_Q object as it is also - * invoked by the FE_Q() - * constructor. - * - * It is assumed that the size of - * the output argument already - * matches the correct size, - * which is equal to the number - * of degrees of freedom in the + * The numbering of the degrees of freedom in continuous finite elements is + * hierarchic, i.e. in such a way that we first number the vertex dofs, in + * the order of the vertices as defined by the triangulation, then the line + * dofs in the order and respecting the direction of the lines, then the + * dofs on quads, etc. However, we could have, as well, numbered them in a + * lexicographic way, i.e. with indices first running in x-direction, then + * in y-direction and finally in z-direction. Discontinuous elements of + * class FE_DGQ() are numbered in this way, for example. + * + * This function constructs a table which lexicographic index each degree of + * freedom in the hierarchic numbering would have. It operates on the + * continuous finite element given as first argument, and outputs the + * lexicographic indices in the second. + * + * Note that since this function uses specifics of the continuous finite + * elements, it can only operate on FiniteElementData objects inherent + * in FE_Q(). However, this function does not take a FE_Q object as it is + * also invoked by the FE_Q() constructor. + * + * It is assumed that the size of the output argument already matches the + * correct size, which is equal to the number of degrees of freedom in the * finite element. */ template @@ -1157,23 +761,17 @@ namespace FETools std::vector &h2l); /** - * Like the previous function but - * instead of returning its - * result through the last - * argument return it as a value. + * Like the previous function but instead of returning its result through + * the last argument return it as a value. */ template std::vector hierarchic_to_lexicographic_numbering (const FiniteElementData &fe_data); /** - * This is the reverse function - * to the above one, generating - * the map from the lexicographic - * to the hierarchical - * numbering. All the remarks - * made about the above function - * are also valid here. + * This is the reverse function to the above one, generating the map from + * the lexicographic to the hierarchical numbering. All the remarks made + * about the above function are also valid here. */ template void @@ -1181,75 +779,44 @@ namespace FETools std::vector &l2h); /** - * Like the previous function but - * instead of returning its - * result through the last - * argument return it as a value. + * Like the previous function but instead of returning its result through + * the last argument return it as a value. */ template std::vector lexicographic_to_hierarchic_numbering (const FiniteElementData &fe_data); /** - * Parse the name of a finite - * element and generate a finite - * element object accordingly. - * - * The name must be in the form which - * is returned by the - * FiniteElement::get_name - * function, where a few - * modifications are allowed: - * - *
  • Dimension template - * parameters <2> etc. can - * be omitted. Alternatively, the - * explicit number can be - * replaced by dim or - * d. If a number is - * given, it must match - * the template parameter of this - * function. + * Parse the name of a finite element and generate a finite element object + * accordingly. * - *
  • The powers used for - * FESystem may either be numbers - * or can be - * replaced by dim or - * d. - *
- * - * If no finite element can be - * reconstructed from this - * string, an exception of type - * @p FETools::ExcInvalidFEName - * is thrown. - * - * The function returns a pointer - * to a newly create finite - * element. It is in the caller's - * responsibility to destroy the - * object pointed to at an + * The name must be in the form which is returned by the + * FiniteElement::get_name function, where a few modifications are allowed: + * + *
  • Dimension template parameters <2> etc. can be + * omitted. Alternatively, the explicit number can be replaced by + * dim or d. If a number is given, it must match + * the template parameter of this function. + * + *
  • The powers used for FESystem may either be numbers or can be + * replaced by dim or d.
+ * + * If no finite element can be reconstructed from this string, an exception + * of type @p FETools::ExcInvalidFEName is thrown. + * + * The function returns a pointer to a newly create finite element. It is in + * the caller's responsibility to destroy the object pointed to at an * appropriate later time. * - * Since the value of the template - * argument can't be deduced from the - * (string) argument given to this - * function, you have to explicitly - * specify it when you call this - * function. + * Since the value of the template argument can't be deduced from the + * (string) argument given to this function, you have to explicitly specify + * it when you call this function. * - * This function knows about all - * the standard elements defined - * in the library. However, it - * doesn't by default know about - * elements that you may have - * defined in your program. To - * make your own elements known - * to this function, use the - * add_fe_name() function. - * This function does not work - * if one wants to get a codimension - * 1 finite element. + * This function knows about all the standard elements defined in the + * library. However, it doesn't by default know about elements that you may + * have defined in your program. To make your own elements known to this + * function, use the add_fe_name() function. This function does not work if + * one wants to get a codimension 1 finite element. */ template FiniteElement * @@ -1257,102 +824,57 @@ namespace FETools /** - * Extend the list of finite - * elements that can be generated - * by get_fe_from_name() by the - * one given as @p name. If - * get_fe_from_name() is later - * called with this name, it will - * use the object given as second - * argument to create a finite - * element object. - * - * The format of the @p name - * parameter should include the - * name of a finite - * element. However, it is safe - * to use either the class name - * alone or to use the result of - * FiniteElement::get_name (which - * includes the space dimension - * as well as the polynomial - * degree), since everything - * after the first non-name - * character will be ignored. - * - * The FEFactory object should be - * an object newly created with - * new. FETools will - * take ownership of this object - * and delete it once it is not - * used anymore. - * - * In most cases, if you want - * objects of type - * MyFE be created - * whenever the name - * my_fe is given to - * get_fe_from_name, you will - * want the second argument to - * this function be of type - * FEFactory@, but you can - * of course create your custom - * finite element factory class. - * - * This function takes over - * ownership of the object given - * as second argument, i.e. you - * should never attempt to - * destroy it later on. The - * object will be deleted at the - * end of the program's lifetime. - * - * If the name of the element - * is already in use, an exception - * is thrown. Thus, functionality - * of get_fe_from_name() can only - * be added, not changed. - * - * @note This function - * manipulates a global table - * (one table for each space - * dimension). It is thread safe - * in the sense that every access - * to this table is secured by a - * lock. Nevertheless, since each - * name can be added only once, - * user code has to make sure - * that only one thread adds a - * new element. - * - * Note also that this table - * exists once for each space - * dimension. If you have a - * program that works with finite - * elements in different space - * dimensions (for example, @ref - * step_4 "step-4" does something - * like this), then you should - * call this function for each - * space dimension for which you - * want your finite element added - * to the map. + * Extend the list of finite elements that can be generated by + * get_fe_from_name() by the one given as @p name. If get_fe_from_name() is + * later called with this name, it will use the object given as second + * argument to create a finite element object. + * + * The format of the @p name parameter should include the name of a finite + * element. However, it is safe to use either the class name alone or to use + * the result of FiniteElement::get_name (which includes the space dimension + * as well as the polynomial degree), since everything after the first + * non-name character will be ignored. + * + * The FEFactory object should be an object newly created with + * new. FETools will take ownership of this object and delete it + * once it is not used anymore. + * + * In most cases, if you want objects of type MyFE be created + * whenever the name my_fe is given to get_fe_from_name, you + * will want the second argument to this function be of type + * FEFactory@, but you can of course create your custom finite + * element factory class. + * + * This function takes over ownership of the object given as second + * argument, i.e. you should never attempt to destroy it later on. The + * object will be deleted at the end of the program's lifetime. + * + * If the name of the element is already in use, an exception is + * thrown. Thus, functionality of get_fe_from_name() can only be added, not + * changed. + * + * @note This function manipulates a global table (one table for each space + * dimension). It is thread safe in the sense that every access to this + * table is secured by a lock. Nevertheless, since each name can be added + * only once, user code has to make sure that only one thread adds a new + * element. + * + * Note also that this table exists once for each space dimension. If you + * have a program that works with finite elements in different space + * dimensions (for example, @ref step_4 "step-4" does something like this), + * then you should call this function for each space dimension for which you + * want your finite element added to the map. */ template void add_fe_name (const std::string &name, const FEFactoryBase *factory); /** - * The string used for - * get_fe_from_name() cannot be - * translated to a finite + * The string used for get_fe_from_name() cannot be translated to a finite * element. * - * Either the string is badly - * formatted or you are using a - * custom element that must be - * added using add_fe_name() - * first. + * Either the string is badly formatted or you are using a custom element + * that must be added using add_fe_name() first. * * @ingroup Exceptions */ @@ -1362,21 +884,13 @@ namespace FETools << arg1 << "'."); /** - * The string used for - * get_fe_from_name() cannot be - * translated to a finite + * The string used for get_fe_from_name() cannot be translated to a finite * element. * - * Dimension arguments in finite - * element names should be - * avoided. If they are there, - * the dimension should be - * dim or - * d. Here, you gave a - * numeric dimension argument, - * which does not match the - * template dimension of the - * finite element class. + * Dimension arguments in finite element names should be avoided. If they + * are there, the dimension should be dim or d. Here, you + * gave a numeric dimension argument, which does not match the template + * dimension of the finite element class. * * @ingroup Exceptions */ @@ -1395,8 +909,7 @@ namespace FETools DeclException0 (ExcInvalidFE); /** - * The finite element must be - * @ref GlossPrimitive "primitive". + * The finite element must be @ref GlossPrimitive "primitive". * * @ingroup Exceptions */ @@ -1409,10 +922,8 @@ namespace FETools DeclException0 (ExcTriangulationMismatch); /** - * A continuous element is used - * on a mesh with hanging nodes, - * but the constraint matrices - * are missing. + * A continuous element is used on a mesh with hanging nodes, but the + * constraint matrices are missing. * * @ingroup Exceptions */ @@ -1430,9 +941,7 @@ namespace FETools */ DeclException0 (ExcGridNotRefinedAtLeastOnce); /** - * The dimensions of the matrix - * used did not match the - * expected dimensions. + * The dimensions of the matrix used did not match the expected dimensions. * * @ingroup Exceptions */ @@ -1442,9 +951,7 @@ namespace FETools << "but should be a " << arg3 << "x" << arg4 << " matrix."); /** - * Exception thrown if an - * embedding matrix was computed - * inaccurately. + * Exception thrown if an embedding matrix was computed inaccurately. * * @ingroup Exceptions */ @@ -1452,8 +959,7 @@ namespace FETools << "Least squares fit leaves a gap of " << arg1); /** - * Exception thrown if one variable - * may not be greater than another. + * Exception thrown if one variable may not be greater than another. * * @ingroup Exceptions */