Debian Codegraph @

include/deal.II/fe/fe_enriched.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2016 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_fe_enriched_h
16 #define dealii_fe_enriched_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/function.h>
21 #include <deal.II/base/quadrature.h>
22 #include <deal.II/base/symmetric_tensor.h>
23
24 #include <deal.II/dofs/dof_handler.h>
25
26 #include <deal.II/fe/fe.h>
27 #include <deal.II/fe/fe_nothing.h>
28 #include <deal.II/fe/fe_q.h>
29 #include <deal.II/fe/fe_system.h>
30 #include <deal.II/fe/fe_update_flags.h>
31
32 #include <deal.II/hp/fe_collection.h>
33
34 #include <map>
35 #include <numeric>
36 #include <set>
37 #include <utility>
38 #include <vector>
39
40 DEAL_II_NAMESPACE_OPEN
41
42 /**
43 * Implementation of a partition of unity finite element method (PUM) by
44 * Babuska and Melenk which enriches a standard
45 * finite element with an enrichment function multiplied with another (usually
46 * linear) finite element:
47 * \f[
48 * U(\mathbf x) = \sum_i N_i(\mathbf x) U_i + \sum_j N_j(\mathbf x) \sum_k
49 * F_k(\mathbf x) U_{jk} \f] where $ N_i(\mathbf x) $ and $ N_j(\mathbf x) $ are
50 * the underlying finite elements (including the mapping from the isoparametric
51 * element to the real element); $ F_k(\mathbf x) $ are the scalar enrichment
52 * functions in real space (e.g. $ 1/r $, $ \exp(-r) $, etc); $ U_i $ and $
53 * U_{jk} $ are the standard and enriched DoFs. This allows to include in the
54 * finite element space a priori knowledge about the partial differential
55 * equation being solved which in turn improves the local approximation
56 * properties of the spaces. This can be useful for highly oscillatory
57 * solutions, problems with domain corners or on unbounded domains or sudden
58 * changes of boundary conditions. PUM method uses finite element spaces which
59 * satisfy the partition of unity property (e.g. FE_Q). Among other properties
60 * this makes the resulting space to reproduce enrichment functions exactly.
61 *
62 * The simplest constructor of this class takes two finite element objects and
63 * an enrichment function to be used. For example
64 *
65 * @code
66 * FE_Enriched<dim> fe(FE_Q<dim>(2),
67 * FE_Q<dim>(1),
68 * function)
69 * @endcode
70 *
71 * In this case, standard DoFs are distributed by <code>FE_Q<dim>(2)</code>,
72 * whereas enriched DoFs are coming from a single finite element
73 * <code>FE_Q<dim>(1)</code> used with a single enrichment function
74 * <code>function</code>. In this case, the total number of DoFs on the
75 * enriched element is the sum of DoFs from <code>FE_Q<dim>(2)</code> and
76 * <code>FE_Q<dim>(1)</code>.
77 *
78 * As an example of an enrichment function, consider $ \exp(-x) $, which
79 * leads to the following shape functions on the unit element:
80 * <table>
81 * <tr>
82 * <td align="center">
83 * @image html fe_enriched_1d.png
84 * </td>
85 * <td align="center">
86 * @image html fe_enriched_h-refinement.png
87 * </td>
88 * </tr>
89 * <tr>
90 * <td align="center">
91 * 1d element, base and enriched shape functions.
92 * </td>
93 * <td align="center">
94 * enriched shape function corresponding to the central vertex.
95 * </td>
96 * </tr>
97 * </table>
98 *
99 * Note that evaluation of gradients (hessians) of the enriched shape functions
100 * or the finite element field requires evaluation of gradients (gradients and
101 * hessians) of the enrichment functions:
102 * @f{align*}{
103 * U(\mathbf x)
104 * &= \sum_i N_i(\mathbf x) U_i
105 * + \sum_{j,k} N_j(\mathbf x) F_k(\mathbf x) U_{jk} \\
106 * \mathbf \nabla U(\mathbf x)
107 * &= \sum_i \mathbf \nabla N_i(\mathbf x) U_i
108 * + \sum_{j,k} \left[\mathbf \nabla N_j(\mathbf x) F_k(\mathbf x) +
109 * N_j(\mathbf x) \mathbf \nabla F_k(\mathbf x) \right]
110 * U_{jk} \\ \mathbf \nabla \mathbf \nabla U(\mathbf x)
111 * &= \sum_i \mathbf \nabla \mathbf \nabla N_i(\mathbf x) U_i
112 * + \sum_{j,k} \left[\mathbf \nabla \mathbf \nabla N_j(\mathbf x)
113 * F_k(\mathbf x) + \mathbf \nabla F_k(\mathbf x) \mathbf \nabla N_j(\mathbf x)
114 * + \mathbf \nabla N_j(\mathbf x) \mathbf \nabla F_k(\mathbf x) + N_j(\mathbf
115 * x) \mathbf \nabla \mathbf \nabla F_k(\mathbf x) \right] U_{jk}
116 * @f}
117 *
118 * <h3>Using enriched and non-enriched FEs together</h3>
119 *
120 * In most applications it is beneficial to introduce enrichments only in
121 * some part of the domain (e.g. around a crack tip) and use standard FE (e.g.
122 * FE_Q) elsewhere. This can be achieved by using the hp-finite element
123 * framework in deal.II that allows for the use of different elements on
124 * different cells. To make the resulting space $C^0$ continuous, it is then
125 * necessary for the DoFHandler class and
126 * DoFTools::make_hanging_node_constraints() function to be able to figure out
127 * what to do at the interface between enriched and non-enriched cells.
128 * Specifically, we want the degrees of freedom corresponding to enriched shape
129 * functions to be zero at these interfaces. These classes and functions can not
130 * to do this automatically, but the effect can be achieved by using not just a
131 * regular FE_Q on cells without enrichment, but to wrap the FE_Q into an
132 * FE_Enriched object <i>without actually enriching it</i>. This can be done as
133 * follows:
134 * @code
135 * FE_Enriched<dim> fe_non_enriched(FE_Q<dim>(1));
136 * @endcode
137 * This constructor is equivalent to calling
138 * @code
139 * FE_Enriched<dim> fe_non_enriched(FE_Q<dim>(1),
140 * FE_Nothing<dim>(1,true),
141 * nullptr);
142 * @endcode
143 * and will result in the correct constraints for enriched DoFs attributed to
144 * support points on the interface between the two regions.
145 *
146 * <h3>References</h3>
147 *
148 * When using this class, please cite @cite davydov2017hp .
149 * The PUM was introduced in @cite melenk1996 and @cite babuska1997 .
150 *
151 * <h3>Implementation</h3>
152 *
153 * The implementation of the class is based on FESystem which is aggregated as
154 * a private member. The simplest constructor <code> FE_Enriched<dim>
155 * fe(FE_Q<dim>(2), FE_Q<dim>(1),function)</code> will internally initialize
156 * FESystem as
157 *
158 * @code
159 * FESystem<dim> fe_system(FE_Q<dim>(2),1,
160 * FE_Q<dim>(1),1);
161 * @endcode
162 *
163 * Note that it would not be wise to have this class derived
164 * from FESystem as the latter concatenates the given elements into different
165 * components of a vector element, whereas the current class combines the given
166 * elements into the same components. For instance, if two scalar elements are
167 * given, the resulting element will be scalar rather than have two components
168 * when doing the same with an FESystem.
169 *
170 * The ordering of the shape function, @p interface_constrains, the @p prolongation (embedding)
171 * and the @p restriction matrices are taken from the FESystem class.
172 *
173 * @ingroup fe
174 */
175 template <int dim, int spacedim = dim>
176 class FE_Enriched : public FiniteElement<dim, spacedim>
177 {
178 public:
179 /**
180 * Constructor which takes base FiniteElement @p fe_base and the enrichment
181 * FiniteElement @p fe_enriched which will be multiplied by the @p enrichment_function.
182 *
183 * In case @p fe_enriched is other than FE_Nothing, the lifetime of the
184 * @p enrichment_function must be at least as long as the FE_Enriched object.
185 */
186 FE_Enriched(const FiniteElement<dim, spacedim> &fe_base,
187 const FiniteElement<dim, spacedim> &fe_enriched,
188 const Function<spacedim> *enrichment_function);
189
190 /**
191 * Constructor which only wraps the base FE @p fe_base.
192 * As for the enriched finite element space, FE_Nothing is used.
193 * Continuity constraints will be automatically generated when
194 * this non-enriched element is used in conjunction with enriched finite
195 * element within a DoFHandler with hp-capabilities.
196 *
197 * See the discussion in the class documentation on how to use this element
198 * in the context of hp-finite element methods.
199 */
200 FE_Enriched(const FiniteElement<dim, spacedim> &fe_base);
201
202 /**
203 * Constructor which takes pointer to the base FiniteElement @p fe_base and
204 * a vector of enriched FiniteElement's @p fe_enriched . @p fe_enriched[i]
205 * finite element will be enriched with functions in @p functions[i].
206 *
207 * This is the most general public constructor which also allows to have
208 * different enrichment functions in different disjoint parts of the domain.
209 * To that end the last argument provides an association of cell iterator
210 * to a Function. This is done to simplify the usage of this class when the
211 * number of disjoint domains with different functions is more than a few.
212 * Otherwise one would have to use different instance of this class for each
213 * disjoint enriched domain.
214 *
215 * If you don't plan to use this feature, you can utilize C++11 lambdas to
216 * define dummy functions. Below is an example which uses two functions with
217 * the first element to be enriched and a single function with the second one.
218 * @code
219 * FE_Enriched<dim> fe(
220 * &fe_base,
221 * {&fe_1, &fe_2},
222 * {{[=] (const typename Triangulation<dim>::cell_iterator &)
223 * -> const Function<dim> *
224 * {
225 * return &fe_1_function1;
226 * },
227 * [=] (const typename Triangulation<dim>::cell_iterator &)
228 * -> const Function<dim> *
229 * {
230 * return &fe_1_function2;
231 * }},
232 * {[=] (const typename Triangulation<dim>::cell_iterator &)
233 * -> const Function<dim> *
234 * {
235 * return &fe_2_function;
236 * }
237 * }});
238 * @endcode
239 *
240 * @note When using the same finite element for enrichment with N
241 * different functions, it is advised to have the second argument of size 1
242 * and the last argument of size 1 x N. The same can be achieved by providing
243 * N equivalent enrichment elements while keeping the last argument of size
244 * N x 1. However this will be much more computationally expensive.
245 *
246 * @note When using different enrichment functions on disjoint domains, no
247 * checks are done by this class that the domains are actually disjoint.
248 */
249 FE_Enriched(
250 const FiniteElement<dim, spacedim> *fe_base,
251 const std::vector<const FiniteElement<dim, spacedim> *> &fe_enriched,
252 const std::vector<std::vector<std::function<const Function<spacedim> *(
253 const typename Triangulation<dim, spacedim>::cell_iterator &)>>>
254 &functions);
255
256 private:
257 /**
258 * The most general private constructor. The first two input parameters are
259 * consistent with those in FESystem. It is used internally only with
260 * <code>multiplicities[0]=1</code>, which is a logical requirement for this
261 * finite element.
262 */
263 FE_Enriched(
264 const std::vector<const FiniteElement<dim, spacedim> *> &fes,
265 const std::vector<unsigned int> &multiplicities,
266 const std::vector<std::vector<std::function<const Function<spacedim> *(
267 const typename Triangulation<dim, spacedim>::cell_iterator &)>>>
268 &functions);
269
270 public:
271 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
272 clone() const override;
273
274 virtual UpdateFlags
275 requires_update_flags(const UpdateFlags update_flags) const override;
276
277 /**
278 * Return a string that identifies a finite element.
279 */
280 virtual std::string
281 get_name() const override;
282
283 /**
284 * Access to a composing element. The index needs to be smaller than the
285 * number of base elements. In the context of this class, the number of
286 * base elements is always more than one: a non-enriched element plus an
287 * element to be enriched, which could be FE_Nothing.
288 */
289 virtual const FiniteElement<dim, spacedim> &
290 base_element(const unsigned int index) const override;
291
292 /**
293 * Return the value of the @p ith shape function at the point @p p. @p p is a
294 * point on the reference element.
295 *
296 * This function returns meaningful values only for non-enriched element as
297 * real-space enrichment requires evaluation of the function at the point in
298 * real-space.
299 */
300 virtual double
301 shape_value(const unsigned int i, const Point<dim> &p) const override;
302
303 /**
304 * @name Transfer matrices
305 * @{
306 */
307
308 /**
309 * Projection from a fine grid space onto a coarse grid space.
310 *
311 * This function only makes sense when all child elements are also enriched
312 * using the same function(s) as the parent element.
313 */
314 virtual const FullMatrix<double> &
315 get_restriction_matrix(
316 const unsigned int child,
317 const RefinementCase<dim> &refinement_case =
318 RefinementCase<dim>::isotropic_refinement) const override;
319
320 /**
321 * Embedding matrix between grids.
322 *
323 * This function only makes sense when all child elements are also enriched
324 * using the same function(s) as the parent element.
325 */
326 virtual const FullMatrix<double> &
327 get_prolongation_matrix(
328 const unsigned int child,
329 const RefinementCase<dim> &refinement_case =
330 RefinementCase<dim>::isotropic_refinement) const override;
331
332 /** @} */
333
334 /**
335 * @name Functions to support hp
336 * @{
337 */
338
339 /**
340 * Return whether this element implements hp-constraints.
341 *
342 * This function returns @p true if and only if all its base elements return @p true
343 * for this function.
344 */
345 virtual bool
346 hp_constraints_are_implemented() const override;
347
348 /**
349 * Return the matrix interpolating from a face of one element to the face
350 * of the neighboring element. The size of the matrix is then
351 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
352 *
353 * Base elements of this element will have to implement this function. They
354 * may only provide interpolation matrices for certain source finite
355 * elements, for example those from the same family. If they don't implement
356 * interpolation from a given element, then they must throw an exception of
357 * type FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented, which
358 * will get propagated out from this element.
359 */
360 virtual void
361 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source,
362 FullMatrix<double> &matrix,
363 const unsigned int face_no = 0) const override;
364
365 /**
366 * Return the matrix interpolating from a face of one element to the
367 * subface of the neighboring element. The size of the matrix is then
368 * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
369 *
370 * Base elements of this element will have to implement this function. They
371 * may only provide interpolation matrices for certain source finite
372 * elements, for example those from the same family. If they don't implement
373 * interpolation from a given element, then they must throw an exception of
374 * type FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented, which
375 * will get propagated out from this element.
376 */
377 virtual void
378 get_subface_interpolation_matrix(
379 const FiniteElement<dim, spacedim> &source,
380 const unsigned int subface,
381 FullMatrix<double> &matrix,
382 const unsigned int face_no = 0) const override;
383
384 /**
385 * If, on a vertex, several finite elements are active, the hp-code first
386 * assigns the degrees of freedom of each of these FEs different global
387 * indices. It then calls this function to find out which of them should get
388 * identical values, and consequently can receive the same global DoF index.
389 * This function therefore returns a list of identities between DoFs of the
390 * present finite element object with the DoFs of @p fe_other, which is a
391 * reference to a finite element object representing one of the other finite
392 * elements active on this particular vertex. The function computes which of
393 * the degrees of freedom of the two finite element objects are equivalent,
394 * both numbered between zero and the corresponding value of
395 * n_dofs_per_vertex() of the two finite elements. The first index of each
396 * pair denotes one of the vertex dofs of the present element, whereas the
397 * second is the corresponding index of the other finite element.
398 */
399 virtual std::vector<std::pair<unsigned int, unsigned int>>
400 hp_vertex_dof_identities(
401 const FiniteElement<dim, spacedim> &fe_other) const override;
402
403 /**
404 * Same as hp_vertex_dof_indices(), except that the function treats degrees
405 * of freedom on lines.
406 */
407 virtual std::vector<std::pair<unsigned int, unsigned int>>
408 hp_line_dof_identities(
409 const FiniteElement<dim, spacedim> &fe_other) const override;
410
411 /**
412 * Same as hp_vertex_dof_indices(), except that the function treats degrees
413 * of freedom on quads.
414 */
415 virtual std::vector<std::pair<unsigned int, unsigned int>>
416 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
417 const unsigned int face_no = 0) const override;
418
419 /**
420 * @copydoc FiniteElement::compare_for_domination()
421 */
422 virtual FiniteElementDomination::Domination
423 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
424 const unsigned int codim = 0) const override final;
425
426 /** @} */
427
428
429 /**
430 * Return enrichment functions
431 */
432 std::vector<std::vector<std::function<const Function<spacedim> *(
433 const typename Triangulation<dim, spacedim>::cell_iterator &)>>>
434 get_enrichments() const;
435
436 /**
437 * Return the underlying FESystem object.
438 */
439 const FESystem<dim, spacedim> &
440 get_fe_system() const;
441
442 protected:
443 /**
444 * A class to hold internal data needed for evaluation of this FE at
445 * quadrature points.
446 */
447 class InternalData : public FiniteElement<dim, spacedim>::InternalDataBase
448 {
449 public:
450 /**
451 * For each Finite Element (base number) and each enrichment function
452 * (base_index) this struct will contain values, gradients and hessians of
453 * the enrichment functions.
454 */
455 struct EnrichmentValues
456 {
457 std::vector<double> values;
458 std::vector<Tensor<1, spacedim>> gradients;
459 std::vector<SymmetricTensor<2, spacedim>> hessians;
460 };
461
462 /**
463 * Constructor. Is used inside setup_data to wrap FESystem's internal
464 * data object. The former is called from get_data, get_subface_data and
465 * get_face_data which FE_Enriched has to implement.
466 *
467 * Since FESystem::get_data(), FESystem::get_face_data() and
468 * FESystem::get_subface_data() just create an object and return a pointer
469 * to it (i.e. they don't retain ownership), we store the cast result in a
470 * std::unique_ptr to indicate that InternalData owns the object.
471 */
472 InternalData(std::unique_ptr<typename FESystem<dim, spacedim>::InternalData>
473 fesystem_data);
474
475 /**
476 * Give read-access to the pointer to a @p InternalData of the @p
477 * <code>base_no</code>th base element of FESystem's data.
478 */
479 typename FiniteElement<dim, spacedim>::InternalDataBase &
480 get_fe_data(const unsigned int base_no) const;
481
482 /**
483 * Give read-access to the pointer to an object into which the
484 * <code>base_no</code>th base element will write its output when calling
485 * FiniteElement::fill_fe_values() and similar functions.
486 */
487 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim> &
488 get_fe_output_object(const unsigned int base_no) const;
489
490 /**
491 * Aggregate FESystem's internal data. It is used every time
492 * we call FESystem's fill_fe_values() and alike.
493 */
494 std::unique_ptr<typename FESystem<dim, spacedim>::InternalData>
495 fesystem_data;
496
497 /**
498 * For each FE used in enrichment (base number <code>i</code>) and each
499 * enrichment function (base multiplicity <code>j</code>),
500 * <code>enrichment_values[i][j]</code> will be used to store possibly
501 * requested values, gradients and hessians of enrichment function
502 * <code>j</code>.
503 *
504 * The variable is made mutable as InternalData's provided to fill_fe_values
505 * and alike are const.
506 *
507 * @note We do not want to store this information in the finite element object itself,
508 * because this would mean that (i) only one FEValues object could use a
509 * finite element object at a time, and (ii) that these objects could not be
510 * used in a multithreaded context.
511 */
512 mutable std::vector<std::vector<EnrichmentValues>> enrichment;
513 };
514
515 /**
516 * For each finite element @p i used in enrichment and each enrichment function
517 * @p j associated with it (essentially its multiplicity),
518 * @p base_no_mult_local_enriched_dofs[i][j] contains the associated local
519 * DoFs on the FE_Enriched finite element.
520 */
521 std::vector<std::vector<std::vector<unsigned int>>>
522 base_no_mult_local_enriched_dofs;
523
524 /**
525 * Enrichment functions.
526 * The size of the first vector is the same as the number of FiniteElement
527 * spaces used with enrichment. Whereas the size of the inner vector
528 * corresponds to the number of enrichment functions associated with a single
529 * FiniteElement.
530 */
531 const std::vector<std::vector<std::function<const Function<spacedim> *(
532 const typename Triangulation<dim, spacedim>::cell_iterator &)>>>
533 enrichments;
534
535 /**
536 * Auxiliary variable used to distinguish between the case when we do
537 * enrichment and when the class simply wraps another FiniteElement.
538 *
539 * This variable is initialized in the constructor by looping over a vector of
540 * enrichment elements and checking if all of them are FE_Nothing. If this is
541 * the case, then the value is set to <code>false</code>, otherwise it is
542 * <code>true</code>.
543 */
544 const bool is_enriched;
545
546 /**
547 * Auxiliary function called from get_data, get_face_data and
548 * get_subface_data. It take internal data of FESystem object in @p fes_data
549 * and the quadrature rule @p qudrature.
550 *
551 * This function essentially take the internal data from an instance of
552 * FESystem class and wraps it into our own InternalData class which
553 * additionally has objects to hold values/gradients/hessians of
554 * enrichment functions at each quadrature point depending on @p flags.
555 */
556 template <int dim_1>
557 std::unique_ptr<typename FiniteElement<dim, spacedim>::InternalDataBase>
558 setup_data(
559 std::unique_ptr<typename FESystem<dim, spacedim>::InternalData> fes_data,
560 const UpdateFlags flags,
561 const Quadrature<dim_1> &quadrature) const;
562
563 /**
564 * Prepare internal data structures and fill in values independent of the
565 * cell. Returns a pointer to an object of which the caller of this function
566 * (FEValues) then has to assume ownership (which includes destruction when it
567 * is no more needed).
568 */
569 virtual std::unique_ptr<
570 typename FiniteElement<dim, spacedim>::InternalDataBase>
571 get_data(
572 const UpdateFlags flags,
573 const Mapping<dim, spacedim> &mapping,
574 const Quadrature<dim> &quadrature,
575 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
576 spacedim>
577 &output_data) const override;
578
579 using FiniteElement<dim, spacedim>::get_face_data;
580
581 virtual std::unique_ptr<
582 typename FiniteElement<dim, spacedim>::InternalDataBase>
583 get_face_data(
584 const UpdateFlags update_flags,
585 const Mapping<dim, spacedim> &mapping,
586 const hp::QCollection<dim - 1> &quadrature,
587 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
588 spacedim>
589 &output_data) const override;
590
591 virtual std::unique_ptr<
592 typename FiniteElement<dim, spacedim>::InternalDataBase>
593 get_subface_data(
594 const UpdateFlags update_flags,
595 const Mapping<dim, spacedim> &mapping,
596 const Quadrature<dim - 1> &quadrature,
597 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
598 spacedim>
599 &output_data) const override;
600
601 virtual void
602 fill_fe_values(
603 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
604 const CellSimilarity::Similarity cell_similarity,
605 const Quadrature<dim> &quadrature,
606 const Mapping<dim, spacedim> &mapping,
607 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
608 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
609 &mapping_data,
610 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
611 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
612 spacedim>
613 &output_data) const override;
614
615 using FiniteElement<dim, spacedim>::fill_fe_face_values;
616
617 virtual void
618 fill_fe_face_values(
619 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
620 const unsigned int face_no,
621 const hp::QCollection<dim - 1> &quadrature,
622 const Mapping<dim, spacedim> &mapping,
623 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
624 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
625 &mapping_data,
626 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
627 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
628 spacedim>
629 &output_data) const override;
630
631 virtual void
632 fill_fe_subface_values(
633 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
634 const unsigned int face_no,
635 const unsigned int sub_no,
636 const Quadrature<dim - 1> &quadrature,
637 const Mapping<dim, spacedim> &mapping,
638 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
639 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
640 &mapping_data,
641 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
642 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
643 spacedim>
644 &output_data) const override;
645
646 private:
647 /**
648 * This function sets up the index table for the system as well as @p
649 * restriction and @p prolongation matrices.
650 */
651 void
652 initialize(const std::vector<const FiniteElement<dim, spacedim> *> &fes,
653 const std::vector<unsigned int> &multiplicities);
654
655 /**
656 * The underlying FESystem object.
657 */
658 const std::unique_ptr<const FESystem<dim, spacedim>> fe_system;
659
660 /**
661 * After calling fill_fe_(face/subface_)values this function
662 * implements the chain rule to multiply stored shape values/gradient/hessians
663 * by those of enrichment function evaluated at quadrature points.
664 */
665 template <int dim_1>
666 void
667 multiply_by_enrichment(
668 const Quadrature<dim_1> &quadrature,
669 const InternalData &fe_data,
670 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
671 &mapping_data,
672 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
673 internal::FEValuesImplementation::FiniteElementRelatedData<dim, spacedim>
674 &output_data) const;
675 };
676
677
678
679 /**
680 * This namespace consists of a class needed to create a collection
681 * of FE_Enriched finite elements (hp::FECollection)
682 * to be used with DoFHandler in hp-mode on a domain with multiple, possibly
683 * overlapping, sub-domains with individual enrichment functions.
684 *
685 * To create hp::FECollection, a graph coloring algorithm is used to assign
686 * colors to enrichment functions before creating hp::FECollection. Hence the
687 * name.
688 */
689 namespace ColorEnriched
690 {
691 /**
692 * An alias template for predicate function which returns a
693 * boolean for a Triangulation<dim,spacedim>::cell_iterator object.
694 *
695 * This is used by helper functions and in the implementation of
696 * ColorEnriched::Helper class.
697 */
698 template <int dim, int spacedim = dim>
699 using predicate_function = std::function<bool(
700 const typename Triangulation<dim, spacedim>::cell_iterator &)>;
701
702 #ifndef DOXYGEN
703 namespace internal
704 {
705 /**
706 * Returns true if there is a connection between subdomains in the mesh
707 * associated with @p dof_handler i.e., if the subdomains share at least
708 * a vertex. The two subdomains are defined by predicates provided by
709 * @p predicate_1 and @p predicate_2. A predicate is a function (or
710 * object of a type with an operator()) which takes in a cell iterator and
711 * gives a boolean. It is said to be active in a cell if it returns true.
712 *
713 * An example of a custom predicate is one that checks the distance from a
714 * fixed point. Note that the operator() takes in a cell iterator. Using the
715 * constructor, the fixed point and the distance can be chosen.
716 * @code
717 * <int dim>
718 * struct predicate
719 * {
720 * predicate(const Point<dim> p, const int radius)
721 * :p(p),radius(radius){}
722 *
723 * template <class Iterator>
724 * bool operator () (const Iterator &i)
725 * {
726 * return ( (i->center() - p).norm() < radius);
727 * }
728 *
729 * private:
730 * Point<dim> p;
731 * int radius;
732 *
733 * };
734 * @endcode
735 * and then the function can be used as follows to find if the subdomains
736 * are connected.
737 * @code
738 * find_connection_between_subdomains
739 * (dof_handler,
740 * predicate<dim>(Point<dim>(0,0), 1)
741 * predicate<dim>(Point<dim>(2,2), 1));
742 * @endcode
743 *
744 * @param[in] dof_handler DoFHandler object
745 * @param[in] predicate_1 A function (or object of a type with an
746 * operator()) defining the subdomain 1. The function takes in a cell and
747 * returns a boolean.
748 * @param[in] predicate_2 Same as @p predicate_1 but defines subdomain 2.
749 * @return A boolean "true" if the subdomains share at least a vertex.
750 */
751 template <int dim, int spacedim>
752 bool
753 find_connection_between_subdomains(
754 const DoFHandler<dim, spacedim> &dof_handler,
755 const predicate_function<dim, spacedim> &predicate_1,
756 const predicate_function<dim, spacedim> &predicate_2);
757
758 /**
759 * Assign colors to subdomains using Graph coloring algorithm where each
760 * subdomain is considered as a graph node. Subdomains which are
761 * connected i.e share at least a vertex have different color. Each
762 * subdomain
763 * is defined using a predicate function of @p predicates.
764 *
765 * @param[in] dof_handler a DoFHandler object
766 * @param[in] predicates predicates defining the subdomains
767 * @param[out] predicate_colors Colors (unsigned int) associated with each
768 * subdomain.
769 */
770 template <int dim, int spacedim>
771 unsigned int
772 color_predicates(
773 const DoFHandler<dim, spacedim> &dof_handler,
774 const std::vector<predicate_function<dim, spacedim>> &predicates,
775 std::vector<unsigned int> &predicate_colors);
776
777 /**
778 * Used to construct data members @p cellwise_color_predicate_map and
779 * @p fe_sets of Helper class. Inputs are DoFHandler object,
780 * vector of predicates and colors associated with them. Before calling
781 * this function, colors can be assigned to predicates (i.e subdomains)
782 * using the function color_predicates.
783 *
784 * Each active FE index has a set of colors associated with it.
785 * A cell with an active FE index i has a set of colors given by
786 * <code>fe_sets[i]</code>. An active FE index with color {a,b}
787 * means that the cell has two active predicates (i.e they return true
788 * for the cell) of color a and b.
789 *
790 * Eg: fe_sets = { {}, {1}, {2}, {1,2} } means
791 * Cells with active FE index 0 have no predicates associated.
792 * Cells with index 1 have a active predicate with color 1.
793 * Cells with index 2 have a active predicate with color 2.
794 * Cells with index 3 have active predicates with color 1 and color 2.
795 *
796 * A map of maps cellwise_color_predicate_map is used to associate
797 * predicate colors in cells with predicate ids. For this purpose, each
798 * cell is given a unique id which is stored in material id for now.
799 * When the grid is refined, material id is inherited to the children, so
800 * map which associates material id with color map will still be relevant.
801 *
802 * Now the color map can be explained with an example. If the cell with
803 * material id 100 has active predicates 4 (color = 1) and 5 (color = 2),
804 * the map will insert pairs (1, 4) and (2, 5) at key 100 (i.e unique id
805 * of cell is mapped with a map which associates color with predicate id).
806 *
807 * @param[in] dof_handler DoFHandler object
808 * @param[in] predicates vector of predicates defining the subdomains.
809 * <code>@p predicates[i]</code> returns true for a cell if it
810 * belongs to subdomain with index i.
811 * @param[in] predicate_colors vector of colors (unsigned int) associated
812 * with each subdomain.
813 * @param[out] cellwise_color_predicate_map A map of maps used to associate
814 * predicate colors in cells with predicate ids.
815 * @param[out] fe_sets a vector of color lists
816 */
817 template <int dim, int spacedim>
818 void
819 set_cellwise_color_set_and_fe_index(
820 DoFHandler<dim, spacedim> &dof_handler,
821 const std::vector<predicate_function<dim, spacedim>> &predicates,
822 const std::vector<unsigned int> &predicate_colors,
823 std::map<unsigned int, std::map<unsigned int, unsigned int>>
824 &cellwise_color_predicate_map,
825 std::vector<std::set<unsigned int>> &fe_sets);
826
827 /**
828 * A function that returns a vector of enrichment functions corresponding
829 * to a color. The size of the vector is equal to total number of different
830 * colors associated with predicates (i.e subdomains).
831 *
832 * Assume that a cell has a active predicates with ids 4 (color = 1) and
833 * 5 (color = 2). cellwise_color_predicate_map has this information
834 * provided we know the material id.
835 *
836 * The constructed color_enrichments is such that
837 * color_enrichments[color=1](cell) will return a pointer to
838 * the enrichment function with id=4, i.e. enrichments[4].
839 * In other words, using the previously collected information in
840 * this function we translate a vector of user provided enrichment
841 * functions into a vector of functions suitable for FE_Enriched class.
842 *
843 * @param[in] n_colors number of colors for predicates
844 * @param[in] enrichments vector of enrichment functions
845 * @param[in] cellwise_color_predicate_map A map of maps used to associate
846 * predicate colors in cells with predicate ids.
847 * @param[out] color_enrichments A vector of functions that take in cell
848 * and return a function pointer.
849 */
850 template <int dim, int spacedim>
851 void
852 make_colorwise_enrichment_functions(
853 const unsigned int n_colors,
854 const std::vector<std::shared_ptr<Function<spacedim>>> &enrichments,
855 const std::map<unsigned int, std::map<unsigned int, unsigned int>>
856 &cellwise_color_predicate_map,
857 std::vector<std::function<const Function<spacedim> *(
858 const typename Triangulation<dim, spacedim>::cell_iterator &)>>
859 &color_enrichments);
860
861
862 /**
863 * Creates a hp::FECollection object constructed using FE_Enriched
864 * elements which itself is constructed using color enrichment functions
865 * and is of size equal to number of colors.
866 *
867 * @param[in] fe_sets a vector of color lists
868 * @param[in] color_enrichments A vector of functions that take in cell
869 * and return a function pointer.
870 * @param[in] fe_base base FiniteElement
871 * @param[in] fe_enriched enriched FiniteElements
872 * @param[in] fe_nothing a finite element with zero degrees of freedom
873 * @param[out] fe_collection a collection of
874 * finite elements
875 */
876 template <int dim, int spacedim>
877 void
878 make_fe_collection_from_colored_enrichments(
879 const unsigned int n_colors,
880 const std::vector<std::set<unsigned int>>
881 &fe_sets, // total list of color sets possible
882 const std::vector<std::function<const Function<spacedim> *(
883 const typename Triangulation<dim, spacedim>::cell_iterator &)>>
884 &color_enrichments, // color wise enrichment functions
885 const FiniteElement<dim, spacedim> &fe_base, // basic FE element
886 const FiniteElement<dim, spacedim>
887 &fe_enriched, // FE multiplied by enrichment function
888 const FE_Nothing<dim, spacedim> &fe_nothing,
889 hp::FECollection<dim, spacedim> &fe_collection);
890 } // namespace internal
891 #endif // DOXYGEN
892
893
894
895 /**
896 * ColorEnriched::Helper class creates a collection of FE_Enriched finite
897 * elements (hp::FECollection) to be used with DoFHandler in a domain
898 * with multiple, possibly overlapping, sub-domains with individual
899 * enrichment functions. Note that the overlapping regions may have
900 * multiple enrichment functions associated with them. This is implemented
901 * using a general constructor of FE_Enriched object which allows different
902 * enrichment functions.
903 *
904 * Consider a domain with multiple enriched sub-domains
905 * which are disjoint i.e. not connected with each other.
906 * To ensure $C^0$ continuity at the interface between
907 * the enriched sub-domain (characterized by a single enrichment
908 * function) and the non-enriched domain, we can use an FE_Enriched
909 * object in the enriched sub-domain and in the non-enriched domain
910 * a standard finite element (eg: FE_Q) wrapped into an FE_Enriched
911 * object (which internally uses a dominating FE_Nothing object).
912 * Refer to the documentation on FE_Enriched for more
913 * information on this. It is to be noted that an FE_Enriched
914 * object is constructed using a base FE
915 * (FiniteElement objects) and one or more
916 * enriched FEs. FE_Nothing is a dummy enriched FE.
917 *
918 * The situation becomes more
919 * complicated when two enriched sub-domains
920 * share an interface. When the number of enrichment functions are
921 * same for the sub-domains, FE_Enriched object of one sub-domain
922 * is constructed such that each enriched FE is paired (figuratively) with a
923 * FE_Nothing in the FE_Enriched object of the other sub-domain.
924 * For example, let the FEs fe_enr1 and fe_enr2, which will be
925 * used with enrichment functions, correspond
926 * to the two sub-domains. Then the FE_Enriched objects of the two
927 * sub-domains are built using
928 * [fe_base, fe_enr1, fe_nothing] and
929 * [fe_base, fe_nothing, fe_enr2] respectively.
930 * Note that the size of the vector of enriched FEs
931 * (used in FE_Enriched constructor) is equal to 2, the
932 * same as the number of enrichment functions. When the number of enrichment
933 * functions is not the same, additional enriched FEs are paired
934 * with FE_Nothing. This ensures that the enriched DOF's at the interface
935 * are set to zero by the DoFTools::make_hanging_node_constraints() function.
936 * Using these two strategies, we construct the appropriate FE_Enriched
937 * using the general constructor. Note that this is
938 * done on a mesh without hanging nodes.
939 *
940 * Now consider a domain with multiple sub-domains which may share
941 * an interface with each other. As discussed previously,
942 * the number of enriched FEs in the FE_Enriched object of each
943 * sub-domain needs to be equal to the number of sub-domains. This is because
944 * we are not using the information of how the domains are connected
945 * and any sub-domain may share interface with any other sub-domain (not
946 * considering overlaps for now!). However, in general, a given sub-domain
947 * shares an interface only with a few sub-domains. This warrants
948 * the use of a graph coloring algorithm to reduce
949 * the size of the vector of enriched FEs
950 * (used in the FE_Enriched constructor). By giving the sub-domains
951 * that share no interface the same color, a single 'std::function'
952 * that returns different enrichment functions for each
953 * sub-domain can be constructed. Then the size of the vector of enriched
954 * FEs is equal to the number of different colors
955 * used for predicates (or sub-domains).
956 *
957 * @note The graph coloring function, SparsityTools::color_sparsity_pattern,
958 * used for assigning colors to the sub-domains
959 * needs MPI (use Utilities::MPI::MPI_InitFinalize to initialize MPI
960 * and the necessary Zoltan setup).
961 * The coloring function, based on Zoltan, is a parallel coloring
962 * algorithm but is used in serial by SparsityTools::color_sparsity_pattern.
963 *
964 * Construction of the Helper class needs a base FiniteElement @p fe_base,
965 * an enriched FiniteElement @p fe_enriched (used for all the
966 * enrichment functions), a vector of predicate
967 * functions (used to define sub-domains) as well as the corresponding
968 * enrichment functions. The FECollection object, a collection of FE_Enriched
969 * objects to be used with a DoFHandler object, can be retrieved
970 * using the member function build_fe_collection which also modifies the
971 * active FE indices of the DoFHandler object (provided as an argument
972 * to the build_fe_collection function).
973 *
974 * <h3>Simple example</h3>
975 * Consider a domain with three sub-domains defined by predicate functions.
976 * Different cells are associated with FE indices as shown in the following
977 * image. The three equal-sized square-shaped sub-domains 'a', 'b'
978 * and 'c' can be seen. The predicates associated with these sub-domains
979 * are also labeled 'a', 'b' and 'c'.
980 * The subdomains 'a' and 'b' intersect with cell labeled with FE
981 * index 3. The cells in 'c' are labeled with FE
982 * index 1. As can be seen, connections exist between 'a' and 'b',
983 * 'b' and 'c' but 'a' and 'c' are not connected.
984 *
985 * \htmlonly <style>div.image
986 * img[src="3source_fe_indices.png"]{width:25%;}</style> \endhtmlonly
987 * @image html 3source_fe_indices.png "Active FE indices"
988 *
989 * As discussed before, the colors of predicates are allotted using
990 * the graph coloring algorithm. Each predicate is a node in the graph and if
991 * two sub-domains share an interface, the corresponding predicates
992 * should be given different colors.
993 * (The predicate colors are different from what is shown
994 * in the image. The colors in the image are as per FE indices).
995 * Predicates 'a' and 'c' can be given the same color since they
996 * are not connected but the color given to 'b' has to be different from
997 * 'a' and 'c'.
998 *
999 * The name of finite element at an index (i) of @p fe_collection
1000 * (hp::FECollection) can be obtained by
1001 * <code>fe_collection[index].get_name()</code> and is
1002 * show in the table below. Note that all the FE_Enriched elements
1003 * are of the same size and FE_Nothing<2>(dominating) is used as
1004 * discussed before.
1005 *
1006 * <table>
1007 * <tr>
1008 * <th>Active FE index</th>
1009 * <th>FiniteElement name</th>
1010 * </tr>
1011 * <tr>
1012 * <td>0</td>
1013 * <td><code>FE_Enriched<2>[FE_Q<2>(2)-FE_Nothing<2>(dominating)-FE_Nothing<2>(dominating)]</code></td>
1014 * </tr>
1015 * <tr>
1016 * <td>1</td>
1017 * <td><code>FE_Enriched<2>[FE_Q<2>(2)-FE_Q<2>(1)-FE_Nothing<2>(dominating)]</code></td>
1018 * </tr>
1019 * <tr>
1020 * <td>2</td>
1021 * <td><code>FE_Enriched<2>[FE_Q<2>(2)-FE_Q<2>(1)-FE_Q<2>(1)]</code></td>
1022 * </tr>
1023 * <tr>
1024 * <td>3</td>
1025 * <td><code>FE_Enriched<2>[FE_Q<2>(2)-FE_Nothing<2>(dominating)-FE_Q<2>(1)]</code></td>
1026 * </tr>
1027 * </table>
1028 *
1029 * The internal data members used by this class need to be available when the
1030 * problem is solved. This can be ensured by declaring the object static,
1031 * which is deallocated only when the program terminates. An alternative
1032 * would be to use it as a data member of the containing class. Since vector
1033 * of predicates and enrichment functions may not be available while
1034 * constructing the Helper, a 'std::shared_ptr' to Helper object can be used
1035 * and constructed when the predicates and enrichment functions are
1036 * available.
1037 *
1038 * @warning The current implementation relies on assigning each cell a
1039 * material id, which shall not be modified after the setup
1040 * and h-adaptive refinement. For a given cell, the material id is used
1041 * to define color predicate map, which doesn't change with refinement.
1042 *
1043 * <h3>Example usage:</h3>
1044 * @code
1045 * FE_Q<dim> fe_base(2);
1046 * FE_Q<dim> fe_enriched(1);
1047 * std::vector< predicate_function<dim> > predicates;
1048 * std::vector< std::shared_ptr<Function<dim>> > enrichments;
1049 *
1050 * Triangulation<dim> triangulation;
1051 * DoFHandler<dim> dof_handler(triangulation);
1052 *
1053 * static ColorEnriched::Helper<dim> FE_helper(fe_base,
1054 * fe_enriched,
1055 * predicates,
1056 * enrichments);
1057 * const hp::FECollection<dim>&
1058 * fe_collection(FE_helper.build_fe_collection(dof_handler));
1059 * @endcode
1060 */
1061 template <int dim, int spacedim = dim>
1062 struct Helper
1063 {
1064 /**
1065 * Constructor for Helper class.
1066 *
1067 * @param fe_base A base FiniteElement
1068 * @param fe_enriched An enriched FiniteElement
1069 * @param predicates std::vector of predicates defining the sub-domains.
1070 * <code>@p predicates[i]</code> returns true for a cell if it
1071 * belongs to a sub-domain with index (i).
1072 * @param enrichments std::vector of enrichment functions
1073 */
1074 Helper(const FiniteElement<dim, spacedim> &fe_base,
1075 const FiniteElement<dim, spacedim> &fe_enriched,
1076 const std::vector<predicate_function<dim, spacedim>> &predicates,
1077 const std::vector<std::shared_ptr<Function<spacedim>>> &enrichments);
1078
1079 /**
1080 * Prepares a DoFHandler object. The active FE indices of
1081 * mesh cells are initialized to work with
1082 * ColorEnriched::Helper<dim,spacedim>::fe_collection.
1083 *
1084 * @param dof_handler a DoFHandler object
1085 * @return hp::FECollection, a collection of
1086 * finite elements needed by @p dof_handler.
1087 */
1088 const hp::FECollection<dim, spacedim> &
1089 build_fe_collection(DoFHandler<dim, spacedim> &dof_handler);
1090
1091 private:
1092 /**
1093 * Contains a collection of FiniteElement objects needed by a DoFHandler
1094 * object.
1095 */
1096 hp::FECollection<dim, spacedim> fe_collection;
1097
1098 /**
1099 * A base FiniteElement used for constructing FE_Enriched
1100 * object required by ColorEnriched::Helper<dim,spacedim>::fe_collection.
1101 */
1102 const FiniteElement<dim, spacedim> &fe_base;
1103
1104 /**
1105 * An enriched FiniteElement used for constructing FE_Enriched
1106 * object required by ColorEnriched::Helper<dim,spacedim>::fe_collection.
1107 */
1108 const FiniteElement<dim, spacedim> &fe_enriched;
1109
1110 /**
1111 * A finite element with zero degrees of freedom used for
1112 * constructing FE_Enriched object required by
1113 * ColorEnriched::Helper<dim,spacedim>::fe_collection
1114 */
1115 const FE_Nothing<dim, spacedim> fe_nothing;
1116
1117 /**
1118 * std::vector of predicates defining the sub-domains.
1119 * <code>@p predicates[i]</code> returns true for a cell if it
1120 * belongs to a sub-domain with index (i).
1121 */
1122 const std::vector<predicate_function<dim, spacedim>> predicates;
1123
1124 /**
1125 * std::vector of enrichment functions corresponding
1126 * to the predicates. These are needed while constructing
1127 * ColorEnriched::Helper<dim,spacedim>::fe_collection.
1128 */
1129 const std::vector<std::shared_ptr<Function<spacedim>>> enrichments;
1130
1131 /**
1132 * An alias template for any callable target such as functions, lambda
1133 * expressions, function objects that take a
1134 * Triangulation<dim,spacedim>::cell_iterator
1135 * and return a pointer to Function<dim>. This is used to define
1136 * Helper<dim,spacedim>::color_enrichments
1137 * which returns an enrichment function
1138 * for a cell in Triangulation<dim,spacedim>.
1139 */
1140 using cell_iterator_function = std::function<const Function<spacedim> *(
1141 const typename Triangulation<dim, spacedim>::cell_iterator &)>;
1142
1143 /**
1144 * std::vector of functions that take in a cell
1145 * and return a function pointer. These are needed while constructing
1146 * fe_collection.
1147 *
1148 * color_enrichments[i](cell_iterator) returns a pointer to
1149 * the correct enrichment function (i.e. whose corresponding
1150 * predicate has the color i) for the cell.
1151 */
1152 std::vector<cell_iterator_function> color_enrichments;
1153
1154 /**
1155 * std::vector of colors (unsigned int) associated
1156 * with each sub-domain. No two connected sub-domains (i.e. sub-domains that
1157 * share a vertex) have the same color.
1158 */
1159 std::vector<unsigned int> predicate_colors;
1160
1161 /**
1162 * Total number of different colors in predicate_colors
1163 */
1164 unsigned int n_colors;
1165
1166 /**
1167 * A map of maps used to associate
1168 * a cell with a map that in turn associates colors of active predicates in
1169 * the cell with corresponding predicate ids.
1170 */
1171 std::map<unsigned int, std::map<unsigned int, unsigned int>>
1172 cellwise_color_predicate_map;
1173
1174 /**
1175 * A vector of different possible color sets for a given set of
1176 * predicates and DoFHandler object
1177 */
1178 std::vector<std::set<unsigned int>> fe_sets;
1179 };
1180 } // namespace ColorEnriched
1181
1182 DEAL_II_NAMESPACE_CLOSE
1183
1184 #endif // dealii_fe_enriched_h