Debian Codegraph @

include/deal.II/numerics/adaptation_strategies.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_adaptation_strategies_h
16 #define dealii_adaptation_strategies_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <deal.II/grid/tria_accessor.h>
24
25 #include <algorithm>
26 #include <numeric>
27 #include <typeinfo>
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 /**
33 * When data is transferred during adaptation, it is not trivial to decide
34 * how to process data from former cells on the old mesh that have been changed
35 * into current cells on the new mesh. Or in other words, how data should be
36 * stored in the cells on the adapted mesh.
37 *
38 * In this namespace, we offer a few strategies that cope with this
39 * problem. Such strategies can be passed to the CellDataTransfer and
40 * parallel::distributed::CellDataTransfer constructors.
41 */
42 namespace AdaptationStrategies
43 {
44 /**
45 * For refinement, all strategies take the parent cell and its associated
46 * data. They return a vector containing data for each individual child that
47 * the parent cell will be refined to.
48 *
49 * The ordering of values in the vector for children data corresponds to the
50 * index when calling TriaAccessor::child_index.
51 */
52 namespace Refinement
53 {
54 /**
55 * Return a vector containing copies of data of the parent cell for each
56 * child.
57 *
58 * @f[
59 * d_{K_c} = d_{K_p}
60 * \qquad
61 * \forall K_c \text{ children of } K_p
62 * @f]
63 */
64 template <int dim, int spacedim, typename value_type>
65 std::vector<value_type>
66 preserve(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
67 &parent,
68 const value_type parent_value);
69
70 /**
71 * Return a vector which contains data of the parent cell being equally
72 * divided among all children.
73 *
74 * @f[
75 * d_{K_c} = d_{K_p} / n_\text{children}
76 * \qquad
77 * \forall K_c \text{ children of } K_p
78 * @f]
79 *
80 * This strategy preserves the $l_1$-norm of the corresponding global data
81 * Vector before and after adaptation.
82 */
83 template <int dim, int spacedim, typename value_type>
84 std::vector<value_type>
85 split(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
86 &parent,
87 const value_type parent_value);
88
89 /**
90 * Return a vector which contains squared data of the parent cell being
91 * equally divided among the squares of all children.
92 *
93 * @f[
94 * d_{K_c}^2 = d_{K_p}^2 / n_\text{children}
95 * \qquad
96 * \forall K_c \text{ children of } K_p
97 * @f]
98 *
99 * This strategy preserves the $l_2$-norm of the corresponding global data
100 * Vector before and after adaptation.
101 */
102 template <int dim, int spacedim, typename value_type>
103 std::vector<value_type>
104 l2_norm(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
105 &parent,
106 const value_type parent_value);
107 } // namespace Refinement
108
109 /**
110 * For coarsening, all strategies take the parent cell and a vector of data
111 * that belonged to its former children. They return the value that will be
112 * assigned to the parent cell.
113 *
114 * The ordering of values in the vector for children data corresponds to the
115 * index when calling TriaAccessor::child_index.
116 */
117 namespace Coarsening
118 {
119 /**
120 * Check if data on all children match, and return value of the first child.
121 *
122 * @f[
123 * d_{K_p} = d_{K_c}
124 * \qquad
125 * \forall K_c \text{ children of } K_p
126 * @f]
127 */
128 template <int dim, int spacedim, typename value_type>
129 value_type
130 check_equality(
131 const typename dealii::Triangulation<dim, spacedim>::cell_iterator
132 &parent,
133 const std::vector<value_type> &children_values);
134
135 /**
136 * Return sum of data on all children.
137 *
138 * @f[
139 * d_{K_p} = \sum d_{K_c}
140 * \qquad
141 * \forall K_c \text{ children of } K_p
142 * @f]
143 *
144 * This strategy preserves the $l_1$-norm of the corresponding global data
145 * vector before and after adaptation.
146 */
147 template <int dim, int spacedim, typename value_type>
148 value_type
149 sum(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
150 &parent,
151 const std::vector<value_type> &children_values);
152
153 /**
154 * Return $ l_2 $-norm of data on all children.
155 *
156 * @f[
157 * d_{K_p}^2 = \sum d_{K_c}^2
158 * \qquad
159 * \forall K_c \text{ children of } K_p
160 * @f]
161 *
162 * This strategy preserves the $l_2$-norm of the corresponding global data
163 * vector before and after adaptation.
164 */
165 template <int dim, int spacedim, typename value_type>
166 value_type
167 l2_norm(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
168 &parent,
169 const std::vector<value_type> &children_values);
170
171 /**
172 * Return mean value of data on all children.
173 *
174 * @f[
175 * d_{K_p} = \sum d_{K_c} / n_\text{children}
176 * \qquad
177 * \forall K_c \text{ children of } K_p
178 * @f]
179 */
180 template <int dim, int spacedim, typename value_type>
181 value_type
182 mean(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
183 &parent,
184 const std::vector<value_type> &children_values);
185
186 /**
187 * Return maximum value of data on all children.
188 *
189 * @f[
190 * d_{K_p} = \max \left( d_{K_c} \right)
191 * \qquad
192 * \forall K_c \text{ children of } K_p
193 * @f]
194 */
195 template <int dim, int spacedim, typename value_type>
196 value_type
197 max(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
198 &parent,
199 const std::vector<value_type> &children_values);
200 } // namespace Coarsening
201 } // namespace AdaptationStrategies
202
203
204
205 /* ---------------- template functions ---------------- */
206
207 #ifndef DOXYGEN
208
209 namespace AdaptationStrategies
210 {
211 namespace Refinement
212 {
213 template <int dim, int spacedim, typename value_type>
214 std::vector<value_type>
215 preserve(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
216 &parent,
217 const value_type parent_value)
218 {
219 Assert(parent->n_children() > 0, ExcInternalError());
220 return std::vector<value_type>(parent->n_children(), parent_value);
221 }
222
223
224
225 template <int dim, int spacedim, typename value_type>
226 std::vector<value_type>
227 split(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
228 &parent,
229 const value_type parent_value)
230 {
231 static_assert(std::is_arithmetic_v<value_type> &&
232 !std::is_same_v<value_type, bool>,
233 "The provided value_type may not meet the requirements "
234 "of this function.");
235
236 Assert(parent->n_children() > 0, ExcInternalError());
237 return std::vector<value_type>(parent->n_children(),
238 parent_value / parent->n_children());
239 }
240
241
242
243 template <int dim, int spacedim, typename value_type>
244 std::vector<value_type>
245 l2_norm(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
246 &parent,
247 const value_type parent_value)
248 {
249 static_assert(std::is_arithmetic_v<value_type> &&
250 !std::is_same_v<value_type, bool>,
251 "The provided value_type may not meet the requirements "
252 "of this function.");
253
254 Assert(parent->n_children() > 0, ExcInternalError());
255 return std::vector<value_type>(parent->n_children(),
256 parent_value /
257 std::sqrt(parent->n_children()));
258 }
259 } // namespace Refinement
260
261
262
263 namespace Coarsening
264 {
265 template <int dim, int spacedim, typename value_type>
266 value_type
267 check_equality(
268 const typename dealii::Triangulation<dim, spacedim>::cell_iterator &,
269 const std::vector<value_type> &children_values)
270 {
271 Assert(!children_values.empty(), ExcInternalError());
272
273 const auto first_child = children_values.cbegin();
274 for (auto other_child = first_child + 1;
275 other_child != children_values.cend();
276 ++other_child)
277 Assert(*first_child == *other_child,
278 ExcMessage(
279 "Values on cells that will be coarsened are not equal!"));
280
281 return *first_child;
282 }
283
284
285
286 template <int dim, int spacedim, typename value_type>
287 value_type
288 sum(const typename dealii::Triangulation<dim, spacedim>::cell_iterator &,
289 const std::vector<value_type> &children_values)
290 {
291 static_assert(std::is_arithmetic_v<value_type> &&
292 !std::is_same_v<value_type, bool>,
293 "The provided value_type may not meet the requirements "
294 "of this function.");
295
296 Assert(!children_values.empty(), ExcInternalError());
297 return std::accumulate(children_values.cbegin(),
298 children_values.cend(),
299 static_cast<value_type>(0));
300 }
301
302
303
304 template <int dim, int spacedim, typename value_type>
305 value_type
306 l2_norm(
307 const typename dealii::Triangulation<dim, spacedim>::cell_iterator &,
308 const std::vector<value_type> &children_values)
309 {
310 static_assert(std::is_arithmetic_v<value_type> &&
311 !std::is_same_v<value_type, bool>,
312 "The provided value_type may not meet the requirements "
313 "of this function.");
314
315 Assert(!children_values.empty(), ExcInternalError());
316 return std::sqrt(std::inner_product(children_values.cbegin(),
317 children_values.cend(),
318 children_values.cbegin(),
319 static_cast<value_type>(0)));
320 }
321
322
323
324 template <int dim, int spacedim, typename value_type>
325 value_type
326 mean(const typename dealii::Triangulation<dim, spacedim>::cell_iterator
327 &parent,
328 const std::vector<value_type> &children_values)
329 {
330 return sum<dim, spacedim, value_type>(parent, children_values) /
331 children_values.size();
332 }
333
334
335
336 template <int dim, int spacedim, typename value_type>
337 value_type
338 max(const typename dealii::Triangulation<dim, spacedim>::cell_iterator &,
339 const std::vector<value_type> &children_values)
340 {
341 Assert(!children_values.empty(), ExcInternalError());
342 return *std::max_element(children_values.cbegin(),
343 children_values.cend());
344 }
345 } // namespace Coarsening
346 } // namespace AdaptationStrategies
347
348 #endif
349
350 DEAL_II_NAMESPACE_CLOSE
351
352 #endif /* dealii_adaptation_strategies_h */