Debian Codegraph @

include/deal.II/distributed/cell_data_transfer.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 2024 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_distributed_cell_data_transfer_h
16 #define dealii_distributed_cell_data_transfer_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/observer_pointer.h>
21
22 #include <deal.II/distributed/tria.h>
23
24 #include <deal.II/numerics/adaptation_strategies.h>
25
26 #include <boost/range/iterator_range.hpp>
27
28 #include <functional>
29
30
31 DEAL_II_NAMESPACE_OPEN
32
33 namespace parallel
34 {
35 namespace distributed
36 {
37 /**
38 * Transfer data that is associated with each active cell (like error
39 * indicators) while refining and/or coarsening a distributed triangulation
40 * and handle the necessary communication.
41 *
42 * This class therefore does for cell-related information what
43 * parallel::distributed::SolutionTransfer does for the values of degrees of
44 * freedom defined on a parallel::distributed::Triangulation.
45 *
46 * This class has been designed to operate on any kind of datatype that is
47 * serializable. A non-distributed container (like Vector or `std::vector`)
48 * has to be provided, which holds the cell-wise data in the same order as
49 * active cells are traversed. In other words, each entry corresponds to the
50 * cell with the same index CellAccessor::active_cell_index(), and the
51 * container has to be of size Triangulation::n_active_cells().
52 *
53 * <h3>Transferring cell-wise data</h3>
54 *
55 * The following code snippet demonstrates how to transfer cell-related data
56 * across refinement/coarsening of the registered triangulation.
57 *
58 * @code
59 * // prepare the triangulation,
60 * triangulation.prepare_coarsening_and_refinement();
61 *
62 * // prepare the CellDataTransfer object for coarsening and refinement
63 * // and give the cell data vector that we intend to unpack later,
64 * Vector<double> data_to_transfer(triangulation.n_active_cells());
65 * //[fill data_to_transfer with cell-wise values...]
66 *
67 * parallel::distributed::CellDataTransfer<dim, spacedim, Vector<double>>
68 * cell_data_trans(triangulation);
69 * cell_data_trans.prepare_for_coarsening_and_refinement(data_to_transfer);
70 *
71 * // actually execute the refinement,
72 * triangulation.execute_coarsening_and_refinement();
73 *
74 * // unpack transferred data,
75 * Vector<double> transferred_data(triangulation.n_active_cells());
76 * cell_data_trans.unpack(transferred_data);
77 *
78 * @endcode
79 *
80 *
81 * <h3>Use for serialization</h3>
82 *
83 * This class can be used to serialize and later deserialize a distributed
84 * mesh with attached data to separate files.
85 *
86 * For serialization, the following code snippet saves not only the
87 * triangulation itself, but also the cell-wise data attached:
88 * @code
89 * Vector<double> data_to_transfer(triangulation.n_active_cells());
90 * //[fill data_to_transfer with cell-wise values...]
91 *
92 * parallel::distributed::CellDataTransfer<dim, spacedim, Vector<double>>
93 * cell_data_trans(triangulation);
94 * cell_data_trans.prepare_for_serialization(data_to_transfer);
95 *
96 * triangulation.save(filename);
97 * @endcode
98 *
99 * Later, during deserialization, both triangulation and data can be
100 * restored as follows:
101 * @code
102 * //[create coarse mesh...]
103 * triangulation.load(filename);
104 *
105 * parallel::distributed::CellDataTransfer<dim, spacedim, Vector<double>>
106 * cell_data_trans(triangulation);
107 * Vector<double> transferred_data(triangulation.n_active_cells());
108 * cell_data_trans.deserialize(transferred_data);
109 * @endcode
110 *
111 * @note If you use more than one object to transfer data via the
112 * parallel::distributed::Triangulation::register_data_attach() and
113 * parallel::distributed::Triangulation::notify_ready_for_unpack() interface
114 * with the aim of serialization, the calls to the corresponding
115 * prepare_for_serialization() and deserialize() functions need to happen in
116 * the same order, respectively. Classes relying on this interface are e.g.
117 * parallel::distributed::CellDataTransfer,
118 * parallel::distributed::SolutionTransfer, and Particles::ParticleHandler.
119 *
120 * @note See the documentation of parallel::distributed::SolutionTransfer for
121 * matching code snippets for both transfer and serialization.
122 *
123 * @ingroup distributed
124 */
125 template <int dim, int spacedim = dim, typename VectorType = Vector<double>>
126 class CellDataTransfer
127 {
128 private:
129 /**
130 * An alias that defines the data type of provided container template.
131 */
132 using value_type = typename VectorType::value_type;
133
134 public:
135 /**
136 * Constructor.
137 *
138 * @param[in] triangulation The triangulation on which all operations will
139 * happen. At the time when this constructor is called, the refinement
140 * in question has not happened yet.
141 * @param[in] transfer_variable_size_data Specify whether your VectorType
142 * container stores values that differ in size. A varying amount of data
143 * may be packed per cell, if for example the underlying ValueType of
144 * the VectorType container is a container itself.
145 * @param[in] refinement_strategy %Function deciding how data will be
146 * stored on refined cells from its parent cell.
147 * @param[in] coarsening_strategy %Function deciding which data to store
148 * on a cell whose children will get coarsened into.
149 */
150 CellDataTransfer(
151 const parallel::distributed::Triangulation<dim, spacedim>
152 &triangulation,
153 const bool transfer_variable_size_data = false,
154 const std::function<std::vector<value_type>(
155 const typename dealii::Triangulation<dim, spacedim>::cell_iterator
156 &parent,
157 const value_type parent_value)> refinement_strategy =
158 &dealii::AdaptationStrategies::Refinement::
159 preserve<dim, spacedim, value_type>,
160 const std::function<value_type(
161 const typename dealii::Triangulation<dim, spacedim>::cell_iterator
162 &parent,
163 const std::vector<value_type> &children_values)> coarsening_strategy =
164 &dealii::AdaptationStrategies::Coarsening::
165 check_equality<dim, spacedim, value_type>);
166
167 /**
168 * Prepare the current object for coarsening and refinement.
169 *
170 * It registers the data transfer of @p in on the underlying triangulation.
171 * @p in includes data to be interpolated onto the new (refined and/or
172 * coarsened) grid. See documentation of this class for more information
173 * on how to use this functionality.
174 *
175 * This function can be called only once for the specified container
176 * until data transfer has been completed. If multiple vectors shall be
177 * transferred via this class, use the function below.
178 */
179 void
180 prepare_for_coarsening_and_refinement(const VectorType &in);
181
182 /**
183 * Same as the function above, only for a list of vectors.
184 */
185 void
186 prepare_for_coarsening_and_refinement(
187 const std::vector<const VectorType *> &all_in);
188
189 /**
190 * Prepare the serialization of the given vector.
191 *
192 * The serialization is done by Triangulation::save(). See documentation
193 * of this class for more information on how to use this functionality.
194 *
195 * This function can be called only once for the specified container
196 * until data transfer has been completed. If multiple vectors shall be
197 * transferred via this class, use the function below.
198 */
199 void
200 prepare_for_serialization(const VectorType &in);
201
202 /**
203 * Same as the function above, only for a list of vectors.
204 */
205 void
206 prepare_for_serialization(const std::vector<const VectorType *> &all_in);
207
208 /**
209 * Unpack the information previously stored in this object before
210 * the mesh was refined or coarsened onto the current set of cells.
211 */
212 void
213 unpack(VectorType &out);
214
215 /**
216 * Same as the function above, only for a list of vectors.
217 */
218 void
219 unpack(std::vector<VectorType *> &all_out);
220
221 /**
222 * Execute the deserialization of the stored information.
223 * This needs to be done after calling Triangulation::load().
224 */
225 void
226 deserialize(VectorType &out);
227
228 /**
229 * Same as the function above, only for a list of vectors.
230 */
231 void
232 deserialize(std::vector<VectorType *> &all_out);
233
234 private:
235 /**
236 * Pointer to the triangulation to work with.
237 */
238 ObserverPointer<const parallel::distributed::Triangulation<dim, spacedim>,
239 CellDataTransfer<dim, spacedim, VectorType>>
240 triangulation;
241
242 /**
243 * Specifies if size of data to transfer varies from cell to cell.
244 */
245 const bool transfer_variable_size_data;
246
247 /**
248 * %Function deciding how data will be stored on refined cells from its
249 * parent cell.
250 */
251 const std::function<std::vector<value_type>(
252 const typename Triangulation<dim, spacedim>::cell_iterator &parent,
253 const value_type parent_value)>
254 refinement_strategy;
255
256 /**
257 * %Function deciding on how to process data from children to be stored on
258 * the parent cell.
259 */
260 const std::function<value_type(
261 const typename Triangulation<dim, spacedim>::cell_iterator &parent,
262 const std::vector<value_type> &children_values)>
263 coarsening_strategy;
264
265 /**
266 * A vector that stores pointers to all the vectors we are supposed to
267 * copy over from the old to the new mesh.
268 */
269 std::vector<const VectorType *> input_vectors;
270
271 /**
272 * The handle that triangulation has assigned to this object
273 * with which we can access our memory offset and our pack function.
274 */
275 unsigned int handle;
276
277 /**
278 * Registers the pack_callback() function to the triangulation
279 * and stores the returning handle.
280 */
281 void
282 register_data_attach();
283
284 /**
285 * A callback function used to pack the data on the current mesh into
286 * objects that can later be retrieved after refinement, coarsening and
287 * repartitioning.
288 */
289 std::vector<char>
290 pack_callback(const typename parallel::distributed::
291 Triangulation<dim, spacedim>::cell_iterator &cell,
292 const CellStatus status);
293
294 /**
295 * A callback function used to unpack the data on the current mesh that
296 * has been packed up previously on the mesh before refinement,
297 * coarsening and repartitioning.
298 */
299 void
300 unpack_callback(
301 const typename parallel::distributed::Triangulation<dim, spacedim>::
302 cell_iterator &cell,
303 const CellStatus status,
304 const boost::iterator_range<std::vector<char>::const_iterator>
305 &data_range,
306 std::vector<VectorType *> &all_out);
307 };
308 } // namespace distributed
309 } // namespace parallel
310
311
312 DEAL_II_NAMESPACE_CLOSE
313
314 #endif /* dealii_distributed_cell_data_transfer_h */