Debian Codegraph @

include/deal.II/fe/fe_nedelec_sz.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2018 - 2024 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_nedelec_sz_h
16 #define dealii_fe_nedelec_sz_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/derivative_form.h>
21 #include <deal.II/base/polynomials_integrated_legendre_sz.h>
22 #include <deal.II/base/qprojector.h>
23 #include <deal.II/base/quadrature_lib.h>
24
25 #include <deal.II/fe/fe.h>
26 #include <deal.II/fe/fe_values.h>
27 #include <deal.II/fe/mapping.h>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 /**
32 * @addtogroup fe
33 * @{
34 */
35
36 /**
37 * This class represents an implementation of the
38 * H<sup>curl</sup>-conforming N&eacute;d&eacute;lec element described in the
39 * PhD thesis @cite Zaglmayr2006. It its used in the same context as
40 * described at the top of the description for the FE_Nedelec class.
41 *
42 * This element overcomes the sign conflict issues present in
43 * traditional N&eacute;d&eacute;lec elements that arise from the edge
44 * and face parameterizations used in the basis functions. Therefore,
45 * this element should provide consistent results for general
46 * quadrilateral and hexahedral elements for which the relative
47 * orientations of edges and faces as seen from all adjacent cells are
48 * often difficult to establish.
49 *
50 * The way this element addresses the sign conflict problem is to
51 * assign local edges and faces a globally defined orientation. The
52 * local edge orientation is always chosen such that the first vertex
53 * defining the edge is the one that has the highest global vertex
54 * numbering, with the second edge vertex being that which has the
55 * lowest global vertex numbering.
56 *
57 * Similarly, the face orientation is always chosen such that the first
58 * vertex is chosen to be that with the highest global vertex numbering of the
59 * four vertices making up the face. The third vertex is then chosen to be that
60 * which is geometrically opposite the first vertex, and the second and fourth
61 * vertices are decided such that the second has a higher global vertex
62 * numbering than the fourth.
63 *
64 * To overcome the sign conflict in the case of non-conforming meshes, hanging
65 * edges (and faces in 3D) must be addressed. This element chooses the
66 * orientation of hanging edges (and faces) based on the parent cell. Moreover,
67 * the associated constraint matrix that restricts the additional DoFs
68 * originating from the hanging edges and faces must be adapted to account for
69 * the orientation of the edges and faces.
70 *
71 * Further details on this element, including some benchmarking, can be found
72 * in the paper @cite Kynch2017. For details on the implementation of the
73 * hanging node constraints, see the paper @cite Kinnewig2023.
74 */
75 template <int dim, int spacedim = dim>
76 class FE_NedelecSZ : public FiniteElement<dim, dim>
77 {
78 public:
79 static_assert(dim == spacedim,
80 "FE_NedelecSZ is only implemented for dim==spacedim!");
81
82 /**
83 * Constructor for the NedelecSZ element of given @p order. The maximal
84 * polynomial degree of the shape functions is `order+1` (in each variable;
85 * the total polynomial degree may be higher). If `order = 0`, the element is
86 * linear and has degrees of freedom only on the edges. If `order >= 1` the
87 * element has degrees of freedom on the edges, faces and volume. For example
88 * the 3d version of FE_NedelecSZ has 12 degrees of freedom for `order = 0`
89 * and 54 for `degree = 1`. It is important to have enough quadrature points
90 * in order to perform the quadrature with sufficient accuracy.
91 * For example
92 * [QGauss<dim>(order + 2)](@ref QGauss)
93 * can be used for the
94 * quadrature formula, where `order` is the order of FE_NedelecSZ.
95 */
96 FE_NedelecSZ(const unsigned int order);
97
98 virtual UpdateFlags
99 requires_update_flags(const UpdateFlags update_flags) const override;
100
101 virtual std::string
102 get_name() const override;
103
104 virtual std::unique_ptr<FiniteElement<dim, dim>>
105 clone() const override;
106
107 /**
108 * Return the value of the <tt>i</tt>th shape function at the point
109 * <tt>p</tt>. See the FiniteElement base class for more information about
110 * the semantics of this function.
111 *
112 * Since this element is vector-valued, this function will
113 * throw an exception.
114 */
115 virtual double
116 shape_value(const unsigned int i, const Point<dim> &p) const override;
117
118 /**
119 * Return the value of the <tt>component</tt>th vector component of the
120 * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
121 * FiniteElement base class for more information about the semantics of this
122 * function.
123 */
124 virtual double
125 shape_value_component(const unsigned int i,
126 const Point<dim> &p,
127 const unsigned int component) const override;
128
129 /**
130 * Return the gradient of the <tt>i</tt>th shape function at the point
131 * <tt>p</tt>. See the FiniteElement base class for more information about
132 * the semantics of this function.
133 *
134 * Since this element is vector-valued, this function will
135 * throw an exception.
136 */
137 virtual Tensor<1, dim>
138 shape_grad(const unsigned int i, const Point<dim> &p) const override;
139
140 /**
141 * Return the gradient of the <tt>component</tt>th vector component of the
142 * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
143 * FiniteElement base class for more information about the semantics of this
144 * function.
145 */
146 virtual Tensor<1, dim>
147 shape_grad_component(const unsigned int i,
148 const Point<dim> &p,
149 const unsigned int component) const override;
150
151 /**
152 * Return the tensor of second derivatives of the <tt>i</tt>th shape
153 * function at point <tt>p</tt> on the unit cell. See the FiniteElement base
154 * class for more information about the semantics of this function.
155 *
156 * Since this element is vector-valued, this function will
157 * throw an exception.
158 */
159 virtual Tensor<2, dim>
160 shape_grad_grad(const unsigned int i, const Point<dim> &p) const override;
161
162 /**
163 * Return the second derivative of the <tt>component</tt>th vector component
164 * of the <tt>i</tt>th shape function at the point <tt>p</tt>. See the
165 * FiniteElement base class for more information about the semantics of this
166 * function.
167 */
168 virtual Tensor<2, dim>
169 shape_grad_grad_component(const unsigned int i,
170 const Point<dim> &p,
171 const unsigned int component) const override;
172
173 /**
174 * Embedding matrix between grids.
175 *
176 * The identity operator from a coarse grid space into a fine grid space is
177 * associated with a matrix @p P. The restriction of this matrix @p P_i to a
178 * single child cell is returned here.
179 *
180 * The matrix @p P is the concatenation, not the sum of the cell matrices @p
181 * P_i. That is, if the same non-zero entry <tt>j,k</tt> exists in two
182 * different child matrices @p P_i, the value should be the same in both
183 * matrices and it is copied into the matrix @p P only once.
184 *
185 * Row and column indices are related to fine grid and coarse grid spaces,
186 * respectively, consistent with the definition of the associated operator.
187 *
188 * These matrices are used by routines assembling the prolongation matrix
189 * for multi-level methods. Upon assembling the transfer matrix between
190 * cells using this matrix array, zero elements in the prolongation matrix
191 * are discarded and will not fill up the transfer matrix.
192 */
193 virtual const FullMatrix<double> &
194 get_prolongation_matrix(
195 const unsigned int child,
196 const RefinementCase<dim> &refinement_case =
197 RefinementCase<dim>::isotropic_refinement) const override;
198
199 protected:
200 /**
201 * The mapping kind to be used to map shape functions from the reference
202 * cell to the mesh cell.
203 */
204 MappingKind mapping_kind;
205
206 /**
207 * Compute the value and the derivatives of the Nedelec functions at
208 * the points given in <tt>p_list</tt>.
209 */
210 void
211 evaluate(const std::vector<Point<dim>> &p_list,
212 const UpdateFlags update_flags,
213 std::unique_ptr<
214 typename dealii::FiniteElement<dim, spacedim>::InternalDataBase>
215 &data_ptr) const;
216
217 virtual std::unique_ptr<
218 typename dealii::FiniteElement<dim, spacedim>::InternalDataBase>
219 get_data(
220 const UpdateFlags update_flags,
221 const Mapping<dim, spacedim> &mapping,
222 const Quadrature<dim> &quadrature,
223 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
224 spacedim>
225 &output_data) const override;
226
227 /**
228 * Compute information about the shape functions on the cell denoted by the
229 * first argument. Note that this function must recompute the cell-dependent
230 * degrees of freedom, and so is not thread-safe at this time.
231 */
232 virtual void
233 fill_fe_values(
234 const typename Triangulation<dim, dim>::cell_iterator &cell,
235 const CellSimilarity::Similarity cell_similarity,
236 const Quadrature<dim> &quadrature,
237 const Mapping<dim, dim> &mapping,
238 const typename Mapping<dim, dim>::InternalDataBase &mapping_internal,
239 const internal::FEValuesImplementation::MappingRelatedData<dim, dim>
240 &mapping_data,
241 const typename FiniteElement<dim, dim>::InternalDataBase &fedata,
242 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim, dim>
243 &data) const override;
244
245 using FiniteElement<dim, spacedim>::fill_fe_face_values;
246
247 /**
248 * Compute information about the shape functions on the cell and face denoted
249 * by the first two arguments. Note that this function must recompute the
250 * cell-dependent degrees of freedom, and so is not thread-safe at this time.
251 */
252 virtual void
253 fill_fe_face_values(
254 const typename Triangulation<dim, dim>::cell_iterator &cell,
255 const unsigned int face_no,
256 const hp::QCollection<dim - 1> &quadrature,
257 const Mapping<dim, dim> &mapping,
258 const typename Mapping<dim, dim>::InternalDataBase &mapping_internal,
259 const internal::FEValuesImplementation::MappingRelatedData<dim, dim>
260 &mapping_data,
261 const typename FiniteElement<dim, dim>::InternalDataBase &fedata,
262 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim, dim>
263 &data) const override;
264
265 /**
266 * Not implemented.
267 */
268 virtual void
269 fill_fe_subface_values(
270 const typename Triangulation<dim, dim>::cell_iterator &cell,
271 const unsigned int face_no,
272 const unsigned int sub_no,
273 const Quadrature<dim - 1> &quadrature,
274 const Mapping<dim, dim> &mapping,
275 const typename Mapping<dim, dim>::InternalDataBase &mapping_internal,
276 const internal::FEValuesImplementation::MappingRelatedData<dim, dim>
277 &mapping_data,
278 const typename FiniteElement<dim, dim>::InternalDataBase &fedata,
279 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim, dim>
280 &data) const override;
281
282 /**
283 * Derived Internal data which is used to store cell-independent data.
284 * Note that due to the nature of this element, a number of useful
285 * pre-computed quantities are stored for the computation of cell-dependent
286 * shape functions.
287 *
288 * The main quantities which are stored are associated with edge and face
289 * parameterizations. These are:
290 * <ul>
291 * <li> $\lambda_{i}$ - trilinear function, equal to one at the $i$-th vertex
292 * and zero at all other vertices.</li>
293 * <li> $\sigma_{i}$ - linear functional associated with the $i$-th vertex.</li>
294 * </ul>
295 *
296 * The definitions of these functionals, as well as the edge and face
297 * parameterizations and edge and face extension parameters, can be found on
298 * page 82 of Zaglmayr's thesis. The details of the definition of the
299 * globally-defined edge and face orientations can be found on page 67.
300 */
301 class InternalData : public FiniteElement<dim, dim>::InternalDataBase
302 {
303 public:
304 /**
305 * Storage for shape functions on the reference element. We only pre-compute
306 * cell-based DoFs, as the edge- and face-based DoFs depend on the cell.
307 *
308 * Due to the cell-dependent DoFs, this variable is declared mutable.
309 */
310 mutable std::vector<std::vector<Tensor<1, dim>>> shape_values;
311
312 /**
313 * Storage for shape function gradients on the reference element. We only
314 * pre-compute cell-based DoFs, as the edge- and face-based DoFs depend on
315 * the cell.
316 *
317 * Due to the cell-dependent DoFs, this variable is declared mutable.
318 */
319 mutable std::vector<std::vector<DerivativeForm<1, dim, dim>>> shape_grads;
320
321 /**
322 * Storage for shape function hessians on the reference element. We only
323 * pre-compute cell-based DoFs, as the edge- and face-based DoFs depend on
324 * the cell.
325 *
326 * Due to the cell-dependent DoFs, this variable is declared mutable.
327 */
328 mutable std::vector<std::vector<DerivativeForm<2, dim, dim>>>
329 shape_hessians;
330
331 /**
332 * Storage for all possible edge parameterization between vertices. These
333 * are required in the computation of edge- and face-based DoFs, which are
334 * cell-dependent.
335 *
336 * The edge parameterization of an edge, E, starting at vertex i and ending
337 * at vertex $j$ is given by $\sigma_{E} = \sigma_{i} - \sigma{j}$.
338 *
339 * sigma_imj_values[q][i][j] stores the value of the edge parameterization
340 * connected by vertices $i$ and $j$ at the q-th quadrature point.
341 *
342 * Note that not all of the $i$ and $j$ combinations result in valid edges
343 * on the hexahedral cell, but they are computed in this fashion for use
344 * with non-standard edge and face orientations.
345 */
346 std::vector<std::vector<std::vector<double>>> sigma_imj_values;
347
348 /**
349 * Storage for gradients of all possible edge parameterizations between
350 * vertices. These are required in the computation of edge- and face-based
351 * DoFs, which are cell-dependent. Note that the components of the gradient
352 * are constant.
353 *
354 * The edge parameterization of an edge, $E$, starting at vertex $i$ and
355 * ending at vertex $j$ is given by $\sigma_{E} = \sigma_{i} - \sigma{j}$.
356 *
357 * sigma_imj_grads[i][j][d] stores the gradient of the edge parameterization
358 * connected by vertices $i$ and $j$ in component $d$.
359 *
360 * Note that the gradient of the edge parameterization is constant on an
361 * edge, so we do not need to store it at every quadrature point.
362 */
363 std::vector<std::vector<std::vector<double>>> sigma_imj_grads;
364
365 /**
366 * Storage for values of edge parameterizations at quadrature points. These
367 * are stored for the 12 edges such that the global vertex numbering would
368 * follow the order defined by the "standard" deal.II cell.
369 *
370 * edge_sigma_values[m][q] stores the edge parameterization value at the
371 * q-th quadrature point on edge m.
372 *
373 * These values change with the orientation of the edges of a physical cell
374 * and so must take the "sign" into account when used for computation.
375 */
376 std::vector<std::vector<double>> edge_sigma_values;
377
378 /**
379 * Storage for gradients of edge parameterization at quadrature points.
380 * These are stored for the 12 edges such that the global vertex numbering
381 * would follow the order defined by the "standard" deal.II cell.
382 *
383 * edge_sigma_grads[m][d] stores the gradient of the edge parameterization
384 * for component d on edge m.
385 *
386 * These values change with the orientation of the edges of a physical cell
387 * and so must take the "sign" into account when used for computation.
388 */
389 std::vector<std::vector<double>> edge_sigma_grads;
390
391 /**
392 * Storage for edge extension parameters at quadrature points. These are
393 * stored for the 12 edges such that the global vertex numbering would
394 * follow the order defined by the "standard" deal.II cell.
395 *
396 * The edge extension parameter of an edge, $E$, starting at vertex $i$ and
397 * ending at vertex $j$ is given by $\lambda_{E} = \lambda_{i} +
398 * \lambda_{j}$.
399 *
400 * Note that under this definition, the values of $\lambda_{E}$ do not
401 * change with the orientation of the edge.
402 *
403 * edge_lambda_values[m][q] stores the edge extension parameter value at
404 * the $q$-th quadrature point on edge $m$.
405 */
406 std::vector<std::vector<double>> edge_lambda_values;
407
408 /**
409 * Storage for gradients of edge extension parameters in 2d. In this case
410 * they are constant. These are stored for the 12 edges such that the global
411 * vertex numbering* would follow the order defined by the "standard"
412 * deal.II cell.
413 *
414 * edge_lambda_grads_2d[m][d] stores the gradient of the edge extension
415 * parameter for component $d$ on edge $m$.
416 */
417 std::vector<std::vector<double>> edge_lambda_grads_2d;
418
419 /**
420 * Storage for gradients of edge extension parameters in 3d. In this case
421 * they are non-constant. These are stored for the 12 edges such that the
422 * global vertex numbering* would follow the order defined by the
423 * "standard" deal.II cell.
424 *
425 * edge_lambda_grads_3d[m][q][d] stores the gradient of the edge extension
426 * parameter for component $d$ at the $q$-th quadrature point on edge m.
427 */
428 std::vector<std::vector<std::vector<double>>> edge_lambda_grads_3d;
429
430 /**
431 * Storage for 2nd derivatives of edge extension parameters in 3d, which are
432 * constant across the cell. These are stored for the 12 edges such that the
433 * global vertex numbering* would follow the order defined by the
434 * "standard" deal.II cell.
435 *
436 * edge_lambda_gradgrads_3d[m][d1][d2] stores the 2nd derivatives of the
437 * edge extension parameters with respect to components d1 and d2 on edge
438 * $m$.
439 */
440 std::vector<std::vector<std::vector<double>>> edge_lambda_gradgrads_3d;
441
442 /**
443 * Storage for the face extension parameters. These are stored for the 6
444 * faces such that the global vertex numbering would follow the order
445 * defined by the "standard" deal.II cell.
446 *
447 * The face extension parameter of a face, F, defined by the vertices
448 * v1, v2, v3, v4 is given by
449 * $\lambda_{F} = \lambda_{v1} + \lambda_{v2} + \lambda_{v3} +
450 * \lambda_{v4}$.
451 *
452 * Note that under this definition, the values of $\lambda_{F}$ do not
453 * change with the orientation of the face.
454 *
455 * face_lambda_values[m][q] stores the face extension parameter value at
456 * the $q$-th quadrature point on face $m$.
457 */
458 std::vector<std::vector<double>> face_lambda_values;
459
460 /**
461 * Storage for gradients of face extension parameters. These are stored for
462 * the 6 faces such that the global vertex numbering would follow the order
463 * defined by the "standard" deal.II cell.
464 *
465 * face_lambda_grads[m][d] stores the gradient of the face extension
466 * parameters for component $d$ on face $m$.
467 */
468 std::vector<std::vector<double>> face_lambda_grads;
469 };
470
471 private:
472 /**
473 * Internal function to return a vector of "dofs per object"
474 * where the components of the returned vector refer to:
475 * 0 = vertex
476 * 1 = edge
477 * 2 = face (which is a cell in 2d)
478 * 3 = cell
479 */
480 static std::vector<unsigned int>
481 get_dpo_vector(const unsigned int degree);
482
483 /**
484 * Internal storage for all required integrated Legendre polynomials.
485 */
486 std::vector<Polynomials::Polynomial<double>> IntegratedLegendrePolynomials;
487
488 /**
489 * Internal function to populate the internal array of integrated Legendre
490 * polynomials.
491 */
492 void
493 create_polynomials(const unsigned int degree);
494
495 /**
496 * Returns the number of DoFs in the basis set.
497 */
498 unsigned int
499 compute_num_dofs(const unsigned int degree) const;
500
501 /**
502 * Populates cell-dependent edge-based shape functions on the given
503 * InternalData object.
504 */
505 void
506 fill_edge_values(const typename Triangulation<dim, dim>::cell_iterator &cell,
507 const Quadrature<dim> &quadrature,
508 const InternalData &fedata) const;
509
510 /**
511 * Populates the cell-dependent face-based shape functions on the given
512 * InternalData object.
513 */
514 void
515 fill_face_values(const typename Triangulation<dim, dim>::cell_iterator &cell,
516 const Quadrature<dim> &quadrature,
517 const InternalData &fedata) const;
518
519 /**
520 * Mutex variables used for protecting the initialization of restriction
521 * and embedding matrices.
522 */
523 mutable Threads::Mutex prolongation_matrix_mutex;
524 };
525
526
527
528 /** @} */
529
530 DEAL_II_NAMESPACE_CLOSE
531
532 #endif