LCOV - code coverage report
Current view: top level - include/fe - fe_lagrange_gll_shape.h (source / functions) Hit Total Coverage
Test: libMesh/libmesh: #4573 (924896) with base 3f0912 Lines: 94 97 96.9 %
Date: 2026-11-18 21:52:26 Functions: 11 11 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : // The libMesh Finite Element Library.
       2             : // Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
       3             : 
       4             : // This library is free software; you can redistribute it and/or
       5             : // modify it under the terms of the GNU Lesser General Public
       6             : // License as published by the Free Software Foundation; either
       7             : // version 2.1 of the License, or (at your option) any later version.
       8             : 
       9             : // This library is distributed in the hope that it will be useful,
      10             : // but WITHOUT ANY WARRANTY; without even the implied warranty of
      11             : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      12             : // Lesser General Public License for more details.
      13             : 
      14             : // You should have received a copy of the GNU Lesser General Public
      15             : // License along with this library; if not, write to the Free Software
      16             : // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
      17             : 
      18             : 
      19             : #ifndef LIBMESH_FE_LAGRANGE_GLL_SHAPE_H
      20             : #define LIBMESH_FE_LAGRANGE_GLL_SHAPE_H
      21             : 
      22             : // Local includes
      23             : #include "libmesh/elem.h"
      24             : #include "libmesh/enum_fe_family.h"
      25             : #include "libmesh/enum_order.h"
      26             : #include "libmesh/fe_lagrange_gll_shape_1D.h"
      27             : #include "libmesh/int_range.h"
      28             : 
      29             : // C++ includes
      30             : #include <array>
      31             : #include <cmath>
      32             : #include <vector>
      33             : 
      34             : // Tensor product evaluation shared by the Gauss-Lobatto nodal families. The families differ
      35             : // only in how a shape function index maps to a tensor index, so each family specializes
      36             : // fe_lagrange_gll_tensor_index and shares the rest.
      37             : 
      38             : namespace libMesh
      39             : {
      40             : 
      41             : /**
      42             :  * The pair of coordinates differentiated by each second derivative index \p j of
      43             :  * FE::shape_second_deriv().
      44             :  *
      45             :  * In dimension d only the first \f$d(d+1)/2\f$ entries are used: one on an edge, three on
      46             :  * a face, and all six on a cell.
      47             :  */
      48             : constexpr unsigned int fe_lagrange_gll_second_deriv_pairs[6][2] =
      49             :   {{0, 0},   // d^2 phi / dxi^2
      50             :    {0, 1},   // d^2 phi / dxi deta
      51             :    {1, 1},   // d^2 phi / deta^2
      52             :    {0, 2},   // d^2 phi / dxi dzeta
      53             :    {1, 2},   // d^2 phi / deta dzeta
      54             :    {2, 2}};  // d^2 phi / dzeta^2
      55             : 
      56             : 
      57             : /**
      58             :  * \returns The number of distinct second derivatives in dimension \p Dim.
      59             :  */
      60             : template <unsigned int Dim>
      61    21476799 : constexpr unsigned int fe_lagrange_gll_n_second_derivs()
      62             : {
      63    21476799 :   return Dim * (Dim + 1) / 2;
      64             : }
      65             : 
      66             : /**
      67             :  * The tensor index of a shape function. Entry d is the index of the one-dimensional shape
      68             :  * function in coordinate d. Entries at and above the element dimension are zero.
      69             :  */
      70             : typedef std::array<unsigned int, 3> GLLTensorIndex;
      71             : 
      72             : 
      73             : /**
      74             :  * \returns The tensor index of shape function \p i of order \p order on an element of
      75             :  * dimension \p dim.
      76             :  *
      77             :  * Each Gauss-Lobatto nodal family specializes this function. Using a family without a
      78             :  * specialization is a link error.
      79             :  */
      80             : template <FEFamily T>
      81             : GLLTensorIndex fe_lagrange_gll_tensor_index(const Elem * elem,
      82             :                                             const Order order,
      83             :                                             const unsigned int dim,
      84             :                                             const unsigned int i);
      85             : 
      86             : 
      87             : /**
      88             :  * All L2_LAGRANGE_GLL degrees of freedom belong to the element. They are numbered
      89             :  * lexicographically over the tensor grid, with the first coordinate varying fastest. QBase
      90             :  * orders the points of a tensor product rule the same way, so shape function i is the one
      91             :  * that is one at quadrature point i. The numbering doesn't depend on the element, so the
      92             :  * element argument is unused.
      93             :  */
      94             : template <>
      95    28219236 : inline GLLTensorIndex fe_lagrange_gll_tensor_index<L2_LAGRANGE_GLL>(const Elem *,
      96             :                                                                     const Order order,
      97             :                                                                     const unsigned int dim,
      98             :                                                                     const unsigned int i)
      99             : {
     100   112876944 :   const unsigned int n = static_cast<unsigned int>(order) + 1;
     101             : 
     102    84657708 :   GLLTensorIndex indices = {};
     103    28219236 :   unsigned int stride = 1;
     104             : 
     105   449026684 :   for (const auto d : make_range(dim))
     106             :     {
     107   336149740 :       indices[d] = (i / stride) % n;
     108   336149740 :       stride *= n;
     109             :     }
     110             : 
     111    28219236 :   libmesh_assert_less (i, stride);
     112             : 
     113   112876944 :   return indices;
     114             : }
     115             : 
     116             : 
     117             : /**
     118             :  * \returns The index of the one-dimensional interpolation point of LAGRANGE_GLL shape
     119             :  * function \p i of order \p order on an edge element.
     120             :  *
     121             :  * The first two shape functions belong to the vertices at -1 and 1, which are the first and
     122             :  * the last points. The interior points sit in-between in increasing order. The numbering is the same
     123             :  * on every edge element, so it needs no Elem.
     124             :  */
     125        4818 : inline unsigned int fe_lagrange_gll_1D_index(const Order order,
     126             :                                              const unsigned int i)
     127             : {
     128       19070 :   const unsigned int degree = static_cast<unsigned int>(order);
     129             : 
     130        4818 :   libmesh_assert_less_equal (i, degree);
     131             : 
     132       19070 :   if (i == 0)
     133        1310 :     return 0;
     134       13860 :   if (i == 1)
     135        1310 :     return degree;
     136        8650 :   return i - 1;
     137             : }
     138             : 
     139             : 
     140             : /**
     141             :  * \returns The tensor index of vertex \p v of \p elem.
     142             :  *
     143             :  * Each reference coordinate of a vertex of a tensor product element is -1 or 1. These are the
     144             :  * first and the last interpolation points in that coordinate.
     145             :  */
     146   101229676 : inline GLLTensorIndex fe_lagrange_gll_vertex_index(const Elem & elem,
     147             :                                                    const unsigned int degree,
     148             :                                                    const unsigned int v)
     149             : {
     150   101229676 :   const Point q = elem.master_point(v);
     151             : 
     152   101229676 :   GLLTensorIndex indices = {};
     153             : 
     154   403653468 :   for (const auto d : make_range(elem.dim()))
     155             :     {
     156    75811048 :       libmesh_assert_equal_to (std::abs(q(d)), 1.);
     157   413307208 :       indices[d] = (q(d) > 0.) ? degree : 0;
     158             :     }
     159             : 
     160   101229676 :   return indices;
     161             : }
     162             : 
     163             : 
     164             : /**
     165             :  * \returns The tensor index that lies \p k interpolation points from \p index, in the
     166             :  * direction that leads from vertex \p from to vertex \p to.
     167             :  *
     168             :  * The two vertices are the ends of an edge. Their tensor indices differ in one coordinate,
     169             :  * where one is 0 and the other is the degree. The result adds \p k to that coordinate of
     170             :  * \p index, or subtracts it if \p to is the end at 0. The other coordinates stay the same.
     171             :  *
     172             :  * An edge degree of freedom is one step from the start vertex of its edge. A face degree of
     173             :  * freedom is two steps from the start vertex of its face, one along each of two edges.
     174             :  */
     175    43054508 : inline GLLTensorIndex fe_lagrange_gll_advance_index(GLLTensorIndex index,
     176             :                                                     const GLLTensorIndex from,
     177             :                                                     const GLLTensorIndex to,
     178             :                                                     const unsigned int k)
     179             : {
     180    14404916 :   unsigned int n_moved = 0;
     181             : 
     182   229837696 :   for (const auto d : index_range(index))
     183   172378272 :     if (from[d] != to[d])
     184             :       {
     185    57459424 :         index[d] = (to[d] > from[d]) ? index[d] + k : index[d] - k;
     186    14404916 :         ++n_moved;
     187             :       }
     188             : 
     189    14404916 :   libmesh_assert_equal_to (n_moved, 1u);
     190    14404916 :   libmesh_ignore(n_moved);
     191             : 
     192    57459424 :   return index;
     193             : }
     194             : 
     195             : 
     196             : /**
     197             :  * An entity is a vertex, an edge, or a face of the element, or its interior. LAGRANGE_GLL
     198             :  * places its degrees of freedom on the entities as HIERARCHIC does:
     199             :  * - one on each vertex,
     200             :  * - degree-1 on each edge,
     201             :  * - (degree-1)^2 on each face,
     202             :  * - the rest on the interior.
     203             :  *
     204             :  * We number the vertex, edge, and face degrees of freedom by the node that owns each one,
     205             :  * in node order, then the interior degrees of freedom. A shape function index thus
     206             :  * identifies an entity and a position in that entity.
     207             :  *
     208             :  * Two elements that share an edge or a face must put each of its degrees of freedom at the
     209             :  * same interpolation point. Each element numbers the corner vertices of that edge or face in
     210             :  * its own local order. Elem::positive_edge_orientation and Elem::oriented_face_vertices give
     211             :  * the same result on both elements, because they compare the positions of the shared
     212             :  * vertices. An edge starts at its lesser vertex. A face starts at its least vertex and goes
     213             :  * along the lesser of the two edges at it.
     214             :  */
     215             : template <>
     216    52920064 : inline GLLTensorIndex fe_lagrange_gll_tensor_index<LAGRANGE_GLL>(const Elem * elem,
     217             :                                                                  const Order order,
     218             :                                                                  const unsigned int dim,
     219             :                                                                  const unsigned int i)
     220             : {
     221    13268621 :   libmesh_assert(elem);
     222    13268621 :   libmesh_assert_equal_to (dim, elem->dim());
     223             : 
     224    52920064 :   if (dim == 1)
     225           0 :     return {fe_lagrange_gll_1D_index(order, i), 0, 0};
     226             : 
     227    52920064 :   const unsigned int degree = static_cast<unsigned int>(order);
     228    52920064 :   const unsigned int n_v = elem->n_vertices();
     229             : 
     230    52920064 :   if (i < n_v)
     231     6553196 :     return fe_lagrange_gll_vertex_index(*elem, degree, i);
     232             : 
     233             :   // At first order, the vertices hold all the degrees of freedom
     234    11626817 :   libmesh_assert_greater (degree, 1);
     235             : 
     236    46366868 :   const unsigned int per_edge = degree - 1;
     237    46366868 :   const unsigned int n_e = elem->n_edges();
     238             : 
     239    46366868 :   if (i < n_v + n_e * per_edge)
     240             :     {
     241    16974688 :       const unsigned int e = (i - n_v) / per_edge;
     242    16974688 :       const unsigned int k = (i - n_v) % per_edge;
     243             : 
     244             :       // The node carrying this edge's degrees of freedom follows the vertices in node order
     245     4256084 :       libmesh_assert (elem->is_node_on_edge(n_v + e, e));
     246             : 
     247             :       // The edge runs from its lesser vertex to its greater one. positive_edge_orientation is
     248             :       // true when the zeroth vertex of the edge is the greater one, in which case the edge
     249             :       // starts at the first vertex.
     250    16974688 :       const unsigned int start = elem->positive_edge_orientation(e) ? 1 : 0;
     251             : 
     252             :       const GLLTensorIndex from =
     253    16974688 :         fe_lagrange_gll_vertex_index(*elem, degree, elem->local_edge_node(e, start));
     254             :       const GLLTensorIndex to =
     255    16974688 :         fe_lagrange_gll_vertex_index(*elem, degree, elem->local_edge_node(e, 1 - start));
     256             : 
     257    21230772 :       return fe_lagrange_gll_advance_index(from, from, to, k + 1);
     258             :     }
     259             : 
     260    29392180 :   const unsigned int per_face = per_edge * per_edge;
     261     7370733 :   const unsigned int after_edges = n_v + n_e * per_edge;
     262    29392180 :   const unsigned int n_f = (dim > 2) ? elem->n_faces() : 0;
     263             : 
     264    29392180 :   if (i < after_edges + n_f * per_face)
     265             :     {
     266    20242368 :       const unsigned int f = (i - after_edges) / per_face;
     267    20242368 :       const unsigned int m = (i - after_edges) % per_face;
     268             : 
     269             :       // The node carrying this face's degrees of freedom follows the edge nodes
     270     5074416 :       libmesh_assert (elem->is_node_on_side(n_v + n_e + f, f));
     271             : 
     272             :       // The vertices of the face, from its least vertex toward the lesser neighbor of that
     273             :       // vertex. The last entry is the other neighbor.
     274    25316784 :       const std::vector<unsigned int> face_vertices = elem->oriented_face_vertices(f);
     275             : 
     276             :       const GLLTensorIndex from =
     277    20242368 :         fe_lagrange_gll_vertex_index(*elem, degree, face_vertices.front());
     278             :       const GLLTensorIndex first =
     279    20242368 :         fe_lagrange_gll_vertex_index(*elem, degree, face_vertices[1]);
     280             :       const GLLTensorIndex second =
     281    20242368 :         fe_lagrange_gll_vertex_index(*elem, degree, face_vertices.back());
     282             : 
     283             :       // The two edges at the start vertex change different coordinates, so the second step
     284             :       // keeps the coordinate that the first step set
     285             :       const GLLTensorIndex along_first =
     286    20242368 :         fe_lagrange_gll_advance_index(from, from, first, m % per_edge + 1);
     287    25316784 :       return fe_lagrange_gll_advance_index(along_first, from, second, m / per_edge + 1);
     288             :     }
     289             : 
     290             :   // The remaining degrees of freedom belong to the interior. They cover the interior of the
     291             :   // tensor grid in lexicographic order, with the first coordinate varying fastest.
     292     9149812 :   const unsigned int m = i - (after_edges + n_f * per_face);
     293             : 
     294     9149812 :   GLLTensorIndex indices = {};
     295     2296317 :   unsigned int stride = 1;
     296             : 
     297    36292928 :   for (const auto d : make_range(dim))
     298             :     {
     299    27143116 :       indices[d] = (m / stride) % per_edge + 1;
     300    27143116 :       stride *= per_edge;
     301             :     }
     302             : 
     303     2296317 :   libmesh_assert_less (m, stride);
     304             : 
     305     9149812 :   return indices;
     306             : }
     307             : 
     308             : 
     309             : /**
     310             :  * \returns Shape function \p i of family \p T in dimension \p Dim, differentiated once
     311             :  * with respect to each coordinate listed in the first \p n_deriv_coords entries of
     312             :  * \p deriv_coords.
     313             :  *
     314             :  * Each factor of the tensor product is a one-dimensional shape function, differentiated as
     315             :  * many times as its coordinate is listed. FE::shape() passes zero coordinates,
     316             :  * FE::shape_deriv() passes one, and FE::shape_second_deriv() passes two.
     317             :  */
     318             : template <FEFamily T, unsigned int Dim>
     319   165797008 : inline Real fe_lagrange_gll_tensor_product(const Elem * elem,
     320             :                                            const Order order,
     321             :                                            const unsigned int i,
     322             :                                            const Point & p,
     323             :                                            const unsigned int * const deriv_coords,
     324             :                                            const unsigned int n_deriv_coords)
     325             : {
     326   165797008 :   const GLLTensorIndex indices = fe_lagrange_gll_tensor_index<T>(elem, order, Dim, i);
     327             : 
     328    41487857 :   Real value = 1.;
     329             : 
     330   659619312 :   for (const auto d : make_range(Dim))
     331             :     {
     332   123566519 :       unsigned int deriv_order = 0;
     333  1135041920 :       for (const auto k : make_range(n_deriv_coords))
     334   641219616 :         if (deriv_coords[k] == d)
     335   215005248 :           ++deriv_order;
     336             : 
     337   493822304 :       switch (deriv_order)
     338             :         {
     339   322007912 :         case 0:
     340   322007912 :           value *= fe_lagrange_gll_1D_shape(order, indices[d], p(d));
     341   322007912 :           break;
     342             : 
     343   128623536 :         case 1:
     344   128623536 :           value *= fe_lagrange_gll_1D_shape_deriv(order, indices[d], 0, p(d));
     345   128623536 :           break;
     346             : 
     347             : #ifdef LIBMESH_ENABLE_SECOND_DERIVATIVES
     348    43190856 :         case 2:
     349    43190856 :           value *= fe_lagrange_gll_1D_shape_second_deriv(order, indices[d], 0, p(d));
     350    43190856 :           break;
     351             : #endif
     352             : 
     353           0 :         default:
     354           0 :           libmesh_error_msg("Invalid derivative order " << deriv_order << ".");
     355             :         }
     356             :     }
     357             : 
     358   165797008 :   return value;
     359             : }
     360             : 
     361             : } // namespace libMesh
     362             : 
     363             : #endif // LIBMESH_FE_LAGRANGE_GLL_SHAPE_H

Generated by: LCOV version 1.14