Debian Codegraph @

include/deal.II/lac/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_sparsity_pattern_h
16 #define dealii_sparsity_pattern_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/array_view.h>
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/linear_index_iterator.h>
25
26 #include <deal.II/lac/sparsity_pattern_base.h>
27
28 // boost::serialization::make_array used to be in array.hpp, but was
29 // moved to a different file in BOOST 1.64
30 #include <boost/version.hpp>
31 #if BOOST_VERSION >= 106400
32 # include <boost/serialization/array_wrapper.hpp>
33 #else
34 # include <boost/serialization/array.hpp>
35 #endif
36 #include <boost/serialization/split_member.hpp>
37
38 #include <algorithm>
39 #include <iostream>
40 #include <memory>
41 #include <vector>
42
43 DEAL_II_NAMESPACE_OPEN
44
45 // Forward declarations
46 #ifndef DOXYGEN
47 class SparsityPattern;
48 class DynamicSparsityPattern;
49 class ChunkSparsityPattern;
50 template <typename number>
51 class FullMatrix;
52 template <typename number>
53 class SparseMatrix;
54 template <typename number>
55 class SparseLUDecomposition;
56 template <typename number>
57 class SparseILU;
58
59 namespace ChunkSparsityPatternIterators
60 {
61 class Accessor;
62 }
63 #endif
64
65 /**
66 * @addtogroup Sparsity
67 * @{
68 */
69
70 namespace internals
71 {
72 namespace SparsityPatternTools
73 {
74 /**
75 * Declare type for container size.
76 */
77 using size_type = types::global_dof_index;
78
79 /**
80 * Helper function to get the column index from a dereferenced iterator in
81 * the copy_from() function, if the inner iterator type points to plain
82 * unsigned integers.
83 */
84 size_type
85 get_column_index_from_iterator(const size_type i);
86
87 /**
88 * Helper function to get the column index from a dereferenced iterator in
89 * the copy_from() function, if the inner iterator type points to pairs of
90 * unsigned integers and some other value.
91 */
92 template <typename value>
93 size_type
94 get_column_index_from_iterator(const std::pair<size_type, value> &i);
95
96 /**
97 * Likewise, but sometimes needed for certain types of containers that
98 * make the first element of the pair constant (such as
99 * <tt>std::map</tt>).
100 */
101 template <typename value>
102 size_type
103 get_column_index_from_iterator(const std::pair<const size_type, value> &i);
104
105 } // namespace SparsityPatternTools
106 } // namespace internals
107
108
109 /**
110 * Iterators on objects of type SparsityPattern.
111 */
112 namespace SparsityPatternIterators
113 {
114 // forward declaration
115 class Iterator;
116
117 /**
118 * Declare type for container size.
119 */
120 using size_type = types::global_dof_index;
121
122 /**
123 * Accessor class for iterators into sparsity patterns. This class is also
124 * the base class for both const and non-const accessor classes into sparse
125 * matrices.
126 *
127 * Note that this class only allows read access to elements, providing their
128 * row and column number (or alternatively the index within the complete
129 * sparsity pattern). It does not allow modifying the sparsity pattern
130 * itself.
131 */
132 class Accessor
133 {
134 public:
135 /**
136 * Size type of SparsityPattern.
137 */
138 using size_type = SparsityPatternIterators::size_type;
139
140 /**
141 * Constructor.
142 */
143 Accessor(const SparsityPattern *matrix, const std::size_t linear_index);
144
145 /**
146 * Constructor. Construct the end accessor for the given sparsity pattern.
147 */
148 Accessor(const SparsityPattern *matrix);
149
150 /**
151 * Default constructor creating a dummy accessor. This constructor is here
152 * only to be able to store accessors in STL containers such as
153 * `std::vector`.
154 */
155 Accessor();
156
157 /**
158 * Row number of the element represented by this object. This function can
159 * only be called for entries for which is_valid_entry() is true.
160 */
161 size_type
162 row() const;
163
164 /**
165 * Index within the current row of the element represented by this object.
166 * This function can only be called for entries for which is_valid_entry()
167 * is true.
168 */
169 size_type
170 index() const;
171
172 /**
173 * This function returns the how-many'th entry within the entire sparsity
174 * pattern the current iterator points to. While the order of entries in
175 * a sparsity pattern is generally not important, this function allows
176 * indexing entries of the sparsity pattern using a linear index.
177 *
178 * This function can only be called for entries for which is_valid_entry()
179 * is true.
180 */
181 size_type
182 global_index() const;
183
184 /**
185 * Column number of the element represented by this object. This function
186 * can only be called for entries for which is_valid_entry() is true.
187 */
188 size_type
189 column() const;
190
191 /**
192 * Return whether the sparsity pattern entry pointed to by this iterator
193 * is valid or not. Note that after compressing the sparsity pattern, all
194 * entries are valid. However, before compression, the sparsity pattern
195 * allocated some memory to be used while still adding new nonzero
196 * entries; if you create iterators in this phase of the sparsity
197 * pattern's lifetime, you will iterate over elements that are not valid.
198 * If this is so, then this function will return false.
199 */
200 bool
201 is_valid_entry() const;
202
203 /**
204 * Comparison. True, if both iterators point to the same matrix position.
205 */
206 bool
207 operator==(const Accessor &) const;
208
209 /**
210 * Comparison operator. Result is true if either the first row number is
211 * smaller or if the row numbers are equal and the first index is smaller.
212 *
213 * This function is only valid if both iterators point into the same
214 * sparsity pattern.
215 */
216 bool
217 operator<(const Accessor &) const;
218
219 protected:
220 DeclExceptionMsg(DummyAccessor,
221 "The instance of this class was initialized"
222 " without SparsityPattern object, which"
223 " means that it is a dummy accessor that can"
224 " not do any operations.");
225
226 /**
227 * The sparsity pattern we operate on accessed.
228 */
229 const SparsityPattern *container;
230
231 /**
232 * Index in global sparsity pattern. This index represents the location
233 * the iterator/accessor points to within the array of the SparsityPattern
234 * class that stores the column numbers. It is also the index within the
235 * values array of a sparse matrix that stores the corresponding value of
236 * this site.
237 */
238 std::size_t linear_index;
239
240 /**
241 * Move the accessor to the next nonzero entry in the matrix.
242 */
243 void
244 advance();
245
246 // Grant access to iterator class.
247 friend class LinearIndexIterator<Iterator, Accessor>;
248
249 // Grant access to accessor class of ChunkSparsityPattern.
250 friend class ChunkSparsityPatternIterators::Accessor;
251 };
252
253
254
255 /**
256 * An iterator class for walking over the elements of a sparsity pattern.
257 *
258 * The typical use for these iterators is to iterate over the elements of a
259 * sparsity pattern (or, since they also serve as the basis for iterating
260 * over the elements of an associated matrix, over the elements of a sparse
261 * matrix), or over the elements of individual rows. There is no guarantee
262 * that the elements of a row are actually traversed in an order in which
263 * column numbers monotonically increase. See the documentation of the
264 * SparsityPattern class for more information.
265 *
266 * @note This class operates directly on the internal data structures of the
267 * SparsityPattern class. As a consequence, some operations are cheap and
268 * some are not. In particular, it is cheap to access the column index of
269 * the sparsity pattern entry pointed to. On the other hand, it is expensive
270 * to access the row index (this requires $O(\log(N))$ operations for a
271 * matrix with $N$ row). As a consequence, when you design algorithms that
272 * use these iterators, it is common practice to not loop over <i>all</i>
273 * elements of a sparsity pattern at once, but to have an outer loop over
274 * all rows and within this loop iterate over the elements of this row. This
275 * way, you only ever need to dereference the iterator to obtain the column
276 * indices whereas the (expensive) lookup of the row index can be avoided by
277 * using the loop index instead.
278 */
279 class Iterator : public LinearIndexIterator<Iterator, Accessor>
280 {
281 public:
282 /**
283 * Size type.
284 */
285 using size_type = types::global_dof_index;
286
287 /**
288 * Type of the stored pointer.
289 */
290 using container_pointer_type = SparsityPattern *;
291
292 /**
293 * Constructor. Create an iterator into the sparsity pattern @p sp for the
294 * given global index (i.e., the index of the given element counting from
295 * the zeroth row).
296 */
297 Iterator(const SparsityPattern *sp, const std::size_t linear_index);
298
299 /**
300 * Constructor. Create an iterator into the sparsity pattern @p sp for
301 * a given accessor.
302 */
303 Iterator(const Accessor &accessor);
304 };
305 } // namespace SparsityPatternIterators
306
307 /**
308 * This class stores a sparsity pattern in
309 * the <a
310 * href="https://en.wikipedia.org/wiki/Sparse_matrix">compressed row storage
311 * (CSR)</a> format to store data, and is used as the basis for the
312 * SparseMatrix class.
313 *
314 * The elements of a SparsityPattern, corresponding to the places where
315 * SparseMatrix objects can store nonzero entries, are stored row-by-row.
316 * Within each row, elements are generally stored left-to-right in increasing
317 * column index order; the exception to this rule is that if the matrix is
318 * square (n_rows() == n_columns()), then the diagonal entry is stored as the
319 * first element in each row to make operations like applying a Jacobi or SSOR
320 * preconditioner faster. As a consequence, if you traverse the elements of a
321 * row of a SparsityPattern with the help of iterators into this object (using
322 * SparsityPattern::begin and SparsityPattern::end) you will find that the
323 * elements are not sorted by column index within each row whenever the matrix
324 * is square (the first item will be the diagonal, followed by the other
325 * entries sorted by column index).
326 *
327 * While this class forms the basis upon which SparseMatrix objects base
328 * their storage format, and thus plays a central role in setting up linear
329 * systems, it is rarely set up directly due to the way it stores its
330 * information. Rather, one typically goes through an intermediate format
331 * first, see for example the step-2 tutorial program as well as the
332 * documentation topic
333 * @ref Sparsity.
334 *
335 * You can iterate over entries in the pattern using begin(), end(),
336 * begin(row), and end(row). These functions return an iterator of type
337 * SparsityPatternIterators::Iterator. When dereferencing an iterator @p it,
338 * you have access to the member functions in
339 * SparsityPatternIterators::Accessor, like <tt>it->column()</tt> and
340 * <tt>it->row()</tt>.
341 */
342 class SparsityPattern : public SparsityPatternBase
343 {
344 public:
345 /**
346 * Declare type for container size.
347 */
348 using size_type = types::global_dof_index;
349
350 /**
351 * Define a value which is used to indicate that a certain value in the
352 * #colnums array is unused, i.e. does not represent a certain column number
353 * index.
354 *
355 * Indices with this invalid value are used to insert new entries to the
356 * sparsity pattern using the add() member function, and are removed when
357 * calling compress().
358 *
359 * You should not assume that the variable declared here has a certain
360 * value. The initialization is given here only to enable the compiler to
361 * perform some optimizations, but the actual value of the variable may
362 * change over time.
363 */
364 static constexpr size_type invalid_entry = numbers::invalid_size_type;
365
366 /**
367 * Typedef an iterator class that allows to walk over all nonzero elements
368 * of a sparsity pattern.
369 */
370 using const_iterator = SparsityPatternIterators::Iterator;
371
372 /**
373 * Typedef an iterator class that allows to walk over all nonzero elements
374 * of a sparsity pattern.
375 *
376 * Since the iterator does not allow to modify the sparsity pattern, this
377 * type is the same as that for @p const_iterator.
378 */
379 using iterator = SparsityPatternIterators::Iterator;
380
381 /**
382 * @name Iterators
383 *
384 * @{
385 */
386
387 /**
388 * Iterator starting at the first entry of the matrix. The resulting
389 * iterator can be used to walk over all nonzero entries of the sparsity
390 * pattern.
391 *
392 * The order in which elements are accessed depends on the storage scheme
393 * implemented by derived classes.
394 */
395 iterator
396 begin() const;
397
398 /**
399 * Final iterator.
400 */
401 iterator
402 end() const;
403
404 /**
405 * Iterator starting at the first entry of row <tt>r</tt>.
406 *
407 * Note that if the given row is empty, i.e. does not contain any nonzero
408 * entries, then the iterator returned by this function equals
409 * <tt>end(r)</tt>. Note also that the iterator may not be dereferenceable in
410 * that case.
411 *
412 * The order in which elements are accessed depends on the storage scheme
413 * implemented by derived classes.
414 */
415 iterator
416 begin(const size_type r) const;
417
418 /**
419 * Final iterator of row <tt>r</tt>. It points to the first element past the
420 * end of line @p r, or past the end of the entire sparsity pattern.
421 *
422 * Note that the end iterator is not necessarily dereferenceable. This is in
423 * particular the case if it is the end iterator for the last row of a
424 * matrix.
425 */
426 iterator
427 end(const size_type r) const;
428
429 /**
430 * @}
431 */
432
433 /**
434 * @name Construction and setup
435 *
436 * Constructors, destructor, functions initializing, copying and filling an
437 * object.
438 */
439 /**
440 * @{
441 */
442
443 /**
444 * Initialize the matrix empty, that is with no memory allocated. This is
445 * useful if you want such objects as member variables in other classes. You
446 * can make the structure usable by calling the reinit() function.
447 */
448 SparsityPattern();
449
450 /**
451 * Copy constructor. This constructor is only allowed to be called if the
452 * matrix structure to be copied is empty. This is so in order to prevent
453 * involuntary copies of objects for temporaries, which can use large
454 * amounts of computing time. However, copy constructors are needed if one
455 * wants to place a SparsityPattern in a container, e.g., to write such
456 * statements like <tt>v.push_back (SparsityPattern());</tt>, with
457 * <tt>v</tt> a std::vector of SparsityPattern objects.
458 *
459 * Usually, it is sufficient to use the explicit keyword to disallow
460 * unwanted temporaries, but this does not work for <tt>std::vector</tt>s.
461 * Since copying a structure like this is not useful anyway because multiple
462 * matrices can use the same sparsity structure, copies are only allowed for
463 * empty objects, as described above.
464 */
465 SparsityPattern(const SparsityPattern &);
466
467 /**
468 * Initialize a rectangular pattern of size <tt>m x n</tt>.
469 *
470 * @param[in] m The number of rows.
471 * @param[in] n The number of columns.
472 * @param[in] max_per_row Maximum number of nonzero entries per row.
473 */
474 SparsityPattern(const size_type m,
475 const size_type n,
476 const unsigned int max_per_row);
477
478
479 /**
480 * Initialize a rectangular pattern of size <tt>m x n</tt>.
481 *
482 * @param[in] m The number of rows.
483 * @param[in] n The number of columns.
484 * @param[in] row_lengths Possible number of nonzero entries for each row.
485 * This vector must have one entry for each row.
486 */
487 SparsityPattern(const size_type m,
488 const size_type n,
489 const std::vector<unsigned int> &row_lengths);
490
491 /**
492 * Initialize a quadratic pattern of dimension <tt>m</tt> with at most
493 * <tt>max_per_row</tt> nonzero entries per row.
494 *
495 * This constructor automatically enables optimized storage of diagonal
496 * elements. To avoid this, use the constructor taking row and column
497 * numbers separately.
498 */
499 SparsityPattern(const size_type m, const unsigned int max_per_row);
500
501 /**
502 * Initialize a quadratic pattern of size <tt>m x m</tt>.
503 *
504 * @param[in] m The number of rows and columns.
505 * @param[in] row_lengths Maximum number of nonzero entries for each row.
506 * This vector must have one entry for each row.
507 */
508 SparsityPattern(const size_type m,
509 const std::vector<unsigned int> &row_lengths);
510
511 /**
512 * Make a copy with extra off-diagonals.
513 *
514 * This constructs objects intended for the application of the ILU(n)-method
515 * or other incomplete decompositions. Therefore, additional to the
516 * original entry structure, space for <tt>extra_off_diagonals</tt>
517 * side-diagonals is provided on both sides of the main diagonal.
518 *
519 * <tt>max_per_row</tt> is the maximum number of nonzero elements per row
520 * which this structure is to hold. It is assumed that this number is
521 * sufficiently large to accommodate both the elements in <tt>original</tt>
522 * as well as the new off-diagonal elements created by this constructor. You
523 * will usually want to give the same number as you gave for
524 * <tt>original</tt> plus the number of side diagonals times two. You may
525 * however give a larger value if you wish to add further nonzero entries
526 * for the decomposition based on other criteria than their being on
527 * side-diagonals.
528 *
529 * This function requires that <tt>original</tt> refers to a quadratic
530 * matrix structure. It must be compressed. The matrix structure is not
531 * compressed after this function finishes.
532 */
533 SparsityPattern(const SparsityPattern &original,
534 const unsigned int max_per_row,
535 const size_type extra_off_diagonals);
536
537 /**
538 * Copy operator. For this the same holds as for the copy constructor: it is
539 * declared, defined and fine to be called, but the latter only for empty
540 * objects.
541 */
542 SparsityPattern &
543 operator=(const SparsityPattern &);
544
545 /**
546 * Reallocate memory for a matrix of size @p m times @p n. The number of
547 * entries for each row is taken from the ArrayView @p row_lengths which
548 * has to give this number of each row $i=0\ldots m-1$.
549 *
550 * If <tt>m*n==0</tt> all memory is freed, resulting in a total
551 * reinitialization of the object. If it is nonzero, new memory is only
552 * allocated if the new size extends the old one. This is done to save time
553 * and to avoid fragmentation of the heap.
554 */
555 void
556 reinit(const size_type m,
557 const size_type n,
558 const ArrayView<const unsigned int> &row_lengths);
559
560 /**
561 * Same as the other reinit(), but uses a std::vector instead of an ArrayView.
562 */
563 void
564 reinit(const size_type m,
565 const size_type n,
566 const std::vector<unsigned int> &row_lengths);
567
568 /**
569 * Reallocate memory and set up data structures for a new matrix with @p m
570 * rows and @p n columns, with at most @p max_per_row
571 * nonzero entries per row.
572 *
573 * This function simply maps its operations to the other reinit()
574 * function.
575 */
576 void
577 reinit(const size_type m, const size_type n, const unsigned int max_per_row);
578
579 /**
580 * This function compresses the sparsity structure that this object
581 * represents. It does so by eliminating unused entries and sorting the
582 * remaining ones to allow faster access by usage of binary search
583 * algorithms. A special sorting scheme is used for the diagonal entry of
584 * quadratic matrices, which is always the first entry of each row.
585 *
586 * The memory which is no more needed is released.
587 *
588 * SparseMatrix objects require the SparsityPattern objects they are
589 * initialized with to be compressed, to reduce memory requirements.
590 */
591 void
592 compress();
593
594
595 /**
596 * This function can be used as a replacement for reinit(), subsequent calls
597 * to add() and a final call to close() if you know exactly in advance the
598 * entries that will form the matrix sparsity pattern.
599 *
600 * The first two parameters determine the size of the matrix. For the two
601 * last ones, note that a sparse matrix can be described by a sequence of
602 * rows, each of which is represented by a sequence of pairs of column
603 * indices and values. In the present context, the begin() and end()
604 * parameters designate iterators (of forward iterator type) into a
605 * container, one representing one row. The distance between begin() and
606 * end() should therefore be equal to n_rows(). These iterators may be
607 * iterators of <tt>std::vector</tt>, <tt>std::list</tt>, pointers into a
608 * C-style array, or any other iterator satisfying the requirements of a
609 * forward iterator. The objects pointed to by these iterators (i.e. what we
610 * get after applying <tt>operator*</tt> or <tt>operator-></tt> to one of
611 * these iterators) must be a container itself that provides functions
612 * <tt>begin</tt> and <tt>end</tt> designating a range of iterators that
613 * describe the contents of one line. Dereferencing these inner iterators
614 * must either yield a pair of an unsigned integer as column index and a
615 * value of arbitrary type (such a type would be used if we wanted to
616 * describe a sparse matrix with one such object), or simply an unsigned
617 * integer (of we only wanted to describe a sparsity pattern). The function
618 * is able to determine itself whether an unsigned integer or a pair is what
619 * we get after dereferencing the inner iterators, through some template
620 * magic.
621 *
622 * While the order of the outer iterators denotes the different rows of the
623 * matrix, the order of the inner iterator denoting the columns does not
624 * matter, as they are sorted internal to this function anyway.
625 *
626 * Since that all sounds very complicated, consider the following example
627 * code, which may be used to fill a sparsity pattern:
628 * @code
629 * std::vector<std::vector<unsigned int> > column_indices (n_rows);
630 * for (unsigned int row=0; row<n_rows; ++row)
631 * // generate necessary columns in this row
632 * fill_row (column_indices[row]);
633 *
634 * sparsity.copy_from (n_rows, n_cols,
635 * column_indices.begin(),
636 * column_indices.end());
637 * @endcode
638 *
639 * Note that this example works since the iterators dereferenced yield
640 * containers with functions <tt>begin</tt> and <tt>end</tt> (namely
641 * <tt>std::vector</tt>s), and the inner iterators dereferenced yield
642 * unsigned integers as column indices. Note that we could have replaced
643 * each of the two <tt>std::vector</tt> occurrences by <tt>std::list</tt>,
644 * and the inner one by <tt>std::set</tt> as well.
645 *
646 * Another example would be as follows, where we initialize a whole matrix,
647 * not only a sparsity pattern:
648 * @code
649 * std::vector<std::map<unsigned int,double> > entries (n_rows);
650 * for (unsigned int row=0; row<n_rows; ++row)
651 * // generate necessary pairs of columns
652 * // and corresponding values in this row
653 * fill_row (entries[row]);
654 *
655 * sparsity.copy_from (n_rows, n_cols,
656 * column_indices.begin(),
657 * column_indices.end());
658 * matrix.reinit (sparsity);
659 * matrix.copy_from (column_indices.begin(),
660 * column_indices.end());
661 * @endcode
662 *
663 * This example works because dereferencing iterators of the inner type
664 * yields a pair of unsigned integers and a value, the first of which we
665 * take as column index. As previously, the outer <tt>std::vector</tt> could
666 * be replaced by <tt>std::list</tt>, and the inner <tt>std::map<unsigned
667 * int,double></tt> could be replaced by <tt>std::vector<std::pair<unsigned
668 * int,double> ></tt>, or a list or set of such pairs, as they all return
669 * iterators that point to such pairs.
670 */
671 template <typename ForwardIterator>
672 void
673 copy_from(const size_type n_rows,
674 const size_type n_cols,
675 const ForwardIterator begin,
676 const ForwardIterator end);
677
678 /**
679 * Copy data from a DynamicSparsityPattern. Previous content of this object
680 * is lost, and the sparsity pattern is in compressed mode afterwards.
681 */
682 void
683 copy_from(const DynamicSparsityPattern &dsp);
684
685 /**
686 * Copy data from a SparsityPattern. Previous content of this object is
687 * lost, and the sparsity pattern is in compressed mode afterwards.
688 */
689 void
690 copy_from(const SparsityPattern &sp);
691
692 /**
693 * Take a full matrix and use its nonzero entries to generate a sparse
694 * matrix entry pattern for this object.
695 *
696 * Previous content of this object is lost, and the sparsity pattern is in
697 * compressed mode afterwards.
698 *
699 * Once you have built a sparsity pattern with this function, you
700 * probably want to attach a SparseMatrix object to it. The original
701 * `matrix` object can then be copied into this SparseMatrix object
702 * using the version of SparseMatrix::copy_from() that takes a
703 * FullMatrix object as argument. Through this procedure, you can
704 * convert a FullMatrix into a SparseMatrix.
705 */
706 template <typename number>
707 void
708 copy_from(const FullMatrix<number> &matrix);
709
710 /**
711 * Add a nonzero entry to the matrix. This function may only be called for
712 * non-compressed sparsity patterns.
713 *
714 * If the entry already exists, nothing bad happens.
715 */
716 void
717 add(const size_type i, const size_type j);
718
719 /**
720 * Add several nonzero entries to the specified matrix row. This function
721 * may only be called for non-compressed sparsity patterns.
722 *
723 * If some of the entries already exist, nothing bad happens.
724 */
725 template <typename ForwardIterator>
726 void
727 add_entries(const size_type row,
728 ForwardIterator begin,
729 ForwardIterator end,
730 const bool indices_are_sorted = false);
731
732 virtual void
733 add_row_entries(const size_type &row,
734 const ArrayView<const size_type> &columns,
735 const bool indices_are_sorted = false) override;
736
737 using SparsityPatternBase::add_entries;
738
739 /**
740 * Make the sparsity pattern symmetric by adding the sparsity pattern of the
741 * transpose object.
742 *
743 * This function throws an exception if the sparsity pattern does not
744 * represent a quadratic matrix.
745 */
746 void
747 symmetrize();
748
749 /**
750 * @}
751 */
752
753
754 /**
755 * @name Querying information
756 */
757 /**
758 * @{
759 */
760
761 /**
762 * Return the number of nonzero elements of this matrix. Actually, it
763 * returns the number of entries in the sparsity pattern; if any of the
764 * entries should happen to be zero, it is counted anyway.
765 *
766 * This function may only be called if the matrix struct is compressed. It
767 * does not make too much sense otherwise anyway.
768 */
769 std::size_t
770 n_nonzero_elements() const;
771
772 /**
773 * Return whether the object is empty. It is empty if no memory is
774 * allocated, which is the same as that both dimensions are zero.
775 */
776 bool
777 empty() const;
778
779 /**
780 * Compute the bandwidth of the matrix represented by this structure. The
781 * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$
782 * represents a nonzero entry of the matrix. Consequently, the maximum
783 * bandwidth a $n\times m$ matrix can have is $\max\{n-1,m-1\}$, a diagonal
784 * matrix has bandwidth 0, and there are at most $2*q+1$ entries per row if
785 * the bandwidth is $q$. The returned quantity is sometimes called "half
786 * bandwidth" in the literature.
787 */
788 size_type
789 bandwidth() const;
790
791 /**
792 * Return whether the structure is compressed or not.
793 */
794 bool
795 is_compressed() const;
796
797 /**
798 * Return the maximum number of entries per row. Before compression, this
799 * equals the number given to the constructor, while after compression, it
800 * equals the maximum number of entries actually allocated by the user.
801 */
802 size_type
803 max_entries_per_row() const;
804
805 /**
806 * Test for equality of two SparsityPatterns.
807 */
808 bool
809 operator==(const SparsityPattern &) const;
810
811 /**
812 * Return whether this object stores only those entries that have been added
813 * explicitly, or if the sparsity pattern contains elements that have been
814 * added through other means (implicitly) while building it. For the current
815 * class, the result is false if and only if it is square because it then
816 * unconditionally stores the diagonal entries whether they have been added
817 * explicitly or not.
818 *
819 * This function mainly serves the purpose of describing the current class
820 * in cases where several kinds of sparsity patterns can be passed as
821 * template arguments.
822 */
823 bool
824 stores_only_added_elements() const;
825
826 /**
827 * Number of entries in a specific row.
828 */
829 unsigned int
830 row_length(const size_type row) const;
831
832 /**
833 * Determine an estimate for the memory consumption (in bytes) of this
834 * object. See MemoryConsumption.
835 */
836 std::size_t
837 memory_consumption() const;
838
839 /**
840 * @}
841 */
842
843 /**
844 * @name Accessing entries
845 *
846 * @{
847 */
848
849 /**
850 * Return the index of the matrix element with row number <tt>i</tt> and
851 * column number <tt>j</tt>. If the matrix element is not a nonzero one,
852 * return SparsityPattern::invalid_entry.
853 *
854 * This function is usually called by the SparseMatrix::operator()(). It may
855 * only be called for compressed sparsity patterns, since in this case
856 * searching whether the entry exists can be done quite fast with a binary
857 * sort algorithm because the column numbers are sorted.
858 *
859 * If <tt>m</tt> is the number of entries in <tt>row</tt>, then the
860 * complexity of this function is <i>log(m)</i> if the sparsity pattern is
861 * compressed.
862 *
863 * @note This function is not cheap since it has to search through all of
864 * the elements of the given row <tt>i</tt> to find whether index <tt>j</tt>
865 * exists. Thus, it is more expensive than necessary in cases where you want
866 * to loop over all of the nonzero elements of this sparsity pattern (or of
867 * a sparse matrix associated with it) or of a single row. In such cases, it
868 * is more efficient to use iterators over the elements of the sparsity
869 * pattern or of the sparse matrix.
870 */
871 size_type
872 operator()(const size_type i, const size_type j) const;
873
874 /**
875 * Check if a value at a certain position may be non-zero.
876 */
877 bool
878 exists(const size_type i, const size_type j) const;
879
880 /**
881 * Access to column number field. Return the column number of the
882 * <tt>index</tt>th entry in <tt>row</tt>. Note that if diagonal elements
883 * are optimized, the first element in each row is the diagonal element,
884 * i.e. <tt>column_number(row,0)==row</tt>.
885 *
886 * If the sparsity pattern is already compressed, then (except for the
887 * diagonal element), the entries are sorted by columns, i.e.
888 * <tt>column_number(row,i)</tt> <tt><</tt> <tt>column_number(row,i+1)</tt>.
889 */
890 size_type
891 column_number(const size_type row, const unsigned int index) const;
892
893 /**
894 * This is the inverse operation to operator()(): given a global index, find
895 * out row and column of the matrix entry to which it belongs. The returned
896 * value is the pair composed of row and column index.
897 *
898 * This function may only be called if the sparsity pattern is closed. The
899 * global index must then be between zero and n_nonzero_elements().
900 *
901 * If <tt>N</tt> is the number of rows of this matrix, then the complexity
902 * of this function is <i>log(N)</i>.
903 */
904 std::pair<size_type, size_type>
905 matrix_position(const std::size_t global_index) const;
906
907 /**
908 * The index of a global matrix entry in its row.
909 *
910 * This function is analogous to operator(), but it computes the index not
911 * with respect to the total field, but only with respect to the row
912 * <tt>j</tt>.
913 */
914 size_type
915 row_position(const size_type i, const size_type j) const;
916
917 /**
918 * @}
919 */
920
921 /**
922 * @name Input/Output
923 */
924 /**
925 * @{
926 */
927
928 /**
929 * Print the sparsity of the matrix. The output consists of one line per row
930 * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
931 * <i>jn</i> are the allocated columns in this row.
932 */
933 void
934 print(std::ostream &out) const;
935
936 /**
937 * Print the sparsity of the matrix in a format that <tt>gnuplot</tt>
938 * understands and which can be used to plot the sparsity pattern in a
939 * graphical way. The format consists of pairs <tt>i j</tt> of nonzero
940 * elements, each representing one entry of this matrix, one per line of the
941 * output file. Indices are counted from zero on, as usual. Since sparsity
942 * patterns are printed in the same way as matrices are displayed, we print
943 * the negative of the column index, which means that the <tt>(0,0)</tt>
944 * element is in the top left rather than in the bottom left corner.
945 *
946 * Print the sparsity pattern in gnuplot by setting the data style to dots
947 * or points and use the <tt>plot</tt> command.
948 */
949 void
950 print_gnuplot(std::ostream &out) const;
951
952 /**
953 * Prints the sparsity of the matrix in a .svg file which can be opened in a
954 * web browser. The .svg file contains squares which correspond to the
955 * entries in the matrix. An entry in the matrix which contains a non-zero
956 * value corresponds with a red square while a zero-valued entry in the
957 * matrix correspond with a white square.
958 */
959 void
960 print_svg(std::ostream &out) const;
961
962 /**
963 * Write the data of this object en bloc to a file. This is done in a binary
964 * mode, so the output is neither readable by humans nor (probably) by other
965 * computers using a different operating system or number format.
966 *
967 * The purpose of this function is that you can swap out matrices and
968 * sparsity pattern if you are short of memory, want to communicate between
969 * different programs, or allow objects to be persistent across different
970 * runs of the program.
971 */
972 void
973 block_write(std::ostream &out) const;
974
975 /**
976 * Read data that has previously been written by block_write() from a file.
977 * This is done using the inverse operations to the above function, so it is
978 * reasonably fast because the bitstream is not interpreted except for a few
979 * numbers up front.
980 *
981 * The object is resized on this operation, and all previous contents are
982 * lost.
983 *
984 * A primitive form of error checking is performed which will recognize the
985 * bluntest attempts to interpret some data as a vector stored bitwise to a
986 * file, but not more.
987 */
988 void
989 block_read(std::istream &in);
990
991 /**
992 * Write the data of this object to a stream for the purpose of
993 * serialization
994 */
995 template <class Archive>
996 void
997 save(Archive &ar, const unsigned int version) const;
998
999 /**
1000 * Read the data of this object from a stream for the purpose of
1001 * serialization
1002 */
1003 template <class Archive>
1004 void
1005 load(Archive &ar, const unsigned int version);
1006
1007 #ifdef DOXYGEN
1008 /**
1009 * Write and read the data of this object from a stream for the purpose
1010 * of serialization.
1011 */
1012 template <class Archive>
1013 void
1014 serialize(Archive &archive, const unsigned int version);
1015 #else
1016 // This macro defines the serialize() method that is compatible with
1017 // the templated save() and load() method that have been implemented.
1018 BOOST_SERIALIZATION_SPLIT_MEMBER()
1019 #endif
1020
1021 /**
1022 * @}
1023 */
1024
1025 /**
1026 * @addtogroup Exceptions
1027 *
1028 * @{
1029 */
1030 /**
1031 * Exception
1032 */
1033 DeclException2(ExcIteratorRange,
1034 int,
1035 int,
1036 << "The iterators denote a range of " << arg1
1037 << " elements, but the given number of rows was " << arg2);
1038 /**
1039 * Exception
1040 */
1041 DeclException1(ExcInvalidNumberOfPartitions,
1042 int,
1043 << "The number of partitions you gave is " << arg1
1044 << ", but must be greater than zero.");
1045
1046 /**
1047 * You tried to add an element to a row, but there was no space left.
1048 */
1049 DeclException2(ExcNotEnoughSpace,
1050 int,
1051 int,
1052 << "Upon entering a new entry to row " << arg1
1053 << ": there was no free entry any more. " << std::endl
1054 << "(Maximum number of entries for this row: " << arg2
1055 << "; maybe the matrix is already compressed?)");
1056
1057 /**
1058 * This operation changes the structure of the SparsityPattern and is not
1059 * possible after compress() has been called.
1060 */
1061 DeclExceptionMsg(
1062 ExcMatrixIsCompressed,
1063 "The operation you attempted changes the structure of the SparsityPattern "
1064 "and is not possible after compress() has been called.");
1065
1066 /**
1067 * The operation is only allowed after the SparsityPattern has been set up
1068 * and compress() was called.
1069 */
1070 DeclExceptionMsg(
1071 ExcNotCompressed,
1072 "The operation you attempted is only allowed after the SparsityPattern "
1073 "has been set up and compress() was called.");
1074
1075 /**
1076 * @}
1077 */
1078 private:
1079 /**
1080 * Is special treatment of diagonals enabled?
1081 */
1082 bool store_diagonal_first_in_row;
1083
1084 /**
1085 * Maximum number of rows that can be stored in the #rowstart array. Since
1086 * reallocation of that array only happens if the present one is too small,
1087 * but never when the size of this matrix structure shrinks, #max_dim might
1088 * be larger than #rows and in this case #rowstart has more elements than
1089 * are used.
1090 */
1091 size_type max_dim;
1092
1093 /**
1094 * Size of the actually allocated array #colnums. Here, the same applies as
1095 * for the #rowstart array, i.e. it may be larger than the actually used
1096 * part of the array.
1097 */
1098 std::size_t max_vec_len;
1099
1100 /**
1101 * Maximum number of elements per row. This is set to the value given to the
1102 * reinit() function (or to the constructor), or to the maximum row length
1103 * computed from the vectors in case the more flexible constructors or
1104 * reinit versions are called. Its value is more or less meaningless after
1105 * compress() has been called.
1106 */
1107 unsigned int max_row_length;
1108
1109 /**
1110 * Array which hold for each row which is the first element in #colnums
1111 * belonging to that row. Note that the size of the array is one larger than
1112 * the number of rows, because the last element is used for
1113 * <tt>row</tt>=#rows, i.e. the row past the last used one. The value of
1114 * #rowstart[#rows]} equals the index of the element past the end in
1115 * #colnums; this way, we are able to write loops like <tt>for
1116 * (i=rowstart[k]; i<rowstart[k+1]; ++i)</tt> also for the last row.
1117 *
1118 * Note that the actual size of the allocated memory may be larger than the
1119 * region that is used. The actual number of elements that was allocated is
1120 * stored in #max_dim.
1121 */
1122 std::unique_ptr<std::size_t[]> rowstart;
1123
1124 /**
1125 * Array of column numbers. In this array, we store for each non-zero
1126 * element its column number. The column numbers for the elements in row
1127 * <i>r</i> are stored within the index range
1128 * #rowstart[<i>r</i>]...#rowstart[<i>r+1</i>]. Therefore to find out
1129 * whether a given element (<i>r,c</i>) exists, we have to check whether the
1130 * column number <i>c</i> exists in the above-mentioned range within this
1131 * array. If it exists, say at position <i>p</i> within this array, the
1132 * value of the respective element in the sparse matrix will also be at
1133 * position <i>p</i> of the values array of that class.
1134 *
1135 * At the beginning, all elements of this array are set to @p -1 indicating
1136 * invalid (unused) column numbers (diagonal elements are preset if
1137 * optimized storage is requested, though). Now, if nonzero elements are
1138 * added, one column number in the row's respective range after the other is
1139 * set to the column number of the added element. When compress is called,
1140 * unused elements (indicated by column numbers @p -1) are eliminated by
1141 * copying the column number of subsequent rows and the column numbers
1142 * within each row (with possible exception of the diagonal element) are
1143 * sorted, such that finding whether an element exists and determining its
1144 * position can be done by a binary search.
1145 */
1146 std::unique_ptr<size_type[]> colnums;
1147
1148 /**
1149 * Store whether the compress() function was called for this object.
1150 */
1151 bool compressed;
1152
1153 // Make all sparse matrices friends of this class.
1154 template <typename number>
1155 friend class SparseMatrix;
1156 template <typename number>
1157 friend class SparseLUDecomposition;
1158 template <typename number>
1159 friend class SparseILU;
1160 template <typename number>
1161 friend class ChunkSparseMatrix;
1162
1163 friend class ChunkSparsityPattern;
1164 friend class DynamicSparsityPattern;
1165
1166 // Also give access to internal details to the iterator/accessor classes.
1167 friend class SparsityPatternIterators::Iterator;
1168 friend class SparsityPatternIterators::Accessor;
1169 friend class ChunkSparsityPatternIterators::Accessor;
1170 };
1171
1172
1173 /**
1174 * @}
1175 */
1176 /*---------------------- Inline functions -----------------------------------*/
1177
1178 #ifndef DOXYGEN
1179
1180
1181 namespace SparsityPatternIterators
1182 {
1183 inline Accessor::Accessor(const SparsityPattern *sparsity_pattern,
1184 const std::size_t i)
1185 : container(sparsity_pattern)
1186 , linear_index(i)
1187 {}
1188
1189
1190
1191 inline Accessor::Accessor(const SparsityPattern *sparsity_pattern)
1192 : container(sparsity_pattern)
1193 , linear_index(container->rowstart[container->rows])
1194 {}
1195
1196
1197
1198 inline Accessor::Accessor()
1199 : container(nullptr)
1200 , linear_index(numbers::invalid_size_type)
1201 {}
1202
1203
1204
1205 inline bool
1206 Accessor::is_valid_entry() const
1207 {
1208 Assert(container != nullptr, DummyAccessor());
1209 return (linear_index < container->rowstart[container->rows] &&
1210 container->colnums[linear_index] != SparsityPattern::invalid_entry);
1211 }
1212
1213
1214
1215 inline size_type
1216 Accessor::row() const
1217 {
1218 Assert(is_valid_entry() == true, ExcInvalidIterator());
1219
1220 const std::size_t *insert_point =
1221 std::upper_bound(container->rowstart.get(),
1222 container->rowstart.get() + container->rows + 1,
1223 linear_index);
1224 return insert_point - container->rowstart.get() - 1;
1225 }
1226
1227
1228
1229 inline size_type
1230 Accessor::column() const
1231 {
1232 Assert(is_valid_entry() == true, ExcInvalidIterator());
1233
1234 return (container->colnums[linear_index]);
1235 }
1236
1237
1238
1239 inline size_type
1240 Accessor::index() const
1241 {
1242 Assert(is_valid_entry() == true, ExcInvalidIterator());
1243
1244 return linear_index - container->rowstart[row()];
1245 }
1246
1247
1248
1249 inline size_type
1250 Accessor::global_index() const
1251 {
1252 Assert(is_valid_entry() == true, ExcInvalidIterator());
1253
1254 return linear_index;
1255 }
1256
1257
1258
1259 inline bool
1260 Accessor::operator==(const Accessor &other) const
1261 {
1262 return (container == other.container && linear_index == other.linear_index);
1263 }
1264
1265
1266
1267 inline bool
1268 Accessor::operator<(const Accessor &other) const
1269 {
1270 Assert(container != nullptr, DummyAccessor());
1271 Assert(other.container != nullptr, DummyAccessor());
1272 Assert(container == other.container, ExcInternalError());
1273
1274 return linear_index < other.linear_index;
1275 }
1276
1277
1278
1279 inline void
1280 Accessor::advance()
1281 {
1282 Assert(container != nullptr, DummyAccessor());
1283 Assert(linear_index < container->rowstart[container->rows],
1284 ExcIteratorPastEnd());
1285 ++linear_index;
1286 }
1287
1288
1289 inline Iterator::Iterator(const SparsityPattern *sp,
1290 const std::size_t linear_index)
1291 : LinearIndexIterator<Iterator, Accessor>(Accessor(sp, linear_index))
1292 {}
1293
1294
1295 inline Iterator::Iterator(const Accessor &accessor)
1296 : LinearIndexIterator<Iterator, Accessor>(accessor)
1297 {}
1298
1299
1300 } // namespace SparsityPatternIterators
1301
1302
1303
1304 inline std::size_t
1305 SparsityPattern::n_nonzero_elements() const
1306 {
1307 Assert(compressed, ExcNotCompressed());
1308
1309 if ((rowstart != nullptr) && (colnums != nullptr))
1310 return rowstart[rows] - rowstart[0];
1311 else
1312 // the object is empty or has zero size
1313 return 0;
1314 }
1315
1316
1317
1318 inline bool
1319 SparsityPattern::is_compressed() const
1320 {
1321 return compressed;
1322 }
1323
1324
1325
1326 inline bool
1327 SparsityPattern::stores_only_added_elements() const
1328 {
1329 return (store_diagonal_first_in_row == false);
1330 }
1331
1332
1333
1334 inline unsigned int
1335 SparsityPattern::row_length(const size_type row) const
1336 {
1337 AssertIndexRange(row, rows);
1338 return rowstart[row + 1] - rowstart[row];
1339 }
1340
1341
1342
1343 inline SparsityPattern::size_type
1344 SparsityPattern::column_number(const size_type row,
1345 const unsigned int index) const
1346 {
1347 AssertIndexRange(row, rows);
1348 AssertIndexRange(index, row_length(row));
1349
1350 return colnums[rowstart[row] + index];
1351 }
1352
1353
1354
1355 inline SparsityPattern::iterator
1356 SparsityPattern::begin() const
1357 {
1358 if (n_rows() > 0)
1359 return {this, rowstart[0]};
1360 else
1361 return end();
1362 }
1363
1364
1365
1366 inline SparsityPattern::iterator
1367 SparsityPattern::end() const
1368 {
1369 if (n_rows() > 0)
1370 return {this, rowstart[rows]};
1371 else
1372 return {nullptr, 0};
1373 }
1374
1375
1376
1377 inline SparsityPattern::iterator
1378 SparsityPattern::begin(const size_type r) const
1379 {
1380 AssertIndexRange(r, n_rows());
1381
1382 return {this, rowstart[r]};
1383 }
1384
1385
1386
1387 inline SparsityPattern::iterator
1388 SparsityPattern::end(const size_type r) const
1389 {
1390 AssertIndexRange(r, n_rows());
1391
1392 return {this, rowstart[r + 1]};
1393 }
1394
1395
1396
1397 namespace internal
1398 {
1399 namespace SparsityPatternTools
1400 {
1401 /**
1402 * Declare type for container size.
1403 */
1404 using size_type = types::global_dof_index;
1405
1406 inline size_type
1407 get_column_index_from_iterator(const size_type i)
1408 {
1409 return i;
1410 }
1411
1412
1413
1414 template <typename value>
1415 inline size_type
1416 get_column_index_from_iterator(const std::pair<size_type, value> &i)
1417 {
1418 return i.first;
1419 }
1420
1421
1422
1423 template <typename value>
1424 inline size_type
1425 get_column_index_from_iterator(const std::pair<const size_type, value> &i)
1426 {
1427 return i.first;
1428 }
1429 } // namespace SparsityPatternTools
1430 } // namespace internal
1431
1432
1433
1434 template <typename ForwardIterator>
1435 void
1436 SparsityPattern::copy_from(const size_type n_rows,
1437 const size_type n_cols,
1438 const ForwardIterator begin,
1439 const ForwardIterator end)
1440 {
1441 Assert(static_cast<size_type>(std::distance(begin, end)) == n_rows,
1442 ExcIteratorRange(std::distance(begin, end), n_rows));
1443
1444 // first determine row lengths for each row. if the matrix is quadratic,
1445 // then we might have to add an additional entry for the diagonal, if that
1446 // is not yet present. as we have to call compress anyway later on, don't
1447 // bother to check whether that diagonal entry is in a certain row or not
1448 const bool is_square = (n_rows == n_cols);
1449 std::vector<unsigned int> row_lengths;
1450 row_lengths.reserve(n_rows);
1451 for (ForwardIterator i = begin; i != end; ++i)
1452 row_lengths.push_back(std::distance(i->begin(), i->end()) +
1453 (is_square ? 1 : 0));
1454 reinit(n_rows, n_cols, row_lengths);
1455
1456 // now enter all the elements into the matrix. note that if the matrix is
1457 // quadratic, then we already have the diagonal element preallocated
1458 //
1459 // for use in the inner loop, we define an alias to the type of the inner
1460 // iterators
1461 size_type row = 0;
1462 using inner_iterator =
1463 typename std::iterator_traits<ForwardIterator>::value_type::const_iterator;
1464 for (ForwardIterator i = begin; i != end; ++i, ++row)
1465 {
1466 size_type *cols = &colnums[rowstart[row]] + (is_square ? 1 : 0);
1467 const inner_iterator end_of_row = i->end();
1468 for (inner_iterator j = i->begin(); j != end_of_row; ++j)
1469 {
1470 const size_type col =
1471 internal::SparsityPatternTools::get_column_index_from_iterator(*j);
1472 AssertIndexRange(col, n_cols);
1473
1474 if ((col != row) || !is_square)
1475 *cols++ = col;
1476 }
1477 }
1478
1479 // finally compress everything. this also sorts the entries within each row
1480 compress();
1481 }
1482
1483
1484
1485 template <class Archive>
1486 inline void
1487 SparsityPattern::save(Archive &ar, const unsigned int) const
1488 {
1489 // forward to serialization function in the base class.
1490 ar &boost::serialization::base_object<const EnableObserverPointer>(*this);
1491
1492 ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed;
1493
1494 if (max_dim != 0)
1495 ar &boost::serialization::make_array(rowstart.get(), max_dim + 1);
1496 else
1497 Assert(rowstart.get() == nullptr, ExcInternalError());
1498
1499 if (max_vec_len != 0)
1500 ar &boost::serialization::make_array(colnums.get(), max_vec_len);
1501 else
1502 Assert(colnums.get() == nullptr, ExcInternalError());
1503 ar &store_diagonal_first_in_row;
1504 }
1505
1506
1507
1508 template <class Archive>
1509 inline void
1510 SparsityPattern::load(Archive &ar, const unsigned int)
1511 {
1512 // forward to serialization function in the base class.
1513 ar &boost::serialization::base_object<EnableObserverPointer>(*this);
1514
1515 ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed;
1516
1517 if (max_dim != 0)
1518 {
1519 rowstart = std::make_unique<std::size_t[]>(max_dim + 1);
1520 ar &boost::serialization::make_array(rowstart.get(), max_dim + 1);
1521 }
1522 else
1523 rowstart.reset();
1524
1525 if (max_vec_len != 0)
1526 {
1527 colnums = std::make_unique<size_type[]>(max_vec_len);
1528 ar &boost::serialization::make_array(colnums.get(), max_vec_len);
1529 }
1530 else
1531 colnums.reset();
1532 ar &store_diagonal_first_in_row;
1533 }
1534
1535
1536 #endif // DOXYGEN
1537
1538 DEAL_II_NAMESPACE_CLOSE
1539
1540 #endif