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
|