Debian Codegraph @

include/deal.II/fe/fe_nothing.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 2023 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_nothing_h
16 #define dealii_fe_nothing_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/fe/fe.h>
21
22 DEAL_II_NAMESPACE_OPEN
23
24
25 /**
26 * @addtogroup fe
27 * @{
28 */
29
30 /**
31 * Definition of a finite element space with zero degrees of freedom and that,
32 * consequently, can only represent a single function: the zero function.
33 *
34 * This class is useful (in the context of an hp-method) to represent empty
35 * cells in the triangulation on which no degrees of freedom should be
36 * allocated, or to describe a field that is extended by zero to a part of the
37 * domain where we don't need it. Thus a triangulation may be divided into two
38 * regions: an active region where normal elements are used, and an inactive
39 * region where FE_Nothing elements are used. The DoFHandler will therefore
40 * assign no degrees of freedom to the FE_Nothing cells, and this subregion is
41 * therefore implicitly deleted from the computation. step-10 and step-46 show
42 * use cases for this element. An interesting application for this element is
43 * also presented in the paper @cite Cangiani2012.
44 *
45 *
46 * <h3>FE_Nothing as seen as a function space</h3>
47 *
48 * Finite elements are often best interpreted as forming a
49 * [function space](https://en.wikipedia.org/wiki/Function_space), i.e., a
50 * set of functions that form a
51 * [vector space](https://en.wikipedia.org/wiki/Vector_space). One can indeed
52 * interpret FE_Nothing in this light: It corresponds to the function space
53 * $V_h=\{0\}$, i.e., the set of functions that are zero everywhere.
54 * (The constructor can take an argument that, if greater than one, extends
55 * the space to one of vector-valued functions with more than one component,
56 * with all components equal to zero everywhere.) Indeed, this is a vector
57 * space since every linear combination of elements in the vector space is
58 * also an element in the vector space, as is every multiple of the single
59 * element zero. It is obvious that the function space has no degrees of
60 * freedom, thus the name of the class.
61 *
62 *
63 * <h3>FE_Nothing in combination with other elements</h3>
64 *
65 * In situations such as those of step-46, one uses FE_Nothing on cells
66 * where one is not interested in a solution variable. For example, in fluid
67 * structure interaction problems, the fluid velocity is only defined on
68 * cells inside the fluid part of the domain. One then uses FE_Nothing
69 * on cells in the solid part of the domain to describe the finite element
70 * space for the velocity. In other words, the velocity lives everywhere
71 * conceptually, but it is identically zero in those parts of the domain
72 * where it is not of interest and doesn't use up any degrees of freedom
73 * there.
74 *
75 * The question is what happens at the interface between areas where one
76 * is interested in the solution (and uses a "normal" finite element) and
77 * where one is not interested (and uses FE_Nothing): Should the solution
78 * at that interface be zero -- i.e., we consider a "continuous" finite
79 * element field that happens to be zero in that area where FE_Nothing
80 * is used -- or is there no requirement for continuity at the interface.
81 * In the deal.II language, this is encoded by what the function
82 * FiniteElement::compare_for_domination() returns: If the FE_Nothing
83 * "dominates", then the solution must be zero at the interface; if it
84 * does not, then there is no requirement and one can think of FE_Nothing
85 * as a function space that is in general discontinuous (i.e., there is
86 * no requirement for any kind of continuity at cell interfaces) but on
87 * every cell equal to zero.
88 *
89 * A constructor argument denotes whether the element should be considered
90 * dominating or not. The default is for it not to dominate, i.e.,
91 * FE_Nothing is treated as a discontinuous element.
92 *
93 *
94 * <h3>FE_Nothing in the context of hanging nodes</h3>
95 *
96 * Note that some care must be taken that the resulting mesh topology
97 * continues to make sense when FE_Nothing elements are introduced. This is
98 * particularly true when dealing with hanging node constraints, because the
99 * library makes some basic assumptions about the nature of those constraints.
100 * The following geometries are acceptable:
101 * @code
102 * +---------+----+----+
103 * | | 0 | |
104 * | 1 +----+----+
105 * | | 0 | |
106 * +---------+----+----+
107 * @endcode
108 * @code
109 * +---------+----+----+
110 * | | 1 | |
111 * | 0 +----+----+
112 * | | 1 | |
113 * +---------+----+----+
114 * @endcode
115 * Here, 0 denotes an FE_Nothing cell, and 1 denotes some other element type.
116 * The library has no difficulty computing the necessary hanging node
117 * constraints in these cases (i.e. no constraint). However, the following
118 * geometry is NOT acceptable (at least in the current implementation):
119 * @code
120 * +---------+----+----+
121 * | | 0 | |
122 * | 1 +----+----+
123 * | | 1 | |
124 * +---------+----+----+
125 * @endcode
126 * The distinction lies in the mixed nature of the child faces, a case we have
127 * not implemented as of yet.
128 */
129 template <int dim, int spacedim = dim>
130 class FE_Nothing : public FiniteElement<dim, spacedim>
131 {
132 public:
133 /**
134 * Constructor.
135 *
136 * @param[in] type Specifies the reference-cell type.
137 *
138 * @param[in] n_components Denotes the number of
139 * vector components to give this finite element. The default is one.
140 *
141 * @param[in] dominate Decides whether FE_Nothing will dominate
142 * any other FE in compare_for_domination() (with the default being `false`).
143 * Therefore at interfaces where, for example, a $Q_1$ meets an FE_Nothing, we
144 * will force the traces of the two functions to be the same. Because the
145 * FE_Nothing encodes a space that is zero everywhere, this means that the
146 * $Q_1$ field will be forced to become zero at this interface. See also the
147 * discussion in the general documentation of this class.
148 */
149 FE_Nothing(const ReferenceCell &type,
150 const unsigned int n_components = 1,
151 const bool dominate = false);
152
153 /**
154 * Same as above but for a hypercube reference-cell type.
155 */
156 FE_Nothing(const unsigned int n_components = 1, const bool dominate = false);
157
158 virtual std::unique_ptr<FiniteElement<dim, spacedim>>
159 clone() const override;
160
161 /**
162 * Return a string that uniquely identifies a finite element. The name is
163 * <tt>FE_Nothing@<dim,spacedim@>(type, n_components, dominating)</tt> where
164 * <tt>dim</tt>, <tt>spacedim</tt>, <tt>type</tt>, and <tt>n_components</tt>
165 * are all specified by the constructor or type signature with the following
166 * exceptions:
167 * <ol>
168 * <li>If <tt>spacedim == dim</tt> then that field is not printed.</li>
169 * <li>If <tt>type</tt> is a hypercube then that field is not printed.</li>
170 * <li>If <tt>n_components == 1</tt> then that field is not printed.</li>
171 * <li>If <tt>dominate == false</tt> then that field is not printed.</li>
172 * </ol>
173 */
174 virtual std::string
175 get_name() const override;
176
177 // for documentation, see the FiniteElement base class
178 virtual UpdateFlags
179 requires_update_flags(const UpdateFlags update_flags) const override;
180
181 /**
182 * Return the value of the @p ith shape function at the point @p p. @p p is
183 * a point on the reference element. Because the current element has no
184 * degrees of freedom, this function should obviously not be called in
185 * practice. All this function really does, therefore, is trigger an
186 * exception.
187 */
188 virtual double
189 shape_value(const unsigned int i, const Point<dim> &p) const override;
190
191 virtual void
192 fill_fe_values(
193 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
194 const CellSimilarity::Similarity cell_similarity,
195 const Quadrature<dim> &quadrature,
196 const Mapping<dim, spacedim> &mapping,
197 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
198 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
199 &mapping_data,
200 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
201 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
202 spacedim>
203 &output_data) const override;
204
205 using FiniteElement<dim, spacedim>::fill_fe_face_values;
206
207 virtual void
208 fill_fe_face_values(
209 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
210 const unsigned int face_no,
211 const hp::QCollection<dim - 1> &quadrature,
212 const Mapping<dim, spacedim> &mapping,
213 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
214 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
215 &mapping_data,
216 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
217 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
218 spacedim>
219 &output_data) const override;
220
221 virtual void
222 fill_fe_subface_values(
223 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
224 const unsigned int face_no,
225 const unsigned int sub_no,
226 const Quadrature<dim - 1> &quadrature,
227 const Mapping<dim, spacedim> &mapping,
228 const typename Mapping<dim, spacedim>::InternalDataBase &mapping_internal,
229 const internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
230 &mapping_data,
231 const typename FiniteElement<dim, spacedim>::InternalDataBase &fe_internal,
232 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
233 spacedim>
234 &output_data) const override;
235
236 /**
237 * Prepare internal data structures and fill in values independent of the
238 * cell. Returns a pointer to an object of which the caller of this function
239 * then has to assume ownership (which includes destruction when it is no
240 * more needed).
241 *
242 * In the current case, this function just returns a default pointer, since
243 * no meaningful data exists for this element.
244 */
245 virtual std::unique_ptr<
246 typename FiniteElement<dim, spacedim>::InternalDataBase>
247 get_data(
248 const UpdateFlags update_flags,
249 const Mapping<dim, spacedim> &mapping,
250 const Quadrature<dim> &quadrature,
251 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
252 spacedim>
253 &output_data) const override;
254
255 /**
256 * @copydoc FiniteElement::compare_for_domination()
257 *
258 * In the current case, this element is assumed to dominate if the second
259 * argument in the constructor @p dominate is true. When this argument is
260 * false and @p fe_other is also of type FE_Nothing(), either element can
261 * dominate. Otherwise there are no_requirements.
262 *
263 * See also the discussion in the general documentation of this class.
264 */
265 virtual FiniteElementDomination::Domination
266 compare_for_domination(const FiniteElement<dim, spacedim> &fe_other,
267 const unsigned int codim = 0) const override final;
268
269
270
271 virtual std::vector<std::pair<unsigned int, unsigned int>>
272 hp_vertex_dof_identities(
273 const FiniteElement<dim, spacedim> &fe_other) const override;
274
275 virtual std::vector<std::pair<unsigned int, unsigned int>>
276 hp_line_dof_identities(
277 const FiniteElement<dim, spacedim> &fe_other) const override;
278
279 virtual std::vector<std::pair<unsigned int, unsigned int>>
280 hp_quad_dof_identities(const FiniteElement<dim, spacedim> &fe_other,
281 const unsigned int face_no = 0) const override;
282
283 virtual bool
284 hp_constraints_are_implemented() const override;
285
286 /**
287 * Return the matrix interpolating from the given finite element to the
288 * present one. Since the current finite element has no degrees of freedom,
289 * the interpolation matrix is necessarily empty.
290 */
291 virtual void
292 get_interpolation_matrix(
293 const FiniteElement<dim, spacedim> &source_fe,
294 FullMatrix<double> &interpolation_matrix) const override;
295
296 /**
297 * Return the matrix interpolating from a face of one element to the face
298 * of the neighboring element. The size of the matrix is then
299 * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
300 *
301 * Since the current finite element has no degrees of freedom, the
302 * interpolation matrix is necessarily empty.
303 */
304
305 virtual void
306 get_face_interpolation_matrix(const FiniteElement<dim, spacedim> &source_fe,
307 FullMatrix<double> &interpolation_matrix,
308 const unsigned int face_no = 0) const override;
309
310
311 /**
312 * Return the matrix interpolating from a face of one element to the
313 * subface of the neighboring element. The size of the matrix is then
314 * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
315 *
316 * Since the current finite element has no degrees of freedom, the
317 * interpolation matrix is necessarily empty.
318 */
319
320 virtual void
321 get_subface_interpolation_matrix(
322 const FiniteElement<dim, spacedim> &source_fe,
323 const unsigned int index,
324 FullMatrix<double> &interpolation_matrix,
325 const unsigned int face_no = 0) const override;
326
327 /**
328 * Return a list of constant modes of the element.
329 *
330 * Since the current finite element has no degrees of freedom, the returned
331 * list is necessarily empty.
332 */
333 virtual std::pair<Table<2, bool>, std::vector<unsigned int>>
334 get_constant_modes() const override;
335
336 /**
337 * @return true if the FE dominates any other.
338 */
339 bool
340 is_dominating() const;
341
342 private:
343 /**
344 * If true, this element will dominate any other apart from itself in
345 * compare_for_domination(). This is because a space that only contains the
346 * zero function is definitely smaller (and consequently dominant) when
347 * compared to any other finite element space.
348 */
349 const bool dominate;
350 };
351
352
353 /** @} */
354
355 DEAL_II_NAMESPACE_CLOSE
356
357 #endif