Debian Codegraph @

include/deal.II/fe/mapping_q1_eulerian.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 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 #ifndef dealii_mapping_q1_eulerian_h
16 #define dealii_mapping_q1_eulerian_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/observer_pointer.h>
21
22 #include <deal.II/dofs/dof_handler.h>
23
24 #include <deal.II/fe/mapping_q.h>
25
26 #include <boost/container/small_vector.hpp>
27
28 #include <array>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 template <typename>
33 class Vector;
34
35
36 /**
37 * @addtogroup mapping
38 * @{
39 */
40
41 /**
42 * This class provides a mapping that adds to the location of each cell
43 * a $d$-linear displacement field. (The generalization to higher order
44 * polynomials is provided in the MappingQEulerian class.) Each
45 * cell is thus shifted in space by values given to the mapping through a
46 * finite element field.
47 *
48 * <h3>Usage</h3>
49 *
50 * The constructor of this class takes two arguments: a reference to the
51 * vector that defines the mapping from the reference configuration to the
52 * current configuration and a reference to the DoFHandler. The vector should
53 * then represent a (flattened out version of a) vector valued field defined
54 * at nodes defined by the DoFHandler, where the number of components of
55 * the vector field equals the number of space dimensions. Thus, the
56 * DoFHandler shall operate on a finite element that has as many components as
57 * space dimensions. As an additional requirement, we impose that it have as
58 * many degree of freedom per vertex as there are space dimensions; since this
59 * object only evaluates the finite element field at the vertices, the values
60 * of all other degrees of freedom (not associated to vertices) are ignored.
61 * These requirements are met if the finite element which the given DoFHandler
62 * operates on is constructed as a system element (FESystem) from @p dim
63 * continuous FE_Q() objects.
64 *
65 * In many cases, the shift vector will also be the solution vector of the
66 * problem under investigation. If this is not the case (i.e. the number of
67 * components of the solution variable is not equal to the space dimension,
68 * e.g. for scalar problems in <tt>dim>1</tt> where the Eulerian coordinates
69 * only give a background field) or for coupled problems where more variables
70 * are computed than just the flow field), then a different DoFHandler has to
71 * be set up on the given triangulation, and the shift vector has then to be
72 * associated to it.
73 *
74 * An example is shown below:
75 * @code
76 * FESystem<dim> fe(FE_Q<dim>(1), dim);
77 * DoFHandler<dim> flowfield_dof_handler(triangulation);
78 * flowfield_dof_handler.distribute_dofs(fe);
79 * Vector<double> displacement_field(flowfield_dof_handler.n_dofs());
80 * MappingQ1Eulerian<dim> mymapping(flowfield_dof_handler,
81 * displacement_field);
82 * @endcode
83 *
84 * Note that since the vector of shift values and the dof handler are only
85 * associated to this object at construction time, you have to make sure that
86 * whenever you use this object, the given objects still represent valid data.
87 *
88 * To enable the use of the MappingQ1Eulerian class also in the context of
89 * parallel codes using the PETSc or Trilinos wrapper classes, the type of
90 * the vector can be specified as template parameter <tt>VectorType</tt>.
91 *
92 * For more information about the <tt>spacedim</tt> template parameter check
93 * the documentation of FiniteElement or the one of Triangulation.
94 */
95 template <int dim, typename VectorType = Vector<double>, int spacedim = dim>
96 class MappingQ1Eulerian : public MappingQ<dim, spacedim>
97 {
98 public:
99 /**
100 * Constructor.
101 *
102 * @param[in] euler_dof_handler A DoFHandler object that defines a finite
103 * element space. This space needs to have exactly dim components
104 * and these will be considered displacements
105 * relative to the original positions of the cells of the triangulation.
106 * This DoFHandler must be based on a <code>FESystem(FE_Q(1),dim)</code>
107 * finite element.
108 * @param[in] euler_vector A finite element function in the space defined by
109 * the first argument. The dim components of this function will be
110 * interpreted as the displacement we use in defining the mapping, relative
111 * to the location of cells of the underlying triangulation.
112 */
113 MappingQ1Eulerian(const DoFHandler<dim, spacedim> &euler_dof_handler,
114 const VectorType &euler_vector);
115
116 /**
117 * Return the mapped vertices of the cell. For the current class, this
118 * function does not use the support points from the geometry of the current
119 * cell but instead evaluates an externally given displacement field in
120 * addition to the geometry of the cell.
121 */
122 virtual boost::container::small_vector<Point<spacedim>,
123 #ifndef _MSC_VER
124 ReferenceCells::max_n_vertices<dim>()
125 #else
126 GeometryInfo<dim>::vertices_per_cell
127 #endif
128 >
129 get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell)
130 const override;
131
132 /**
133 * Return a pointer to a copy of the present object. The caller of this copy
134 * then assumes ownership of it.
135 */
136 virtual std::unique_ptr<Mapping<dim, spacedim>>
137 clone() const override;
138
139 /**
140 * Always returns @p false because MappingQ1Eulerian does not in general
141 * preserve vertex locations (unless the translation vector happens to
142 * provide for zero displacements at vertex locations).
143 */
144 virtual bool
145 preserves_vertex_locations() const override;
146
147 /**
148 * Exception.
149 */
150 DeclException0(ExcInactiveCell);
151
152
153
154 protected:
155 /**
156 * Compute mapping-related information for a cell. See the documentation of
157 * Mapping::fill_fe_values() for a discussion of purpose, arguments, and
158 * return value of this function.
159 *
160 * This function overrides the function in the base class since we cannot
161 * use any cell similarity for this class.
162 */
163 virtual CellSimilarity::Similarity
164 fill_fe_values(
165 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
166 const CellSimilarity::Similarity cell_similarity,
167 const Quadrature<dim> &quadrature,
168 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
169 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
170 &output_data) const override;
171
172 /**
173 * Compute the support points of the mapping. For the current class, these
174 * are the vertices, as obtained by calling Mapping::get_vertices(). See the
175 * documentation of MappingQ::compute_mapping_support_points() for
176 * more information.
177 */
178 virtual std::vector<Point<spacedim>>
179 compute_mapping_support_points(
180 const typename Triangulation<dim, spacedim>::cell_iterator &cell)
181 const override;
182
183 /**
184 * Reference to the vector of shifts.
185 */
186 ObserverPointer<const VectorType,
187 MappingQ1Eulerian<dim, VectorType, spacedim>>
188 euler_transform_vectors;
189
190 /**
191 * Pointer to the DoFHandler to which the mapping vector is associated.
192 */
193 ObserverPointer<const DoFHandler<dim, spacedim>,
194 MappingQ1Eulerian<dim, VectorType, spacedim>>
195 shiftmap_dof_handler;
196 };
197
198 /** @} */
199
200 /*----------------------------------------------------------------------*/
201
202 #ifndef DOXYGEN
203
204 template <int dim, typename VectorType, int spacedim>
205 inline bool
206 MappingQ1Eulerian<dim, VectorType, spacedim>::preserves_vertex_locations() const
207 {
208 return false;
209 }
210
211 #endif // DOXYGEN
212
213 DEAL_II_NAMESPACE_CLOSE
214
215 #endif