Debian Codegraph @

include/deal.II/numerics/vector_tools_interpolate.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_vector_tools_interpolate_h
16 #define dealii_vector_tools_interpolate_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/template_constraints.h>
21 #include <deal.II/base/types.h>
22
23 #include <deal.II/fe/component_mask.h>
24
25 #include <map>
26
27 DEAL_II_NAMESPACE_OPEN
28
29 template <typename number>
30 class AffineConstraints;
31
32 template <int dim, int spacedim>
33 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
34 class DoFHandler;
35
36 template <typename number>
37 class FullMatrix;
38 template <int dim, typename Number>
39 class Function;
40 template <typename MeshType>
41 DEAL_II_CXX20_REQUIRES(concepts::is_triangulation_or_dof_handler<MeshType>)
42 class InterGridMap;
43 template <int dim, int spacedim>
44 class Mapping;
45
46 namespace hp
47 {
48 template <int dim, int spacedim>
49 class MappingCollection;
50 }
51
52 namespace VectorTools
53 {
54 /**
55 * @name Interpolation and projection
56 */
57 /** @{ */
58
59 /**
60 * Compute the interpolation of @p function at the support points to the
61 * finite element space described by the Triangulation and FiniteElement
62 * object with which the given DoFHandler argument is initialized. It is
63 * assumed that the number of components of @p function matches that of the
64 * finite element used by @p dof.
65 *
66 * Note that you may have to call <tt>hanging_nodes.distribute(vec)</tt>
67 * with the hanging nodes from space @p dof afterwards, to make the result
68 * continuous again.
69 *
70 * See the general documentation of this namespace for further information.
71 *
72 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
73 */
74 template <int dim, int spacedim, typename VectorType>
75 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
76 void interpolate(
77 const Mapping<dim, spacedim> &mapping,
78 const DoFHandler<dim, spacedim> &dof,
79 const Function<spacedim, typename VectorType::value_type> &function,
80 VectorType &vec,
81 const ComponentMask &component_mask = {},
82 const unsigned int level = numbers::invalid_unsigned_int);
83
84 /**
85 * Same as above but in an hp-context.
86 *
87 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
88 */
89 template <int dim, int spacedim, typename VectorType>
90 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
91 void interpolate(
92 const hp::MappingCollection<dim, spacedim> &mapping,
93 const DoFHandler<dim, spacedim> &dof,
94 const Function<spacedim, typename VectorType::value_type> &function,
95 VectorType &vec,
96 const ComponentMask &component_mask = {},
97 const unsigned int level = numbers::invalid_unsigned_int);
98
99
100 /**
101 * Call the @p interpolate() function above with
102 * <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt>.
103 *
104 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
105 */
106 template <int dim, int spacedim, typename VectorType>
107 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
108 void interpolate(
109 const DoFHandler<dim, spacedim> &dof,
110 const Function<spacedim, typename VectorType::value_type> &function,
111 VectorType &vec,
112 const ComponentMask &component_mask = {},
113 const unsigned int level = numbers::invalid_unsigned_int);
114
115 /**
116 * Interpolate different finite element spaces. The interpolation of vector
117 * @p data_1 (which is assumed to be ghosted, see
118 * @ref GlossGhostedVector)
119 * is executed from the FE space represented by @p dof_1
120 * to the vector @p data_2 on FE space @p dof_2.
121 * The interpolation on each cell is represented by the matrix @p transfer.
122 * Curved boundaries are neglected so far.
123 *
124 * Note that you may have to call <tt>hanging_nodes.distribute(data_2)</tt>
125 * with the hanging nodes from space @p dof_2 afterwards, to make the result
126 * continuous again.
127 *
128 * @note Instantiations for this template are provided for some vector types
129 * (see the general documentation of the namespace), but only the same
130 * vector for InVector and OutVector. Other combinations must be
131 * instantiated by hand.
132 *
133 * @dealiiConceptRequires{concepts::is_dealii_vector_type<InVector>
134 * &&concepts::is_writable_dealii_vector_type<OutVector>}
135 */
136 template <int dim, class InVector, class OutVector, int spacedim>
137 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<InVector> &&
138 concepts::is_writable_dealii_vector_type<OutVector>)
139 void interpolate(const DoFHandler<dim, spacedim> &dof_1,
140 const DoFHandler<dim, spacedim> &dof_2,
141 const FullMatrix<double> &transfer,
142 const InVector &data_1,
143 OutVector &data_2);
144
145 /**
146 * This function is a kind of generalization or modification of the very
147 * first interpolate() function in the series. It interpolates a set of
148 * functions onto the finite element space defined by the DoFHandler argument,
149 * where the determination which function to use on each cell is made
150 * based on the material id (see
151 * @ref GlossMaterialId)
152 * of each cell.
153 *
154 * @param[in] mapping The mapping to use to determine the location of
155 * support points at which the functions are to be evaluated.
156 * @param[in] dof_handler DoFHandler initialized with Triangulation and
157 * FiniteElement objects and that defines the finite element space.
158 * @param[in] function_map A std::map reflecting the correspondence between
159 * material ids on those cells on which something should be interpolated,
160 * and the functions to be interpolated onto the finite element space.
161 * @param[out] dst The global finie element vector holding the
162 * output of the interpolated values.
163 * @param[in] component_mask A mask of components that shall be interpolated.
164 *
165 * @note If the algorithm encounters a cell whose material id is not listed
166 * in the given @p function_map, then @p dst will not be updated in the
167 * respective degrees of freedom of the output vector. For example, if
168 * @p dst was initialized to zero, then those zeros which correspond to
169 * the missed material ids will still remain in @p dst after calling
170 * this function.
171 *
172 * @note Degrees of freedom located on faces between cells of different
173 * material ids will get their value by that cell which was called last in
174 * the respective loop over cells implemented in this function. Since the
175 * order of cells is somewhat arbitrary, you cannot control it. However, if
176 * you want to have control over the order in which cells are visited, let us
177 * take a
178 * look at the following example: Let @p u be a variable of interest which
179 * is approximated by some CG finite element. Let @p 0, @p 1 and @p 2 be
180 * material ids of cells on the triangulation. Let 0: 0.0, 1: 1.0, 2: 2.0 be
181 * the whole @p function_map that you want to pass to this function, where
182 * @p key is a material id and @p value is a value of @p u. By using the
183 * whole @p function_map you do not really know which values will be
184 * assigned to the face DoFs. On the other hand, if you split the whole @p
185 * function_map into three smaller independent objects 0: 0.0 and 1: 1.0 and
186 * 2: 2.0 and make three distinct calls of this function passing each of
187 * these objects separately (the order depends on what you want to get
188 * between cells), then each subsequent call will rewrite the intercell @p
189 * dofs of the previous one.
190 *
191 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
192 */
193 template <int dim, int spacedim, typename VectorType>
194 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
195 void interpolate_based_on_material_id(
196 const Mapping<dim, spacedim> &mapping,
197 const DoFHandler<dim, spacedim> &dof_handler,
198 const std::map<types::material_id,
199 const Function<spacedim, typename VectorType::value_type> *>
200 &function_map,
201 VectorType &dst,
202 const ComponentMask &component_mask = {});
203
204 /**
205 * Compute the interpolation of a @p dof_handler_1 function @p u1 (i.e.,
206 * a function defined on the mesh that underlies @p dof_handler_1, using
207 * the finite element associated with that DoFHandler) to
208 * a @p dof_handler_2 function @p u2 (i.e., a function defined on the mesh
209 * and finite element associated with @p dof_handler_2). This function
210 * assumes that @p dof_handler_1 and @p dof_handler_2 are defined on
211 * (possibly different) triangulations that have a common coarse grid.
212 *
213 * dof1 and dof2 need to have the same finite element discretization.
214 *
215 * Note that for continuous elements on grids with hanging nodes (i.e.
216 * locally refined grids) this function does not give the expected output.
217 * Indeed, the resulting output vector does not necessarily respect
218 * continuity requirements at hanging nodes, due to local cellwise
219 * interpolation.
220 *
221 * For this case (continuous elements on grids with hanging nodes), please
222 * use the interpolate_to_different_mesh function with an additional
223 * AffineConstraints argument, see below, or make the field conforming
224 * yourself by calling the AffineConstraints::distribute() function of your
225 * hanging node constraints object.
226 *
227 * @note This function works with parallel::distributed::Triangulation, but
228 * only if the parallel partitioning is the same for both meshes (see the
229 * parallel::distributed::Triangulation<dim>::no_automatic_repartitioning
230 * flag). In practice, this is rarely the case because two triangulations,
231 * partitioned in their own ways, will not typically have corresponding
232 * cells owned by the same process, and implementing the interpolation
233 * procedure would require transferring data between processes in ways
234 * that are difficult to implement efficiently. However, some special
235 * cases can more easily be implemented, namely the case where one
236 * of the meshes is strictly coarser or finer than the other. For these
237 * cases, see the interpolate_to_coarser_mesh() and
238 * interpolate_to_finer_mesh().
239 *
240 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
241 */
242 template <int dim, int spacedim, typename VectorType>
243 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
244 void interpolate_to_different_mesh(
245 const DoFHandler<dim, spacedim> &dof_handler_1,
246 const VectorType &u1,
247 const DoFHandler<dim, spacedim> &dof_handler_2,
248 VectorType &u2);
249
250 /**
251 * This is a variation of the previous function that takes an additional
252 * constraint object as argument.
253 *
254 * @p constraints is a hanging node constraints object corresponding to
255 * @p dof2. This object is particularly important when interpolating onto
256 * continuous elements on grids with hanging nodes (locally refined grids):
257 * Without it - due to cellwise interpolation - the resulting output vector
258 * does not necessarily respect continuity requirements at hanging nodes.
259 *
260 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
261 */
262 template <int dim, int spacedim, typename VectorType>
263 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
264 void interpolate_to_different_mesh(
265 const DoFHandler<dim, spacedim> &dof_handler_1,
266 const VectorType &u1,
267 const DoFHandler<dim, spacedim> &dof_handler_2,
268 const AffineConstraints<typename VectorType::value_type> &constraints,
269 VectorType &u2);
270
271 /**
272 * The same function as above, but takes an InterGridMap object directly as
273 * a parameter. This function is useful for interpolating several vectors at
274 * the same time.
275 *
276 * @p intergridmap has to be initialized via InterGridMap::make_mapping
277 * pointing from a source DoFHandler to a destination DoFHandler.
278 *
279 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
280 */
281 template <int dim, int spacedim, typename VectorType>
282 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
283 void interpolate_to_different_mesh(
284 const InterGridMap<DoFHandler<dim, spacedim>> &intergridmap,
285 const VectorType &u1,
286 const AffineConstraints<typename VectorType::value_type> &constraints,
287 VectorType &u2);
288
289 /**
290 * This function addresses one of the limitations of the
291 * interpolate_to_different_mesh() function, namely that the latter only
292 * works on parallel triangulations in very specific cases where both
293 * triangulations involved happen to be partitioned in such a way that
294 * if a process owns a cell of one mesh, it also needs to own the
295 * corresponding parent of child cells of the other mesh. In practice, this is
296 * rarely the case.
297 *
298 * This function does not have this restriction, and consequently also works
299 * in parallel, as long as the mesh we interpolate onto can be obtained from
300 * the mesh we interpolate off by *coarsening*. In other words, the target
301 * mesh is coarser than the source mesh.
302 *
303 * The function takes an additional constraints argument that is used after
304 * interpolation to ensure that the output vector is conforming (that is,
305 * that all entries of the output vector conform to their constraints).
306 * @p constraints_coarse therefore needs to correspond to
307 * @p dof_handler_coarse .
308 *
309 * The opposite operation, interpolation from a coarser to a finer mesh,
310 * is implemented in the interpolate_to_finer_mesh() function.
311 */
312 template <int dim, int spacedim, typename VectorType>
313 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
314 void interpolate_to_coarser_mesh(
315 const DoFHandler<dim, spacedim> &dof_handler_fine,
316 const VectorType &u_fine,
317 const DoFHandler<dim, spacedim> &dof_handler_coarse,
318 const AffineConstraints<typename VectorType::value_type>
319 &constraints_coarse,
320 VectorType &u_coarse);
321
322 /**
323 * This function addresses one of the limitations of the
324 * interpolate_to_different_mesh() function, namely that the latter only
325 * works on parallel triangulations in very specific cases where both
326 * triangulations involved happen to be partitioned in such a way that
327 * if a process owns a cell of one mesh, it also needs to own the
328 * corresponding parent of child cells of the other mesh. In practice, this is
329 * rarely the case.
330 *
331 * This function does not have this restriction, and consequently also works
332 * in parallel, as long as the mesh we interpolate onto can be obtained from
333 * the mesh we interpolate off by *refinement*. In other words, the target
334 * mesh is finer than the source mesh.
335 *
336 * The function takes an additional constraints argument that is used after
337 * interpolation to ensure that the output vector is conforming (that is,
338 * that all entries of the output vector conform to their constraints).
339 * @p constraints_finee therefore needs to correspond to
340 * @p dof_handler_fine .
341 *
342 * The opposite operation, interpolation from a finer to a coarser mesh,
343 * is implemented in the interpolate_to_coarser_mesh() function.
344 */
345 template <int dim, int spacedim, typename VectorType>
346 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
347 void interpolate_to_finer_mesh(
348 const DoFHandler<dim, spacedim> &dof_handler_coarse,
349 const VectorType &u_coarse,
350 const DoFHandler<dim, spacedim> &dof_handler_fine,
351 const AffineConstraints<typename VectorType::value_type> &constraints_fine,
352 VectorType &u_fine);
353
354 /** @} */
355
356 /**
357 * Geometrical interpolation
358 */
359 /** @{ */
360 /**
361 * Given a DoFHandler containing at least a spacedim vector field, this
362 * function interpolates the Triangulation at the support points of a FE_Q()
363 * finite element of the same degree as the degree of the required
364 * components.
365 *
366 * Curved manifold are respected, and the resulting VectorType will be
367 * geometrically consistent. The resulting map is guaranteed to be
368 * interpolatory at the support points of a FE_Q() finite element of the
369 * same degree as the degree of the required components.
370 *
371 * If the underlying finite element is an FE_Q(1)^spacedim, then the
372 * resulting @p VectorType is a finite element field representation of the
373 * vertices of the Triangulation.
374 *
375 * The optional ComponentMask argument can be used to specify what
376 * components of the FiniteElement to use to describe the
377 * geometry. If no mask is specified at construction time, then a
378 * default-constructed mask is used, which is then interpreted as
379 * saying that the first `spacedim` components of the FiniteElement
380 * are assumed to represent the geometry of the problem.
381 *
382 * This function is only implemented for FiniteElements where the specified
383 * components are primitive.
384 *
385 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
386 */
387 template <int dim, int spacedim, typename VectorType>
388 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
389 void get_position_vector(const DoFHandler<dim, spacedim> &dh,
390 VectorType &vector,
391 const ComponentMask &mask = {});
392
393 /**
394 * Like the above function but also taking @p mapping as argument.
395 * This will introduce an additional approximation between the true geometry
396 * specified by the manifold if the degree of the mapping is lower than the
397 * degree of the finite element in the DoFHandler @p dh, but more
398 * importantly it allows to fill location vectors for mappings that do not
399 * preserve vertex locations (like Eulerian mappings).
400 *
401 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
402 */
403 template <int dim, int spacedim, typename VectorType>
404 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
405 void get_position_vector(const Mapping<dim, spacedim> &mapping,
406 const DoFHandler<dim, spacedim> &dh,
407 VectorType &vector,
408 const ComponentMask &mask = {});
409
410 /** @} */
411 } // namespace VectorTools
412
413 DEAL_II_NAMESPACE_CLOSE
414
415 #endif // dealii_vector_tools_interpolate_h