Debian Codegraph @

include/deal.II/distributed/fully_distributed_tria.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_fully_distributed_tria_h
16 #define dealii_fully_distributed_tria_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/mpi_stub.h>
22
23 #include <deal.II/distributed/repartitioning_policy_tools.h>
24 #include <deal.II/distributed/tria_base.h>
25
26 #include <deal.II/grid/tria_description.h>
27
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declarations
33 #ifndef DOXYGEN
34 // forward declaration of the data type for periodic face pairs
35 namespace GridTools
36 {
37 template <typename CellIterator>
38 struct PeriodicFacePair;
39 }
40 #endif
41
42 namespace parallel
43 {
44 /**
45 * A namespace for the fully distributed triangulation.
46 */
47 namespace fullydistributed
48 {
49 /**
50 * A distributed triangulation with a distributed coarse grid.
51 *
52 * The motivation for parallel::fullydistributed::Triangulation has its
53 * origins in the following observations about complex geometries and/or
54 * about given meshes created by an external mesh generator. We regard
55 * complex geometries as geometries that can be meshed only with a
56 * non-negligible number of coarse cells (>10,000):
57 * - storing the coarse-grid information on every process is too expensive
58 * from a memory point of view (as done by
59 * parallel::distributed::Triangulation). Normally, a process only needs a
60 * small section of the global triangulation, i.e., a small section of the
61 * coarse grid such that a partitioning of the coarse grid is indeed
62 * essential. The cells stored on each process consist of the
63 * @ref GlossLocallyOwnedCell "locally owned cells" and the
64 * @ref GlossGhostCell "ghost cells".
65 * - the distribution of the active cells - on the finest level - among all
66 * processes by simply partitioning a space-filling curve might not lead
67 * to an optimal result for triangulations that originate from large
68 * coarse grids: e.g. partitions that belong to the same process might
69 * be discontinuous, leading to increased communication (within a
70 * node and beyond). Graph-based partitioning algorithms might be a sound
71 * alternative to the space filling curve used by
72 * parallel::distributed::Triangulation.
73 *
74 * To be able to construct a fully partitioned triangulation that
75 * distributes the coarse grid and gives flexibility regarding partitioning,
76 * the following ingredients are required:
77 * - a locally relevant coarse-grid triangulation
78 * (vertices, cell definition; including a layer of ghost cells)
79 * - a mapping of the locally relevant coarse-grid triangulation into the
80 * global coarse-grid triangulation
81 * - information about which cell should be refined as well as information
82 * regarding the subdomain_id, the level_subdomain_id, manifold_id,
83 * and boundary_id of each cell.
84 *
85 * The ingredients listed above are bundled in the struct
86 * TriangulationDescription::Description. The user has to fill this
87 * data structure - in a pre-processing step - before actually creating the
88 * triangulation. Predefined functions to create
89 * TriangulationDescription::Description can be found in the namespace
90 * TriangulationDescription::Utilities.
91 *
92 * Once the TriangulationDescription::Description `construction_data` has
93 * been constructed, the triangulation `tria` can be created by calling
94 * `tria.create_triangulation(construction_data);`.
95 *
96 * @note This triangulation supports: 1D/2d/3d, hanging nodes,
97 * geometric multigrid, and periodicity.
98 *
99 * @note You can create a triangulation with hanging nodes and multigrid
100 * levels with create_triangulation(). However, once it has been
101 * created, it cannot be altered anymore, i.e. you cannot coarsen or
102 * refine afterwards.
103 *
104 * @note Currently only simple periodicity conditions (i.e. without offsets
105 * and rotation matrices - see also the documentation of
106 * GridTools::collect_periodic_faces()) are supported.
107 *
108 * @dealiiConceptRequires{(concepts::is_valid_dim_spacedim<dim, spacedim>)}
109 */
110 template <int dim, int spacedim = dim>
111 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
112 class Triangulation
113 : public parallel::DistributedTriangulationBase<dim, spacedim>
114 {
115 public:
116 using cell_iterator =
117 typename dealii::Triangulation<dim, spacedim>::cell_iterator;
118
119 using active_cell_iterator =
120 typename dealii::Triangulation<dim, spacedim>::active_cell_iterator;
121
122 /**
123 * Constructor.
124 *
125 * @param mpi_communicator The MPI communicator to be used for the
126 * triangulation.
127 */
128 explicit Triangulation(const MPI_Comm mpi_communicator);
129
130 /**
131 * Destructor.
132 */
133 virtual ~Triangulation() = default;
134
135 /**
136 * Create a triangulation from the provided
137 * TriangulationDescription::Description.
138 *
139 * @note Don't forget to attach the manifolds with set_manifold() before
140 * calling this function if manifolds are needed.
141 *
142 * @note The namespace TriangulationDescription::Utilities contains functions
143 * to create TriangulationDescription::Description.
144 *
145 * @param construction_data The data needed for this process.
146 *
147 * @note This is the function to be used instead of
148 * Triangulation::create_triangulation() for some of the other
149 * triangulations of deal.II.
150 */
151 void
152 create_triangulation(
153 const TriangulationDescription::Description<dim, spacedim>
154 &construction_data) override;
155
156 /**
157 * @note This function is not implemented for this class and throws
158 * an assertion. Instead, use
159 * the other create_triangulation() function to create the
160 * triangulation.
161 */
162 virtual void
163 create_triangulation(const std::vector<Point<spacedim>> &vertices,
164 const std::vector<dealii::CellData<dim>> &cells,
165 const SubCellData &subcelldata) override;
166
167 /**
168 * Implementation of the same function as in the base class.
169 *
170 * @param other_tria The triangulation to be copied. It can be a serial
171 * Triangulation or a parallel::distributed::Triangulation. Both
172 * can have been refined already.
173 *
174 * @note This function uses the partitioner registered with
175 * set_partitioner().
176 */
177 void
178 copy_triangulation(
179 const dealii::Triangulation<dim, spacedim> &other_tria) override;
180
181 /**
182 * Register a partitioner, which is used within the method
183 * copy_triangulation.
184 *
185 * @param partitioner A partitioning function, which takes as input argument
186 * a reference to the triangulation to be partitioned
187 * and the number of partitions to be created.
188 * The function needs to set subdomain
189 * ids for each active cell of the given triangulation,
190 * with values between zero (inclusive)
191 * and the second argument to the function (exclusive).
192 * @param settings See the description of the Settings enumerator.
193 *
194 * @note As a default, GridTools::partition_triangulation_zorder() is used
195 * as partitioner and data structures on multigrid levels are not
196 * set up.
197 */
198 void
199 set_partitioner(
200 const std::function<void(dealii::Triangulation<dim, spacedim> &,
201 const unsigned int)> &partitioner,
202 const TriangulationDescription::Settings &settings);
203
204 /**
205 * Register a partitioner, which is used within the method
206 * repartition().
207 */
208 void
209 set_partitioner(
210 const RepartitioningPolicyTools::Base<dim, spacedim> &partitioner,
211 const TriangulationDescription::Settings &settings);
212
213 /**
214 * Execute repartitioning and use the partitioner attached by the
215 * method set_partitioner();
216 */
217 void
218 repartition();
219
220 /**
221 * Coarsen and refine the mesh according to refinement and coarsening
222 * flags set.
223 *
224 * @note Not implemented yet.
225 */
226 virtual void
227 execute_coarsening_and_refinement() override;
228
229 /**
230 * Override the implementation of prepare_coarsening_and_refinement from
231 * the base class.
232 *
233 * @note Not implemented yet.
234 */
235 virtual bool
236 prepare_coarsening_and_refinement() override;
237
238 /**
239 * Return the local memory consumption in bytes.
240 */
241 virtual std::size_t
242 memory_consumption() const override;
243
244 virtual bool
245 is_multilevel_hierarchy_constructed() const override;
246
247 /**
248 * Save the triangulation into the given file. This file needs to be
249 * reachable from all nodes in the computation on a shared network file
250 * system. See the SolutionTransfer class on how to store solution vectors
251 * into this file. Additional cell-based data can be saved using
252 * register_data_attach().
253 */
254 virtual void
255 save(const std::string &filename) const override;
256
257 /**
258 * Load the triangulation saved with save() back in. The mesh
259 * must be empty before calling this function.
260 *
261 * You need to load with the same number of MPI processes that
262 * you saved with.
263 *
264 * Cell-based data that was saved with register_data_attach() can be read
265 * in with notify_ready_to_unpack() after calling load().
266 */
267 virtual void
268 load(const std::string &filename) override;
269
270 private:
271 virtual unsigned int
272 coarse_cell_id_to_coarse_cell_index(
273 const types::coarse_cell_id coarse_cell_id) const override;
274
275 virtual types::coarse_cell_id
276 coarse_cell_index_to_coarse_cell_id(
277 const unsigned int coarse_cell_index) const override;
278
279 /**
280 * Go through all active cells that are locally owned and record how they
281 * will change in the private member vector local_cell_relations.
282 *
283 * As no adaptive mesh refinement is supported at the moment for this
284 * class, all cells will be flagged with CellStatus::cell_will_persist.
285 * These relations will currently only be used for serialization.
286 *
287 * The stored vector will have a size equal to the number of locally owned
288 * active cells and will be ordered by the occurrence of those cells.
289 */
290 void
291 update_cell_relations();
292
293 virtual void
294 update_number_cache() override;
295
296 /**
297 * store the Settings.
298 */
299 TriangulationDescription::Settings settings;
300
301 /**
302 * Partitioner used in copy_triangulation().
303 */
304 std::function<void(dealii::Triangulation<dim, spacedim> &,
305 const unsigned int)>
306 partitioner;
307
308 /**
309 * Partitioner used during repartition().
310 */
311 ObserverPointer<const RepartitioningPolicyTools::Base<dim, spacedim>>
312 partitioner_distributed;
313
314 /**
315 * Sorted list of pairs of coarse-cell ids and their indices.
316 */
317 std::vector<std::pair<types::coarse_cell_id, unsigned int>>
318 coarse_cell_id_to_coarse_cell_index_vector;
319
320 /**
321 * List of the coarse-cell id for each coarse cell (stored at
322 * cell->index()).
323 */
324 std::vector<types::coarse_cell_id>
325 coarse_cell_index_to_coarse_cell_id_vector;
326
327 /**
328 * Boolean indicating that the function create_triangulation() was called
329 * for internal usage.
330 */
331 bool currently_processing_create_triangulation_for_internal_usage;
332
333 /**
334 * Boolean indicating that the function
335 * prepare_coarsening_and_refinement() was called for internal usage.
336 */
337 bool
338 currently_processing_prepare_coarsening_and_refinement_for_internal_usage;
339 };
340
341 } // namespace fullydistributed
342 } // namespace parallel
343
344
345 DEAL_II_NAMESPACE_CLOSE
346
347 #endif