Debian Codegraph @

include/deal.II/multigrid/mg_transfer_component.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 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_mg_transfer_component_h
16 #define dealii_mg_transfer_component_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/mg_level_object.h>
21
22 #include <deal.II/dofs/dof_handler.h>
23
24 #include <deal.II/fe/component_mask.h>
25
26 #include <deal.II/lac/affine_constraints.h>
27 #include <deal.II/lac/block_sparsity_pattern.h>
28 #include <deal.II/lac/block_vector.h>
29 #include <deal.II/lac/vector_memory.h>
30
31 #include <deal.II/multigrid/mg_base.h>
32
33 #include <memory>
34 #include <set>
35
36
37 DEAL_II_NAMESPACE_OPEN
38
39 // Forward declaration
40 #ifndef DOXYGEN
41 template <int dim, int spacedim>
42 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
43 class DoFHandler;
44 #endif
45
46 /*
47 * MGTransferBase is defined in mg_base.h
48 */
49
50 /**
51 * @addtogroup mg
52 * @{
53 */
54
55 /**
56 * Implementation of matrix generation for component wise multigrid transfer.
57 *
58 * @note MGTransferBlockBase is probably the more logical class. Still
59 * eventually, a class should be developed allowing to select multiple
60 * components.
61 */
62 class MGTransferComponentBase
63 {
64 public:
65 /**
66 * Memory used by this object.
67 */
68 std::size_t
69 memory_consumption() const;
70
71
72 protected:
73 /**
74 * Actually build the prolongation matrices for each level.
75 *
76 * This function is only called by derived classes. These can also set the
77 * member variables <code>selected_component</code> and
78 * <code>mg_selected_component</code> member variables to restrict the
79 * transfer matrices to certain components. Furthermore, they use
80 * <code>target_component</code> and <code>mg_target_component</code> for
81 * re-ordering and grouping of components.
82 */
83 template <int dim, int spacedim>
84 void
85 build(const DoFHandler<dim, spacedim> &dof_handler);
86
87 /**
88 * Flag of selected components.
89 *
90 * The transfer operators only act on the components having a <tt>true</tt>
91 * entry here. If renumbering by #target_component is used, this refers to
92 * the <b>renumbered</b> components.
93 */
94 ComponentMask component_mask;
95
96 /**
97 * Flag of selected components.
98 *
99 * The transfer operators only act on the components having a <tt>true</tt>
100 * entry here. If renumbering by #mg_target_component is used, this refers
101 * to the <b>renumbered</b> components.
102 */
103 ComponentMask mg_component_mask;
104
105 /**
106 * Target component of the fine-level vector if renumbering is required.
107 */
108 std::vector<unsigned int> target_component;
109
110 /**
111 * Target component if renumbering of level vectors is required.
112 */
113 std::vector<unsigned int> mg_target_component;
114
115 /**
116 * Sizes of the multi-level vectors.
117 */
118 mutable std::vector<std::vector<types::global_dof_index>> sizes;
119
120 /**
121 * Start index of each component.
122 */
123 std::vector<types::global_dof_index> component_start;
124
125 /**
126 * Start index of each component on all levels.
127 */
128 std::vector<std::vector<types::global_dof_index>> mg_component_start;
129
130 /**
131 * Call build() function first.
132 */
133 DeclException0(ExcMatricesNotBuilt);
134
135 private:
136 std::vector<std::shared_ptr<BlockSparsityPattern>> prolongation_sparsities;
137
138 protected:
139 /**
140 * The actual prolongation matrix. column indices belong to the dof indices
141 * of the parent cell, i.e. the coarse level. while row indices belong to
142 * the child cell, i.e. the fine level.
143 */
144 std::vector<std::shared_ptr<BlockSparseMatrix<double>>> prolongation_matrices;
145
146 /**
147 * This variable holds the mapping for the <tt>copy_to/from_mg</tt>-functions.
148 * The data is first the global index, then the level index.
149 */
150 std::vector<std::vector<std::pair<types::global_dof_index, unsigned int>>>
151 copy_to_and_from_indices;
152
153 /**
154 * Store the boundary_indices. These are needed for the boundary values in
155 * the restriction matrix.
156 */
157 std::vector<std::set<types::global_dof_index>> boundary_indices;
158 };
159
160 // TODO:[GK] Update documentation for copy_* functions
161
162 // TODO: Use same kind of template argument as MGTransferSelect
163
164 /**
165 * Implementation of the MGTransferBase interface for block matrices and
166 * simple vectors. This class uses MGTransferComponentBase selecting a single
167 * component or grouping several components into a single block. The transfer
168 * operators themselves are implemented for Vector and BlockVector objects.
169 *
170 * See MGTransferBase to find out which of the transfer classes is best for
171 * your needs.
172 */
173 template <typename number>
174 class MGTransferSelect : public MGTransferBase<Vector<number>>,
175 private MGTransferComponentBase
176 {
177 public:
178 /**
179 * Constructor without constraint matrices. Use this constructor only with
180 * discontinuous finite elements or with no local refinement.
181 */
182 MGTransferSelect();
183
184 /**
185 * Constructor with constraint matrices.
186 */
187 MGTransferSelect(const AffineConstraints<double> &constraints);
188
189 /**
190 * Destructor.
191 */
192 virtual ~MGTransferSelect() override = default;
193
194 // TODO: rewrite docs; make sure defaulted args are actually allowed
195 /**
196 * Actually build the prolongation matrices for grouped components.
197 *
198 * This function is a front-end for the same function in
199 * MGTransferComponentBase.
200 *
201 * @arg selected Number of the block of the global vector to be copied from
202 * and to the multilevel vector. This number refers to the renumbering by
203 * <tt>target_component</tt>.
204 *
205 * @arg mg_selected Number of the block for which the transfer matrices
206 * should be built.
207 *
208 * If <tt>mg_target_component</tt> is present, this refers to the renumbered
209 * components.
210 *
211 * @arg target_component this argument allows grouping and renumbering of
212 * components in the fine-level vector (see DoFRenumbering::component_wise).
213 *
214 * @arg mg_target_component this argument allows grouping and renumbering
215 * of components in the level vectors (see DoFRenumbering::component_wise).
216 * It also affects the behavior of the <tt>selected</tt> argument
217 *
218 * @arg boundary_indices holds the boundary indices on each level.
219 */
220 template <int dim, int spacedim>
221 void
222 build(const DoFHandler<dim, spacedim> &dof,
223 unsigned int selected,
224 unsigned int mg_selected,
225 const std::vector<unsigned int> &target_component =
226 std::vector<unsigned int>(),
227 const std::vector<unsigned int> &mg_target_component =
228 std::vector<unsigned int>(),
229 const std::vector<std::set<types::global_dof_index>> &boundary_indices =
230 std::vector<std::set<types::global_dof_index>>());
231
232 /**
233 * Change selected component. Handle with care!
234 */
235 void
236 select(const unsigned int component,
237 const unsigned int mg_component = numbers::invalid_unsigned_int);
238
239 virtual void
240 prolongate(const unsigned int to_level,
241 Vector<number> &dst,
242 const Vector<number> &src) const override;
243
244 virtual void
245 restrict_and_add(const unsigned int from_level,
246 Vector<number> &dst,
247 const Vector<number> &src) const override;
248
249 /**
250 * Transfer from a vector on the global grid to a multilevel vector for the
251 * active degrees of freedom. In particular, for a globally refined mesh only
252 * the finest level in @p dst is filled as a plain copy of @p src. All the
253 * other level objects are left untouched.
254 */
255 template <int dim, typename number2, int spacedim>
256 void
257 copy_to_mg(const DoFHandler<dim, spacedim> &mg_dof,
258 MGLevelObject<Vector<number>> &dst,
259 const Vector<number2> &src) const;
260
261 /**
262 * Transfer from multilevel vector to normal vector.
263 *
264 * Copies data from active portions of an multilevel vector into the
265 * respective positions of a Vector.
266 */
267 template <int dim, typename number2, int spacedim>
268 void
269 copy_from_mg(const DoFHandler<dim, spacedim> &mg_dof,
270 Vector<number2> &dst,
271 const MGLevelObject<Vector<number>> &src) const;
272
273 /**
274 * Add a multi-level vector to a normal vector.
275 *
276 * Works as the previous function, but probably not for continuous elements.
277 */
278 template <int dim, typename number2, int spacedim>
279 void
280 copy_from_mg_add(const DoFHandler<dim, spacedim> &mg_dof,
281 Vector<number2> &dst,
282 const MGLevelObject<Vector<number>> &src) const;
283
284 /**
285 * Transfer from a vector on the global grid to a multilevel vector for the
286 * active degrees of freedom. In particular, for a globally refined mesh only
287 * the finest level in @p dst is filled as a plain copy of @p src. All the
288 * other level objects are left untouched.
289 */
290 template <int dim, typename number2, int spacedim>
291 void
292 copy_to_mg(const DoFHandler<dim, spacedim> &mg_dof,
293 MGLevelObject<Vector<number>> &dst,
294 const BlockVector<number2> &src) const;
295
296 /**
297 * Transfer from multilevel vector to normal vector.
298 *
299 * Copies data from active portions of a multilevel vector into the
300 * respective positions of a global BlockVector.
301 */
302 template <int dim, typename number2, int spacedim>
303 void
304 copy_from_mg(const DoFHandler<dim, spacedim> &mg_dof,
305 BlockVector<number2> &dst,
306 const MGLevelObject<Vector<number>> &src) const;
307
308 /**
309 * Add a multi-level vector to a normal vector.
310 *
311 * Works as the previous function, but probably not for continuous elements.
312 */
313 template <int dim, typename number2, int spacedim>
314 void
315 copy_from_mg_add(const DoFHandler<dim, spacedim> &mg_dof,
316 BlockVector<number2> &dst,
317 const MGLevelObject<Vector<number>> &src) const;
318
319 /**
320 * Memory used by this object.
321 */
322 std::size_t
323 memory_consumption() const;
324
325 private:
326 /**
327 * Implementation of the public function.
328 */
329 template <int dim, class OutVector, int spacedim>
330 void
331 do_copy_from_mg(const DoFHandler<dim, spacedim> &mg_dof,
332 OutVector &dst,
333 const MGLevelObject<Vector<number>> &src) const;
334
335 /**
336 * Implementation of the public function.
337 */
338 template <int dim, class OutVector, int spacedim>
339 void
340 do_copy_from_mg_add(const DoFHandler<dim, spacedim> &mg_dof,
341 OutVector &dst,
342 const MGLevelObject<Vector<number>> &src) const;
343
344 /**
345 * Actual implementation of copy_to_mg().
346 */
347 template <int dim, class InVector, int spacedim>
348 void
349 do_copy_to_mg(const DoFHandler<dim, spacedim> &mg_dof,
350 MGLevelObject<Vector<number>> &dst,
351 const InVector &src) const;
352 /**
353 * Selected component of global vector.
354 */
355 unsigned int selected_component;
356 /**
357 * Selected component inside multigrid.
358 */
359 unsigned int mg_selected_component;
360
361 /**
362 * The degrees of freedom on the refinement edges. For each level the index
363 * set denotes which level degrees of freedom are on the refinement edge
364 * towards the lower level, excluding boundary dofs.
365 */
366 std::vector<IndexSet> interface_dofs;
367
368 /**
369 * The constraints of the global system.
370 */
371 public:
372 ObserverPointer<const AffineConstraints<double>> constraints;
373 };
374
375 /** @} */
376
377 //---------------------------------------------------------------------------
378 template <typename number>
379 inline void
380 MGTransferSelect<number>::select(const unsigned int component,
381 const unsigned int mg_component)
382 {
383 selected_component = component;
384 mg_selected_component =
385 (mg_component == numbers::invalid_unsigned_int) ? component : mg_component;
386 }
387
388 DEAL_II_NAMESPACE_CLOSE
389
390 #endif