Debian Codegraph @

include/deal.II/fe/mapping_q_eulerian.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2008 - 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
16 #ifndef dealii_mapping_q_eulerian_h
17 #define dealii_mapping_q_eulerian_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/mutex.h>
22 #include <deal.II/base/observer_pointer.h>
23
24 #include <deal.II/dofs/dof_accessor.h>
25 #include <deal.II/dofs/dof_handler.h>
26
27 #include <deal.II/fe/fe_values.h>
28 #include <deal.II/fe/mapping_q.h>
29
30 #include <deal.II/grid/tria_iterator.h>
31
32 #include <boost/container/small_vector.hpp>
33
34
35 DEAL_II_NAMESPACE_OPEN
36
37 template <typename>
38 class Vector;
39
40
41 /**
42 * @addtogroup mapping
43 * @{
44 */
45
46 /**
47 * This class is an extension of the MappingQ1Eulerian class to higher order
48 * $Q_p$ mappings. It is useful when one wants to calculate shape function
49 * information on a domain that is deforming as the computation proceeds.
50 *
51 * <h3>Usage</h3>
52 *
53 * The constructor of this class takes three arguments: the polynomial degree
54 * of the desired Qp mapping, a reference to the vector that defines the
55 * mapping from the initial configuration to the current configuration, and a
56 * reference to the DoFHandler. The most common case is to use the solution
57 * vector for the problem under consideration as the shift vector. The key
58 * requirement is that the number of components of the given vector field must
59 * be equal to (or possibly greater than) the number of space dimensions. If
60 * there are more components than space dimensions (for example, if one is
61 * working with a coupled problem where there are additional solution
62 * variables), the first <tt>dim</tt> components are assumed to represent the
63 * displacement field, and the remaining components are ignored. If this
64 * assumption does not hold one may need to set up a separate DoFHandler on
65 * the triangulation and associate the desired shift vector to it.
66 *
67 * Typically, the DoFHandler operates on a finite element that is constructed
68 * as a system element (FESystem) from continuous FE_Q objects. An example
69 * is shown below:
70 * @code
71 * FESystem<dim> fe(FE_Q<dim>(2), dim, FE_Q<dim>(1), 1);
72 * DoFHandler<dim> dof_handler(triangulation);
73 * dof_handler.distribute_dofs(fe);
74 * Vector<double> displacement_field(dof_handler.n_dofs());
75 * // ... compute displacement field somehow...
76 * MappingQEulerian<dim> q2_mapping(2, dof_handler, displacement_field);
77 * @endcode
78 *
79 * In this example, our element consists of <tt>(dim+1)</tt> components. Only
80 * the first <tt>dim</tt> components will be used, however, to define the Q2
81 * mapping. The remaining components are ignored.
82 *
83 * Note that it is essential to call the distribute_dofs(...) function before
84 * constructing a mapping object.
85 *
86 * Also note that since the vector of shift values and the dof handler are
87 * only associated to this object at construction time, you have to make sure
88 * that whenever you use this object, the given objects still represent valid
89 * data.
90 *
91 * To enable the use of the MappingQEulerian class also in the context of
92 * parallel codes using the PETSc or Trilinos wrapper classes, the type
93 * of the vector can be specified as template parameter <tt>VectorType</tt>.
94 */
95 template <int dim, typename VectorType = Vector<double>, int spacedim = dim>
96 class MappingQEulerian : public MappingQ<dim, spacedim>
97 {
98 public:
99 /**
100 * Constructor.
101 *
102 * @param[in] degree The polynomial degree of the desired $Q_p$ mapping.
103 * @param[in] euler_dof_handler A DoFHandler object that defines a finite
104 * element space. This space needs to have at least dim components and the
105 * first dim components of the space will be considered displacements
106 * relative to the original positions of the cells of the triangulation.
107 * @param[in] euler_vector A finite element function in the space defined by
108 * the second argument. The first dim components of this function will be
109 * interpreted as the displacement we use in defining the mapping, relative
110 * to the location of cells of the underlying triangulation.
111 * @param[in] level The multi-grid level at which the mapping will
112 * be used. It is mainly used to check if the size of the @p euler_vector
113 * is consistent with the @p euler_dof_handler .
114 */
115 MappingQEulerian(const unsigned int degree,
116 const DoFHandler<dim, spacedim> &euler_dof_handler,
117 const VectorType &euler_vector,
118 const unsigned int level = numbers::invalid_unsigned_int);
119
120 /**
121 * Return the mapped vertices of the cell. For the current class, this
122 * function does not use the support points from the geometry of the current
123 * cell but instead evaluates an externally given displacement field in
124 * addition to the geometry of the cell.
125 */
126 virtual boost::container::small_vector<Point<spacedim>,
127 #ifndef _MSC_VER
128 ReferenceCells::max_n_vertices<dim>()
129 #else
130 GeometryInfo<dim>::vertices_per_cell
131 #endif
132 >
133 get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell)
134 const override;
135
136 /**
137 * Return a pointer to a copy of the present object. The caller of this copy
138 * then assumes ownership of it.
139 */
140 virtual std::unique_ptr<Mapping<dim, spacedim>>
141 clone() const override;
142
143 /**
144 * Always return @p false because MappingQEulerian does not in general
145 * preserve vertex locations (unless the translation vector happens to
146 * provide zero displacements at vertex locations).
147 */
148 virtual bool
149 preserves_vertex_locations() const override;
150
151 // for documentation, see the Mapping base class
152 virtual std::vector<Point<spacedim>>
153 compute_mapping_support_points(
154 const typename Triangulation<dim, spacedim>::cell_iterator &cell)
155 const override;
156
157 /**
158 * Exception which is thrown when the mapping is being evaluated at
159 * non-active cell.
160 */
161 DeclException0(ExcInactiveCell);
162
163 protected:
164 /**
165 * Compute mapping-related information for a cell. See the documentation of
166 * Mapping::fill_fe_values() for a discussion of purpose, arguments, and
167 * return value of this function.
168 *
169 * This function overrides the function in the base class since we cannot
170 * use any cell similarity for this class.
171 */
172 virtual CellSimilarity::Similarity
173 fill_fe_values(
174 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
175 const CellSimilarity::Similarity cell_similarity,
176 const Quadrature<dim> &quadrature,
177 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
178 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
179 &output_data) const override;
180
181 /**
182 * Reference to the vector of shifts.
183 */
184 ObserverPointer<const VectorType, MappingQEulerian<dim, VectorType, spacedim>>
185 euler_vector;
186
187 /**
188 * Pointer to the DoFHandler to which the mapping vector is associated.
189 */
190 ObserverPointer<const DoFHandler<dim, spacedim>,
191 MappingQEulerian<dim, VectorType, spacedim>>
192 euler_dof_handler;
193
194 private:
195 /**
196 * Multigrid level at which the mapping is to be used.
197 */
198 const unsigned int level;
199
200 /**
201 * Special quadrature rule used to define the support points in the
202 * reference configuration.
203 */
204 class SupportQuadrature : public Quadrature<dim>
205 {
206 public:
207 /**
208 * Constructor, with an argument defining the desired polynomial degree.
209 */
210 SupportQuadrature(const unsigned int map_degree);
211 };
212
213 /**
214 * A member variable holding the quadrature points in the right order.
215 */
216 const SupportQuadrature support_quadrature;
217
218 /**
219 * A MappingQ object, which is used by the fe_values
220 * member variable to compute the undeformed mapping support
221 * points, before adding any deformation.
222 */
223 const MappingQ<dim, spacedim> mapping_q;
224
225 /**
226 * FEValues object used to query the given finite element field at the
227 * support points in the reference configuration.
228 *
229 * The variable is marked as mutable since we have to call
230 * FEValues::reinit from compute_mapping_support_points, a function that
231 * is 'const'.
232 */
233 mutable FEValues<dim, spacedim> fe_values;
234
235 /**
236 * A variable to guard access to the fe_values variable.
237 */
238 mutable Threads::Mutex fe_values_mutex;
239 };
240
241 /** @} */
242
243
244 /*----------------------------------------------------------------------*/
245
246 #ifndef DOXYGEN
247
248 template <int dim, typename VectorType, int spacedim>
249 inline bool
250 MappingQEulerian<dim, VectorType, spacedim>::preserves_vertex_locations() const
251 {
252 return false;
253 }
254
255 #endif // DOXYGEN
256
257
258 DEAL_II_NAMESPACE_CLOSE
259
260
261 #endif // dealii_mapping_q_eulerian_h