// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2002 - 2024 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_fe_q_hierarchical_h #define dealii_fe_q_hierarchical_h #include #include #include DEAL_II_NAMESPACE_OPEN /** * @addtogroup fe * @{ */ /** * Implementation of hierarchical @p Qp shape functions that yield the finite * element space of continuous, piecewise polynomials of degree @p p. This * class is realized using tensor product polynomials based on a hierarchical * basis Polynomials::Hierarchical on the interval [0,1] which is * suitable for building an @p hp tensor product finite element if we assume * that each element has a single degree. * * The constructor of this class takes the degree @p p of this finite element. * * This class is not implemented for the codimension one case (spacedim != * dim). * *

Implementation

* * The constructor creates a TensorProductPolynomials object that includes the * tensor product of @p Hierarchical polynomials of degree @p p. This @p * TensorProductPolynomials object provides all values and derivatives of the * shape functions. * *

Numbering of the degrees of freedom (DoFs)

* * The original ordering of the shape functions represented by the * TensorProductPolynomials is a tensor product numbering. However, the shape * functions on a cell are renumbered beginning with the shape functions whose * support points are at the vertices, then on the line, on the quads, and * finally (for 3d) on the hexes. To be explicit, these numberings are listed * in the following: * *

Q1 elements

* * The $Q_1^H$ element is of polynomial degree one and, consequently, is * exactly the same as the $Q_1$ element in class FE_Q. In particular, the * shape function are defined in the exact same way: * *
    *
  • 1d case: * @verbatim * 0-------1 * @endverbatim * *
  • 2d case: * @verbatim * 2-------3 * | | * | | * | | * 0-------1 * @endverbatim * *
  • 3d case: * @verbatim * 6-------7 6-------7 * /| | / /| * / | | / / | * / | | / / | * 4 | | 4-------5 | * | 2-------3 | | 3 * | / / | | / * | / / | | / * |/ / | |/ * 0-------1 0-------1 * @endverbatim * * The respective coordinate values of the support points of the degrees of * freedom are as follows: *
      *
    • Shape function 0: [0, 0, 0]; *
    • Shape function 1: [1, 0, 0]; *
    • Shape function 2: [0, 1, 0]; *
    • Shape function 3: [1, 1, 0]; *
    • Shape function 4: [0, 0, 1]; *
    • Shape function 5: [1, 0, 1]; *
    • Shape function 6: [0, 1, 1]; *
    • Shape function 7: [1, 1, 1]; *
    *
* * In 2d, these shape functions look as follows: * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0001.png *
$Q_1^H$ element, shape function 0 * $Q_1^H$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0003.png *
$Q_1^H$ element, shape function 2 * $Q_1^H$ element, shape function 3
* * *

Q2 elements

*
    *
  • 1d case: * @verbatim * 0---2---1 * @endverbatim * *
  • 2d case: * @verbatim * 2---7---3 * | | * 4 8 5 * | | * 0---6---1 * @endverbatim * *
  • 3d case: * @verbatim * 6--15---7 6--15---7 * /| | / /| * 12 | 19 12 1319 * / 18 | / / | * 4 | | 4---14--5 | * | 2---11--3 | | 3 * | / / | 17 / * 16 8 9 16 | 9 * |/ / | |/ * 0---10--1 0---8---1 * * *-------* *-------* * /| | / /| * / | 23 | / 25 / | * / | | / / | * * | | *-------* | * |20 *-------* | |21 * * | / / | 22 | / * | / 24 / | | / * |/ / | |/ * *-------* *-------* * @endverbatim * The center node has number 26. * * The respective coordinate values of the support points of the degrees of * freedom are as follows: *
      *
    • Shape function 0: [0, 0, 0]; *
    • Shape function 1: [1, 0, 0]; *
    • Shape function 2: [0, 1, 0]; *
    • Shape function 3: [1, 1, 0]; *
    • Shape function 4: [0, 0, 1]; *
    • Shape function 5: [1, 0, 1]; *
    • Shape function 6: [0, 1, 1]; *
    • Shape function 7: [1, 1, 1]; *
    • Shape function 8: [0, 1/2, 0]; *
    • Shape function 9: [1, 1/2, 0]; *
    • Shape function 10: [1/2, 0, 0]; *
    • Shape function 11: [1/2, 1, 0]; *
    • Shape function 12: [0, 1/2, 1]; *
    • Shape function 13: [1, 1/2, 1]; *
    • Shape function 14: [1/2, 0, 1]; *
    • Shape function 15: [1/2, 1, 1]; *
    • Shape function 16: [0, 0, 1/2]; *
    • Shape function 17: [1, 0, 1/2]; *
    • Shape function 18: [0, 1, 1/2]; *
    • Shape function 19: [1, 1, 1/2]; *
    • Shape function 20: [0, 1/2, 1/2]; *
    • Shape function 21: [1, 1/2, 1/2]; *
    • Shape function 22: [1/2, 0, 1/2]; *
    • Shape function 23: [1/2, 1, 1/2]; *
    • Shape function 24: [1/2, 1/2, 0]; *
    • Shape function 25: [1/2, 1/2, 1]; *
    • Shape function 26: [1/2, 1/2, 1/2]; *
    *
* * * In 2d, these shape functions look as follows (the black plane corresponds * to zero; negative shape function values may not be visible): * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0001.png *
$Q_2^H$ element, shape function 0 * $Q_2^H$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0003.png *
$Q_2^H$ element, shape function 2 * $Q_2^H$ element, shape function 3
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0004.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0005.png *
$Q_2^H$ element, shape function 4 * $Q_2^H$ element, shape function 5
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0006.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0007.png *
$Q_2^H$ element, shape function 6 * $Q_2^H$ element, shape function 7
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0008.png *
$Q_2^H$ element, * shape function 8
* * *

Q3 elements

*
    *
  • 1d case: * @verbatim * 0--2--3--1 * @endverbatim * *
  • 2d case: * @verbatim * 2--10-11-3 * | | * 5 14 15 7 * | | * 4 12 13 6 * | | * 0--8--9--1 * @endverbatim *
* * In 2d, these shape functions look as follows (the black plane corresponds * to zero; negative shape function values may not be visible): * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0001.png *
$Q_3^H$ element, shape function 0 * $Q_3^H$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0003.png *
$Q_3^H$ element, shape function 2 * $Q_3^H$ element, shape function 3
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0004.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0005.png *
$Q_3^H$ element, shape function 4 * $Q_3^H$ element, shape function 5
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0006.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0007.png *
$Q_3^H$ element, shape function 6 * $Q_3^H$ element, shape function 7
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0008.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0009.png *
$Q_3^H$ element, shape function 8 * $Q_3^H$ element, shape function 9
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0010.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0011.png *
$Q_3^H$ element, shape function 10 * $Q_3^H$ element, shape function 11
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0012.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0013.png *
$Q_3^H$ element, shape function 12 * $Q_3^H$ element, shape function 13
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0014.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0015.png *
$Q_3^H$ element, shape function 14 * $Q_3^H$ element, shape function 15
* * *

Q4 elements

*
    *
  • 1d case: * @verbatim * 0--2--3--4--1 * @endverbatim * *
  • 2d case: * @verbatim * 2--13-14-15-3 * | | * 6 22 23 24 9 * | | * 5 19 20 21 8 * | | * 4 16 17 18 7 * | | * 0--10-11-12-1 * @endverbatim *
* * In 2d, these shape functions look as follows (the black plane corresponds * to zero; negative shape function values may not be visible): * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0000.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0001.png *
$Q_4^H$ element, shape function 0 * $Q_4^H$ element, shape function 1
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0002.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0003.png *
$Q_4^H$ element, shape function 2 * $Q_4^H$ element, shape function 3
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0004.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0005.png *
$Q_4^H$ element, shape function 4 * $Q_4^H$ element, shape function 5
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0006.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0007.png *
$Q_4^H$ element, shape function 6 * $Q_4^H$ element, shape function 7
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0008.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0009.png *
$Q_4^H$ element, shape function 8 * $Q_4^H$ element, shape function 9
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0010.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0011.png *
$Q_4^H$ element, shape function 10 * $Q_4^H$ element, shape function 11
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0012.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0013.png *
$Q_4^H$ element, shape function 12 * $Q_4^H$ element, shape function 13
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0014.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0015.png *
$Q_4^H$ element, shape function 14 * $Q_4^H$ element, shape function 15
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0016.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0017.png *
$Q_4^H$ element, shape function 16 * $Q_4^H$ element, shape function 17
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0018.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0019.png *
$Q_4^H$ element, shape function 18 * $Q_4^H$ element, shape function 19
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0020.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0021.png *
$Q_4^H$ element, shape function 20 * $Q_4^H$ element, shape function 21
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0022.png * * @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0023.png *
$Q_4^H$ element, shape function 22 * $Q_4^H$ element, shape function 23
* @image html http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0024.png *
$Q_4^H$ element, * shape function 24
*/ template class FE_Q_Hierarchical : public FE_Poly { public: /** * Constructor for tensor product polynomials of degree @p p. */ FE_Q_Hierarchical(const unsigned int p); /** * Return a string that uniquely identifies a finite element. This class * returns FE_Q_Hierarchical(degree), with @p dim and @p * degree replaced by appropriate values. */ virtual std::string get_name() const override; virtual std::unique_ptr> clone() const override; /** * This function returns @p true, if the shape function @p shape_index has * non-zero function values somewhere on the face @p face_index. */ virtual bool has_support_on_face(const unsigned int shape_index, const unsigned int face_index) const override; /** * @name Functions to support hp * @{ */ /** * Return whether this element implements its hanging node constraints in * the new way, which has to be used to make elements "hp-compatible". * * For the FE_Q_Hierarchical class the result is always true (independent of * the degree of the element), as it implements the complete set of * functions necessary for hp-capability. */ virtual bool hp_constraints_are_implemented() const override; /** * Return the matrix interpolating from the given finite element to the * present one. Interpolation only between FE_Q_Hierarchical is supported. */ virtual void get_interpolation_matrix(const FiniteElement &source, FullMatrix &matrix) const override; /** * Embedding matrix between grids. Only isotropic refinement is supported. */ virtual const FullMatrix & get_prolongation_matrix( const unsigned int child, const RefinementCase &refinement_case = RefinementCase::isotropic_refinement) const override; /** * If, on a vertex, several finite elements are active, the hp-code first * assigns the degrees of freedom of each of these FEs different global * indices. It then calls this function to find out which of them should get * identical values, and consequently can receive the same global DoF index. * This function therefore returns a list of identities between DoFs of the * present finite element object with the DoFs of @p fe_other, which is a * reference to a finite element object representing one of the other finite * elements active on this particular vertex. The function computes which of * the degrees of freedom of the two finite element objects are equivalent, * both numbered between zero and the corresponding value of * n_dofs_per_vertex() of the two finite elements. The first index of each * pair denotes one of the vertex dofs of the present element, whereas the * second is the corresponding index of the other finite element. */ virtual std::vector> hp_vertex_dof_identities(const FiniteElement &fe_other) const override; /** * Same as above but for lines. */ virtual std::vector> hp_line_dof_identities(const FiniteElement &fe_other) const override; /** * Same as above but for faces. */ virtual std::vector> hp_quad_dof_identities(const FiniteElement &fe_other, const unsigned int face_no = 0) const override; /** * @copydoc FiniteElement::compare_for_domination() */ virtual FiniteElementDomination::Domination compare_for_domination(const FiniteElement &fe_other, const unsigned int codim = 0) const override final; /** @} */ /** * Return the matrix interpolating from a face of one element to the face of * the neighboring element. The size of the matrix is then * source.dofs_per_face times this->dofs_per_face. * * Derived elements will have to implement this function. They may only * provide interpolation matrices for certain source finite elements, for * example those from the same family. If they don't implement interpolation * from a given element, then they must throw an exception of type * FiniteElement::ExcInterpolationNotImplemented. */ virtual void get_face_interpolation_matrix(const FiniteElement &source, FullMatrix &matrix, const unsigned int face_no = 0) const override; /** * Return the matrix interpolating from a face of one element to the subface * of the neighboring element. The size of the matrix is then * source.dofs_per_face times this->dofs_per_face. * * Derived elements will have to implement this function. They may only * provide interpolation matrices for certain source finite elements, for * example those from the same family. If they don't implement interpolation * from a given element, then they must throw an exception of type * ExcInterpolationNotImplemented. */ virtual void get_subface_interpolation_matrix( const FiniteElement &source, const unsigned int subface, FullMatrix &matrix, const unsigned int face_no = 0) const override; /** * Determine an estimate for the memory consumption (in bytes) of this * object. * * This function is made virtual, since finite element objects are usually * accessed through pointers to their base class, rather than the class * itself. */ virtual std::size_t memory_consumption() const override; /** * For a finite element of degree @p sub_degree < @p degree, we return a * vector which maps the numbering on an FE of degree @p sub_degree into the * numbering on this element. */ std::vector get_embedding_dofs(const unsigned int sub_degree) const; /** * Return a list of constant modes of the element. For this element, the * list consists of true arguments for the first vertex shape functions and * false for the remaining ones. */ virtual std::pair, std::vector> get_constant_modes() const override; private: /** * Only for internal use. Its full name is @p get_dofs_per_object_vector * function and it creates the @p dofs_per_object vector that is needed * within the constructor to be passed to the constructor of @p * FiniteElementData. */ static std::vector get_dpo_vector(const unsigned int degree); /** * 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. * * The dofs associated with 1d hierarchical polynomials are ordered with the * vertices first ($phi_0(x)=1-x$ and $phi_1(x)=x$) and then the line dofs * (the higher degree polynomials). The 2d and 3d hierarchical polynomials * originate from the 1d hierarchical polynomials by tensor product. In the * following, the resulting numbering of dofs will be denoted by * `fe_q_hierarchical numbering`. * * This function constructs a table which fe_q_hierarchical index each * degree of freedom in the hierarchic numbering would have. * * This function is analogous to the * FETools::hierarchic_to_lexicographic_numbering() function. However, in * contrast to the fe_q_hierarchical numbering defined above, the * lexicographic numbering originates from the tensor products of * consecutive numbered dofs (like for LagrangeEquidistant). * * 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. */ static std::vector hierarchic_to_fe_q_hierarchical_numbering(const FiniteElementData &fe); /** * This is an analogon to the previous function, but working on faces. */ static std::vector face_fe_q_hierarchical_to_hierarchic_numbering(const unsigned int degree); /** * Initialize two auxiliary fields that will be used in setting up the * various matrices in the constructor. */ void build_dofs_cell(std::vector> &dofs_cell, std::vector> &dofs_subcell) const; /** * Initialize the hanging node constraints matrices. Called from the * constructor. */ void initialize_constraints(const std::vector> &dofs_subcell); /** * Initialize the embedding matrices. Called from the constructor. */ void initialize_embedding_and_restriction( const std::vector> &dofs_cell, const std::vector> &dofs_subcell); /** * Initialize the @p generalized_support_points field of the FiniteElement class. * Called from the constructor. */ void initialize_generalized_support_points(); /** * Initialize the @p generalized_face_support_points field of the FiniteElement * class. Called from the constructor. */ void initialize_generalized_face_support_points(); /** * Mapping from lexicographic to shape function numbering on first face. */ const std::vector face_renumber; // Allow access from other dimensions. We need this since we want to call // the functions @p get_dpo_vector and @p // lexicographic_to_hierarchic_numbering for the faces of the finite element // of dimension dim+1. template friend class FE_Q_Hierarchical; }; /** @} */ /* -------------- declaration of explicit specializations ------------- */ template <> void FE_Q_Hierarchical<1>::initialize_generalized_face_support_points(); template <> bool FE_Q_Hierarchical<1>::has_support_on_face(const unsigned int, const unsigned int) const; template <> std::vector FE_Q_Hierarchical<1>::face_fe_q_hierarchical_to_hierarchic_numbering( const unsigned int); DEAL_II_NAMESPACE_CLOSE #endif