Reference documentation for deal.II version Git 4e8af90f34 2022-01-22 18:32:44 +0100
\(\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\}}\)
dof_accessor.h
Go to the documentation of this file.
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2021 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_dof_accessor_h
17 #define dealii_dof_accessor_h
18 
19 
20 #include <deal.II/base/config.h>
21 
24 
26 
27 #include <deal.II/hp/dof_handler.h>
28 
30 #include <boost/container/small_vector.hpp>
32 
33 #include <vector>
34 
36 
37 // Forward declarations
38 #ifndef DOXYGEN
39 template <typename number>
40 class FullMatrix;
41 template <typename number>
42 class Vector;
43 template <typename number>
44 class AffineConstraints;
45 
46 template <typename Accessor>
47 class TriaRawIterator;
48 
49 template <int, int>
50 class FiniteElement;
51 
52 namespace internal
53 {
54  namespace DoFCellAccessorImplementation
55  {
56  struct Implementation;
57  }
58 
59  namespace DoFHandlerImplementation
60  {
61  struct Implementation;
62  namespace Policy
63  {
64  struct Implementation;
65  }
66  } // namespace DoFHandlerImplementation
67 
68  namespace hp
69  {
70  namespace DoFHandlerImplementation
71  {
72  struct Implementation;
73  }
74  } // namespace hp
75 } // namespace internal
76 #endif
77 
78 // note: the file dof_accessor.templates.h is included at the end of
79 // this file. this includes a lot of templates and thus makes
80 // compilation slower, but at the same time allows for more aggressive
81 // inlining and thus faster code.
82 
83 
84 namespace internal
85 {
86  namespace DoFAccessorImplementation
87  {
104  template <int structdim, int dim, int spacedim>
105  struct Inheritance
106  {
112  };
113 
114 
120  template <int dim, int spacedim>
121  struct Inheritance<dim, dim, spacedim>
122  {
128  };
129 
130  struct Implementation;
131  } // namespace DoFAccessorImplementation
132 } // namespace internal
133 
134 
135 /* -------------------------------------------------------------------------- */
136 
137 
138 
210 template <int structdim, int dim, int spacedim, bool level_dof_access>
211 class DoFAccessor : public ::internal::DoFAccessorImplementation::
212  Inheritance<structdim, dim, spacedim>::BaseClass
213 {
214 public:
219  static const unsigned int dimension = dim;
220 
225  static const unsigned int space_dimension = spacedim;
226 
231  using BaseClass = typename ::internal::DoFAccessorImplementation::
232  Inheritance<structdim, dimension, space_dimension>::BaseClass;
233 
238 
249  DoFAccessor();
250 
267  const int level,
268  const int index,
269  const DoFHandler<dim, spacedim> * dof_handler);
270 
275  default;
276 
280  DoFAccessor( // NOLINT
282  default; // NOLINT
283 
287  ~DoFAccessor() = default;
288 
301  template <int structdim2, int dim2, int spacedim2>
303 
308  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
309  DoFAccessor(
311 
315  template <bool level_dof_access2>
317 
329  delete;
330 
335  operator=( // NOLINT
337  default; // NOLINT
338 
347  get_dof_handler() const;
348 
352  template <bool level_dof_access2>
353  void
355 
360  void
361  copy_from(const TriaAccessorBase<structdim, dim, spacedim> &da);
362 
367  static bool
368  is_level_cell();
369 
381  child(const unsigned int c) const;
382 
388  typename ::internal::DoFHandlerImplementation::
389  Iterators<dim, spacedim, level_dof_access>::line_iterator
390  line(const unsigned int i) const;
391 
397  typename ::internal::DoFHandlerImplementation::
398  Iterators<dim, spacedim, level_dof_access>::quad_iterator
399  quad(const unsigned int i) const;
400 
446  void
447  get_dof_indices(std::vector<types::global_dof_index> &dof_indices,
448  const unsigned int fe_index =
450 
457  void
458  get_mg_dof_indices(const int level,
459  std::vector<types::global_dof_index> &dof_indices,
460  const unsigned int fe_index =
462 
466  void
467  set_mg_dof_indices(
468  const int level,
469  const std::vector<types::global_dof_index> &dof_indices,
470  const unsigned int fe_index = DoFHandler<dim, spacedim>::invalid_fe_index);
471 
494  vertex_dof_index(const unsigned int vertex,
495  const unsigned int i,
496  const unsigned int fe_index =
498 
505  mg_vertex_dof_index(const int level,
506  const unsigned int vertex,
507  const unsigned int i,
508  const unsigned int fe_index =
510 
539  dof_index(const unsigned int i,
540  const unsigned int fe_index =
542 
547  mg_dof_index(const int level, const unsigned int i) const;
548 
570  unsigned int
571  n_active_fe_indices() const;
572 
580  unsigned int
581  nth_active_fe_index(const unsigned int n) const;
582 
589  std::set<unsigned int>
590  get_active_fe_indices() const;
591 
601  bool
602  fe_index_is_active(const unsigned int fe_index) const;
603 
610  get_fe(const unsigned int fe_index) const;
611 
621  DeclExceptionMsg(ExcInvalidObject,
622  "This accessor object has not been "
623  "associated with any DoFHandler object.");
629  DeclException0(ExcVectorNotEmpty);
635  DeclException0(ExcVectorDoesNotMatch);
641  DeclException0(ExcMatrixDoesNotMatch);
649  DeclException0(ExcNotActive);
656 
657 protected:
662 
663 public:
677  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
678  bool
679  operator==(
681 
685  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
686  bool
687  operator!=(
689 
690 protected:
694  void
695  set_dof_handler(DoFHandler<dim, spacedim> *dh);
696 
715  void
716  set_dof_index(const unsigned int i,
718  const unsigned int fe_index =
720 
721  void
722  set_mg_dof_index(const int level,
723  const unsigned int i,
724  const types::global_dof_index index) const;
725 
726  void
727  set_mg_vertex_dof_index(const int level,
728  const unsigned int vertex,
729  const unsigned int i,
731  const unsigned int fe_index =
733 
734  // Iterator classes need to be friends because they need to access
735  // operator== and operator!=.
736  template <typename>
737  friend class TriaRawIterator;
738  template <int, int, int, bool>
739  friend class DoFAccessor;
740 
741 private:
742  // Make the DoFHandler class a friend so that it can call the set_xxx()
743  // functions.
744  template <int, int>
745  friend class DoFHandler;
746 
747  friend struct ::internal::DoFHandlerImplementation::Policy::
748  Implementation;
749  friend struct ::internal::DoFHandlerImplementation::Implementation;
750  friend struct ::internal::hp::DoFHandlerImplementation::Implementation;
751  friend struct ::internal::DoFCellAccessorImplementation::Implementation;
752  friend struct ::internal::DoFAccessorImplementation::Implementation;
753 };
754 
755 
756 
764 template <int spacedim, bool level_dof_access>
765 class DoFAccessor<0, 1, spacedim, level_dof_access>
766  : public TriaAccessor<0, 1, spacedim>
767 {
768 public:
773  static const unsigned int dimension = 1;
774 
779  static const unsigned int space_dimension = spacedim;
780 
786 
791 
802  DoFAccessor();
803 
820  DoFAccessor(
822  const typename TriaAccessor<0, 1, spacedim>::VertexKind vertex_kind,
823  const unsigned int vertex_index,
824  const DoFHandler<1, spacedim> * dof_handler);
825 
833  const int = 0,
834  const int = 0,
835  const DoFHandler<1, spacedim> *dof_handler = 0);
836 
849  template <int structdim2, int dim2, int spacedim2>
851 
856  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
857  DoFAccessor(
859 
864 
868  // NOLINTNEXTLINE OSX does not compile with noexcept
870 
874  ~DoFAccessor() = default;
875 
886  operator=(const DoFAccessor<0, 1, spacedim, level_dof_access> &da) = delete;
887 
892  operator=(DoFAccessor<0, 1, spacedim, level_dof_access> &&) noexcept =
893  default;
894 
902  const DoFHandler<1, spacedim> &
903  get_dof_handler() const;
904 
908  template <bool level_dof_access2>
909  void
910  copy_from(const DoFAccessor<0, 1, spacedim, level_dof_access2> &a);
911 
916  void
917  copy_from(const TriaAccessorBase<0, 1, spacedim> &da);
918 
931  TriaIterator<DoFAccessor<0, 1, spacedim, level_dof_access>>
932  child(const unsigned int c) const;
933 
940  typename ::internal::DoFHandlerImplementation::
941  Iterators<1, spacedim, level_dof_access>::line_iterator
942  line(const unsigned int i) const;
943 
950  typename ::internal::DoFHandlerImplementation::
951  Iterators<1, spacedim, level_dof_access>::quad_iterator
952  quad(const unsigned int i) const;
953 
997  void
998  get_dof_indices(
999  std::vector<types::global_dof_index> &dof_indices,
1000  const unsigned int fe_index = AccessorData::invalid_fe_index) const;
1001 
1008  void
1009  get_mg_dof_indices(
1010  const int level,
1011  std::vector<types::global_dof_index> &dof_indices,
1012  const unsigned int fe_index = AccessorData::invalid_fe_index) const;
1013 
1033  vertex_dof_index(
1034  const unsigned int vertex,
1035  const unsigned int i,
1036  const unsigned int fe_index = AccessorData::invalid_fe_index) const;
1037 
1056  dof_index(const unsigned int i,
1057  const unsigned int fe_index = AccessorData::invalid_fe_index) const;
1058 
1077  unsigned int
1078  n_active_fe_indices() const;
1079 
1087  unsigned int
1088  nth_active_fe_index(const unsigned int n) const;
1089 
1098  bool
1099  fe_index_is_active(const unsigned int fe_index) const;
1100 
1106  const FiniteElement<1, spacedim> &
1107  get_fe(const unsigned int fe_index) const;
1108 
1118  DeclExceptionMsg(ExcInvalidObject,
1119  "This accessor object has not been "
1120  "associated with any DoFHandler object.");
1126  DeclException0(ExcVectorNotEmpty);
1132  DeclException0(ExcVectorDoesNotMatch);
1138  DeclException0(ExcMatrixDoesNotMatch);
1146  DeclException0(ExcNotActive);
1153 
1154 protected:
1158  DoFHandler<1, spacedim> *dof_handler;
1159 
1163  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
1164  bool
1165  operator==(
1166  const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
1167 
1171  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
1172  bool
1173  operator!=(
1174  const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
1175 
1179  void
1180  set_dof_handler(DoFHandler<1, spacedim> *dh);
1181 
1200  void
1201  set_dof_index(
1202  const unsigned int i,
1203  const types::global_dof_index index,
1204  const unsigned int fe_index = AccessorData::invalid_fe_index) const;
1205 
1206  // Iterator classes need to be friends because they need to access
1207  // operator== and operator!=.
1208  template <typename>
1209  friend class TriaRawIterator;
1210 
1211 
1212  // Make the DoFHandler class a friend so that it can call the set_xxx()
1213  // functions.
1214  template <int, int>
1215  friend class DoFHandler;
1216 
1217  friend struct ::internal::DoFHandlerImplementation::Policy::
1218  Implementation;
1219  friend struct ::internal::DoFHandlerImplementation::Implementation;
1220  friend struct ::internal::hp::DoFHandlerImplementation::Implementation;
1221  friend struct ::internal::DoFCellAccessorImplementation::Implementation;
1222 };
1223 
1224 
1225 
1226 /* -------------------------------------------------------------------------- */
1227 
1228 
1249 template <int structdim, int dim, int spacedim = dim>
1250 class DoFInvalidAccessor : public InvalidAccessor<structdim, dim, spacedim>
1251 {
1252 public:
1256  using AccessorData =
1258 
1267  const int level = -1,
1268  const int index = -1,
1269  const AccessorData * local_data = 0);
1270 
1279 
1284  template <typename OtherAccessor>
1285  DoFInvalidAccessor(const OtherAccessor &);
1286 
1293  dof_index(const unsigned int i,
1294  const unsigned int fe_index =
1296 
1302  void
1303  set_dof_index(const unsigned int i,
1304  const types::global_dof_index index,
1305  const unsigned int fe_index =
1307 };
1308 
1309 
1310 
1311 /* -------------------------------------------------------------------------- */
1312 
1313 
1325 template <int dimension_, int space_dimension_, bool level_dof_access>
1326 class DoFCellAccessor : public DoFAccessor<dimension_,
1327  dimension_,
1328  space_dimension_,
1329  level_dof_access>
1330 {
1331 public:
1335  static const unsigned int dim = dimension_;
1336 
1340  static const unsigned int spacedim = space_dimension_;
1341 
1342 
1347 
1352  using BaseClass =
1354 
1359 
1364  using face_iterator = TriaIterator<DoFAccessor<dimension_ - 1,
1365  dimension_,
1366  space_dimension_,
1367  level_dof_access>>;
1368 
1380  const int level,
1381  const int index,
1382  const AccessorData *local_data);
1383 
1396  template <int structdim2, int dim2, int spacedim2>
1398 
1403  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
1404  explicit DoFCellAccessor(
1406 
1412  default;
1413 
1417  DoFCellAccessor( // NOLINT
1419  &&) = default; // NOLINT
1420 
1424  ~DoFCellAccessor() = default;
1425 
1436  operator=(
1438  delete;
1439 
1444  operator=( // NOLINT
1446  &&) = default; // NOLINT
1447 
1462  parent() const;
1463 
1477  neighbor(const unsigned int i) const;
1478 
1485  periodic_neighbor(const unsigned int i) const;
1486 
1493  neighbor_or_periodic_neighbor(const unsigned int i) const;
1494 
1501  child(const unsigned int i) const;
1502 
1506  boost::container::small_vector<
1507  TriaIterator<
1510  child_iterators() const;
1511 
1519  face(const unsigned int i) const;
1520 
1524  boost::container::small_vector<face_iterator,
1526  face_iterators() const;
1527 
1535  neighbor_child_on_subface(const unsigned int face_no,
1536  const unsigned int subface_no) const;
1537 
1545  periodic_neighbor_child_on_subface(const unsigned int face_no,
1546  const unsigned int subface_no) const;
1547 
1576  template <class InputVector, typename number>
1577  void
1578  get_dof_values(const InputVector &values, Vector<number> &local_values) const;
1579 
1597  template <class InputVector, typename ForwardIterator>
1598  void
1599  get_dof_values(const InputVector &values,
1600  ForwardIterator local_values_begin,
1601  ForwardIterator local_values_end) const;
1602 
1623  template <class InputVector, typename ForwardIterator>
1624  void
1625  get_dof_values(
1627  const InputVector & values,
1628  ForwardIterator local_values_begin,
1629  ForwardIterator local_values_end) const;
1630 
1655  template <class OutputVector, typename number>
1656  void
1657  set_dof_values(const Vector<number> &local_values,
1658  OutputVector & values) const;
1659 
1691  template <class InputVector, typename number>
1692  void
1693  get_interpolated_dof_values(
1694  const InputVector &values,
1695  Vector<number> & interpolated_values,
1696  const unsigned int fe_index =
1698 
1751  template <class OutputVector, typename number>
1752  void
1753  set_dof_values_by_interpolation(
1754  const Vector<number> &local_values,
1755  OutputVector & values,
1756  const unsigned int fe_index =
1758 
1773  template <typename number, typename OutputVector>
1774  void
1775  distribute_local_to_global(const Vector<number> &local_source,
1776  OutputVector & global_destination) const;
1777 
1792  template <typename ForwardIterator, typename OutputVector>
1793  void
1794  distribute_local_to_global(ForwardIterator local_source_begin,
1795  ForwardIterator local_source_end,
1796  OutputVector & global_destination) const;
1797 
1811  template <typename ForwardIterator, typename OutputVector>
1812  void
1813  distribute_local_to_global(
1815  ForwardIterator local_source_begin,
1816  ForwardIterator local_source_end,
1817  OutputVector & global_destination) const;
1818 
1825  template <typename number, typename OutputMatrix>
1826  void
1827  distribute_local_to_global(const FullMatrix<number> &local_source,
1828  OutputMatrix &global_destination) const;
1829 
1834  template <typename number, typename OutputMatrix, typename OutputVector>
1835  void
1836  distribute_local_to_global(const FullMatrix<number> &local_matrix,
1837  const Vector<number> & local_vector,
1838  OutputMatrix & global_matrix,
1839  OutputVector & global_vector) const;
1840 
1865  void
1866  get_active_or_mg_dof_indices(
1867  std::vector<types::global_dof_index> &dof_indices) const;
1868 
1900  void
1901  get_dof_indices(std::vector<types::global_dof_index> &dof_indices) const;
1902 
1907  void
1908  get_mg_dof_indices(std::vector<types::global_dof_index> &dof_indices) const;
1909 
1935  get_fe() const;
1936 
1962  unsigned int
1963  active_fe_index() const;
1964 
1991  void
1992  set_active_fe_index(const unsigned int i) const;
2001  void
2002  set_dof_indices(const std::vector<types::global_dof_index> &dof_indices);
2003 
2007  void
2008  set_mg_dof_indices(const std::vector<types::global_dof_index> &dof_indices);
2009 
2013  void
2014  update_cell_dof_indices_cache() const;
2015 
2042  get_future_fe() const;
2043 
2062  unsigned int
2063  future_fe_index() const;
2064 
2073  void
2074  set_future_fe_index(const unsigned int i) const;
2075 
2082  bool
2083  future_fe_index_set() const;
2084 
2093  void
2094  clear_future_fe_index() const;
2099 private:
2100  // Make the DoFHandler class a friend so that it can call the
2101  // update_cell_dof_indices_cache() function
2102  template <int, int>
2103  friend class DoFHandler;
2104  friend struct ::internal::DoFCellAccessorImplementation::Implementation;
2105 };
2106 
2107 
2108 template <int structdim, int dim, int spacedim, bool level_dof_access>
2109 inline bool
2111 {
2112  return level_dof_access;
2113 }
2114 
2115 
2116 
2117 template <int structdim, int dim, int spacedim>
2118 template <typename OtherAccessor>
2120  const OtherAccessor &)
2121 {
2122  Assert(false,
2123  ExcMessage("You are attempting an illegal conversion between "
2124  "iterator/accessor types. The constructor you call "
2125  "only exists to make certain template constructs "
2126  "easier to write as dimension independent code but "
2127  "the conversion is not valid in the current context."));
2128 }
2129 
2130 
2131 
2133 
2134 // include more templates
2135 #include "dof_accessor.templates.h"
2136 
2137 
2138 #endif
bool operator!=(const AlignedVector< T > &lhs, const AlignedVector< T > &rhs)
const ::Triangulation< dim, spacedim > & tria
STL namespace.
typename InvalidAccessor< structdim, dim, spacedim >::AccessorData AccessorData
typename ::internal::DoFAccessorImplementation::Inheritance< structdim, dimension, space_dimension >::BaseClass BaseClass
Definition: dof_accessor.h:232
bool operator==(const AlignedVector< T > &lhs, const AlignedVector< T > &rhs)
typename TriaAccessorBase< structdim, dim, spacedim >::AccessorData AccessorData
#define DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
Definition: config.h:420
static ::ExceptionBase & ExcMessage(std::string arg1)
Definition: types.h:31
#define Assert(cond, exc)
Definition: exceptions.h:1461
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:487
#define DeclException0(Exception0)
Definition: exceptions.h:464
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:407
unsigned int level
Definition: grid_out.cc:4617
Definition: hp.h:117
unsigned int global_dof_index
Definition: types.h:76
static bool is_level_cell()
DoFHandler< dim, spacedim > * dof_handler
Definition: dof_accessor.h:661
DoFInvalidAccessor(const Triangulation< dim, spacedim > *parent=0, const int level=-1, const int index=-1, const AccessorData *local_data=0)
Definition: dof_accessor.cc:46
#define DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
Definition: config.h:458
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:406
void get_active_fe_indices(const DoFHandler< dim, spacedim > &dof_handler, std::vector< unsigned int > &active_fe_indices)
Definition: dof_tools.cc:1302
static ::ExceptionBase & ExcCantCompareIterators()