Debian Codegraph @

include/deal.II/lac/block_sparsity_pattern.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2000 - 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_block_sparsity_pattern_h
16 #define dealii_block_sparsity_pattern_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/observer_pointer.h>
24 #include <deal.II/base/table.h>
25
26 #include <deal.II/lac/block_indices.h>
27 #include <deal.II/lac/dynamic_sparsity_pattern.h>
28 #include <deal.II/lac/sparsity_pattern.h>
29 #include <deal.II/lac/sparsity_pattern_base.h>
30 #include <deal.II/lac/trilinos_sparsity_pattern.h>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declarations
35 #ifndef DOXYGEN
36 template <typename number>
37 class BlockSparseMatrix;
38 class BlockDynamicSparsityPattern;
39 #endif
40
41 /**
42 * @addtogroup Sparsity
43 * @{
44 */
45
46
47 /**
48 * This is the base class for block versions of the sparsity pattern and
49 * dynamic sparsity pattern classes. It has not much functionality, but only
50 * administrates an array of sparsity pattern objects and delegates work to
51 * them. It has mostly the same interface as has the SparsityPattern, and
52 * DynamicSparsityPattern, and simply transforms calls to its member functions
53 * to calls to the respective member functions of the member sparsity
54 * patterns.
55 *
56 * The largest difference between the SparsityPattern and
57 * DynamicSparsityPattern classes and this class is that mostly, the matrices
58 * have different properties and you will want to work on the blocks making up
59 * the matrix rather than the whole matrix. You can access the different
60 * blocks using the <tt>block(row,col)</tt> function.
61 *
62 * Attention: this object is not automatically notified if the size of one of
63 * its subobjects' size is changed. After you initialize the sizes of the
64 * subobjects, you will therefore have to call the <tt>collect_sizes()</tt>
65 * function of this class! Note that, of course, all sub-matrices in a
66 * (block-)row have to have the same number of rows, and that all sub-matrices
67 * in a (block-)column have to have the same number of columns.
68 *
69 * You will in general not want to use this class, but one of the derived
70 * classes.
71 *
72 * @todo Handle optimization of diagonal elements of the underlying
73 * SparsityPattern correctly.
74 *
75 * @see
76 * @ref GlossBlockLA "Block (linear algebra)"
77 */
78 template <typename SparsityPatternType>
79 class BlockSparsityPatternBase : public SparsityPatternBase
80 {
81 public:
82 /**
83 * Declare type for container size.
84 */
85 using size_type = types::global_dof_index;
86
87 /**
88 * Define a value which is used to indicate that a certain value in the @p
89 * colnums array is unused, i.e. does not represent a certain column number
90 * index.
91 *
92 * This value is only an alias to the respective value of the
93 * SparsityPattern class.
94 */
95 static const size_type invalid_entry = SparsityPattern::invalid_entry;
96
97 /**
98 * Initialize the matrix empty, that is with no memory allocated. This is
99 * useful if you want such objects as member variables in other classes. You
100 * can make the structure usable by calling the reinit() function.
101 */
102 BlockSparsityPatternBase();
103
104 /**
105 * Initialize the matrix with the given number of block rows and columns.
106 * The blocks themselves are still empty, and you have to call
107 * collect_sizes() after you assign them sizes.
108 */
109 BlockSparsityPatternBase(const size_type n_block_rows,
110 const size_type n_block_columns);
111
112 /**
113 * Copy constructor. This constructor is only allowed to be called if the
114 * sparsity pattern to be copied is empty, i.e. there are no block allocated
115 * at present. This is for the same reason as for the SparsityPattern, see
116 * there for the details.
117 */
118 BlockSparsityPatternBase(const BlockSparsityPatternBase &bsp);
119
120 /**
121 * Resize the matrix, by setting the number of block rows and columns. This
122 * deletes all blocks and replaces them with uninitialized ones, i.e. ones
123 * for which also the sizes are not yet set. You have to do that by calling
124 * the reinit() functions of the blocks themselves. Do not forget to call
125 * collect_sizes() after that on this object.
126 *
127 * The reason that you have to set sizes of the blocks yourself is that the
128 * sizes may be varying, the maximum number of elements per row may be
129 * varying, etc. It is simpler not to reproduce the interface of the
130 * SparsityPattern class here but rather let the user call whatever function
131 * they desire.
132 */
133 void
134 reinit(const size_type n_block_rows, const size_type n_block_columns);
135
136 /**
137 * Copy operator. For this the same holds as for the copy constructor: it is
138 * declared, defined and fine to be called, but the latter only for empty
139 * objects.
140 */
141 BlockSparsityPatternBase &
142 operator=(const BlockSparsityPatternBase &);
143
144 /**
145 * This function collects the sizes of the sub-objects and stores them in
146 * internal arrays, in order to be able to relay global indices into the
147 * matrix to indices into the subobjects. You *must* call this function each
148 * time after you have changed the size of the sub-objects.
149 */
150 void
151 collect_sizes();
152
153 /**
154 * Access the block with the given coordinates.
155 */
156 SparsityPatternType &
157 block(const size_type row, const size_type column);
158
159 /**
160 * Access the block with the given coordinates. Version for constant
161 * objects.
162 */
163 const SparsityPatternType &
164 block(const size_type row, const size_type column) const;
165
166 /**
167 * Grant access to the object describing the distribution of row indices to
168 * the individual blocks.
169 */
170 const BlockIndices &
171 get_row_indices() const;
172
173 /**
174 * Grant access to the object describing the distribution of column indices
175 * to the individual blocks.
176 */
177 const BlockIndices &
178 get_column_indices() const;
179
180 /**
181 * This function compresses the sparsity structures that this object
182 * represents. It simply calls @p compress for all sub-objects.
183 */
184 void
185 compress();
186
187 /**
188 * Return the number of blocks in a column.
189 */
190 size_type
191 n_block_rows() const;
192
193 /**
194 * Return the number of blocks in a row.
195 */
196 size_type
197 n_block_cols() const;
198
199 /**
200 * Return whether the object is empty. It is empty if no memory is
201 * allocated, which is the same as that both dimensions are zero. This
202 * function is just the concatenation of the respective call to all
203 * sub-matrices.
204 */
205 bool
206 empty() const;
207
208 /**
209 * Return the maximum number of entries per row. It returns the maximal
210 * number of entries per row accumulated over all blocks in a row, and the
211 * maximum over all rows.
212 */
213 size_type
214 max_entries_per_row() const;
215
216 /**
217 * Add a nonzero entry to the matrix. This function may only be called for
218 * non-compressed sparsity patterns.
219 *
220 * If the entry already exists, nothing bad happens.
221 *
222 * This function simply finds out to which block <tt>(i,j)</tt> belongs and
223 * then relays to that block.
224 */
225 void
226 add(const size_type i, const size_type j);
227
228 /**
229 * Add several nonzero entries to the specified matrix row. This function
230 * may only be called for non-compressed sparsity patterns.
231 *
232 * If some of the entries already exist, nothing bad happens.
233 *
234 * This function simply finds out to which blocks <tt>(row,col)</tt> for
235 * <tt>col</tt> in the iterator range belong and then relays to those
236 * blocks.
237 */
238 template <typename ForwardIterator>
239 void
240 add_entries(const size_type row,
241 ForwardIterator begin,
242 ForwardIterator end,
243 const bool indices_are_sorted = false);
244
245 /**
246 * Add several nonzero entries to the specified matrix row. This function may
247 * only be called for non-compressed sparsity patterns and works the same way
248 * as the overload which takes iterators.
249 */
250 virtual void
251 add_row_entries(const size_type &row,
252 const ArrayView<const size_type> &columns,
253 const bool indices_are_sorted = false) override;
254
255 using SparsityPatternBase::add_entries;
256
257 /**
258 * Return number of rows of this matrix, which equals the dimension of the
259 * image space. It is the sum of rows of the (block-)rows of sub-matrices.
260 */
261 using SparsityPatternBase::n_rows;
262
263 /**
264 * Return number of columns of this matrix, which equals the dimension of
265 * the range space. It is the sum of columns of the (block-)columns of
266 * sub-matrices.
267 */
268 using SparsityPatternBase::n_cols;
269
270 /**
271 * Check if a value at a certain position may be non-zero.
272 */
273 bool
274 exists(const size_type i, const size_type j) const;
275
276 /**
277 * Number of entries in a specific row, added up over all the blocks that
278 * form this row.
279 */
280 unsigned int
281 row_length(const size_type row) const;
282
283 /**
284 * Return the number of nonzero elements of this matrix. Actually, it
285 * returns the number of entries in the sparsity pattern; if any of the
286 * entries should happen to be zero, it is counted anyway.
287 *
288 * This function may only be called if the matrix struct is compressed. It
289 * does not make too much sense otherwise anyway.
290 *
291 * In the present context, it is the sum of the values as returned by the
292 * sub-objects.
293 */
294 size_type
295 n_nonzero_elements() const;
296
297 /**
298 * Print the sparsity of the matrix. The output consists of one line per row
299 * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
300 * <i>jn</i> are the allocated columns in this row.
301 */
302 void
303 print(std::ostream &out) const;
304
305 /**
306 * Print the sparsity of the matrix in a format that <tt>gnuplot</tt>
307 * understands and which can be used to plot the sparsity pattern in a
308 * graphical way. This is the same functionality implemented for usual
309 * sparsity patterns, see
310 * SparsityPattern::print_gnuplot().
311 */
312 void
313 print_gnuplot(std::ostream &out) const;
314
315 /**
316 * Print the sparsity of the matrix in <tt>svg</tt> format. This is the same
317 * functionality implemented for usual sparsity patterns, see
318 * SparsityPattern::print_svg().
319 */
320 void
321 print_svg(std::ostream &out) const;
322
323 /**
324 * Determine an estimate for the memory consumption (in bytes) of this
325 * object.
326 */
327 std::size_t
328 memory_consumption() const;
329
330 /**
331 * @addtogroup Exceptions
332 * @{
333 */
334
335 /**
336 * Exception
337 */
338 DeclExceptionMsg(
339 ExcNeedsCollectSizes,
340 "The number of rows and columns (returned by n_rows() and n_cols()) does "
341 "not match their directly computed values. This typically means that a "
342 "call to collect_sizes() is missing.");
343
344 /**
345 * Exception
346 */
347 DeclException4(ExcIncompatibleRowNumbers,
348 int,
349 int,
350 int,
351 int,
352 << "The blocks [" << arg1 << ',' << arg2 << "] and [" << arg3
353 << ',' << arg4 << "] have differing row numbers.");
354 /**
355 * Exception
356 */
357 DeclException4(ExcIncompatibleColNumbers,
358 int,
359 int,
360 int,
361 int,
362 << "The blocks [" << arg1 << ',' << arg2 << "] and [" << arg3
363 << ',' << arg4 << "] have differing column numbers.");
364 /** @} */
365
366 protected:
367 /**
368 * Number of block rows.
369 */
370 size_type block_rows;
371
372 /**
373 * Number of block columns.
374 */
375 size_type block_columns;
376
377 /**
378 * Array of sparsity patterns.
379 */
380 Table<2, std::unique_ptr<SparsityPatternType>> sub_objects;
381
382 /**
383 * Object storing and managing the transformation of row indices to indices
384 * of the sub-objects.
385 */
386 BlockIndices row_indices;
387
388 /**
389 * Object storing and managing the transformation of column indices to
390 * indices of the sub-objects.
391 */
392 BlockIndices column_indices;
393
394 private:
395 /**
396 * Internal utility function for computing the number of rows.
397 */
398 size_type
399 compute_n_rows() const;
400
401 /**
402 * Internal utility function for computing the number of columns.
403 */
404 size_type
405 compute_n_cols() const;
406
407 /**
408 * Temporary vector for counting the elements written into the individual
409 * blocks when doing a collective add or set.
410 */
411 std::vector<size_type> counter_within_block;
412
413 /**
414 * Temporary vector for column indices on each block when writing local to
415 * global data on each sparse matrix.
416 */
417 std::vector<std::vector<size_type>> block_column_indices;
418
419 // Make the block sparse matrix a friend, so that it can use our
420 // #row_indices and #column_indices objects.
421 template <typename number>
422 friend class BlockSparseMatrix;
423 };
424
425
426
427 /**
428 * This class extends the base class to implement an array of sparsity
429 * patterns that can be used by block sparse matrix objects. It only adds a
430 * few additional member functions, but the main interface stems from the base
431 * class, see there for more information.
432 *
433 * This class is an example of the "static" type of
434 * @ref Sparsity.
435 */
436 class BlockSparsityPattern : public BlockSparsityPatternBase<SparsityPattern>
437 {
438 public:
439 /**
440 * Initialize the matrix empty, that is with no memory allocated. This is
441 * useful if you want such objects as member variables in other classes. You
442 * can make the structure usable by calling the reinit() function.
443 */
444 BlockSparsityPattern() = default;
445
446 /**
447 * Initialize the matrix with the given number of block rows and columns.
448 * The blocks themselves are still empty, and you have to call
449 * collect_sizes() after you assign them sizes.
450 */
451 BlockSparsityPattern(const size_type n_rows, const size_type n_columns);
452
453 /**
454 * Forwarding to BlockSparsityPatternBase::reinit().
455 */
456 void
457 reinit(const size_type n_block_rows, const size_type n_block_columns);
458
459 /**
460 * Initialize the pattern with two BlockIndices for the block structures of
461 * matrix rows and columns as well as a row length vector.
462 *
463 * The row length vector should be in the format produced by DoFTools.
464 * Alternatively, there is a simplified version, where each of the inner
465 * vectors has length one. Then, the corresponding entry is used as the
466 * maximal row length.
467 *
468 * For the diagonal blocks, the inner SparsityPattern is initialized with
469 * optimized diagonals, while this is not done for the off-diagonal blocks.
470 */
471 void
472 reinit(const BlockIndices &row_indices,
473 const BlockIndices &col_indices,
474 const std::vector<std::vector<unsigned int>> &row_lengths);
475
476
477 /**
478 * Return whether the structure is compressed or not, i.e. whether all
479 * sub-matrices are compressed.
480 */
481 bool
482 is_compressed() const;
483
484 /**
485 * Copy data from an object of type BlockDynamicSparsityPattern, i.e. resize
486 * this object to the size of the given argument, and copy over the contents
487 * of each of the subobjects. Previous content of this object is lost.
488 */
489 void
490 copy_from(const BlockDynamicSparsityPattern &dsp);
491 };
492
493
494
495 /**
496 * This class extends the base class to implement an array of compressed
497 * sparsity patterns that can be used to initialize objects of type
498 * BlockSparsityPattern. It does not add additional member functions, but
499 * rather acts as an @p alias to introduce the name of this class, without
500 * requiring the user to specify the templated name of the base class. For
501 * information on the interface of this class refer to the base class. The
502 * individual blocks are based on the DynamicSparsityPattern class.
503 *
504 * This class is an example of the "dynamic" type of
505 * @ref Sparsity.
506 *
507 * <h3>Example</h3>
508 *
509 * Usage of this class is very similar to DynamicSparsityPattern, but since
510 * the use of block indices causes some additional complications, we give a
511 * short example.
512 *
513 * After the DoFHandler <tt>dof</tt> and the AffineConstraints
514 * <tt>constraints</tt> have been set up with a system element, we must count
515 * the degrees of freedom in each matrix block:
516 *
517 * @code
518 * const std::vector<unsigned int> dofs_per_block =
519 * DoFTools::count_dofs_per_fe_block(dof);
520 * @endcode
521 *
522 * Now, we are ready to set up the BlockDynamicSparsityPattern.
523 *
524 * @code
525 * BlockDynamicSparsityPattern dsp(fe.n_blocks(), fe.n_blocks());
526 * for (unsigned int i = 0; i < fe.n_blocks(); ++i)
527 * for (unsigned int j = 0; j < fe.n_blocks(); ++j)
528 * dsp.block(i, j).reinit(dofs_per_block[i], dofs_per_block[j]);
529 * dsp.collect_sizes();
530 * @endcode
531 *
532 * It is filled as if it were a normal pattern
533 *
534 * @code
535 * DoFTools::make_sparsity_pattern(dof, dsp);
536 * constraints.condense(dsp);
537 * @endcode
538 *
539 * In the end, it is copied to a normal BlockSparsityPattern for later use.
540 *
541 * @code
542 * BlockSparsityPattern sparsity;
543 * sparsity.copy_from(dsp);
544 * @endcode
545 */
546
547 class BlockDynamicSparsityPattern
548 : public BlockSparsityPatternBase<DynamicSparsityPattern>
549 {
550 public:
551 /**
552 * Initialize the matrix empty, that is with no memory allocated. This is
553 * useful if you want such objects as member variables in other classes. You
554 * can make the structure usable by calling the reinit() function.
555 */
556 BlockDynamicSparsityPattern() = default;
557
558 /**
559 * Initialize the matrix with the given number of block rows and columns.
560 * The blocks themselves are still empty, and you have to call
561 * collect_sizes() after you assign them sizes.
562 */
563 BlockDynamicSparsityPattern(const size_type n_rows,
564 const size_type n_columns);
565
566 /**
567 * Initialize the pattern with two BlockIndices for the block structures of
568 * matrix rows and columns. This function is equivalent to calling the
569 * previous constructor with the length of the two index vector and then
570 * entering the index values.
571 */
572 BlockDynamicSparsityPattern(const std::vector<size_type> &row_block_sizes,
573 const std::vector<size_type> &col_block_sizes);
574
575 /**
576 * Initialize the pattern with symmetric blocks. The number of IndexSets in
577 * the vector determine the number of rows and columns of blocks. The size
578 * of each block is determined by the size() of the respective IndexSet.
579 * Each block only stores the rows given by the values in the IndexSet,
580 * which is useful for distributed memory parallel computations and usually
581 * corresponds to the locally relevant DoFs.
582 */
583 BlockDynamicSparsityPattern(const std::vector<IndexSet> &partitioning);
584
585 /**
586 * Initialize the pattern with two BlockIndices for the block structures of
587 * matrix rows and columns.
588 */
589 BlockDynamicSparsityPattern(const BlockIndices &row_indices,
590 const BlockIndices &col_indices);
591
592
593 /**
594 * Resize the pattern to a tensor product of matrices with dimensions
595 * defined by the arguments.
596 *
597 * The matrix will have as many block rows and columns as there are entries
598 * in the two arguments. The block at position (<i>i,j</i>) will have the
599 * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
600 */
601 void
602 reinit(const std::vector<size_type> &row_block_sizes,
603 const std::vector<size_type> &col_block_sizes);
604
605 /**
606 * Resize the pattern with symmetric blocks determined by the size() of each
607 * IndexSet. See the constructor taking a vector of IndexSets for details.
608 */
609 void
610 reinit(const std::vector<IndexSet> &partitioning);
611
612 /**
613 * Resize the matrix to a tensor product of matrices with dimensions defined
614 * by the arguments. The two BlockIndices objects must be initialized and
615 * the sparsity pattern will have the same block structure afterwards.
616 */
617 void
618 reinit(const BlockIndices &row_indices, const BlockIndices &col_indices);
619
620 /**
621 * Access to column number field. Return the column number of the @p index
622 * th entry in row @p row.
623 */
624 size_type
625 column_number(const size_type row, const unsigned int index) const;
626
627 /**
628 * Allow the use of the reinit functions of the base class as well.
629 */
630 using BlockSparsityPatternBase<DynamicSparsityPattern>::reinit;
631 };
632
633 /** @} */
634
635
636 #ifdef DEAL_II_WITH_TRILINOS
637
638
639 namespace TrilinosWrappers
640 {
641 /**
642 * @addtogroup TrilinosWrappers
643 * @{
644 */
645
646 /**
647 * This class extends the base class to implement an array of Trilinos
648 * sparsity patterns that can be used to initialize Trilinos block sparse
649 * matrices that can be distributed among different processors. It is used in
650 * the same way as the dealii::BlockSparsityPattern except that it builds upon
651 * the TrilinosWrappers::SparsityPattern instead of the
652 * dealii::SparsityPattern.
653 *
654 * This class is has properties of the "dynamic" type of
655 * @ref Sparsity
656 * (in the sense that it can extend the memory if too little elements were
657 * allocated), but otherwise is more like the basic deal.II SparsityPattern
658 * (in the sense that the method compress() needs to be called before the
659 * pattern can be used).
660 *
661 * This class is used in step-32.
662 */
663 class BlockSparsityPattern
664 : public dealii::BlockSparsityPatternBase<SparsityPattern>
665 {
666 public:
667 /**
668 * Initialize the matrix empty, that is with no memory allocated. This is
669 * useful if you want such objects as member variables in other classes.
670 * You can make the structure usable by calling the reinit() function.
671 */
672 BlockSparsityPattern() = default;
673
674 /**
675 * Initialize the matrix with the given number of block rows and columns.
676 * The blocks themselves are still empty, and you have to call
677 * collect_sizes() after you assign them sizes.
678 */
679 BlockSparsityPattern(const size_type n_rows, const size_type n_columns);
680
681 /**
682 * Initialize the pattern with two BlockIndices for the block structures
683 * of matrix rows and columns. This function is equivalent to calling the
684 * previous constructor with the length of the two index vector and then
685 * entering the index values.
686 */
687 BlockSparsityPattern(const std::vector<size_type> &row_block_sizes,
688 const std::vector<size_type> &col_block_sizes);
689
690 /**
691 * Initialize the pattern with an array of index sets that specifies both
692 * rows and columns of the matrix (so the final matrix will be a square
693 * matrix), where the size() of the IndexSets specifies the size of the
694 * blocks and the values in each IndexSet denotes the rows that are going
695 * to be saved in each block.
696 */
697 BlockSparsityPattern(const std::vector<IndexSet> &parallel_partitioning,
698 const MPI_Comm communicator = MPI_COMM_WORLD);
699
700 /**
701 * Initialize the pattern with two arrays of index sets that specify rows
702 * and columns of the matrix, where the size() of the IndexSets specifies
703 * the size of the blocks and the values in each IndexSet denotes the rows
704 * that are going to be saved in each block. The additional index set
705 * writable_rows is used to set all rows that we allow to write locally.
706 * This constructor is used to create matrices that allow several threads
707 * to write simultaneously into the matrix (to different rows, of course),
708 * see the method TrilinosWrappers::SparsityPattern::reinit method with
709 * three index set arguments for more details.
710 */
711 BlockSparsityPattern(
712 const std::vector<IndexSet> &row_parallel_partitioning,
713 const std::vector<IndexSet> &column_parallel_partitioning,
714 const std::vector<IndexSet> &writeable_rows,
715 const MPI_Comm communicator = MPI_COMM_WORLD);
716
717 /**
718 * Resize the matrix to a tensor product of matrices with dimensions
719 * defined by the arguments.
720 *
721 * The matrix will have as many block rows and columns as there are
722 * entries in the two arguments. The block at position (<i>i,j</i>) will
723 * have the dimensions <tt>row_block_sizes[i]</tt> times
724 * <tt>col_block_sizes[j]</tt>.
725 */
726 void
727 reinit(const std::vector<size_type> &row_block_sizes,
728 const std::vector<size_type> &col_block_sizes);
729
730 /**
731 * Resize the matrix to a square tensor product of matrices. See the
732 * constructor that takes a vector of IndexSets for details.
733 */
734 void
735 reinit(const std::vector<IndexSet> &parallel_partitioning,
736 const MPI_Comm communicator = MPI_COMM_WORLD);
737
738 /**
739 * Resize the matrix to a rectangular block matrices. This method allows
740 * rows and columns to be different, both in the outer block structure and
741 * within the blocks.
742 */
743 void
744 reinit(const std::vector<IndexSet> &row_parallel_partitioning,
745 const std::vector<IndexSet> &column_parallel_partitioning,
746 const MPI_Comm communicator = MPI_COMM_WORLD);
747
748 /**
749 * Resize the matrix to a rectangular block matrices that furthermore
750 * explicitly specify the writable rows in each of the blocks. This method
751 * is used to create matrices that allow several threads to write
752 * simultaneously into the matrix (to different rows, of course), see the
753 * method TrilinosWrappers::SparsityPattern::reinit method with three
754 * index set arguments for more details.
755 */
756 void
757 reinit(const std::vector<IndexSet> &row_parallel_partitioning,
758 const std::vector<IndexSet> &column_parallel_partitioning,
759 const std::vector<IndexSet> &writeable_rows,
760 const MPI_Comm communicator = MPI_COMM_WORLD);
761
762 /**
763 * Allow the use of the reinit functions of the base class as well.
764 */
765 using BlockSparsityPatternBase<SparsityPattern>::reinit;
766 };
767
768 /** @} */
769
770 } /* namespace TrilinosWrappers */
771
772 #endif
773
774 /*--------------------- Template functions ----------------------------------*/
775
776
777
778 template <typename SparsityPatternType>
779 inline SparsityPatternType &
780 BlockSparsityPatternBase<SparsityPatternType>::block(const size_type row,
781 const size_type column)
782 {
783 AssertIndexRange(row, n_block_rows());
784 AssertIndexRange(column, n_block_cols());
785 return *sub_objects(row, column);
786 }
787
788
789
790 template <typename SparsityPatternType>
791 inline const SparsityPatternType &
792 BlockSparsityPatternBase<SparsityPatternType>::block(
793 const size_type row,
794 const size_type column) const
795 {
796 AssertIndexRange(row, n_block_rows());
797 AssertIndexRange(column, n_block_cols());
798 return *sub_objects(row, column);
799 }
800
801
802
803 template <typename SparsityPatternType>
804 inline const BlockIndices &
805 BlockSparsityPatternBase<SparsityPatternType>::get_row_indices() const
806 {
807 return row_indices;
808 }
809
810
811
812 template <typename SparsityPatternType>
813 inline const BlockIndices &
814 BlockSparsityPatternBase<SparsityPatternType>::get_column_indices() const
815 {
816 return column_indices;
817 }
818
819
820
821 template <typename SparsityPatternType>
822 inline void
823 BlockSparsityPatternBase<SparsityPatternType>::add(const size_type i,
824 const size_type j)
825 {
826 // if you get an error here, are
827 // you sure you called
828 // <tt>collect_sizes()</tt> before?
829 const std::pair<size_type, size_type> row_index =
830 row_indices.global_to_local(i),
831 col_index =
832 column_indices.global_to_local(j);
833 sub_objects[row_index.first][col_index.first]->add(row_index.second,
834 col_index.second);
835 }
836
837
838
839 template <typename SparsityPatternType>
840 template <typename ForwardIterator>
841 void
842 BlockSparsityPatternBase<SparsityPatternType>::add_entries(
843 const size_type row,
844 ForwardIterator begin,
845 ForwardIterator end,
846 const bool indices_are_sorted)
847 {
848 // In debug mode, verify that collect_sizes() was called by redoing the
849 // calculation
850 Assert(n_rows() == compute_n_rows(), ExcNeedsCollectSizes());
851 Assert(n_cols() == compute_n_cols(), ExcNeedsCollectSizes());
852
853 const size_type n_cols = static_cast<size_type>(end - begin);
854
855 if (indices_are_sorted && n_cols > 0)
856 {
857 block_column_indices[0].resize(0);
858
859 const std::pair<size_type, size_type> row_index =
860 this->row_indices.global_to_local(row);
861 const auto n_blocks = column_indices.size();
862
863 // Assume we start with the first block: since we assemble sparsity
864 // patterns one cell at a time this should always be true
865 size_type current_block = 0;
866 size_type current_start_index = column_indices.block_start(current_block);
867 size_type next_start_index =
868 current_block == n_blocks - 1 ?
869 numbers::invalid_dof_index :
870 column_indices.block_start(current_block + 1);
871
872 for (auto it = begin; it < end; ++it)
873 {
874 // BlockIndices::global_to_local() is a bit slow so instead we just
875 // keep track of which block we are in - as the indices are sorted we
876 // know that the block number can only increase.
877 if (*it >= next_start_index)
878 {
879 // we found a column outside the present block: write the present
880 // block entries and continue to the next block
881 sub_objects[row_index.first][current_block]->add_entries(
882 row_index.second,
883 block_column_indices[0].begin(),
884 block_column_indices[0].end(),
885 true);
886 block_column_indices[0].clear();
887
888 auto block_and_col = column_indices.global_to_local(*it);
889 current_block = block_and_col.first;
890 current_start_index = column_indices.block_start(current_block);
891 next_start_index =
892 current_block == n_blocks - 1 ?
893 numbers::invalid_dof_index :
894 column_indices.block_start(current_block + 1);
895 }
896 const size_type local_index = *it - current_start_index;
897 block_column_indices[0].push_back(local_index);
898
899 // Check that calculation:
900 if constexpr (running_in_debug_mode())
901 {
902 {
903 auto check_block_and_col = column_indices.global_to_local(*it);
904 Assert(current_block == check_block_and_col.first,
905 ExcInternalError());
906 Assert(local_index == check_block_and_col.second,
907 ExcInternalError());
908 }
909 }
910 }
911 // add whatever is left over:
912 sub_objects[row_index.first][current_block]->add_entries(
913 row_index.second,
914 block_column_indices[0].begin(),
915 block_column_indices[0].end(),
916 true);
917
918 return;
919 }
920 else
921 {
922 // Resize sub-arrays to n_cols. This
923 // is a bit wasteful, but we resize
924 // only a few times (then the maximum
925 // row length won't increase that
926 // much any more). At least we know
927 // that all arrays are going to be of
928 // the same size, so we can check
929 // whether the size of one is large
930 // enough before actually going
931 // through all of them.
932 if (block_column_indices[0].size() < n_cols)
933 for (size_type i = 0; i < this->n_block_cols(); ++i)
934 block_column_indices[i].resize(n_cols);
935
936 // Reset the number of added elements
937 // in each block to zero.
938 for (size_type i = 0; i < this->n_block_cols(); ++i)
939 counter_within_block[i] = 0;
940
941 // Go through the column indices to
942 // find out which portions of the
943 // values should be set in which
944 // block of the matrix. We need to
945 // touch all the data, since we can't
946 // be sure that the data of one block
947 // is stored contiguously (in fact,
948 // indices will be intermixed when it
949 // comes from an element matrix).
950 for (ForwardIterator it = begin; it != end; ++it)
951 {
952 const size_type col = *it;
953
954 const std::pair<size_type, size_type> col_index =
955 this->column_indices.global_to_local(col);
956
957 const size_type local_index = counter_within_block[col_index.first]++;
958
959 block_column_indices[col_index.first][local_index] = col_index.second;
960 }
961
962 // Now we found out about where the
963 // individual columns should start and
964 // where we should start reading out
965 // data. Now let's write the data into
966 // the individual blocks!
967 const std::pair<size_type, size_type> row_index =
968 this->row_indices.global_to_local(row);
969 for (size_type block_col = 0; block_col < n_block_cols(); ++block_col)
970 {
971 if (counter_within_block[block_col] == 0)
972 continue;
973 sub_objects[row_index.first][block_col]->add_entries(
974 row_index.second,
975 block_column_indices[block_col].begin(),
976 block_column_indices[block_col].begin() +
977 counter_within_block[block_col],
978 indices_are_sorted);
979 }
980 }
981 }
982
983
984
985 template <typename SparsityPatternType>
986 void
987 BlockSparsityPatternBase<SparsityPatternType>::add_row_entries(
988 const size_type &row,
989 const ArrayView<const size_type> &columns,
990 const bool indices_are_sorted)
991 {
992 add_entries(row, columns.begin(), columns.end(), indices_are_sorted);
993 }
994
995
996
997 template <typename SparsityPatternType>
998 inline bool
999 BlockSparsityPatternBase<SparsityPatternType>::exists(const size_type i,
1000 const size_type j) const
1001 {
1002 // if you get an error here, are
1003 // you sure you called
1004 // <tt>collect_sizes()</tt> before?
1005 const std::pair<size_type, size_type> row_index =
1006 row_indices.global_to_local(i),
1007 col_index =
1008 column_indices.global_to_local(j);
1009 return sub_objects[row_index.first][col_index.first]->exists(
1010 row_index.second, col_index.second);
1011 }
1012
1013
1014
1015 template <typename SparsityPatternType>
1016 inline unsigned int
1017 BlockSparsityPatternBase<SparsityPatternType>::row_length(
1018 const size_type row) const
1019 {
1020 const std::pair<size_type, size_type> row_index =
1021 row_indices.global_to_local(row);
1022
1023 unsigned int c = 0;
1024
1025 for (size_type b = 0; b < n_block_rows(); ++b)
1026 c += sub_objects[row_index.first][b]->row_length(row_index.second);
1027
1028 return c;
1029 }
1030
1031
1032
1033 template <typename SparsityPatternType>
1034 inline typename BlockSparsityPatternBase<SparsityPatternType>::size_type
1035 BlockSparsityPatternBase<SparsityPatternType>::n_block_cols() const
1036 {
1037 return block_columns;
1038 }
1039
1040
1041
1042 template <typename SparsityPatternType>
1043 inline typename BlockSparsityPatternBase<SparsityPatternType>::size_type
1044 BlockSparsityPatternBase<SparsityPatternType>::n_block_rows() const
1045 {
1046 return block_rows;
1047 }
1048
1049
1050 inline BlockDynamicSparsityPattern::size_type
1051 BlockDynamicSparsityPattern::column_number(const size_type row,
1052 const unsigned int index) const
1053 {
1054 // .first= ith block, .second = jth row in that block
1055 const std::pair<size_type, size_type> row_index =
1056 row_indices.global_to_local(row);
1057
1058 AssertIndexRange(index, row_length(row));
1059
1060 size_type c = 0;
1061 size_type block_columns = 0; // sum of n_cols for all blocks to the left
1062 for (unsigned int b = 0; b < this->n_block_cols(); ++b)
1063 {
1064 unsigned int rowlen =
1065 sub_objects[row_index.first][b]->row_length(row_index.second);
1066 if (index < c + rowlen)
1067 return block_columns +
1068 sub_objects[row_index.first][b]->column_number(row_index.second,
1069 index - c);
1070 c += rowlen;
1071 block_columns += sub_objects[row_index.first][b]->n_cols();
1072 }
1073
1074 DEAL_II_ASSERT_UNREACHABLE();
1075 return 0;
1076 }
1077
1078
1079 inline void
1080 BlockSparsityPattern::reinit(const size_type new_block_rows,
1081 const size_type new_block_columns)
1082 {
1083 BlockSparsityPatternBase<SparsityPattern>::reinit(new_block_rows,
1084 new_block_columns);
1085 }
1086
1087
1088 DEAL_II_NAMESPACE_CLOSE
1089
1090 #endif