Debian Codegraph @

include/deal.II/multigrid/mg_transfer_block.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 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_mg_transfer_block_h
16 #define dealii_mg_transfer_block_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/lac/block_sparsity_pattern.h>
25 #include <deal.II/lac/block_vector.h>
26 #include <deal.II/lac/vector_memory.h>
27
28 #include <deal.II/multigrid/mg_base.h>
29 #include <deal.II/multigrid/mg_constrained_dofs.h>
30
31 #include <memory>
32
33
34 DEAL_II_NAMESPACE_OPEN
35
36
37 // Forward declaration
38 #ifndef DOXYGEN
39 template <int dim, int spacedim>
40 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
41 class DoFHandler;
42 #endif
43
44 /*
45 * MGTransferBase is defined in mg_base.h
46 */
47
48 /**
49 * @addtogroup mg
50 * @{
51 */
52
53 /**
54 * Implementation of matrix generation for MGTransferBlock.
55 *
56 * This is the base class for MGTransfer objects for systems of equations
57 * where multigrid is applied only to one or some blocks, where a
58 * @ref GlossBlock
59 * comprises all degrees of freedom generated by one base element.
60 */
61 class MGTransferBlockBase
62 {
63 public:
64 /**
65 * Constructor without constraint matrices. Use this constructor only with
66 * discontinuous finite elements or with no local refinement.
67 */
68 MGTransferBlockBase();
69
70 /**
71 * Constructor with constraint matrices as well as mg_constrained_dofs.
72 */
73 MGTransferBlockBase(const MGConstrainedDoFs &mg_constrained_dofs);
74
75 /**
76 * Memory used by this object.
77 */
78 std::size_t
79 memory_consumption() const;
80
81 protected:
82 /**
83 * Actually build the prolongation matrices for each level.
84 *
85 * This function is only called by derived classes. These can also set the
86 * member variables #selected and others to restrict the transfer matrices
87 * to certain blocks.
88 */
89 template <int dim, int spacedim>
90 void
91 build(const DoFHandler<dim, spacedim> &dof_handler);
92
93 /**
94 * Flag of selected blocks.
95 *
96 * The transfer operators only act on the blocks having a <tt>true</tt>
97 * entry here.
98 */
99 // TODO: rename this to block_mask, in the same way as has already been done
100 // in MGTransferComponent, and give it type BlockMask
101 std::vector<bool> selected;
102
103 /**
104 * Number of blocks of multigrid vector.
105 */
106 unsigned int n_mg_blocks;
107
108 /**
109 * For each block of the whole block vector, list to what block of the
110 * multigrid vector it is mapped. Since depending on #selected, there may be
111 * fewer multilevel blocks than original blocks, some of the entries may be
112 * illegal unsigned integers.
113 */
114 // TODO: rename this to mg_block_mask, in the same way as has already been
115 // done in MGTransferComponent, and give it type BlockMask
116 std::vector<unsigned int> mg_block;
117
118 /**
119 * Sizes of the multi-level vectors.
120 */
121 mutable std::vector<std::vector<types::global_dof_index>> sizes;
122
123 /**
124 * Start index of each block.
125 */
126 std::vector<types::global_dof_index> block_start;
127
128 /**
129 * Start index of each block on all levels.
130 */
131 std::vector<std::vector<types::global_dof_index>> mg_block_start;
132
133 /**
134 * Call build() function first.
135 */
136 DeclException0(ExcMatricesNotBuilt);
137
138 private:
139 std::vector<std::shared_ptr<BlockSparsityPattern>> prolongation_sparsities;
140
141 protected:
142 /**
143 * The actual prolongation matrix. column indices belong to the dof indices
144 * of the parent cell, i.e. the coarse level. while row indices belong to
145 * the child cell, i.e. the fine level.
146 */
147 std::vector<std::shared_ptr<BlockSparseMatrix<double>>> prolongation_matrices;
148
149 /**
150 * Mapping for the <tt>copy_to/from_mg</tt>-functions. The indices into this
151 * vector are (in this order): global block number, level number. The data
152 * is first the global index inside the block, then the level index inside
153 * the block.
154 */
155 std::vector<std::vector<std::vector<std::pair<unsigned int, unsigned int>>>>
156 copy_indices;
157
158 /**
159 * The mg_constrained_dofs of the level systems.
160 */
161
162 ObserverPointer<const MGConstrainedDoFs, MGTransferBlockBase>
163 mg_constrained_dofs;
164 };
165
166 /**
167 * Implementation of the MGTransferBase interface for block matrices and block
168 * vectors.
169 *
170 * @warning This class is in an untested state. If you use it and you
171 * encounter problems, please contact Guido Kanschat.
172 *
173 * In addition to the functionality of MGTransferPrebuilt, the operation may
174 * be restricted to certain blocks of the vector.
175 *
176 * If the restricted mode is chosen, block vectors used in the transfer
177 * routines may only have as many blocks as there are @p trues in the
178 * selected-field.
179 *
180 * See MGTransferBase to find out which of the transfer classes is best for
181 * your needs.
182 */
183 template <typename number>
184 class MGTransferBlock : public MGTransferBase<BlockVector<number>>,
185 private MGTransferBlockBase
186 {
187 public:
188 /**
189 * Default constructor.
190 */
191 MGTransferBlock();
192
193 /**
194 * Destructor.
195 */
196 virtual ~MGTransferBlock() override;
197
198 /**
199 * Initialize additional #factors and #memory if the restriction of the
200 * blocks is to be weighted differently.
201 */
202 void
203 initialize(const std::vector<number> &factors,
204 VectorMemory<Vector<number>> &memory);
205
206 /**
207 * Build the prolongation matrices for each level.
208 *
209 * This function is a front-end for the same function in
210 * MGTransferBlockBase.
211 */
212 template <int dim, int spacedim>
213 void
214 build(const DoFHandler<dim, spacedim> &dof_handler,
215 const std::vector<bool> &selected);
216
217 virtual void
218 prolongate(const unsigned int to_level,
219 BlockVector<number> &dst,
220 const BlockVector<number> &src) const override;
221
222 virtual void
223 restrict_and_add(const unsigned int from_level,
224 BlockVector<number> &dst,
225 const BlockVector<number> &src) const override;
226
227 /**
228 * Transfer from a vector on the global grid to a multilevel vector for the
229 * active degrees of freedom. In particular, for a globally refined mesh only
230 * the finest level in @p dst is filled as a plain copy of @p src. All the
231 * other level objects are left untouched.
232 *
233 * The action for discontinuous elements is as follows: on an active mesh
234 * cell, the global vector entries are simply copied to the corresponding
235 * entries of the level vector. Then, these values are restricted down to
236 * the coarsest level.
237 */
238 template <int dim, typename number2, int spacedim>
239 void
240 copy_to_mg(const DoFHandler<dim, spacedim> &dof_handler,
241 MGLevelObject<BlockVector<number>> &dst,
242 const BlockVector<number2> &src) const;
243
244 /**
245 * Transfer from multi-level vector to normal vector.
246 *
247 * Copies data from active portions of a multilevel vector into the
248 * respective positions of a global vector.
249 */
250 template <int dim, typename number2, int spacedim>
251 void
252 copy_from_mg(const DoFHandler<dim, spacedim> &dof_handler,
253 BlockVector<number2> &dst,
254 const MGLevelObject<BlockVector<number>> &src) const;
255
256 /**
257 * Add a multi-level vector to a normal vector.
258 *
259 * Works as the previous function, but probably not for continuous elements.
260 */
261 template <int dim, typename number2, int spacedim>
262 void
263 copy_from_mg_add(const DoFHandler<dim, spacedim> &dof_handler,
264 BlockVector<number2> &dst,
265 const MGLevelObject<BlockVector<number>> &src) const;
266
267 using MGTransferBlockBase::memory_consumption;
268
269 private:
270 /**
271 * Optional multiplication factors for each block. Requires initialization
272 * of #memory.
273 */
274 std::vector<number> factors;
275
276 /**
277 * Memory pool required if additional multiplication using #factors is
278 * desired.
279 */
280 ObserverPointer<VectorMemory<Vector<number>>, MGTransferBlock<number>> memory;
281 };
282
283
284 // TODO:[GK] Update documentation for copy_* functions
285
286 /**
287 * Implementation of the MGTransferBase interface for block matrices and
288 * simple vectors. This class uses MGTransferBlockBase selecting a single
289 * block. The intergrid transfer operators are implemented for Vector objects,
290 * The copy functions between regular and multigrid vectors for Vector and
291 * BlockVector.
292 *
293 * See MGTransferBase to find out which of the transfer classes is best for
294 * your needs.
295 */
296 template <typename number>
297 class MGTransferBlockSelect : public MGTransferBase<Vector<number>>,
298 private MGTransferBlockBase
299 {
300 public:
301 /**
302 * Constructor without constraint matrices. Use this constructor only with
303 * discontinuous finite elements or with no local refinement.
304 */
305 MGTransferBlockSelect();
306
307 /**
308 * Constructor with constraint matrices as well as mg_constrained_dofs.
309 */
310 MGTransferBlockSelect(const MGConstrainedDoFs &mg_constrained_dofs);
311
312 /**
313 * Destructor.
314 */
315 virtual ~MGTransferBlockSelect() override = default;
316
317 /**
318 * Actually build the prolongation matrices for grouped blocks.
319 *
320 * This function is a front-end for the same function in
321 * MGTransferBlockBase.
322 *
323 * @param dof_handler The DoFHandler to use.
324 * @param selected Number of the block for which the transfer matrices
325 * should be built.
326 */
327 template <int dim, int spacedim>
328 void
329 build(const DoFHandler<dim, spacedim> &dof_handler, unsigned int selected);
330
331 /**
332 * Change selected block. Handle with care!
333 */
334 void
335 select(const unsigned int block);
336
337 virtual void
338 prolongate(const unsigned int to_level,
339 Vector<number> &dst,
340 const Vector<number> &src) const override;
341
342 virtual void
343 restrict_and_add(const unsigned int from_level,
344 Vector<number> &dst,
345 const Vector<number> &src) const override;
346
347 /**
348 * Transfer a single block from a vector on the global grid to a multilevel
349 * vector for the active degrees of freedom. In particular, for a globally
350 * refined mesh only the finest level in @p dst is filled as a plain copy of
351 * @p src. All the other level objects are left untouched.
352 */
353 template <int dim, typename number2, int spacedim>
354 void
355 copy_to_mg(const DoFHandler<dim, spacedim> &dof_handler,
356 MGLevelObject<Vector<number>> &dst,
357 const Vector<number2> &src) const;
358
359 /**
360 * Transfer from multilevel vector to normal vector.
361 *
362 * Copies data from active portions of an multilevel vector into the
363 * respective positions of a Vector.
364 */
365 template <int dim, typename number2, int spacedim>
366 void
367 copy_from_mg(const DoFHandler<dim, spacedim> &dof_handler,
368 Vector<number2> &dst,
369 const MGLevelObject<Vector<number>> &src) const;
370
371 /**
372 * Add a multi-level vector to a normal vector.
373 *
374 * Works as the previous function, but probably not for continuous elements.
375 */
376 template <int dim, typename number2, int spacedim>
377 void
378 copy_from_mg_add(const DoFHandler<dim, spacedim> &dof_handler,
379 Vector<number2> &dst,
380 const MGLevelObject<Vector<number>> &src) const;
381
382 /**
383 * Transfer a block from a vector on the global grid to multilevel vectors.
384 * Only the values for the active degrees of freedom of the block selected are
385 * transferred. In particular, for a globally refined mesh only the finest
386 * level in @p dst is filled as a plain copy of @p src. All the other level
387 * objects are left untouched.
388 */
389 template <int dim, typename number2, int spacedim>
390 void
391 copy_to_mg(const DoFHandler<dim, spacedim> &dof_handler,
392 MGLevelObject<Vector<number>> &dst,
393 const BlockVector<number2> &src) const;
394
395 /**
396 * Transfer from multilevel vector to normal vector.
397 *
398 * Copies data from active portions of a multilevel vector into the
399 * respective positions of a global BlockVector.
400 */
401 template <int dim, typename number2, int spacedim>
402 void
403 copy_from_mg(const DoFHandler<dim, spacedim> &dof_handler,
404 BlockVector<number2> &dst,
405 const MGLevelObject<Vector<number>> &src) const;
406
407 /**
408 * Add a multi-level vector to a normal vector.
409 *
410 * Works as the previous function, but probably not for continuous elements.
411 */
412 template <int dim, typename number2, int spacedim>
413 void
414 copy_from_mg_add(const DoFHandler<dim, spacedim> &dof_handler,
415 BlockVector<number2> &dst,
416 const MGLevelObject<Vector<number>> &src) const;
417
418 /**
419 * Memory used by this object.
420 */
421 std::size_t
422 memory_consumption() const;
423
424 private:
425 /**
426 * Implementation of the public function.
427 */
428 template <int dim, class OutVector, int spacedim>
429 void
430 do_copy_from_mg(const DoFHandler<dim, spacedim> &dof_handler,
431 OutVector &dst,
432 const MGLevelObject<Vector<number>> &src,
433 const unsigned int offset) const;
434
435 /**
436 * Implementation of the public function.
437 */
438 template <int dim, class OutVector, int spacedim>
439 void
440 do_copy_from_mg_add(const DoFHandler<dim, spacedim> &dof_handler,
441 OutVector &dst,
442 const MGLevelObject<Vector<number>> &src,
443 const unsigned int offset) const;
444
445 /**
446 * Actual implementation of copy_to_mg().
447 */
448 template <int dim, class InVector, int spacedim>
449 void
450 do_copy_to_mg(const DoFHandler<dim, spacedim> &dof_handler,
451 MGLevelObject<Vector<number>> &dst,
452 const InVector &src,
453 const unsigned int offset) const;
454 /**
455 * Selected block.
456 */
457 unsigned int selected_block;
458 };
459
460 /** @} */
461
462 //------------------------- inline function definition ------------------------
463 template <typename number>
464 inline void
465 MGTransferBlockSelect<number>::select(const unsigned int block)
466 {
467 selected_block = block;
468 }
469
470 DEAL_II_NAMESPACE_CLOSE
471
472 #endif