Reference documentation for deal.II version 9.4.0
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
fe_tools.h
Go to the documentation of this file.
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 2000 - 2022 by the deal.II authors
4 //
5 // This file is part of the deal.II library.
6 //
7 // The deal.II library is free software; you can use it, redistribute
8 // it, and/or modify it under the terms of the GNU Lesser General
9 // Public License as published by the Free Software Foundation; either
10 // version 2.1 of the License, or (at your option) any later version.
11 // The full text of the license can be found in the file LICENSE.md at
12 // the top level directory of deal.II.
13 //
14 // ---------------------------------------------------------------------
15 
16 #ifndef dealii_fe_tools_H
17 #define dealii_fe_tools_H
18 
19 
20 
21 #include <deal.II/base/config.h>
22 
27 #include <deal.II/base/tensor.h>
28 
30 
32 
34 
35 #include <memory>
36 #include <string>
37 #include <vector>
38 
39 
41 
42 // Forward declarations
43 #ifndef DOXYGEN
44 template <typename number>
45 class FullMatrix;
46 template <int dim>
47 class Quadrature;
48 template <int dim, int spacedim>
49 class FiniteElement;
50 template <int dim, int spacedim>
51 class DoFHandler;
52 template <int dim>
53 class FiniteElementData;
54 template <typename number>
55 class AffineConstraints;
56 #endif
57 
58 
61 
62 
75 namespace FETools
76 {
85  template <int dim, int spacedim = dim>
86  class FEFactoryBase : public Subscriptor
87  {
88  public:
92  virtual std::unique_ptr<FiniteElement<dim, spacedim>>
93  get(const unsigned int degree) const = 0;
94 
100  virtual std::unique_ptr<FiniteElement<dim, spacedim>>
101  get(const Quadrature<1> &quad) const = 0;
102 
106  virtual ~FEFactoryBase() override = default;
107  };
108 
118  template <class FE>
119  class FEFactory : public FEFactoryBase<FE::dimension, FE::space_dimension>
120  {
121  public:
125  virtual std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>>
126  get(const unsigned int degree) const override;
127 
132  virtual std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>>
133  get(const Quadrature<1> &quad) const override;
134  };
135 
151  template <int dim, int spacedim>
152  void
154  std::vector<unsigned int> & renumbering,
155  std::vector<std::vector<unsigned int>> &start_indices);
156 
172  template <int dim, int spacedim>
173  void
175  std::vector<types::global_dof_index> &renumbering,
176  std::vector<types::global_dof_index> &block_data,
177  bool return_start_indices = true);
178 
192  template <int dim, typename number, int spacedim>
193  void
195  const FiniteElement<dim, spacedim> &fe2,
196  FullMatrix<number> &interpolation_matrix);
197 
209  template <int dim, typename number, int spacedim>
210  void
212  const FiniteElement<dim, spacedim> &fe2,
213  FullMatrix<number> &interpolation_matrix);
214 
226  template <int dim, typename number, int spacedim>
227  void
229  const FiniteElement<dim, spacedim> &fe2,
230  FullMatrix<number> &difference_matrix);
231 
235  template <int dim, typename number, int spacedim>
236  void
238  const FiniteElement<dim, spacedim> &fe2,
240 
309  template <int dim, int spacedim>
312 
351  template <int dim, typename number, int spacedim>
352  void
354  const FiniteElement<dim, spacedim> & fe,
355  std::vector<std::vector<FullMatrix<number>>> &matrices,
356  const bool isotropic_only = false,
357  const double threshold = 1.e-12);
358 
380  template <int dim, typename number, int spacedim>
381  void
385  const unsigned int face_coarse,
386  const unsigned int face_fine,
387  const double threshold = 1.e-12);
388 
420  template <int dim, typename number, int spacedim>
421  void
423  const FiniteElement<dim, spacedim> & fe,
424  std::vector<std::vector<FullMatrix<number>>> &matrices,
425  const bool isotropic_only = false);
426 
512  template <int dim, int spacedim>
513  void
516  const Quadrature<dim> & lhs_quadrature,
517  const Quadrature<dim> & rhs_quadrature,
518  FullMatrix<double> & X);
519 
527  template <int dim, int spacedim>
528  void
531  const Quadrature<dim> & quadrature,
532  FullMatrix<double> & I_q);
533 
547  template <int dim>
548  void
550  const FullMatrix<double> & projection_matrix,
551  const std::vector<Tensor<1, dim>> &vector_of_tensors_at_qp,
552  std::vector<Tensor<1, dim>> & vector_of_tensors_at_nodes);
553 
554 
555 
559  template <int dim>
560  void
562  const FullMatrix<double> & projection_matrix,
563  const std::vector<SymmetricTensor<2, dim>> &vector_of_tensors_at_qp,
564  std::vector<SymmetricTensor<2, dim>> & vector_of_tensors_at_nodes);
565 
566 
567 
577  template <int dim, int spacedim>
578  void
581  const Quadrature<dim - 1> & lhs_quadrature,
582  const Quadrature<dim - 1> & rhs_quadrature,
584  const unsigned int face,
585  FullMatrix<double> & X);
586 
587 
588 
604  template <int dim, int spacedim, typename number>
605  void
607  const FiniteElement<dim, spacedim> &finite_element,
608  const std::vector<Vector<number>> & support_point_values,
609  std::vector<number> & dof_values);
610 
611 
612 
614 
647  template <int dim, int spacedim, class InVector, class OutVector>
648  void
650  const InVector & u1,
651  const DoFHandler<dim, spacedim> &dof2,
652  OutVector & u2);
653 
670  template <int dim, int spacedim, class InVector, class OutVector>
671  void
673  const DoFHandler<dim, spacedim> & dof1,
674  const InVector & u1,
675  const DoFHandler<dim, spacedim> & dof2,
677  OutVector & u2);
678 
692  template <int dim, class InVector, class OutVector, int spacedim>
693  void
695  const InVector & u1,
696  const FiniteElement<dim, spacedim> &fe2,
697  OutVector & u1_interpolated);
698 
711  template <int dim, class InVector, class OutVector, int spacedim>
712  void
714  const DoFHandler<dim, spacedim> & dof1,
716  const InVector & u1,
717  const DoFHandler<dim, spacedim> & dof2,
719  OutVector & u1_interpolated);
720 
730  template <int dim, class InVector, class OutVector, int spacedim>
731  void
733  const InVector & z1,
734  const FiniteElement<dim, spacedim> &fe2,
735  OutVector & z1_difference);
736 
749  template <int dim, class InVector, class OutVector, int spacedim>
750  void
752  const DoFHandler<dim, spacedim> & dof1,
754  const InVector & z1,
755  const DoFHandler<dim, spacedim> & dof2,
757  OutVector & z1_difference);
758 
759 
760 
769  template <int dim, class InVector, class OutVector, int spacedim>
770  void
772  const InVector & u1,
773  const DoFHandler<dim, spacedim> &dof2,
774  OutVector & u2);
775 
836  template <int dim, class InVector, class OutVector, int spacedim>
837  void
839  const InVector & z1,
840  const DoFHandler<dim, spacedim> &dof2,
841  OutVector & z2);
842 
855  template <int dim, class InVector, class OutVector, int spacedim>
856  void
858  const DoFHandler<dim, spacedim> & dof1,
859  const InVector & z1,
860  const DoFHandler<dim, spacedim> & dof2,
862  OutVector & z2);
863 
865 
879  template <int dim>
880  std::vector<unsigned int>
882 
889  template <int dim>
890  std::vector<unsigned int>
892 
968  namespace Compositing
969  {
986  template <int dim, int spacedim>
989  const std::vector<const FiniteElement<dim, spacedim> *> &fes,
990  const std::vector<unsigned int> & multiplicities,
991  const bool do_tensor_product = true);
992 
998  template <int dim, int spacedim>
1001  const std::initializer_list<
1002  std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1003  &fe_systems);
1004 
1008  template <int dim, int spacedim>
1011  const unsigned int N1,
1012  const FiniteElement<dim, spacedim> *fe2 = nullptr,
1013  const unsigned int N2 = 0,
1014  const FiniteElement<dim, spacedim> *fe3 = nullptr,
1015  const unsigned int N3 = 0,
1016  const FiniteElement<dim, spacedim> *fe4 = nullptr,
1017  const unsigned int N4 = 0,
1018  const FiniteElement<dim, spacedim> *fe5 = nullptr,
1019  const unsigned int N5 = 0);
1020 
1033  template <int dim, int spacedim>
1034  std::vector<bool>
1036  const std::vector<const FiniteElement<dim, spacedim> *> &fes,
1037  const std::vector<unsigned int> & multiplicities);
1038 
1044  template <int dim, int spacedim>
1045  std::vector<bool>
1047  const std::initializer_list<
1048  std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1049  &fe_systems);
1050 
1065  template <int dim, int spacedim>
1066  std::vector<bool>
1068  const FiniteElement<dim, spacedim> *fe1,
1069  const unsigned int N1,
1070  const FiniteElement<dim, spacedim> *fe2 = nullptr,
1071  const unsigned int N2 = 0,
1072  const FiniteElement<dim, spacedim> *fe3 = nullptr,
1073  const unsigned int N3 = 0,
1074  const FiniteElement<dim, spacedim> *fe4 = nullptr,
1075  const unsigned int N4 = 0,
1076  const FiniteElement<dim, spacedim> *fe5 = nullptr,
1077  const unsigned int N5 = 0);
1078 
1079 
1096  template <int dim, int spacedim>
1097  std::vector<ComponentMask>
1099  const std::vector<const FiniteElement<dim, spacedim> *> &fes,
1100  const std::vector<unsigned int> & multiplicities,
1101  const bool do_tensor_product = true);
1102 
1108  template <int dim, int spacedim>
1109  std::vector<ComponentMask>
1111  const std::initializer_list<
1112  std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1113  &fe_systems);
1114 
1133  template <int dim, int spacedim>
1134  std::vector<ComponentMask>
1136  const FiniteElement<dim, spacedim> *fe1,
1137  const unsigned int N1,
1138  const FiniteElement<dim, spacedim> *fe2 = nullptr,
1139  const unsigned int N2 = 0,
1140  const FiniteElement<dim, spacedim> *fe3 = nullptr,
1141  const unsigned int N3 = 0,
1142  const FiniteElement<dim, spacedim> *fe4 = nullptr,
1143  const unsigned int N4 = 0,
1144  const FiniteElement<dim, spacedim> *fe5 = nullptr,
1145  const unsigned int N5 = 0,
1146  const bool do_tensor_product = true);
1147 
1164  template <int dim, int spacedim>
1165  void
1167  std::vector<std::pair<std::pair<unsigned int, unsigned int>,
1168  unsigned int>> &system_to_base_table,
1169  std::vector<std::pair<unsigned int, unsigned int>>
1170  & system_to_component_table,
1171  std::vector<std::pair<std::pair<unsigned int, unsigned int>,
1172  unsigned int>> &component_to_base_table,
1173  const FiniteElement<dim, spacedim> & finite_element,
1174  const bool do_tensor_product = true);
1175 
1191  template <int dim, int spacedim>
1192  void
1194  std::vector<std::pair<std::pair<unsigned int, unsigned int>,
1195  unsigned int>> &face_system_to_base_table,
1196  std::vector<std::pair<unsigned int, unsigned int>>
1197  & face_system_to_component_table,
1198  const FiniteElement<dim, spacedim> &finite_element,
1199  const bool do_tensor_product = true,
1200  const unsigned int face_no = 0 /*TODO*/);
1201 
1202  } // namespace Compositing
1203 
1204 
1238  template <int dim, int spacedim = dim>
1239  std::unique_ptr<FiniteElement<dim, spacedim>>
1240  get_fe_by_name(const std::string &name);
1241 
1284  template <int dim, int spacedim>
1285  void
1286  add_fe_name(const std::string & name,
1287  const FEFactoryBase<dim, spacedim> *factory);
1288 
1299  std::string,
1300  << "Can't re-generate a finite element from the string '"
1301  << arg1 << "'.");
1302 
1315  char,
1316  int,
1317  << "The dimension " << arg1
1318  << " in the finite element string must match "
1319  << "the space dimension " << arg2 << '.');
1320 
1327 
1341 
1349  "You are using continuous elements on a grid with "
1350  "hanging nodes but without providing hanging node "
1351  "constraints. Use the respective function with "
1352  "additional AffineConstraints argument(s), instead.");
1365  int,
1366  int,
1367  int,
1368  int,
1369  << "This is a " << arg1 << 'x' << arg2 << " matrix, "
1370  << "but should be a " << arg3 << 'x' << arg4 << " matrix.");
1371 
1378  double,
1379  << "Least squares fit leaves a gap of " << arg1);
1380 
1387  int,
1388  int,
1389  << arg1 << " must be greater than " << arg2);
1390 } // namespace FETools
1391 
1392 
1393 #ifndef DOXYGEN
1394 
1395 namespace FETools
1396 {
1397  template <class FE>
1398  std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>>
1399  FEFactory<FE>::get(const unsigned int degree) const
1400  {
1401  return std::make_unique<FE>(degree);
1402  }
1403 
1404  namespace Compositing
1405  {
1406  template <int dim, int spacedim>
1407  std::vector<bool>
1409  const std::initializer_list<
1410  std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1411  &fe_systems)
1412  {
1413  std::vector<const FiniteElement<dim, spacedim> *> fes;
1414  std::vector<unsigned int> multiplicities;
1415 
1416  const auto extract =
1417  [&fes, &multiplicities](
1418  const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1419  unsigned int> &fe_system) {
1420  fes.push_back(fe_system.first.get());
1421  multiplicities.push_back(fe_system.second);
1422  };
1423 
1424  for (const auto &p : fe_systems)
1425  extract(p);
1426 
1427  return compute_restriction_is_additive_flags(fes, multiplicities);
1428  }
1429 
1430 
1431 
1432  template <int dim, int spacedim>
1435  const std::initializer_list<
1436  std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1437  &fe_systems)
1438  {
1439  std::vector<const FiniteElement<dim, spacedim> *> fes;
1440  std::vector<unsigned int> multiplicities;
1441 
1442  const auto extract =
1443  [&fes, &multiplicities](
1444  const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1445  unsigned int> &fe_system) {
1446  fes.push_back(fe_system.first.get());
1447  multiplicities.push_back(fe_system.second);
1448  };
1449 
1450  for (const auto &p : fe_systems)
1451  extract(p);
1452 
1453  return multiply_dof_numbers(fes, multiplicities, true);
1454  }
1455 
1456 
1457 
1458  template <int dim, int spacedim>
1459  std::vector<ComponentMask>
1461  const std::initializer_list<
1462  std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>>
1463  &fe_systems)
1464  {
1465  std::vector<const FiniteElement<dim, spacedim> *> fes;
1466  std::vector<unsigned int> multiplicities;
1467 
1468  const auto extract =
1469  [&fes, &multiplicities](
1470  const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>,
1471  unsigned int> &fe_system) {
1472  fes.push_back(fe_system.first.get());
1473  multiplicities.push_back(fe_system.second);
1474  };
1475 
1476  for (const auto &p : fe_systems)
1477  extract(p);
1478 
1479  return compute_nonzero_components(fes, multiplicities, true);
1480  }
1481  } // namespace Compositing
1482 } // namespace FETools
1483 
1484 #endif
1485 
1489 
1490 #endif /* dealii_fe_tools_H */
virtual ~FEFactoryBase() override=default
virtual std::unique_ptr< FiniteElement< dim, spacedim > > get(const unsigned int degree) const =0
virtual std::unique_ptr< FiniteElement< dim, spacedim > > get(const Quadrature< 1 > &quad) const =0
virtual std::unique_ptr< FiniteElement< FE::dimension, FE::space_dimension > > get(const unsigned int degree) const override
virtual std::unique_ptr< FiniteElement< FE::dimension, FE::space_dimension > > get(const Quadrature< 1 > &quad) const override
Definition: vector.h:109
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:442
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:443
static ::ExceptionBase & ExcTriangulationMismatch()
static ::ExceptionBase & ExcNotGreaterThan(int arg1, int arg2)
static ::ExceptionBase & ExcGridNotRefinedAtLeastOnce()
#define DeclException0(Exception0)
Definition: exceptions.h:464
static ::ExceptionBase & ExcInvalidFEDimension(char arg1, int arg2)
static ::ExceptionBase & ExcInvalidFE()
static ::ExceptionBase & ExcMatrixDimensionMismatch(int arg1, int arg2, int arg3, int arg4)
static ::ExceptionBase & ExcInvalidFEName(std::string arg1)
#define DeclException4(Exception4, type1, type2, type3, type4, outsequence)
Definition: exceptions.h:578
static ::ExceptionBase & ExcLeastSquaresError(double arg1)
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:532
static ::ExceptionBase & ExcHangingNodesNotAllowed()
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:487
static ::ExceptionBase & ExcFENotPrimitive()
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:509
FiniteElementData< dim > multiply_dof_numbers(const std::vector< const FiniteElement< dim, spacedim > * > &fes, const std::vector< unsigned int > &multiplicities, const bool do_tensor_product=true)
std::vector< ComponentMask > compute_nonzero_components(const std::vector< const FiniteElement< dim, spacedim > * > &fes, const std::vector< unsigned int > &multiplicities, const bool do_tensor_product=true)
std::vector< bool > compute_restriction_is_additive_flags(const std::vector< const FiniteElement< dim, spacedim > * > &fes, const std::vector< unsigned int > &multiplicities)
void build_cell_tables(std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int >> &system_to_base_table, std::vector< std::pair< unsigned int, unsigned int >> &system_to_component_table, std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int >> &component_to_base_table, const FiniteElement< dim, spacedim > &finite_element, const bool do_tensor_product=true)
void build_face_tables(std::vector< std::pair< std::pair< unsigned int, unsigned int >, unsigned int >> &face_system_to_base_table, std::vector< std::pair< unsigned int, unsigned int >> &face_system_to_component_table, const FiniteElement< dim, spacedim > &finite_element, const bool do_tensor_product=true, const unsigned int face_no=0)
void interpolation_difference(const DoFHandler< dim, spacedim > &dof1, const InVector &z1, const FiniteElement< dim, spacedim > &fe2, OutVector &z1_difference)
std::vector< unsigned int > hierarchic_to_lexicographic_numbering(unsigned int degree)
void project_dg(const DoFHandler< dim, spacedim > &dof1, const InVector &u1, const DoFHandler< dim, spacedim > &dof2, OutVector &u2)
void get_back_interpolation_matrix(const FiniteElement< dim, spacedim > &fe1, const FiniteElement< dim, spacedim > &fe2, FullMatrix< number > &interpolation_matrix)
void compute_component_wise(const FiniteElement< dim, spacedim > &fe, std::vector< unsigned int > &renumbering, std::vector< std::vector< unsigned int >> &start_indices)
void get_projection_matrix(const FiniteElement< dim, spacedim > &fe1, const FiniteElement< dim, spacedim > &fe2, FullMatrix< number > &matrix)
void compute_embedding_matrices(const FiniteElement< dim, spacedim > &fe, std::vector< std::vector< FullMatrix< number >>> &matrices, const bool isotropic_only=false, const double threshold=1.e-12)
void compute_projection_matrices(const FiniteElement< dim, spacedim > &fe, std::vector< std::vector< FullMatrix< number >>> &matrices, const bool isotropic_only=false)
void add_fe_name(const std::string &name, const FEFactoryBase< dim, spacedim > *factory)
std::vector< unsigned int > lexicographic_to_hierarchic_numbering(unsigned int degree)
void compute_interpolation_to_quadrature_points_matrix(const FiniteElement< dim, spacedim > &fe, const Quadrature< dim > &quadrature, FullMatrix< double > &I_q)
FullMatrix< double > compute_node_matrix(const FiniteElement< dim, spacedim > &fe)
void convert_generalized_support_point_values_to_dof_values(const FiniteElement< dim, spacedim > &finite_element, const std::vector< Vector< number >> &support_point_values, std::vector< number > &dof_values)
void compute_projection_from_quadrature_points_matrix(const FiniteElement< dim, spacedim > &fe, const Quadrature< dim > &lhs_quadrature, const Quadrature< dim > &rhs_quadrature, FullMatrix< double > &X)
void get_interpolation_matrix(const FiniteElement< dim, spacedim > &fe1, const FiniteElement< dim, spacedim > &fe2, FullMatrix< number > &interpolation_matrix)
void extrapolate(const DoFHandler< dim, spacedim > &dof1, const InVector &z1, const DoFHandler< dim, spacedim > &dof2, OutVector &z2)
void compute_face_embedding_matrices(const FiniteElement< dim, spacedim > &fe, FullMatrix< number >(&matrices)[GeometryInfo< dim >::max_children_per_face], const unsigned int face_coarse, const unsigned int face_fine, const double threshold=1.e-12)
void interpolate(const DoFHandler< dim, spacedim > &dof1, const InVector &u1, const DoFHandler< dim, spacedim > &dof2, OutVector &u2)
std::unique_ptr< FiniteElement< dim, spacedim > > get_fe_by_name(const std::string &name)
void compute_block_renumbering(const FiniteElement< dim, spacedim > &fe, std::vector< types::global_dof_index > &renumbering, std::vector< types::global_dof_index > &block_data, bool return_start_indices=true)
void compute_projection_from_face_quadrature_points_matrix(const FiniteElement< dim, spacedim > &fe, const Quadrature< dim - 1 > &lhs_quadrature, const Quadrature< dim - 1 > &rhs_quadrature, const typename DoFHandler< dim, spacedim >::active_cell_iterator &cell, const unsigned int face, FullMatrix< double > &X)
void get_interpolation_difference_matrix(const FiniteElement< dim, spacedim > &fe1, const FiniteElement< dim, spacedim > &fe2, FullMatrix< number > &difference_matrix)
void compute_projection_from_quadrature_points(const FullMatrix< double > &projection_matrix, const std::vector< Tensor< 1, dim >> &vector_of_tensors_at_qp, std::vector< Tensor< 1, dim >> &vector_of_tensors_at_nodes)
void back_interpolate(const DoFHandler< dim, spacedim > &dof1, const InVector &u1, const FiniteElement< dim, spacedim > &fe2, OutVector &u1_interpolated)
@ matrix
Contents is actually a matrix.
constexpr ReturnType< rank, T >::value_type & extract(T &t, const ArrayType &indices)