Debian Codegraph @

include/deal.II/numerics/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_cell_data_transfer_h
16 #define dealii_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/grid/tria.h>
23
24 #include <deal.II/numerics/adaptation_strategies.h>
25
26 #include <algorithm>
27 #include <functional>
28 #include <set>
29
30
31 DEAL_II_NAMESPACE_OPEN
32
33 /**
34 * Transfer data that is associated with each active cell (like error
35 * indicators) while refining and/or coarsening a triangulation.
36 *
37 * This class therefore does for cell-related information what
38 * SolutionTransfer does for the values of degrees of freedom defined on a
39 * Triangulation.
40 *
41 * A non-distributed container (like Vector or `std::vector`) has to be
42 * provided, which holds the cell-wise data in the same order as active cells
43 * are traversed. In other words, each entry corresponds to the cell with the
44 * same index CellAccessor::active_cell_index(), and the container has to be of
45 * size Triangulation::n_active_cells().
46 *
47 * <h3>Transferring cell-wise data</h3>
48 *
49 * The following code snippet demonstrates how to transfer cell-related data
50 * across refinement/coarsening of the registered triangulation.
51 *
52 * @code
53 * // prepare the triangulation,
54 * triangulation.prepare_coarsening_and_refinement();
55 *
56 * // prepare the CellDataTransfer object for coarsening and refinement
57 * // and give the cell data vector that we intend to unpack later,
58 * Vector<double> data_to_transfer(triangulation.n_active_cells());
59 * //[fill data_to_transfer with cell-wise values...]
60 *
61 * CellDataTransfer<dim, spacedim, Vector<double>>
62 * cell_data_trans(triangulation);
63 * cell_data_trans.prepare_for_coarsening_and_refinement();
64 *
65 * // actually execute the refinement,
66 * triangulation.execute_coarsening_and_refinement();
67 *
68 * // unpack transferred data,
69 * Vector<double> transferred_data(triangulation.n_active_cells());
70 * cell_data_trans.unpack(data_to_transfer, transferred_data);
71 * @endcode
72 *
73 * When using a parallel::shared::Triangulation, we need to ensure that we have
74 * the global data available in our local vector before refinement happened. We
75 * can achieve this as follows:
76 *
77 * @code
78 * Vector<double> data_to_transfer(triangulation.n_active_cells());
79 * //[fill data_to_transfer with cell-wise values...]
80 *
81 * PETScWrappers::MPI::Vector
82 * distributed_data_to_transfer(mpi_communicator,
83 * triangulation.n_active_cells(),
84 * triangulation.n_locally_owned_active_cells());
85 * for (const auto &cell : triangulation.active_cell_iterators())
86 * if (cell->is_locally_owned())
87 * {
88 * const unsigned int index = cell->active_cell_index();
89 * distributed_data_to_transfer(index) = data_to_transfer(index);
90 * }
91 * distributed_data_to_transfer.compress(VectorOperation::insert);
92 *
93 * data_to_transfer = distributed_data_to_transfer;
94 * @endcode
95 *
96 * For the parallel distributed case, a designated class
97 * parallel::distributed::CellDataTransfer is available. Please refer to this
98 * particular class when using a parallel::distributed::Triangulation.
99 *
100 * @note See the documentation of SolutionTransfer for matching code snippets
101 * for transfer.
102 *
103 * @ingroup numerics
104 */
105 template <int dim, int spacedim = dim, typename VectorType = Vector<double>>
106 class CellDataTransfer
107 {
108 private:
109 /**
110 * An alias that defines the data type of provided container template.
111 */
112 using value_type = typename VectorType::value_type;
113
114 public:
115 /**
116 * Constructor.
117 *
118 * @param[in] triangulation The triangulation on which all operations will
119 * happen. At the time when this constructor is called, the refinement
120 * in question has not happened yet.
121 * @param[in] refinement_strategy %Function deciding how data will be stored
122 * on refined cells from its parent cell.
123 * @param[in] coarsening_strategy %Function deciding which data to store on
124 * a cell whose children will get coarsened into.
125 */
126 CellDataTransfer(
127 const Triangulation<dim, spacedim> &triangulation,
128 const std::function<std::vector<value_type>(
129 const typename Triangulation<dim, spacedim>::cell_iterator &parent,
130 const value_type parent_value)> refinement_strategy =
131 &AdaptationStrategies::Refinement::preserve<dim, spacedim, value_type>,
132 const std::function<value_type(
133 const typename Triangulation<dim, spacedim>::cell_iterator &parent,
134 const std::vector<value_type> &children_values)> coarsening_strategy =
135 &AdaptationStrategies::Coarsening::
136 check_equality<dim, spacedim, value_type>);
137
138 /**
139 * Prepare the current object for coarsening and refinement.
140 *
141 * Stores the active_cell_indices of all active cells on the associated
142 * triangulation and attribute them to either persisting, refined or coarsened
143 * cells.
144 */
145 void
146 prepare_for_coarsening_and_refinement();
147
148 /**
149 * Transfer the information from the previous mesh to the updated one.
150 *
151 * Data from the previous mesh supplied by @p in will be transferred to the updated
152 * mesh and stored in @p out. @p out has to provide enough space to hold the
153 * transferred data, i.e. has to be of size `triangulation.n_active_cells()`.
154 */
155 void
156 unpack(const VectorType &in, VectorType &out);
157
158 private:
159 /**
160 * Pointer to the triangulation to work with.
161 */
162 ObserverPointer<const Triangulation<dim, spacedim>,
163 CellDataTransfer<dim, spacedim, VectorType>>
164 triangulation;
165
166 /**
167 * %Function deciding how data will be stored on refined cells from its parent
168 * cell.
169 */
170 const std::function<std::vector<value_type>(
171 const typename Triangulation<dim, spacedim>::cell_iterator &parent,
172 const value_type parent_value)>
173 refinement_strategy;
174
175 /**
176 * %Function deciding on how to process data from children to be stored on the
177 * parent cell.
178 */
179 const std::function<value_type(
180 const typename Triangulation<dim, spacedim>::cell_iterator &parent,
181 const std::vector<value_type> &children_indices)>
182 coarsening_strategy;
183
184 /**
185 * Container to temporarily store the iterator and active cell index
186 * of cells that persist.
187 */
188 std::map<const typename Triangulation<dim, spacedim>::cell_iterator,
189 const unsigned int>
190 persisting_cells_active_index;
191
192 /**
193 * Container to temporarily store the iterator and active cell index
194 * of cells that will be refined.
195 */
196 std::map<const typename Triangulation<dim, spacedim>::cell_iterator,
197 const unsigned int>
198 refined_cells_active_index;
199
200 /**
201 * Container to temporarily store the iterator of parent cells that will
202 * remain after coarsening along with the active cell indices of the
203 * corresponding children cells.
204 */
205 std::map<const typename Triangulation<dim, spacedim>::cell_iterator,
206 const std::set<unsigned int>>
207 coarsened_cells_active_index;
208
209 /**
210 * Number of active cells on the initial triangulation that has not been
211 * refined yet.
212 *
213 * It will be set in prepare_for_coarsening_and_refinement() and used to
214 * validate user inputs after refinement happened (only in debug mode).
215 */
216 unsigned int n_active_cells_pre;
217 };
218
219
220 DEAL_II_NAMESPACE_CLOSE
221
222 #endif /* dealii_cell_data_transfer_h */