Debian Codegraph @

include/deal.II/fe/mapping_q_cache.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 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_q_cache_h
16 #define dealii_mapping_q_cache_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/function.h>
22 #include <deal.II/base/mg_level_object.h>
23
24 #include <deal.II/fe/mapping_q.h>
25
26 #include <deal.II/grid/tria.h>
27
28 #include <boost/container/small_vector.hpp>
29 #include <boost/signals2/connection.hpp>
30
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declarations
35 #ifndef DOXYGEN
36 template <int dim, int spacedim>
37 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
38 class DoFHandler;
39 #endif
40
41
42 /**
43 * @addtogroup mapping
44 * @{
45 */
46
47 /**
48 * This class implements a caching strategy for objects of the MappingQ family
49 * in terms of the MappingQ::compute_mapping_support_points() function,
50 * which is used in all operations of MappingQ. The information of the
51 * mapping is pre-computed by the MappingQCache::initialize() function.
52 *
53 * The use of this class is discussed extensively in step-65.
54 */
55 template <int dim, int spacedim = dim>
56 class MappingQCache : public MappingQ<dim, spacedim>
57 {
58 public:
59 /**
60 * Constructor. @p polynomial_degree denotes the polynomial degree of the
61 * polynomials that are used to map cells from the reference to the real
62 * cell.
63 */
64 explicit MappingQCache(const unsigned int polynomial_degree);
65
66 /**
67 * Copy constructor.
68 */
69 explicit MappingQCache(const MappingQCache<dim, spacedim> &mapping);
70
71 /**
72 * Destructor.
73 */
74 ~MappingQCache();
75
76 /**
77 * clone() functionality. For documentation, see Mapping::clone().
78 */
79 virtual std::unique_ptr<Mapping<dim, spacedim>>
80 clone() const override;
81
82 /**
83 * Returns @p false because the preservation of vertex locations depends on
84 * the mapping handed to the reinit() function.
85 */
86 virtual bool
87 preserves_vertex_locations() const override;
88
89 /**
90 * Initialize the data cache by computing the mapping support points for all
91 * cells (on all levels) of the given triangulation.
92 *
93 * @note The cache is invalidated upon the signal
94 * Triangulation::Signals::any_change of the underlying triangulation.
95 */
96 void
97 initialize(const Mapping<dim, spacedim> &mapping,
98 const Triangulation<dim, spacedim> &triangulation);
99
100 /**
101 * Initialize the data cache by letting the function given as an argument
102 * provide the mapping support points for all cells (on all levels) of the
103 * given triangulation. The function must return a vector of
104 * `Point<spacedim>` whose length is the same as the size of the polynomial
105 * space, $(p+1)^\text{dim}$, where $p$ is the polynomial degree of the
106 * mapping, and it must be in the order the mapping or FE_Q sort their
107 * points, i.e., all $2^\text{dim}$ vertex points first, then the points on
108 * the lines, quads, and hexes according to the usual hierarchical
109 * numbering. No attempt is made to validate these points internally, except
110 * for the number of given points.
111 *
112 * @note If multiple threads are enabled, this function will run in
113 * parallel, invoking the function passed in several times. Thus, in case
114 * MultithreadInfo::n_threads()>1, the user code must make sure that the
115 * function, typically a lambda, does not write into data shared with other
116 * threads.
117 *
118 * @note The cache is invalidated upon the signal
119 * Triangulation::Signals::any_change of the underlying triangulation.
120 */
121 void
122 initialize(const Triangulation<dim, spacedim> &triangulation,
123 const std::function<std::vector<Point<spacedim>>(
124 const typename Triangulation<dim, spacedim>::cell_iterator &)>
125 &compute_points_on_cell);
126
127 /**
128 * Initialize the data cache by computing the mapping support points for all
129 * cells (on all levels) of the given triangulation and a given @p mapping
130 * and transforming these points via the function @p transformation_function.
131 *
132 * The bool @p function_describes_relative_displacement indicates that
133 * the function @p transformation_function maps to absolute coordinates.
134 * If the parameter is set to true, the return value of the function is
135 * interpreted as relative deformation and the result is eventually added
136 * to the original point for the support points eventually used by this class.
137 *
138 * This function calls the previous function so the comments regarding
139 * threading listed above apply also here.
140 *
141 * @note The cache is invalidated upon the signal
142 * Triangulation::Signals::any_change of the underlying triangulation.
143 */
144 void
145 initialize(const Mapping<dim, spacedim> &mapping,
146 const Triangulation<dim, spacedim> &tria,
147 const std::function<Point<spacedim>(
148 const typename Triangulation<dim, spacedim>::cell_iterator &,
149 const Point<spacedim> &)> &transformation_function,
150 const bool function_describes_relative_displacement);
151
152 /**
153 * The same as above but taking a dealii::Function object.
154 */
155 void
156 initialize(const Mapping<dim, spacedim> &mapping,
157 const Triangulation<dim, spacedim> &tria,
158 const Function<spacedim> &transformation_function,
159 const bool function_describes_relative_displacement);
160
161 /**
162 * Initialize the data cache of the active cells by a discrete field
163 * (specified
164 * by @p dof_handler and @p vector) that describes the absolute or
165 * relative position of each support point.
166 *
167 * @note By using this function for reinitialization, this class behaves like
168 * MappingFEField (vector_describes_relative_displacement == false) or
169 * MappingQEulerian (vector_describes_relative_displacement == true), but
170 * with much more efficient operations internally.
171 */
172 template <typename VectorType>
173 void
174 initialize(const Mapping<dim, spacedim> &mapping,
175 const DoFHandler<dim, spacedim> &dof_handler,
176 const VectorType &vector,
177 const bool vector_describes_relative_displacement);
178
179 /**
180 * Initialize the data cache of all non-artificial cells by a solution
181 * (specified by @p dof_handler and a set of @p vectors on all levels of the
182 * triangulation) that describes the absolute or relative position of each
183 * support point.
184 *
185 * @note By using this function for reinitialization, this class behaves like
186 * MappingFEField (vector_describes_relative_displacement == false) or
187 * MappingQEulerian (vector_describes_relative_displacement == true), but
188 * with much more efficient operations internally.
189 */
190 template <typename VectorType>
191 void
192 initialize(const Mapping<dim, spacedim> &mapping,
193 const DoFHandler<dim, spacedim> &dof_handler,
194 const MGLevelObject<VectorType> &vectors,
195 const bool vector_describes_relative_displacement);
196
197 /**
198 * @copydoc Mapping::get_vertices()
199 */
200 virtual boost::container::small_vector<Point<spacedim>,
201 #ifndef _MSC_VER
202 ReferenceCells::max_n_vertices<dim>()
203 #else
204 GeometryInfo<dim>::vertices_per_cell
205 #endif
206 >
207 get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell)
208 const override;
209
210 /**
211 * Return the memory consumption (in bytes) of the cache.
212 */
213 std::size_t
214 memory_consumption() const;
215
216 protected:
217 /**
218 * This is the main function overridden from the base class MappingQ.
219 */
220 virtual std::vector<Point<spacedim>>
221 compute_mapping_support_points(
222 const typename Triangulation<dim, spacedim>::cell_iterator &cell)
223 const override;
224
225 private:
226 /**
227 * The point cache filled upon calling initialize(). It is made a shared
228 * pointer to allow several instances (created via clone()) to share this
229 * cache.
230 */
231 std::shared_ptr<std::vector<std::vector<std::vector<Point<spacedim>>>>>
232 support_point_cache;
233
234 /**
235 * The connection to Triangulation::signals::any that must be reset once
236 * this class goes out of scope.
237 */
238 boost::signals2::connection clear_signal;
239
240 /**
241 * Specifies if support_point_cache has been set up for the cells on the
242 * levels.
243 */
244 bool uses_level_info;
245 };
246
247 /** @} */
248
249 DEAL_II_NAMESPACE_CLOSE
250
251 #endif