LCOV - code coverage report
Current view: top level - include/fe - fe_base.h (source / functions) Hit Total Coverage
Test: libMesh/libmesh: #4667 (c50533) with base aa4ea8 Lines: 73 152 48.0 %
Date: 2026-11-17 18:48:15 Functions: 33 89 37.1 %
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             : 
      20             : #ifndef LIBMESH_FE_BASE_H
      21             : #define LIBMESH_FE_BASE_H
      22             : 
      23             : // Local includes
      24             : #include "libmesh/libmesh_common.h"
      25             : #include "libmesh/compare_types.h"
      26             : #include "libmesh/fe_abstract.h"
      27             : #include "libmesh/fe_transformation_base.h"
      28             : #include "libmesh/point.h"
      29             : #include "libmesh/reference_counted_object.h"
      30             : #include "libmesh/tensor_tools.h"
      31             : #include "libmesh/type_n_tensor.h"
      32             : #include "libmesh/vector_value.h"
      33             : #include "libmesh/dense_matrix.h"
      34             : #include "libmesh/dense_vector.h"
      35             : 
      36             : // C++ includes
      37             : #include <cstddef>
      38             : #include <vector>
      39             : #include <memory>
      40             : 
      41             : namespace libMesh
      42             : {
      43             : 
      44             : 
      45             : // forward declarations
      46             : template <typename T> class DenseMatrix;
      47             : template <typename T> class DenseVector;
      48             : class BoundaryInfo;
      49             : class DofConstraints;
      50             : class DofMap;
      51             : class Elem;
      52             : class MeshBase;
      53             : template <typename T> class NumericVector;
      54             : class QBase;
      55             : template <typename T> class FETransformationBase;
      56             : class FEType;
      57             : 
      58             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
      59             : class NodeConstraints;
      60             : #endif
      61             : 
      62             : #ifdef LIBMESH_ENABLE_PERIODIC
      63             : class PeriodicBoundaries;
      64             : class PointLocatorBase;
      65             : #endif
      66             : 
      67             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
      68             : template <unsigned int Dim, FEFamily T_radial, InfMapType T_map>
      69             : class InfFE;
      70             : #endif
      71             : 
      72             : /**
      73             :  * This class forms the foundation from which generic finite
      74             :  * elements may be derived.  In the current implementation the
      75             :  * templated derived class \p FE offers a wide variety of commonly
      76             :  * used finite element concepts.  Check there for details.
      77             :  *
      78             :  * Use the \p FEGenericBase<OutputType>::build() method to create an
      79             :  * object of any of the derived classes which is compatible with
      80             :  * OutputType.
      81             :  *
      82             :  * \author Benjamin S. Kirk
      83             :  * \date 2002
      84             :  */
      85             : template <typename OutputType>
      86             : class FEGenericBase : public FEAbstract
      87             : {
      88             : protected:
      89             : 
      90             :   /**
      91             :    * Constructor.  Optionally initializes required data
      92             :    * structures.  Protected so that this base class
      93             :    * cannot be explicitly instantiated.
      94             :    */
      95             :   FEGenericBase (const unsigned int dim,
      96             :                  const FEType & fet);
      97             : 
      98             : public:
      99             : 
     100             :   /**
     101             :    * Destructor.
     102             :    */
     103             :   virtual ~FEGenericBase();
     104             : 
     105             :   /**
     106             :    * Builds a specific finite element type.  A \p
     107             :    * std::unique_ptr<FEGenericBase> is returned to prevent a memory leak. This
     108             :    * way the user need not remember to delete the object.
     109             :    *
     110             :    * The build call will fail if the OutputType of this class is not
     111             :    * compatible with the output required for the requested \p type
     112             :    */
     113             :   static std::unique_ptr<FEGenericBase> build (const unsigned int dim,
     114             :                                                const FEType & type);
     115             : 
     116             :   /**
     117             :    * Convenient typedefs for gradients of output, hessians of output,
     118             :    * and potentially-complex-valued versions of same.
     119             :    */
     120             :   typedef OutputType                                                      OutputShape;
     121             :   typedef typename TensorTools::IncrementRank<OutputShape>::type          OutputGradient;
     122             :   typedef typename TensorTools::IncrementRank<OutputGradient>::type       OutputTensor;
     123             :   typedef typename TensorTools::DecrementRank<OutputShape>::type          OutputDivergence;
     124             :   typedef typename TensorTools::MakeNumber<OutputShape>::type             OutputNumber;
     125             :   typedef typename TensorTools::IncrementRank<OutputNumber>::type         OutputNumberGradient;
     126             :   typedef typename TensorTools::IncrementRank<OutputNumberGradient>::type OutputNumberTensor;
     127             :   typedef typename TensorTools::DecrementRank<OutputNumber>::type         OutputNumberDivergence;
     128             : 
     129             : 
     130             : 
     131             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
     132             : 
     133             :   /**
     134             :    * Builds a specific infinite element type.  A \p
     135             :    * std::unique_ptr<FEGenericBase> is returned to prevent a memory leak. This
     136             :    * way the user need not remember to delete the object.
     137             :    *
     138             :    * The build call will fail if the OutputShape of this class is not
     139             :    * compatible with the output required for the requested \p type
     140             :    */
     141             :   static std::unique_ptr<FEGenericBase> build_InfFE (const unsigned int dim,
     142             :                                                      const FEType & type);
     143             : 
     144             : #endif
     145             : 
     146             : #ifdef LIBMESH_ENABLE_AMR
     147             : 
     148             :   /**
     149             :    * Computes the constraint matrix contributions (for
     150             :    * non-conforming adapted meshes) corresponding to
     151             :    * variable number \p var_number, using generic
     152             :    * projections.
     153             :    */
     154             :   static void compute_proj_constraints (DofConstraints & constraints,
     155             :                                         DofMap & dof_map,
     156             :                                         const unsigned int variable_number,
     157             :                                         const Elem * elem);
     158             : 
     159             :   /**
     160             :    * Creates a local projection on \p coarse_elem, based on the
     161             :    * DoF values in \p global_vector for it's children.  Computes a
     162             :    * vector of coefficients corresponding to dof_indices for only the
     163             :    * single given \p var
     164             :    */
     165             : 
     166             :   static void coarsened_dof_values(const NumericVector<Number> & global_vector,
     167             :                                    const DofMap & dof_map,
     168             :                                    const Elem * coarse_elem,
     169             :                                    DenseVector<Number> & coarse_dofs,
     170             :                                    const unsigned int var,
     171             :                                    const bool use_old_dof_indices = false);
     172             : 
     173             :   /**
     174             :    * Creates a local projection on \p coarse_elem, based on the
     175             :    * DoF values in \p global_vector for it's children.  Computes a
     176             :    * vector of coefficients corresponding to all dof_indices.
     177             :    */
     178             : 
     179             :   static void coarsened_dof_values(const NumericVector<Number> & global_vector,
     180             :                                    const DofMap & dof_map,
     181             :                                    const Elem * coarse_elem,
     182             :                                    DenseVector<Number> & coarse_dofs,
     183             :                                    const bool use_old_dof_indices = false);
     184             : 
     185             : #endif // #ifdef LIBMESH_ENABLE_AMR
     186             : 
     187             : #ifdef LIBMESH_ENABLE_PERIODIC
     188             : 
     189             :   /**
     190             :    * Computes the constraint matrix contributions (for
     191             :    * meshes with periodic boundary conditions) corresponding to
     192             :    * variable number \p var_number, using generic projections.
     193             :    */
     194             :   static void compute_periodic_constraints (DofConstraints & constraints,
     195             :                                             DofMap & dof_map,
     196             :                                             const PeriodicBoundaries & boundaries,
     197             :                                             const MeshBase & mesh,
     198             :                                             const PointLocatorBase * point_locator,
     199             :                                             const unsigned int variable_number,
     200             :                                             const Elem * elem);
     201             : 
     202             : #endif // LIBMESH_ENABLE_PERIODIC
     203             : 
     204             :   /**
     205             :    * \returns The shape function values at the quadrature points
     206             :    * on the element.
     207             :    */
     208        6520 :   const std::vector<std::vector<OutputShape>> & get_phi() const
     209        6520 :   { libmesh_assert(!calculations_started || calculate_phi);
     210   323803113 :     calculate_phi = true; return phi; }
     211             : 
     212             :   /**
     213             :    * \returns The dual (biorthogonal) shape function values at the quadrature
     214             :    * points on the element.
     215             :    *
     216             :    * The dual basis is constructed to satisfy
     217             :    * \f$ \int \Phi_j N_k \, d\gamma = \delta_{jk} \int N_k \, d\gamma \f$
     218             :    * against the primal basis \f$ N \f$. That biorthogonality is what makes a
     219             :    * mortar coupling matrix diagonal, so a Lagrange multiplier can be condensed
     220             :    * with a diagonal inverse.
     221             :    *
     222             :    * \note For SECOND order LAGRANGE and L2_LAGRANGE on QUAD8, TRI6 and TRI7
     223             :    * these functions are biorthogonal to a locally
     224             :    * transformed primal basis rather than to \f$ N \f$ itself: \f$ \int N_k \f$
     225             :    * is not positive on those faces (exactly 0 at a TRI6 vertex, -1/3 at a QUAD8
     226             :    * corner), so the usual construction degenerates. For those element types
     227             :    * \f$ \int \Phi_j N_k \f$ is therefore not diagonal; it factors as
     228             :    * \f$ D = \tilde{D} T^{-1} \f$ with \f$ \tilde{D} \f$ diagonal, leaving
     229             :    * \f$ D^{-1} = T \tilde{D}^{-1} \f$ sparse and cheap to apply. The functions
     230             :    * returned here are still expressed in the primal basis, so the type and
     231             :    * meaning of this return value are unchanged. See Popp, Wohlmuth, Gee and
     232             :    * Wall, SIAM J. Sci. Comput. 34(4):B421-B446, 2012, Sec. 4.4.1 and Eq. (4.12).
     233             :    */
     234           0 :   const std::vector<std::vector<OutputShape>> & get_dual_phi() const
     235             :   {
     236           0 :     libmesh_assert(!calculations_started || calculate_dual);
     237           0 :     calculate_dual = true;
     238             :     // Dual phi computation relies on primal phi computation
     239           0 :     this->request_phi();
     240           0 :     return dual_phi;
     241             :   }
     242             : 
     243      986714 :   virtual void request_phi() const override
     244      986714 :   { get_phi(); }
     245             : 
     246           0 :   virtual void request_dual_phi() const override
     247           0 :   { get_dual_phi(); }
     248             : 
     249             :   /**
     250             :    * \returns The shape function derivatives at the quadrature
     251             :    * points.
     252             :    */
     253      107648 :   const std::vector<std::vector<OutputGradient>> & get_dphi() const
     254      107648 :   { libmesh_assert(!calculations_started || calculate_dphi);
     255   276042673 :     calculate_dphi = calculate_dphiref = true; return dphi; }
     256             : 
     257             :   /**
     258             :    * \returns The dual shape function derivatives at the quadrature points.
     259             :    *
     260             :    * \note See get_dual_phi() for the QUAD8/TRI6 caveat.
     261             :    */
     262           0 :   const std::vector<std::vector<OutputGradient>> & get_dual_dphi() const
     263           0 :   { libmesh_assert(!calculations_started || calculate_dphi);
     264           0 :     calculate_dphi = calculate_dual = calculate_dphiref = true; return dual_dphi; }
     265             : 
     266      115497 :   virtual void request_dphi() const override
     267      115497 :   { get_dphi(); }
     268             : 
     269           0 :   virtual void request_dual_dphi() const override
     270           0 :   { get_dual_dphi(); }
     271             : 
     272             :   /**
     273             :    * \returns The coefficients expressing the dual basis in the primal basis.
     274             :    *
     275             :    * \note See get_dual_phi() for the QUAD8/TRI6 caveat.
     276             :    */
     277           0 :   const DenseMatrix<Real> & get_dual_coeff() const
     278           0 :   { return dual_coeff; }
     279             : 
     280             :   /**
     281             :    * \returns The curl of the shape function at the quadrature
     282             :    * points.
     283             :    */
     284             :   virtual_for_inffe
     285      525637 :   const std::vector<std::vector<OutputShape>> & get_curl_phi() const
     286      202175 :   { libmesh_assert(!calculations_started || calculate_curl_phi);
     287     2859877 :     calculate_curl_phi = calculate_dphiref = true; return curl_phi; }
     288             : 
     289             :   /**
     290             :    * \returns The divergence of the shape function at the quadrature
     291             :    * points.
     292             :    */
     293             :   virtual_for_inffe
     294      140745 :   const std::vector<std::vector<OutputDivergence>> & get_div_phi() const
     295       47027 :   { libmesh_assert(!calculations_started || calculate_div_phi);
     296      687657 :     calculate_div_phi = calculate_dphiref = true; return div_phi; }
     297             : 
     298             :   /**
     299             :    * \returns The shape function x-derivative at the quadrature
     300             :    * points.
     301             :    */
     302           0 :   const std::vector<std::vector<OutputShape>> & get_dphidx() const
     303           0 :   { libmesh_assert(!calculations_started || calculate_dphi);
     304           0 :     calculate_dphi = calculate_dphiref = true; return dphidx; }
     305             : 
     306             :   /**
     307             :    * \returns The shape function y-derivative at the quadrature
     308             :    * points.
     309             :    */
     310           0 :   const std::vector<std::vector<OutputShape>> & get_dphidy() const
     311           0 :   { libmesh_assert(!calculations_started || calculate_dphi);
     312           0 :     calculate_dphi = calculate_dphiref = true; return dphidy; }
     313             : 
     314             :   /**
     315             :    * \returns The shape function z-derivative at the quadrature
     316             :    * points.
     317             :    */
     318           0 :   const std::vector<std::vector<OutputShape>> & get_dphidz() const
     319           0 :   { libmesh_assert(!calculations_started || calculate_dphi);
     320           0 :     calculate_dphi = calculate_dphiref = true; return dphidz; }
     321             : 
     322             :   /**
     323             :    * \returns The shape function xi-derivative at the quadrature
     324             :    * points.
     325             :    */
     326     8370216 :   const std::vector<std::vector<OutputShape>> & get_dphidxi() const
     327     8370216 :   { libmesh_assert(!calculations_started || calculate_dphiref);
     328    92125719 :     calculate_dphiref = true; return dphidxi; }
     329             : 
     330             :   /**
     331             :    * \returns The shape function eta-derivative at the quadrature
     332             :    * points.
     333             :    */
     334     8346296 :   const std::vector<std::vector<OutputShape>> & get_dphideta() const
     335     8346296 :   { libmesh_assert(!calculations_started || calculate_dphiref);
     336     8346296 :     calculate_dphiref = true; return dphideta; }
     337             : 
     338             :   /**
     339             :    * \returns The shape function zeta-derivative at the quadrature
     340             :    * points.
     341             :    */
     342     1440031 :   const std::vector<std::vector<OutputShape>> & get_dphidzeta() const
     343     1440031 :   { libmesh_assert(!calculations_started || calculate_dphiref);
     344     1440031 :     calculate_dphiref = true; return dphidzeta; }
     345             : 
     346             : #ifdef LIBMESH_ENABLE_SECOND_DERIVATIVES
     347             : 
     348             :   /**
     349             :    * \returns The shape function second derivatives at the quadrature
     350             :    * points.
     351             :    */
     352      176499 :   const std::vector<std::vector<OutputTensor>> & get_d2phi() const
     353      176499 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     354     2229712 :     calculate_d2phi = calculate_dphiref = true; return d2phi; }
     355             : 
     356             :   /**
     357             :    * \returns The dual shape function second derivatives at the quadrature
     358             :    * points.
     359             :    *
     360             :    * \note See get_dual_phi() for the QUAD8/TRI6 caveat.
     361             :    */
     362           0 :   const std::vector<std::vector<OutputTensor>> & get_dual_d2phi() const
     363           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     364           0 :     calculate_d2phi = calculate_dual = calculate_dphiref = true; return dual_d2phi; }
     365             : 
     366             :   /**
     367             :    * \returns The shape function second derivatives at the quadrature
     368             :    * points.
     369             :    */
     370           0 :   const std::vector<std::vector<OutputShape>> & get_d2phidx2() const
     371           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     372           0 :     calculate_d2phi = calculate_dphiref = true; return d2phidx2; }
     373             : 
     374             :   /**
     375             :    * \returns The shape function second derivatives at the quadrature
     376             :    * points.
     377             :    */
     378           0 :   const std::vector<std::vector<OutputShape>> & get_d2phidxdy() const
     379           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     380           0 :     calculate_d2phi = calculate_dphiref = true; return d2phidxdy; }
     381             : 
     382             :   /**
     383             :    * \returns The shape function second derivatives at the quadrature
     384             :    * points.
     385             :    */
     386           0 :   const std::vector<std::vector<OutputShape>> & get_d2phidxdz() const
     387           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     388           0 :     calculate_d2phi = calculate_dphiref = true; return d2phidxdz; }
     389             : 
     390             :   /**
     391             :    * \returns The shape function second derivatives at the quadrature
     392             :    * points.
     393             :    */
     394           0 :   const std::vector<std::vector<OutputShape>> & get_d2phidy2() const
     395           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     396           0 :     calculate_d2phi =  calculate_dphiref = true; return d2phidy2; }
     397             : 
     398             :   /**
     399             :    * \returns The shape function second derivatives at the quadrature
     400             :    * points.
     401             :    */
     402           0 :   const std::vector<std::vector<OutputShape>> & get_d2phidydz() const
     403           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     404           0 :     calculate_d2phi = calculate_dphiref = true; return d2phidydz; }
     405             : 
     406             :   /**
     407             :    * \returns The shape function second derivatives at the quadrature
     408             :    * points.
     409             :    */
     410           0 :   const std::vector<std::vector<OutputShape>> & get_d2phidz2() const
     411           0 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     412           0 :     calculate_d2phi = calculate_dphiref = true; return d2phidz2; }
     413             : 
     414             :   /**
     415             :    * \returns The shape function second derivatives at the quadrature
     416             :    * points, in reference coordinates
     417             :    */
     418      636800 :   const std::vector<std::vector<OutputShape>> & get_d2phidxi2() const
     419      636800 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     420     8069570 :     calculate_d2phi = calculate_dphiref = true; return d2phidxi2; }
     421             : 
     422             :   /**
     423             :    * \returns The shape function second derivatives at the quadrature
     424             :    * points, in reference coordinates
     425             :    */
     426      627765 :   const std::vector<std::vector<OutputShape>> & get_d2phidxideta() const
     427      627765 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     428      627765 :     calculate_d2phi = calculate_dphiref = true; return d2phidxideta; }
     429             : 
     430             :   /**
     431             :    * \returns The shape function second derivatives at the quadrature
     432             :    * points, in reference coordinates
     433             :    */
     434      532187 :   const std::vector<std::vector<OutputShape>> & get_d2phidxidzeta() const
     435      532187 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     436      532187 :     calculate_d2phi = calculate_dphiref = true; return d2phidxidzeta; }
     437             : 
     438             :   /**
     439             :    * \returns The shape function second derivatives at the quadrature
     440             :    * points, in reference coordinates
     441             :    */
     442      627765 :   const std::vector<std::vector<OutputShape>> & get_d2phideta2() const
     443      627765 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     444      627765 :     calculate_d2phi = calculate_dphiref = true; return d2phideta2; }
     445             : 
     446             :   /**
     447             :    * \returns The shape function second derivatives at the quadrature
     448             :    * points, in reference coordinates
     449             :    */
     450      532187 :   const std::vector<std::vector<OutputShape>> & get_d2phidetadzeta() const
     451      532187 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     452      532187 :     calculate_d2phi = calculate_dphiref = true; return d2phidetadzeta; }
     453             : 
     454             :   /**
     455             :    * \returns The shape function second derivatives at the quadrature
     456             :    * points, in reference coordinates
     457             :    */
     458      532187 :   const std::vector<std::vector<OutputShape>> & get_d2phidzeta2() const
     459      532187 :   { libmesh_assert(!calculations_started || calculate_d2phi);
     460      532187 :     calculate_d2phi = calculate_dphiref = true; return d2phidzeta2; }
     461             : 
     462             : #endif //LIBMESH_ENABLE_SECOND_DERIVATIVES
     463             : 
     464             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
     465             : 
     466             :   /**
     467             :    * \returns The global first derivative of the phase term
     468             :    * which is used in infinite elements, evaluated at the
     469             :    * quadrature points.
     470             :    *
     471             :    * In case of the general finite element class \p FE this
     472             :    * field is initialized to all zero, so that the variational
     473             :    * formulation for an infinite element produces correct element
     474             :    * matrices for a mesh using both finite and infinite elements.
     475             :    */
     476           0 :   const std::vector<OutputGradient> & get_dphase() const
     477           0 :   { return dphase; }
     478             : 
     479             : 
     480             :   /**
     481             :    * \returns The multiplicative weight at each quadrature point.
     482             :    * This weight is used for certain infinite element weak
     483             :    * formulations, so that weighted Sobolev spaces are
     484             :    * used for the trial function space.  This renders the
     485             :    * variational form easily computable.
     486             :    *
     487             :    * In case of the general finite element class \p FE this
     488             :    * field is initialized to all ones, so that the variational
     489             :    * formulation for an infinite element produces correct element
     490             :    * matrices for a mesh using both finite and infinite elements.
     491             :    */
     492           2 :   virtual const std::vector<Real> & get_Sobolev_weight() const
     493           2 :   { return weight; }
     494             : 
     495             :   /**
     496             :    * \returns The first global derivative of the multiplicative
     497             :    * weight at each quadrature point. See \p get_Sobolev_weight()
     498             :    * for details.  In case of \p FE initialized to all zero.
     499             :    */
     500           0 :   virtual const std::vector<RealGradient> & get_Sobolev_dweight() const
     501           0 :   { return dweight; }
     502             : 
     503             :   /**
     504             :    * \returns The multiplicative weight (see \p get_Sobolev_weight)
     505             :    * but weighted with the radial coordinate square.
     506             :    *
     507             :    * In finite elements, this gives just 1, similar to \p get_Sobolev_Weight()
     508             :    */
     509        1340 :   virtual const std::vector<Real> & get_Sobolev_weightxR_sq() const
     510        1340 :   { return weight; }
     511             : 
     512             :   /**
     513             :    * \returns The first global derivative of the multiplicative weight
     514             :    * (see \p dget_Sobolev_weight) but weighted with the square of the
     515             :    * radial coordinate.
     516             :    *
     517             :    * In finite elements, this is 0.
     518             :    */
     519        1340 :   virtual const std::vector<RealGradient> & get_Sobolev_dweightxR_sq() const
     520        1340 :   { return dweight; }
     521             : 
     522             :   /**
     523             :    * \returns The shape function \p phi (for FE) and \p phi weighted by r/decay
     524             :    *  for InfFE.
     525             :    *
     526             :    * To compensate for the decay function applied to the Jacobian (see \p get_JxWxdecay_sq),
     527             :    * the wave function \p phi should be divided by  this function.
     528             :    *
     529             :    * The factor r must be compensated for by the Sobolev \p weight.
     530             :    * (i.e. by using \p get_Sobolev_weightxR_sq())
     531             :    **/
     532        1340 :   virtual const std::vector<std::vector<OutputShape>> & get_phi_over_decayxR () const
     533        1340 :   { return get_phi();}
     534             : 
     535             :   /**
     536             :    * \returns the gradient of the shape function (see \p get_dphi()),
     537             :    * but in case of \p InfFE, weighted with r/decay.
     538             :    * See \p  get_phi_over_decayxR() for details.
     539             :    */
     540        1340 :   virtual const std::vector<std::vector<OutputGradient>> & get_dphi_over_decayxR () const
     541        1340 :   { return get_dphi();}
     542             : 
     543             :   /**
     544             :    * \returns the gradient of the shape function (see \p get_dphi()),
     545             :    * but in case of \p InfFE, weighted with 1/decay.
     546             :    *
     547             :    * In contrast to the shape function, its gradient stays finite
     548             :    * when divided by the decay function.
     549             :    */
     550           0 :   virtual const std::vector<std::vector<OutputGradient>> & get_dphi_over_decay () const
     551           0 :   { return get_dphi();}
     552             : 
     553             : #endif
     554             : 
     555             :   /**
     556             :    * Prints the value of each shape function at each quadrature point.
     557             :    */
     558             :   virtual void print_phi(std::ostream & os) const override;
     559             :   virtual void print_dual_phi(std::ostream & os) const override;
     560             : 
     561             :   /**
     562             :    * Prints the value of each shape function's derivative
     563             :    * at each quadrature point.
     564             :    */
     565             :   virtual void print_dphi(std::ostream & os) const override;
     566             :   virtual void print_dual_dphi(std::ostream & os) const override;
     567             : 
     568             : #ifdef LIBMESH_ENABLE_SECOND_DERIVATIVES
     569             : 
     570             :   /**
     571             :    * Prints the value of each shape function's second derivatives
     572             :    * at each quadrature point.
     573             :    */
     574             :   virtual void print_d2phi(std::ostream & os) const override;
     575             :   virtual void print_dual_d2phi(std::ostream & os) const override;
     576             : 
     577             : #endif
     578             : 
     579             : 
     580             : protected:
     581             : 
     582             : 
     583             : 
     584             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
     585             : 
     586             :   /**
     587             :    * Initialize the data fields for the base of an
     588             :    * an infinite element.  Implement this in the derived
     589             :    * class \p FE<Dim,T>.
     590             :    */
     591             :   virtual void init_base_shape_functions(const std::vector<Point> & qp,
     592             :                                          const Elem * e) = 0;
     593             : 
     594             : #endif
     595             : 
     596             :   /**
     597             :    * Determine which values are to be calculated, for both the FE
     598             :    * itself and for the FEMap.
     599             :    */
     600             :   virtual_for_inffe
     601             :   void determine_calculations();
     602             : 
     603             :   /**
     604             :    * \returns true iff no calculations have been requested of this
     605             :    * FE object or of its associated FEMap
     606             :    */
     607    27860068 :   bool calculating_nothing() const
     608             :   {
     609    29751625 :     return calculate_nothing &&
     610     1891557 :       !this->calculate_phi && !this->calculate_dphi &&
     611             : #ifdef LIBMESH_ENABLE_SECOND_DERIVATIVES
     612     1891557 :       !this->calculate_d2phi &&
     613             : #endif
     614    29917338 :       !this->calculate_curl_phi && !this->calculate_div_phi &&
     615     4401982 :       !this->calculate_map;
     616             :   }
     617             : 
     618             :   /**
     619             :    * After having updated the jacobian and the transformation
     620             :    * from local to global coordinates in \p FEMap::compute_map(),
     621             :    * the first derivatives of the shape functions are
     622             :    * transformed to global coordinates, giving \p dphi,
     623             :    * \p dphidx, \p dphidy, and \p dphidz. This method
     624             :    * should rarely be re-defined in derived classes, but
     625             :    * still should be usable for children. Therefore, keep
     626             :    * it protected.
     627             :    */
     628             :   virtual void compute_shape_functions(const Elem * elem, const std::vector<Point> & qp) override;
     629             : 
     630             :   /**
     631             :    * Compute the dual basis coefficients \p dual_coeff
     632             :    * we rely on the \p JxW (or weights) and the \p phi values,
     633             :    * which can come from default or customized qrule
     634             :    */
     635             :   void compute_dual_shape_coeffs(const std::vector<Real> & JxW, const std::vector<std::vector<OutputShape>> & phi);
     636             : 
     637             :   /**
     638             :    * Compute \p dual_phi, \p dual_dphi, \p dual_d2phi
     639             :    * It is only valid for this to be called after reinit has occurred with a
     640             :    * quadrature rule
     641             :    */
     642             :   void compute_dual_shape_functions();
     643             : 
     644             :   /**
     645             :    * Object that handles computing shape function values, gradients, etc
     646             :    * in the physical domain.
     647             :    */
     648             :   std::unique_ptr<FETransformationBase<OutputType>> _fe_trans;
     649             : 
     650             :   /**
     651             :    * Shape function values.
     652             :    */
     653             :   std::vector<std::vector<OutputShape>>   phi;
     654             :   std::vector<std::vector<OutputShape>>   dual_phi;
     655             : 
     656             :   /**
     657             :    * Shape function derivative values.
     658             :    */
     659             :   std::vector<std::vector<OutputGradient>>  dphi;
     660             :   std::vector<std::vector<OutputGradient>>  dual_dphi;
     661             : 
     662             :   /**
     663             :    * Coefficient matrix for the dual basis.
     664             :    */
     665             :   mutable DenseMatrix<Real> dual_coeff;
     666             : 
     667             :   /**
     668             :    * Shape function curl values. Only defined for vector types.
     669             :    */
     670             :   std::vector<std::vector<OutputShape>> curl_phi;
     671             : 
     672             :   /**
     673             :    * Shape function divergence values. Only defined for vector types.
     674             :    */
     675             :   std::vector<std::vector<OutputDivergence>> div_phi;
     676             : 
     677             :   /**
     678             :    * Shape function derivatives in the xi direction.
     679             :    */
     680             :   std::vector<std::vector<OutputShape>>   dphidxi;
     681             : 
     682             :   /**
     683             :    * Shape function derivatives in the eta direction.
     684             :    */
     685             :   std::vector<std::vector<OutputShape>>   dphideta;
     686             : 
     687             :   /**
     688             :    * Shape function derivatives in the zeta direction.
     689             :    */
     690             :   std::vector<std::vector<OutputShape>>   dphidzeta;
     691             : 
     692             :   /**
     693             :    * Shape function derivatives in the x direction.
     694             :    */
     695             :   std::vector<std::vector<OutputShape>>   dphidx;
     696             : 
     697             :   /**
     698             :    * Shape function derivatives in the y direction.
     699             :    */
     700             :   std::vector<std::vector<OutputShape>>   dphidy;
     701             : 
     702             :   /**
     703             :    * Shape function derivatives in the z direction.
     704             :    */
     705             :   std::vector<std::vector<OutputShape>>   dphidz;
     706             : 
     707             : 
     708             : #ifdef LIBMESH_ENABLE_SECOND_DERIVATIVES
     709             : 
     710             :   /**
     711             :    * Shape function second derivative values.
     712             :    */
     713             :   std::vector<std::vector<OutputTensor>>  d2phi;
     714             :   std::vector<std::vector<OutputTensor>>  dual_d2phi;
     715             : 
     716             :   /**
     717             :    * Shape function second derivatives in the xi direction.
     718             :    */
     719             :   std::vector<std::vector<OutputShape>>   d2phidxi2;
     720             : 
     721             :   /**
     722             :    * Shape function second derivatives in the xi-eta direction.
     723             :    */
     724             :   std::vector<std::vector<OutputShape>>   d2phidxideta;
     725             : 
     726             :   /**
     727             :    * Shape function second derivatives in the xi-zeta direction.
     728             :    */
     729             :   std::vector<std::vector<OutputShape>>   d2phidxidzeta;
     730             : 
     731             :   /**
     732             :    * Shape function second derivatives in the eta direction.
     733             :    */
     734             :   std::vector<std::vector<OutputShape>>   d2phideta2;
     735             : 
     736             :   /**
     737             :    * Shape function second derivatives in the eta-zeta direction.
     738             :    */
     739             :   std::vector<std::vector<OutputShape>>   d2phidetadzeta;
     740             : 
     741             :   /**
     742             :    * Shape function second derivatives in the zeta direction.
     743             :    */
     744             :   std::vector<std::vector<OutputShape>>   d2phidzeta2;
     745             : 
     746             :   /**
     747             :    * Shape function second derivatives in the x direction.
     748             :    */
     749             :   std::vector<std::vector<OutputShape>>   d2phidx2;
     750             : 
     751             :   /**
     752             :    * Shape function second derivatives in the x-y direction.
     753             :    */
     754             :   std::vector<std::vector<OutputShape>>   d2phidxdy;
     755             : 
     756             :   /**
     757             :    * Shape function second derivatives in the x-z direction.
     758             :    */
     759             :   std::vector<std::vector<OutputShape>>   d2phidxdz;
     760             : 
     761             :   /**
     762             :    * Shape function second derivatives in the y direction.
     763             :    */
     764             :   std::vector<std::vector<OutputShape>>   d2phidy2;
     765             : 
     766             :   /**
     767             :    * Shape function second derivatives in the y-z direction.
     768             :    */
     769             :   std::vector<std::vector<OutputShape>>   d2phidydz;
     770             : 
     771             :   /**
     772             :    * Shape function second derivatives in the z direction.
     773             :    */
     774             :   std::vector<std::vector<OutputShape>>   d2phidz2;
     775             : 
     776             : #endif
     777             : 
     778             : 
     779             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
     780             : 
     781             :   //--------------------------------------------------------------
     782             :   /* protected members for infinite elements, which are accessed
     783             :    * from the outside through some inline functions
     784             :    */
     785             : 
     786             : 
     787             :   /**
     788             :    * Used for certain infinite element families:
     789             :    * the first derivatives of the phase term in global coordinates,
     790             :    * over all quadrature points.
     791             :    */
     792             :   std::vector<OutputGradient> dphase;
     793             : 
     794             :   /**
     795             :    * Used for certain infinite element families:
     796             :    * the global derivative of the additional radial weight \f$ 1/{r^2} \f$,
     797             :    * over all quadrature points.
     798             :    */
     799             :   std::vector<RealGradient> dweight;
     800             : 
     801             :   /**
     802             :    * Used for certain infinite element families:
     803             :    * the additional radial weight \f$ 1/{r^2} \f$ in local coordinates,
     804             :    * over all quadrature points.
     805             :    */
     806             :   std::vector<Real>  weight;
     807             : 
     808             : #endif
     809             : 
     810             : private:
     811             : 
     812             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
     813             : 
     814             :   /**
     815             :    * Make all \p InfFE<Dim,T_radial,T_map> classes friends
     816             :    * so that they can safely used \p FE<Dim-1,T_base> through
     817             :    * a \p FEGenericBase * as base approximation.
     818             :    */
     819             :   template <unsigned int friend_Dim, FEFamily friend_T_radial, InfMapType friend_T_map>
     820             :   friend class InfFE;
     821             : 
     822             : #endif
     823             : 
     824             : 
     825             : };
     826             : 
     827             : // --------------------------------------------------------------------
     828             : // Generic templates. We specialize for OutputType = Real, so these are
     829             : // only used for OutputType = RealVectorValue
     830             : template <typename OutputType>
     831           0 : void FEGenericBase<OutputType>::compute_dual_shape_functions ()
     832             : {
     833           0 :   libmesh_error_msg(
     834             :       "Computation of dual shape functions for vector finite element "
     835             :       "families is not currently implemented");
     836             : }
     837             : 
     838             : template <typename OutputType>
     839           0 : void FEGenericBase<OutputType>::compute_dual_shape_coeffs(const std::vector<Real> & /*JxW*/, const std::vector<std::vector<OutputShape>> & /*phi_vals*/)
     840             : {
     841           0 :   libmesh_error_msg(
     842             :       "Computation of dual shape functions for vector finite element "
     843             :       "families is not currently implemented");
     844             : }
     845             : 
     846             : // -----------------------------------------------------------
     847             : // Forward declaration of specialization
     848             : template <>
     849             : void FEGenericBase<Real>::compute_dual_shape_functions();
     850             : 
     851             : template <>
     852             : void FEGenericBase<Real>::compute_dual_shape_coeffs(const std::vector<Real> & /*JxW*/, const std::vector<std::vector<OutputShape>> & /*phi_vals*/);
     853             : 
     854             : 
     855             : // Typedefs for convenience and backwards compatibility
     856             : typedef FEGenericBase<Real> FEBase;
     857             : typedef FEGenericBase<RealGradient> FEVectorBase;
     858             : 
     859             : 
     860             : 
     861             : 
     862             : // ------------------------------------------------------------
     863             : // FEGenericBase class inline members
     864             : template <typename OutputType>
     865             : inline
     866    13066292 : FEGenericBase<OutputType>::FEGenericBase(const unsigned int d,
     867             :                                          const FEType & fet) :
     868             :   FEAbstract(d,fet),
     869    11607919 :   _fe_trans( FETransformationBase<OutputType>::build(fet) ),
     870    11607919 :   phi(),
     871    11607919 :   dual_phi(),
     872    11607919 :   dphi(),
     873    11607919 :   dual_dphi(),
     874             :   curl_phi(),
     875             :   div_phi(),
     876             :   dphidxi(),
     877             :   dphideta(),
     878             :   dphidzeta(),
     879             :   dphidx(),
     880             :   dphidy(),
     881             :   dphidz()
     882             : #ifdef LIBMESH_ENABLE_SECOND_DERIVATIVES
     883             :   ,d2phi(),
     884             :   dual_d2phi(),
     885             :   d2phidxi2(),
     886             :   d2phidxideta(),
     887             :   d2phidxidzeta(),
     888             :   d2phideta2(),
     889             :   d2phidetadzeta(),
     890             :   d2phidzeta2(),
     891             :   d2phidx2(),
     892             :   d2phidxdy(),
     893             :   d2phidxdz(),
     894             :   d2phidy2(),
     895             :   d2phidydz(),
     896    11073008 :   d2phidz2()
     897             : #endif
     898             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
     899             :   ,dphase(),
     900             :   dweight(),
     901     1993284 :   weight()
     902             : #endif
     903             : {
     904    13066292 : }
     905             : 
     906             : 
     907             : 
     908             : template <typename OutputType>
     909             : inline
     910    13066292 : FEGenericBase<OutputType>::~FEGenericBase()
     911             : {
     912    15053463 : }
     913             : 
     914             : 
     915             : 
     916             : /**
     917             :  * \returns The adjacent vertices of each mid-edge shape function of \p elem for the transformed
     918             :  * dual basis of compute_dual_shape_coefficients(), or an empty vector for the standard basis
     919             :  */
     920             : std::vector<std::vector<unsigned int>>
     921             : dual_shape_transformed_vertices (const Elem * elem,
     922             :                                  const FEType & fe_type,
     923             :                                  const unsigned int n_shapes);
     924             : 
     925             : /**
     926             :  * Computes the dual basis coefficients \p coeff, psi_j = sum_i coeff(i,j) N_i, from the shape
     927             :  * values \p phi and weights \p JxW of a quadrature rule. \p vertices comes from
     928             :  * dual_shape_transformed_vertices(). \p T may be any type for which DenseMatrix<T> is
     929             :  * instantiated, such as a dual number type.
     930             :  */
     931             : template <typename T>
     932           0 : void compute_dual_shape_coefficients (const std::vector<T> & JxW,
     933             :                                       const std::vector<std::vector<T>> & phi,
     934             :                                       const std::vector<std::vector<unsigned int>> & vertices,
     935             :                                       DenseMatrix<T> & coeff)
     936             : {
     937           0 :   const unsigned int sz = phi.size();
     938           0 :   libmesh_error_msg_if(!sz, "ERROR: cannot compute dual shape coefficients with empty phi values");
     939           0 :   libmesh_assert_less_equal(vertices.size(), sz);
     940             : 
     941             :   //compute dual basis coefficient (coeff)
     942           0 :   coeff.resize(sz, sz);
     943           0 :   DenseMatrix<T> A(sz, sz), D(sz, sz);
     944             : 
     945           0 :   for (const auto i : index_range(phi))
     946           0 :     for (const auto qp : index_range(phi[i]))
     947             :     {
     948           0 :       D(i,i) += JxW[qp]*phi[i][qp];
     949           0 :       for (const auto j : index_range(phi))
     950           0 :         A(i,j) += JxW[qp]*phi[i][qp]*phi[j][qp];
     951             :     }
     952             : 
     953             :   // The integral positivity condition on the dual basis (Popp, Wohlmuth, Gee and Wall, SIAM J. Sci.
     954             :   // Comput. 34(4):B421-B446, 2012, Eq. (4.2)) fails on QUAD8 and TRI6: D(k,k) = \int N_k is -1/3 at a
     955             :   // QUAD8 corner and exactly 0 at a TRI6 vertex (their Eqs. (4.3) and (4.4)), the latter leaving those
     956             :   // dual shape functions identically zero. Biorthogonalize instead against the locally quadratic
     957             :   // transformed basis Ntilde = T N of their Sec. 4.4.1, in which each vertex absorbs a fraction alpha
     958             :   // of its adjacent mid-edge shapes. That replaces D by T^-1 diag(T d), which for this T is the sparse
     959             :   // update below. alpha = 1/5 is recommended there, and makes the weights strictly positive (QUAD8
     960             :   // 1/5 and 4/5, TRI6 1/15 and 1/10) while preserving the partition of unity. T = I elsewhere.
     961           0 :   const Real alpha = Real(1)/5;
     962             :   // Mid-edge nodes are the trailing indices, and only vertex entries are written, so D(m,m) here
     963             :   // is never a value an earlier iteration modified.
     964           0 :   for (const auto k : index_range(vertices))
     965             :     {
     966           0 :       const auto m = sz - vertices.size() + k;
     967           0 :       for (const auto vertex : vertices[k])
     968             :         {
     969           0 :           D(vertex, vertex) += alpha*D(m,m);
     970           0 :           D(vertex, m)      -= alpha*D(m,m);
     971             :         }
     972             :     }
     973             : 
     974             :   // coeff = A^-1*D
     975           0 :   for (const auto j : index_range(phi))
     976             :   {
     977           0 :     DenseVector<T> Dcol(sz), coeffcol(sz);
     978           0 :     for (const auto i : index_range(phi))
     979           0 :       Dcol(i) = D(i, j);
     980           0 :     A.cholesky_solve(Dcol, coeffcol);
     981             : 
     982           0 :     for (const auto row : index_range(phi))
     983           0 :       coeff(row, j)=coeffcol(row);
     984             :   }
     985           0 : }
     986             : 
     987             : } // namespace libMesh
     988             : 
     989             : #endif // LIBMESH_FE_BASE_H

Generated by: LCOV version 1.14