Debian Codegraph @

include/deal.II/lac/sparse_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2002 - 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_sparse_matrix_h
16 #define dealii_sparse_matrix_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/mpi_stub.h>
22 #include <deal.II/base/observer_pointer.h>
23
24 #include <deal.II/lac/exceptions.h>
25 #include <deal.II/lac/identity_matrix.h>
26 #include <deal.II/lac/sparsity_pattern.h>
27 #include <deal.II/lac/vector_operation.h>
28
29 #include <iterator>
30 #include <memory>
31
32
33 DEAL_II_NAMESPACE_OPEN
34
35 // Forward declarations
36 #ifndef DOXYGEN
37 template <typename number>
38 class Vector;
39 template <typename number>
40 class FullMatrix;
41 template <typename Matrix>
42 class BlockMatrixBase;
43 template <typename number>
44 class SparseILU;
45 # ifdef DEAL_II_WITH_MPI
46 namespace Utilities
47 {
48 namespace MPI
49 {
50 template <typename Number>
51 void
52 sum(const SparseMatrix<Number> &, const MPI_Comm, SparseMatrix<Number> &);
53 }
54 } // namespace Utilities
55 # endif
56
57 # ifdef DEAL_II_WITH_TRILINOS
58 namespace TrilinosWrappers
59 {
60 class SparseMatrix;
61 }
62 # endif
63 #endif
64
65 /**
66 * @addtogroup Matrix1
67 * @{
68 */
69
70 /**
71 * A namespace in which we declare iterators over the elements of sparse
72 * matrices.
73 */
74 namespace SparseMatrixIterators
75 {
76 /**
77 * Declare type for container size.
78 */
79 using size_type = types::global_dof_index;
80
81 // forward declaration
82 template <typename number, bool Constness>
83 class Iterator;
84
85 /**
86 * General template for sparse matrix accessors. The first template argument
87 * denotes the underlying numeric type, the second the constness of the
88 * matrix.
89 *
90 * The general template is not implemented, only the specializations for the
91 * two possible values of the second template argument. Therefore, the
92 * interface listed here only serves as a template provided since doxygen
93 * does not link the specializations.
94 */
95 template <typename number, bool Constness>
96 class Accessor : public SparsityPatternIterators::Accessor
97 {
98 public:
99 /**
100 * Value of this matrix entry.
101 */
102 number
103 value() const;
104
105 /**
106 * Value of this matrix entry.
107 */
108 number &
109 value();
110
111 /**
112 * Return a reference to the matrix into which this accessor points. Note
113 * that in the present case, this is a constant reference.
114 */
115 const SparseMatrix<number> &
116 get_matrix() const;
117 };
118
119
120
121 /**
122 * Accessor class for constant matrices, used in the const_iterators. This
123 * class builds on the accessor classes used for sparsity patterns to loop
124 * over all nonzero entries, and only adds the accessor functions to gain
125 * access to the actual value stored at a certain location.
126 */
127 template <typename number>
128 class Accessor<number, true> : public SparsityPatternIterators::Accessor
129 {
130 public:
131 /**
132 * Typedef for the type (including constness) of the matrix to be used
133 * here.
134 */
135 using MatrixType = const SparseMatrix<number>;
136
137 /**
138 * Constructor.
139 */
140 Accessor(MatrixType *matrix, const std::size_t index_within_matrix);
141
142 /**
143 * Constructor. Construct the end accessor for the given matrix.
144 */
145 Accessor(MatrixType *matrix);
146
147 /**
148 * Copy constructor to get from a non-const accessor to a const accessor.
149 */
150 Accessor(const SparseMatrixIterators::Accessor<number, false> &a);
151
152 /**
153 * Value of this matrix entry.
154 */
155 number
156 value() const;
157
158 /**
159 * Return a reference to the matrix into which this accessor points. Note
160 * that in the present case, this is a constant reference.
161 */
162 const MatrixType &
163 get_matrix() const;
164
165 private:
166 /**
167 * Pointer to the matrix we use.
168 */
169 MatrixType *matrix;
170
171 /**
172 * Make the advance function of the base class available.
173 */
174 using SparsityPatternIterators::Accessor::advance;
175
176 // Make iterator class a friend.
177 template <typename, bool>
178 friend class Iterator;
179 };
180
181
182 /**
183 * Accessor class for non-constant matrices, used in the iterators. This
184 * class builds on the accessor classes used for sparsity patterns to loop
185 * over all nonzero entries, and only adds the accessor functions to gain
186 * access to the actual value stored at a certain location.
187 */
188 template <typename number>
189 class Accessor<number, false> : public SparsityPatternIterators::Accessor
190 {
191 private:
192 /**
193 * Reference class. This is what the accessor class returns when you call
194 * the value() function. The reference acts just as if it were a reference
195 * to the actual value of a matrix entry, i.e. you can read and write it,
196 * you can add and multiply to it, etc, but since the matrix does not give
197 * away the address of this matrix entry, we have to go through functions
198 * to do all this.
199 *
200 * The constructor takes a pointer to an accessor object that describes
201 * which element of the matrix it points to. This creates an ambiguity
202 * when one writes code like iterator->value()=0 (instead of
203 * iterator->value()=0.0), since the right hand side is an integer that
204 * can both be converted to a <tt>number</tt> (i.e., most commonly a
205 * double) or to another object of type <tt>Reference</tt>. The compiler
206 * then complains about not knowing which conversion to take.
207 *
208 * For some reason, adding another overload operator=(int) doesn't seem to
209 * cure the problem. We avoid it, however, by adding a second, dummy
210 * argument to the Reference constructor, that is unused, but makes sure
211 * there is no second matching conversion sequence using a one-argument
212 * right hand side.
213 *
214 * The testcase oliver_01 checks that this actually works as intended.
215 */
216 class Reference
217 {
218 public:
219 /**
220 * Constructor. For the second argument, see the general class
221 * documentation.
222 */
223 Reference(const Accessor *accessor, const bool dummy);
224
225 /**
226 * Conversion operator to the data type of the matrix.
227 */
228 operator number() const;
229
230 /**
231 * Set the element of the matrix we presently point to to @p n.
232 */
233 const Reference &
234 operator=(const number n) const;
235
236 /**
237 * Add @p n to the element of the matrix we presently point to.
238 */
239 const Reference &
240 operator+=(const number n) const;
241
242 /**
243 * Subtract @p n from the element of the matrix we presently point to.
244 */
245 const Reference &
246 operator-=(const number n) const;
247
248 /**
249 * Multiply the element of the matrix we presently point to by @p n.
250 */
251 const Reference &
252 operator*=(const number n) const;
253
254 /**
255 * Divide the element of the matrix we presently point to by @p n.
256 */
257 const Reference &
258 operator/=(const number n) const;
259
260 private:
261 /**
262 * Pointer to the accessor that denotes which element we presently point
263 * to.
264 */
265 const Accessor *accessor;
266 };
267
268 public:
269 /**
270 * Typedef for the type (including constness) of the matrix to be used
271 * here.
272 */
273 using MatrixType = SparseMatrix<number>;
274
275 /**
276 * Constructor.
277 */
278 Accessor(MatrixType *matrix, const std::size_t index);
279
280 /**
281 * Constructor. Construct the end accessor for the given matrix.
282 */
283 Accessor(MatrixType *matrix);
284
285 /**
286 * Value of this matrix entry, returned as a read- and writable reference.
287 */
288 Reference
289 value() const;
290
291 /**
292 * Return a reference to the matrix into which this accessor points. Note
293 * that in the present case, this is a non-constant reference.
294 */
295 MatrixType &
296 get_matrix() const;
297
298 private:
299 /**
300 * Pointer to the matrix we use.
301 */
302 MatrixType *matrix;
303
304 /**
305 * Make the advance function of the base class available.
306 */
307 using SparsityPatternIterators::Accessor::advance;
308
309 // Make iterator class a friend.
310 template <typename, bool>
311 friend class Iterator;
312 };
313
314
315
316 /**
317 * Iterator for constant and non-constant matrices.
318 *
319 * The typical use for these iterators is to iterate over the elements of a
320 * sparse matrix or over the elements of individual rows. Note that there is
321 * no guarantee that the elements of a row are actually traversed in an
322 * order in which columns monotonically increase. See the documentation of
323 * the SparsityPattern class for more information.
324 *
325 * The first template argument denotes the underlying numeric type, the
326 * second the constness of the matrix.
327 *
328 * Since there is a specialization of this class for
329 * <tt>Constness=false</tt>, this class is for iterators to constant
330 * matrices.
331 *
332 * @note This class operates directly on the internal data structures of the
333 * SparsityPattern and SparseMatrix classes. As a consequence, some
334 * operations are cheap and some are not. In particular, it is cheap to
335 * access the column index and the value of an entry pointed to. On the
336 * other hand, it is expensive to access the row index (this requires
337 * $O(\log(N))$ operations for a matrix with $N$ row). As a consequence,
338 * when you design algorithms that use these iterators, it is common
339 * practice to not loop over <i>all</i> elements of a sparse matrix at once,
340 * but to have an outer loop over all rows and within this loop iterate over
341 * the elements of this row. This way, you only ever need to dereference the
342 * iterator to obtain the column indices and values whereas the (expensive)
343 * lookup of the row index can be avoided by using the loop index instead.
344 */
345 template <typename number, bool Constness>
346 class Iterator
347 {
348 public:
349 /**
350 * Typedef for the matrix type (including constness) we are to operate on.
351 */
352 using MatrixType = typename Accessor<number, Constness>::MatrixType;
353
354 /**
355 * An alias for the type you get when you dereference an iterator of the
356 * current kind.
357 */
358 using value_type = const Accessor<number, Constness> &;
359
360 /**
361 * A type that denotes what data types is used to express the difference
362 * between two iterators.
363 */
364 using difference_type = size_type;
365
366 /**
367 * Constructor. Create an iterator into the matrix @p matrix for the given
368 * index in the complete matrix (counting from the zeroth entry).
369 */
370 Iterator(MatrixType *matrix, const std::size_t index_within_matrix);
371
372 /**
373 * Constructor. Create the end iterator for the given matrix.
374 */
375 Iterator(MatrixType *matrix);
376
377 /**
378 * Conversion constructor to get from a non-const iterator to a const
379 * iterator.
380 */
381 Iterator(const SparseMatrixIterators::Iterator<number, false> &i);
382
383 /**
384 * Copy assignment operator from a non-const iterator to a const iterator.
385 */
386 const Iterator<number, Constness> &
387 operator=(const SparseMatrixIterators::Iterator<number, false> &i);
388
389 /**
390 * Prefix increment.
391 */
392 Iterator &
393 operator++();
394
395 /**
396 * Postfix increment.
397 */
398 Iterator
399 operator++(int);
400
401 /**
402 * Dereferencing operator.
403 */
404 const Accessor<number, Constness> &
405 operator*() const;
406
407 /**
408 * Dereferencing operator.
409 */
410 const Accessor<number, Constness> *
411 operator->() const;
412
413 /**
414 * Comparison. True, if both iterators point to the same matrix position.
415 */
416 bool
417 operator==(const Iterator &) const;
418
419 /**
420 * Inverse of <tt>==</tt>.
421 */
422 bool
423 operator!=(const Iterator &) const;
424
425 /**
426 * Comparison operator. Result is true if either the first row number is
427 * smaller or if the row numbers are equal and the first index is smaller.
428 *
429 * This function is only valid if both iterators point into the same
430 * matrix.
431 */
432 bool
433 operator<(const Iterator &) const;
434
435 /**
436 * Comparison operator. Works in the same way as above operator, just the
437 * other way round.
438 */
439 bool
440 operator>(const Iterator &) const;
441
442 /**
443 * Return the distance between the current iterator and the argument. The
444 * distance is given by how many times one has to apply operator++ to the
445 * current iterator to get the argument (for a positive return value), or
446 * operator-- (for a negative return value).
447 */
448 int
449 operator-(const Iterator &p) const;
450
451 /**
452 * Return an iterator that is @p n ahead of the current one.
453 */
454 Iterator
455 operator+(const size_type n) const;
456
457 private:
458 /**
459 * Store an object of the accessor class.
460 */
461 Accessor<number, Constness> accessor;
462 };
463
464 } // namespace SparseMatrixIterators
465
466 DEAL_II_NAMESPACE_CLOSE // Do not convert for module purposes
467
468 namespace std
469 {
470 template <typename number, bool Constness>
471 struct iterator_traits<
472 dealii::SparseMatrixIterators::Iterator<number, Constness>>
473 {
474 using iterator_category = forward_iterator_tag;
475 using value_type =
476 typename dealii::SparseMatrixIterators::Iterator<number,
477 Constness>::value_type;
478 using difference_type = typename dealii::SparseMatrixIterators::
479 Iterator<number, Constness>::difference_type;
480 };
481 } // namespace std
482
483 DEAL_II_NAMESPACE_OPEN // Do not convert for module purposes
484
485 /**
486 * @}
487 */
488
489
490 // TODO: Add multithreading to the other vmult functions.
491
492 /**
493 * Sparse matrix. This class implements the functionality to store matrix
494 * entry values in the locations denoted by a SparsityPattern. See
495 * @ref Sparsity
496 * for a discussion about the separation between sparsity patterns and
497 * matrices.
498 *
499 * The elements of a SparseMatrix are stored in the same order in which the
500 * SparsityPattern class stores its entries. Within each row, elements are
501 * generally stored left-to-right in increasing column index order; the
502 * exception to this rule is that if the matrix is square (m() == n()), then
503 * the diagonal entry is stored as the first element in each row to make
504 * operations like applying a Jacobi or SSOR preconditioner faster. As a
505 * consequence, if you traverse the elements of a row of a SparseMatrix with
506 * the help of iterators into this object (using SparseMatrix::begin and
507 * SparseMatrix::end) you will find that the elements are not sorted by column
508 * index within each row whenever the matrix is square.
509 *
510 * @note Instantiations for this template are provided for <tt>@<float@> and
511 * @<double@></tt>; others can be generated in application programs (see the
512 * section on
513 * @ref Instantiations
514 * in the manual).
515 *
516 * @ingroup Matrix1
517 */
518 template <typename number>
519 class SparseMatrix : public virtual EnableObserverPointer
520 {
521 public:
522 /**
523 * Declare type for container size.
524 */
525 using size_type = types::global_dof_index;
526
527 /**
528 * Type of the matrix entries. This alias is analogous to
529 * <tt>value_type</tt> in the standard library containers.
530 */
531 using value_type = number;
532
533 /**
534 * Declare a type that has holds real-valued numbers with the same precision
535 * as the template argument to this class. If the template argument of this
536 * class is a real data type, then real_type equals the template argument.
537 * If the template argument is a std::complex type then real_type equals the
538 * type underlying the complex numbers.
539 *
540 * This alias is used to represent the return type of norms.
541 */
542 using real_type = typename numbers::NumberTraits<number>::real_type;
543
544 /**
545 * Typedef of an iterator class walking over all the nonzero entries of this
546 * matrix. This iterator cannot change the values of the matrix.
547 */
548 using const_iterator = SparseMatrixIterators::Iterator<number, true>;
549
550 /**
551 * Typedef of an iterator class walking over all the nonzero entries of this
552 * matrix. This iterator @em can change the values of the matrix, but of
553 * course can't change the sparsity pattern as this is fixed once a sparse
554 * matrix is attached to it.
555 */
556 using iterator = SparseMatrixIterators::Iterator<number, false>;
557
558 /**
559 * A structure that describes some of the traits of this class in terms of
560 * its run-time behavior. Some other classes (such as the block matrix
561 * classes) that take one or other of the matrix classes as its template
562 * parameters can tune their behavior based on the variables in this class.
563 */
564 struct Traits
565 {
566 /**
567 * It is safe to elide additions of zeros to individual elements of this
568 * matrix.
569 */
570 static const bool zero_addition_can_be_elided = true;
571 };
572
573 /**
574 * @name Constructors and initialization
575 */
576 /** @{ */
577 /**
578 * Constructor; initializes the matrix to be empty, without any structure,
579 * i.e. the matrix is not usable at all. This constructor is therefore only
580 * useful for matrices which are members of a class. All other matrices
581 * should be created at a point in the data flow where all necessary
582 * information is available.
583 *
584 * You have to initialize the matrix before usage with reinit(const
585 * SparsityPattern&).
586 */
587 SparseMatrix();
588
589 /**
590 * Copy constructor. This constructor is only allowed to be called if the
591 * matrix to be copied is empty. This is for the same reason as for the
592 * SparsityPattern, see there for the details.
593 *
594 * If you really want to copy a whole matrix, you can do so by using the
595 * copy_from() function.
596 */
597 SparseMatrix(const SparseMatrix &);
598
599 /**
600 * Move constructor. Construct a new sparse matrix by transferring the
601 * internal data of the matrix @p m into a new object.
602 *
603 * Move construction allows an object to be returned from a function or
604 * packed into a tuple even when the class cannot be copy-constructed.
605 */
606 SparseMatrix(SparseMatrix<number> &&m) noexcept;
607
608 /**
609 * Constructor. Takes the given matrix sparsity structure to represent the
610 * sparsity pattern of this matrix. You can change the sparsity pattern
611 * later on by calling the reinit(const SparsityPattern&) function.
612 *
613 * You have to make sure that the lifetime of the sparsity structure is at
614 * least as long as that of this matrix or as long as reinit(const
615 * SparsityPattern&) is not called with a new sparsity pattern.
616 *
617 * The constructor is marked explicit so as to disallow that someone passes
618 * a sparsity pattern in place of a sparse matrix to some function, where an
619 * empty matrix would be generated then.
620 */
621 explicit SparseMatrix(const SparsityPattern &sparsity);
622
623 /**
624 * Copy constructor: initialize the matrix with the identity matrix. This
625 * constructor will throw an exception if the sizes of the sparsity pattern
626 * and the identity matrix do not coincide, or if the sparsity pattern does
627 * not provide for nonzero entries on the entire diagonal.
628 */
629 SparseMatrix(const SparsityPattern &sparsity, const IdentityMatrix &id);
630
631 /**
632 * Destructor. Free all memory, but do not release the memory of the
633 * sparsity structure.
634 */
635 virtual ~SparseMatrix() override;
636
637 /**
638 * Copy operator. Since copying entire sparse matrices is a very expensive
639 * operation, we disallow doing so except for the special case of empty
640 * matrices of size zero. This doesn't seem particularly useful, but is
641 * exactly what one needs if one wanted to have a
642 * <code>std::vector@<SparseMatrix@<double@> @></code>: in that case, one
643 * can create a vector (which needs the ability to copy objects) of empty
644 * matrices that are then later filled with something useful.
645 */
646 SparseMatrix<number> &
647 operator=(const SparseMatrix<number> &);
648
649 /**
650 * Move assignment operator. This operator replaces the present matrix with
651 * @p m by transferring the internal data of @p m.
652 */
653 SparseMatrix<number> &
654 operator=(SparseMatrix<number> &&m) noexcept;
655
656 /**
657 * Copy operator: initialize the matrix with the identity matrix. This
658 * operator will throw an exception if the sizes of the sparsity pattern and
659 * the identity matrix do not coincide, or if the sparsity pattern does not
660 * provide for nonzero entries on the entire diagonal.
661 */
662 SparseMatrix<number> &
663 operator=(const IdentityMatrix &id);
664
665 /**
666 * This operator assigns a scalar to a matrix. Since this does usually not
667 * make much sense (should we set all matrix entries to this value? Only
668 * the nonzero entries of the sparsity pattern?), this operation is only
669 * allowed if the actual value to be assigned is zero. This operator only
670 * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
671 * all elements of the matrix to zero, but keep the sparsity pattern
672 * previously used.
673 *
674 * @dealiiOperationIsMultithreaded
675 */
676 SparseMatrix &
677 operator=(const double d);
678
679 /**
680 * Reinitialize the sparse matrix with the given sparsity pattern. The
681 * latter tells the matrix how many nonzero elements there need to be
682 * reserved.
683 *
684 * Regarding memory allocation, the same applies as said above.
685 *
686 * You have to make sure that the lifetime of the sparsity structure is at
687 * least as long as that of this matrix or as long as reinit(const
688 * SparsityPattern &) is not called with a new sparsity structure.
689 *
690 * The elements of the matrix are set to zero by this function.
691 */
692 virtual void
693 reinit(const SparsityPattern &sparsity);
694
695 /**
696 * Reinitialize the sparse matrix with the sparsity pattern of the given
697 * @p sparse_matrix. See also comments of the function above.
698 *
699 * @note The elements of the matrix are set to zero by this function.
700 */
701 template <typename number2>
702 void
703 reinit(const SparseMatrix<number2> &sparse_matrix);
704
705 /**
706 * Release all memory and return to a state just like after having called
707 * the default constructor. It also forgets the sparsity pattern it was
708 * previously tied to.
709 */
710 virtual void
711 clear();
712 /** @} */
713 /**
714 * @name Information on the matrix
715 */
716 /** @{ */
717 /**
718 * Return whether the object is empty. It is empty if either both dimensions
719 * are zero or no SparsityPattern is associated.
720 */
721 bool
722 empty() const;
723
724 /**
725 * Return the dimension of the codomain (or range) space. Note that the
726 * matrix is of dimension $m \times n$.
727 */
728 size_type
729 m() const;
730
731 /**
732 * Return the dimension of the domain space. Note that the matrix is of
733 * dimension $m \times n$.
734 */
735 size_type
736 n() const;
737
738 /**
739 * Return the number of entries in a specific row.
740 */
741 size_type
742 get_row_length(const size_type row) const;
743
744 /**
745 * Return the number of nonzero elements of this matrix. Actually, it
746 * returns the number of entries in the sparsity pattern; if any of the
747 * entries should happen to be zero, it is counted anyway.
748 */
749 std::size_t
750 n_nonzero_elements() const;
751
752 /**
753 * Return the number of actually nonzero elements of this matrix. It is
754 * possible to specify the parameter <tt>threshold</tt> in order to count
755 * only the elements that have absolute value greater than the threshold.
756 *
757 * Note, that this function does (in contrary to n_nonzero_elements()) not
758 * count all entries of the sparsity pattern but only the ones that are
759 * nonzero (or whose absolute value is greater than threshold).
760 */
761 std::size_t
762 n_actually_nonzero_elements(const double threshold = 0.) const;
763
764 /**
765 * Return a (constant) reference to the underlying sparsity pattern of this
766 * matrix.
767 *
768 * Though the return value is declared <tt>const</tt>, you should be aware
769 * that it may change if you call any nonconstant function of objects which
770 * operate on it.
771 */
772 const SparsityPattern &
773 get_sparsity_pattern() const;
774
775 /**
776 * Determine an estimate for the memory consumption (in bytes) of this
777 * object. See MemoryConsumption.
778 */
779 std::size_t
780 memory_consumption() const;
781
782 /**
783 * Dummy function for compatibility with distributed, parallel matrices.
784 */
785 void compress(VectorOperation::values);
786
787 /** @} */
788 /**
789 * @name Modifying entries
790 */
791 /** @{ */
792 /**
793 * Set the element (<i>i,j</i>) to <tt>value</tt>. Throws an error if the
794 * entry does not exist or if <tt>value</tt> is not a finite number. Still,
795 * it is allowed to store zero values in non-existent fields.
796 */
797 void
798 set(const size_type i, const size_type j, const number value);
799
800 /**
801 * Set all elements given in a FullMatrix into the sparse matrix locations
802 * given by <tt>indices</tt>. In other words, this function writes the
803 * elements in <tt>full_matrix</tt> into the calling matrix, using the
804 * local-to-global indexing specified by <tt>indices</tt> for both the rows
805 * and the columns of the matrix. This function assumes a quadratic sparse
806 * matrix and a quadratic full_matrix, the usual situation in FE
807 * calculations.
808 *
809 * The optional parameter <tt>elide_zero_values</tt> can be used to specify
810 * whether zero values should be set anyway or they should be filtered away
811 * (and not change the previous content in the respective element if it
812 * exists). The default value is <tt>false</tt>, i.e., even zero values are
813 * treated.
814 */
815 template <typename number2>
816 void
817 set(const std::vector<size_type> &indices,
818 const FullMatrix<number2> &full_matrix,
819 const bool elide_zero_values = false);
820
821 /**
822 * Same function as before, but now including the possibility to use
823 * rectangular full_matrices and different local-to-global indexing on rows
824 * and columns, respectively.
825 */
826 template <typename number2>
827 void
828 set(const std::vector<size_type> &row_indices,
829 const std::vector<size_type> &col_indices,
830 const FullMatrix<number2> &full_matrix,
831 const bool elide_zero_values = false);
832
833 /**
834 * Set several elements in the specified row of the matrix with column
835 * indices as given by <tt>col_indices</tt> to the respective value.
836 *
837 * The optional parameter <tt>elide_zero_values</tt> can be used to specify
838 * whether zero values should be set anyway or they should be filtered away
839 * (and not change the previous content in the respective element if it
840 * exists). The default value is <tt>false</tt>, i.e., even zero values are
841 * treated.
842 */
843 template <typename number2>
844 void
845 set(const size_type row,
846 const std::vector<size_type> &col_indices,
847 const std::vector<number2> &values,
848 const bool elide_zero_values = false);
849
850 /**
851 * Set several elements to values given by <tt>values</tt> in a given row in
852 * columns given by col_indices into the sparse matrix.
853 *
854 * The optional parameter <tt>elide_zero_values</tt> can be used to specify
855 * whether zero values should be inserted anyway or they should be filtered
856 * away. The default value is <tt>false</tt>, i.e., even zero values are
857 * inserted/replaced.
858 */
859 template <typename number2>
860 void
861 set(const size_type row,
862 const size_type n_cols,
863 const size_type *col_indices,
864 const number2 *values,
865 const bool elide_zero_values = false);
866
867 /**
868 * Add <tt>value</tt> to the element (<i>i,j</i>). Throws an error if the
869 * entry does not exist or if <tt>value</tt> is not a finite number. Still,
870 * it is allowed to store zero values in non-existent fields.
871 */
872 void
873 add(const size_type i, const size_type j, const number value);
874
875 /**
876 * Add all elements given in a FullMatrix<double> into sparse matrix
877 * locations given by <tt>indices</tt>. In other words, this function adds
878 * the elements in <tt>full_matrix</tt> to the respective entries in calling
879 * matrix, using the local-to-global indexing specified by <tt>indices</tt>
880 * for both the rows and the columns of the matrix. This function assumes a
881 * quadratic sparse matrix and a quadratic full_matrix, the usual situation
882 * in FE calculations.
883 *
884 * The optional parameter <tt>elide_zero_values</tt> can be used to specify
885 * whether zero values should be added anyway or these should be filtered
886 * away and only non-zero data is added. The default value is <tt>true</tt>,
887 * i.e., zero values won't be added into the matrix.
888 */
889 template <typename number2>
890 void
891 add(const std::vector<size_type> &indices,
892 const FullMatrix<number2> &full_matrix,
893 const bool elide_zero_values = true);
894
895 /**
896 * Same function as before, but now including the possibility to use
897 * rectangular full_matrices and different local-to-global indexing on rows
898 * and columns, respectively.
899 */
900 template <typename number2>
901 void
902 add(const std::vector<size_type> &row_indices,
903 const std::vector<size_type> &col_indices,
904 const FullMatrix<number2> &full_matrix,
905 const bool elide_zero_values = true);
906
907 /**
908 * Add the provided values to several elements in the specified row of the
909 * matrix with column indices as given by <tt>col_indices</tt>.
910 *
911 * The optional parameter <tt>elide_zero_values</tt> can be used to specify
912 * whether zero values should be added anyway or these should be filtered
913 * away and only non-zero data is added. The default value is <tt>true</tt>,
914 * i.e., zero values won't be added into the matrix.
915 */
916 template <typename number2>
917 void
918 add(const size_type row,
919 const std::vector<size_type> &col_indices,
920 const std::vector<number2> &values,
921 const bool elide_zero_values = true);
922
923 /**
924 * Add an array of values given by <tt>values</tt> in the given global
925 * matrix row at columns specified by col_indices in the sparse matrix.
926 *
927 * The optional parameter <tt>elide_zero_values</tt> can be used to specify
928 * whether zero values should be added anyway or these should be filtered
929 * away and only non-zero data is added. The default value is <tt>true</tt>,
930 * i.e., zero values won't be added into the matrix.
931 */
932 template <typename number2>
933 void
934 add(const size_type row,
935 const size_type n_cols,
936 const size_type *col_indices,
937 const number2 *values,
938 const bool elide_zero_values = true,
939 const bool col_indices_are_sorted = false);
940
941 /**
942 * Multiply the entire matrix by a fixed factor.
943 */
944 SparseMatrix &
945 operator*=(const number factor);
946
947 /**
948 * Divide the entire matrix by a fixed factor.
949 */
950 SparseMatrix &
951 operator/=(const number factor);
952
953 /**
954 * Symmetrize the matrix by forming the mean value between the existing
955 * matrix and its transpose, $A = \frac 12(A+A^T)$.
956 *
957 * This operation assumes that the underlying sparsity pattern represents a
958 * symmetric object. If this is not the case, then the result of this
959 * operation will not be a symmetric matrix, since it only explicitly
960 * symmetrizes by looping over the lower left triangular part for efficiency
961 * reasons; if there are entries in the upper right triangle, then these
962 * elements are missed in the symmetrization. Symmetrization of the sparsity
963 * pattern can be obtain by SparsityPattern::symmetrize().
964 */
965 void
966 symmetrize();
967
968 /**
969 * Copy the matrix given as argument into the current object.
970 *
971 * Copying matrices is an expensive operation that we do not want to happen
972 * by accident through compiler generated code for <code>operator=</code>.
973 * (This would happen, for example, if one accidentally declared a function
974 * argument of the current type <i>by value</i> rather than <i>by
975 * reference</i>.) The functionality of copying matrices is implemented in
976 * this member function instead. All copy operations of objects of this type
977 * therefore require an explicit function call.
978 *
979 * The source matrix may be a matrix of arbitrary type, as long as its data
980 * type is convertible to the data type of this matrix.
981 *
982 * The function returns a reference to <tt>*this</tt>.
983 */
984 template <typename somenumber>
985 SparseMatrix<number> &
986 copy_from(const SparseMatrix<somenumber> &source);
987
988 /**
989 * This function is complete analogous to the SparsityPattern::copy_from()
990 * function in that it allows to initialize a whole matrix in one step. See
991 * there for more information on argument types and their meaning. You can
992 * also find a small example on how to use this function there.
993 *
994 * The only difference to the cited function is that the objects which the
995 * inner iterator points to need to be of type <tt>std::pair<unsigned int,
996 * value</tt>, where <tt>value</tt> needs to be convertible to the element
997 * type of this class, as specified by the <tt>number</tt> template
998 * argument.
999 *
1000 * Previous content of the matrix is overwritten. Note that the entries
1001 * specified by the input parameters need not necessarily cover all elements
1002 * of the matrix. Elements not covered remain untouched.
1003 */
1004 template <typename ForwardIterator>
1005 void
1006 copy_from(const ForwardIterator begin, const ForwardIterator end);
1007
1008 /**
1009 * Copy the nonzero entries of a full matrix into this object. Previous
1010 * content is deleted.
1011 *
1012 * Note that the underlying sparsity pattern must be appropriate to
1013 * hold the nonzero entries of the full matrix. This can be achieved
1014 * using that version of SparsityPattern::copy_from() that takes a
1015 * FullMatrix as argument.
1016 */
1017 template <typename somenumber>
1018 void
1019 copy_from(const FullMatrix<somenumber> &matrix);
1020
1021 #ifdef DEAL_II_WITH_TRILINOS
1022 /**
1023 * Copy the given Trilinos matrix to this one. The operation triggers an
1024 * assertion if the sparsity patterns of the current object does not contain
1025 * the location of a non-zero entry of the given argument.
1026 *
1027 * This function assumes that the two matrices have the same sizes.
1028 *
1029 * The function returns a reference to <tt>*this</tt>.
1030 */
1031 SparseMatrix<number> &
1032 copy_from(const TrilinosWrappers::SparseMatrix &matrix);
1033 #endif
1034
1035 /**
1036 * Add <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
1037 * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. This function
1038 * throws an error if the sparsity patterns of the two involved matrices do
1039 * not point to the same object, since in this case the operation is
1040 * cheaper.
1041 *
1042 * The source matrix may be a sparse matrix over an arbitrary underlying
1043 * scalar type, as long as its data type is convertible to the data type of
1044 * this matrix.
1045 */
1046 template <typename somenumber>
1047 void
1048 add(const number factor, const SparseMatrix<somenumber> &matrix);
1049
1050 /** @} */
1051 /**
1052 * @name Accessing elements
1053 */
1054 /** @{ */
1055
1056 /**
1057 * Return the value of the entry (<i>i,j</i>). This may be an expensive
1058 * operation and you should always take care where to call this function. In
1059 * order to avoid abuse, this function throws an exception if the required
1060 * element does not exist in the matrix.
1061 *
1062 * In case you want a function that returns zero instead (for entries that
1063 * are not in the sparsity pattern of the matrix), use the el() function.
1064 *
1065 * If you are looping over all elements, consider using one of the iterator
1066 * classes instead, since they are tailored better to a sparse matrix
1067 * structure.
1068 */
1069 const number &
1070 operator()(const size_type i, const size_type j) const;
1071
1072 /**
1073 * In contrast to the one above, this function allows modifying the object.
1074 */
1075 number &
1076 operator()(const size_type i, const size_type j);
1077
1078 /**
1079 * This function is mostly like operator()() in that it returns the value of
1080 * the matrix entry (<i>i,j</i>). The only difference is that if this entry
1081 * does not exist in the sparsity pattern, then instead of raising an
1082 * exception, zero is returned. While this may be convenient in some cases,
1083 * note that it is simple to write algorithms that are slow compared to an
1084 * optimal solution, since the sparsity of the matrix is not used.
1085 *
1086 * If you are looping over all elements, consider using one of the iterator
1087 * classes instead, since they are tailored better to a sparse matrix
1088 * structure.
1089 */
1090 number
1091 el(const size_type i, const size_type j) const;
1092
1093 /**
1094 * Return the main diagonal element in the <i>i</i>th row. This function
1095 * throws an error if the matrix is not quadratic.
1096 *
1097 * This function is considerably faster than the operator()(), since for
1098 * quadratic matrices, the diagonal entry may be the first to be stored in
1099 * each row and access therefore does not involve searching for the right
1100 * column number.
1101 */
1102 number
1103 diag_element(const size_type i) const;
1104
1105 /**
1106 * Same as above, but return a writeable reference. You're sure you know
1107 * what you do?
1108 */
1109 number &
1110 diag_element(const size_type i);
1111
1112 /** @} */
1113 /**
1114 * @name Multiplying matrices and vectors
1115 */
1116 /** @{ */
1117 /**
1118 * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i> being
1119 * this matrix.
1120 *
1121 * Note that while this function can operate on all vectors that offer
1122 * iterator classes, it is only really effective for objects of type
1123 * @ref Vector.
1124 * For all classes for which iterating over elements, or random member
1125 * access is expensive, this function is not efficient. In particular, if
1126 * you want to multiply with BlockVector objects, you should consider using
1127 * a BlockSparseMatrix as well.
1128 *
1129 * Source and destination must not be the same vector.
1130 *
1131 * @dealiiOperationIsMultithreaded
1132 */
1133 template <class OutVector, class InVector>
1134 void
1135 vmult(OutVector &dst, const InVector &src) const;
1136
1137 /**
1138 * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
1139 * <i>M</i> being this matrix. This function does the same as vmult() but
1140 * takes the transposed matrix.
1141 *
1142 * Note that while this function can operate on all vectors that offer
1143 * iterator classes, it is only really effective for objects of type
1144 * @ref Vector.
1145 * For all classes for which iterating over elements, or random member
1146 * access is expensive, this function is not efficient. In particular, if
1147 * you want to multiply with BlockVector objects, you should consider using
1148 * a BlockSparseMatrix as well.
1149 *
1150 * Source and destination must not be the same vector.
1151 */
1152 template <class OutVector, class InVector>
1153 void
1154 Tvmult(OutVector &dst, const InVector &src) const;
1155
1156 /**
1157 * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i> with
1158 * <i>M</i> being this matrix.
1159 *
1160 * Note that while this function can operate on all vectors that offer
1161 * iterator classes, it is only really effective for objects of type
1162 * @ref Vector.
1163 * For all classes for which iterating over elements, or random member
1164 * access is expensive, this function is not efficient. In particular, if
1165 * you want to multiply with BlockVector objects, you should consider using
1166 * a BlockSparseMatrix as well.
1167 *
1168 * Source and destination must not be the same vector.
1169 *
1170 * @dealiiOperationIsMultithreaded
1171 */
1172 template <class OutVector, class InVector>
1173 void
1174 vmult_add(OutVector &dst, const InVector &src) const;
1175
1176 /**
1177 * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
1178 * <i>dst</i> with <i>M</i> being this matrix. This function does the same
1179 * as vmult_add() but takes the transposed matrix.
1180 *
1181 * Note that while this function can operate on all vectors that offer
1182 * iterator classes, it is only really effective for objects of type
1183 * @ref Vector.
1184 * For all classes for which iterating over elements, or random member
1185 * access is expensive, this function is not efficient. In particular, if
1186 * you want to multiply with BlockVector objects, you should consider using
1187 * a BlockSparseMatrix as well.
1188 *
1189 * Source and destination must not be the same vector.
1190 */
1191 template <class OutVector, class InVector>
1192 void
1193 Tvmult_add(OutVector &dst, const InVector &src) const;
1194
1195 /**
1196 * Return the square of the norm of the vector $v$ with respect to the norm
1197 * induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful, e.g. in
1198 * the finite element context, where the $L_2$ norm of a function equals the
1199 * matrix norm with respect to the @ref GlossMassMatrix "mass matrix" of the vector representing
1200 * the nodal values of the finite element function.
1201 *
1202 * Obviously, the matrix needs to be quadratic for this operation, and for
1203 * the result to actually be a norm it also needs to be either real
1204 * symmetric or complex hermitian.
1205 *
1206 * The underlying template types of both this matrix and the given vector
1207 * should either both be real or complex-valued, but not mixed, for this
1208 * function to make sense.
1209 *
1210 * @dealiiOperationIsMultithreaded
1211 */
1212 template <typename somenumber>
1213 somenumber
1214 matrix_norm_square(const Vector<somenumber> &v) const;
1215
1216 /**
1217 * Compute the matrix scalar product $\left(u,Mv\right)$.
1218 *
1219 * @dealiiOperationIsMultithreaded
1220 */
1221 template <typename somenumber>
1222 somenumber
1223 matrix_scalar_product(const Vector<somenumber> &u,
1224 const Vector<somenumber> &v) const;
1225
1226 /**
1227 * Compute the residual of an equation <i>Mx=b</i>, where the residual is
1228 * defined to be <i>r=b-Mx</i>. Write the residual into <tt>dst</tt>. The
1229 * <i>l<sub>2</sub></i> norm of the residual vector is returned.
1230 *
1231 * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
1232 *
1233 * @dealiiOperationIsMultithreaded
1234 */
1235 template <typename somenumber>
1236 somenumber
1237 residual(Vector<somenumber> &dst,
1238 const Vector<somenumber> &x,
1239 const Vector<somenumber> &b) const;
1240
1241 /**
1242 * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
1243 * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
1244 * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
1245 *
1246 * This function assumes that the calling matrix @p A and the argument @p B
1247 * have compatible sizes. By default, the output matrix @p C will be
1248 * resized appropriately.
1249 *
1250 * By default, i.e., if the optional argument @p rebuild_sparsity_pattern
1251 * is @p true, the sparsity pattern of the matrix C will be
1252 * changed to ensure that all entries that result from the product $AB$
1253 * can be stored in $C$. This is an expensive operation, and if there is
1254 * a way to predict the sparsity pattern up front, you should probably
1255 * build it yourself before calling this function with @p false as last
1256 * argument. In this case, the rebuilding of the sparsity pattern is
1257 * bypassed.
1258 *
1259 * When setting @p rebuild_sparsity_pattern to @p true (i.e., leaving it
1260 * at the default value), it is important to realize that the matrix
1261 * @p C passed as first argument still has to be initialized with a
1262 * sparsity pattern (either at the time of creation of the SparseMatrix
1263 * object, or via the SparseMatrix::reinit() function). This is because
1264 * we could create a sparsity pattern inside the current function, and
1265 * then associate @p C with it, but there would be no way to transfer
1266 * ownership of this sparsity pattern to anyone once the current function
1267 * finishes. Consequently, the function requires that @p C be already
1268 * associated with a sparsity pattern object, and this object is then
1269 * reset to fit the product of @p A and @p B.
1270 *
1271 * As a consequence of this, however, it is also important to realize
1272 * that the sparsity pattern of @p C is modified and that this would
1273 * render invalid <i>all other SparseMatrix objects</i> that happen
1274 * to <i>also</i> use that sparsity pattern object.
1275 */
1276 template <typename numberB, typename numberC>
1277 void
1278 mmult(SparseMatrix<numberC> &C,
1279 const SparseMatrix<numberB> &B,
1280 const Vector<number> &V = Vector<number>(),
1281 const bool rebuild_sparsity_pattern = true) const;
1282
1283 /**
1284 * Perform the matrix-matrix multiplication with the transpose of
1285 * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
1286 * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>, where
1287 * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
1288 *
1289 * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
1290 * have compatible sizes. The size of <tt>C</tt> will be set within this
1291 * function.
1292 *
1293 * The content as well as the sparsity pattern of the matrix C will be
1294 * changed by this function, so make sure that the sparsity pattern is not
1295 * used somewhere else in your program. This is an expensive operation, so
1296 * think twice before you use this function.
1297 *
1298 * There is an optional flag <tt>rebuild_sparsity_pattern</tt> that can be
1299 * used to bypass the creation of a new sparsity pattern and instead uses
1300 * the sparsity pattern stored in <tt>C</tt>. In that case, make sure that
1301 * it really fits. The default is to rebuild the sparsity pattern.
1302 *
1303 * @note Rebuilding the sparsity pattern requires changing it. This means
1304 * that all other matrices that are associated with this sparsity pattern
1305 * will then have invalid entries.
1306 */
1307 template <typename numberB, typename numberC>
1308 void
1309 Tmmult(SparseMatrix<numberC> &C,
1310 const SparseMatrix<numberB> &B,
1311 const Vector<number> &V = Vector<number>(),
1312 const bool rebuild_sparsity_pattern = true) const;
1313
1314 /** @} */
1315 /**
1316 * @name Matrix norms
1317 */
1318 /** @{ */
1319
1320 /**
1321 * Return the $l_1$-norm of the matrix, that is $|M|_1=\max_{\mathrm{all\
1322 * columns\ }j}\sum_{\mathrm{all\ rows\ } i} |M_{ij}|$, (max. sum of
1323 * columns). This is the natural matrix norm that is compatible to the
1324 * $l_1$-norm for vectors, i.e. $|Mv|_1\leq |M|_1 |v|_1$. (cf.
1325 * Haemmerlin-Hoffmann: Numerische Mathematik)
1326 */
1327 real_type
1328 l1_norm() const;
1329
1330 /**
1331 * Return the $l_\infty$-norm of the matrix, that is
1332 * $|M|_\infty=\max_{\mathrm{all\ rows\ }i}\sum_{\mathrm{all\ columns\ }j}
1333 * |M_{ij}|$, (max. sum of rows). This is the natural matrix norm that is
1334 * compatible to the $l_\infty$-norm of vectors, i.e. $|Mv|_\infty \leq
1335 * |M|_\infty |v|_\infty$. (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
1336 */
1337 real_type
1338 linfty_norm() const;
1339
1340 /**
1341 * Return the frobenius norm of the matrix, i.e. the square root of the sum
1342 * of squares of all entries in the matrix.
1343 */
1344 real_type
1345 frobenius_norm() const;
1346 /** @} */
1347 /**
1348 * @name Preconditioning methods
1349 */
1350 /** @{ */
1351
1352 /**
1353 * Apply the Jacobi preconditioner, which multiplies every element of the
1354 * <tt>src</tt> vector by the inverse of the respective diagonal element and
1355 * multiplies the result with the relaxation factor <tt>omega</tt>.
1356 */
1357 template <typename somenumber>
1358 void
1359 precondition_Jacobi(Vector<somenumber> &dst,
1360 const Vector<somenumber> &src,
1361 const number omega = 1.) const;
1362
1363 /**
1364 * Apply SSOR preconditioning to <tt>src</tt> with damping <tt>omega</tt>.
1365 * The optional argument <tt>pos_right_of_diagonal</tt> is supposed to
1366 * provide an array where each entry specifies the position just right of
1367 * the diagonal in the global array of nonzeros.
1368 */
1369 template <typename somenumber>
1370 void
1371 precondition_SSOR(Vector<somenumber> &dst,
1372 const Vector<somenumber> &src,
1373 const number omega = 1.,
1374 const std::vector<std::size_t> &pos_right_of_diagonal =
1375 std::vector<std::size_t>()) const;
1376
1377 /**
1378 * Apply SOR preconditioning matrix to <tt>src</tt>.
1379 */
1380 template <typename somenumber>
1381 void
1382 precondition_SOR(Vector<somenumber> &dst,
1383 const Vector<somenumber> &src,
1384 const number omega = 1.) const;
1385
1386 /**
1387 * Apply transpose SOR preconditioning matrix to <tt>src</tt>.
1388 */
1389 template <typename somenumber>
1390 void
1391 precondition_TSOR(Vector<somenumber> &dst,
1392 const Vector<somenumber> &src,
1393 const number omega = 1.) const;
1394
1395 /**
1396 * Perform SSOR preconditioning in-place. Apply the preconditioner matrix
1397 * without copying to a second vector. <tt>omega</tt> is the relaxation
1398 * parameter.
1399 */
1400 template <typename somenumber>
1401 void
1402 SSOR(Vector<somenumber> &v, const number omega = 1.) const;
1403
1404 /**
1405 * Perform an SOR preconditioning in-place. <tt>omega</tt> is the
1406 * relaxation parameter.
1407 */
1408 template <typename somenumber>
1409 void
1410 SOR(Vector<somenumber> &v, const number omega = 1.) const;
1411
1412 /**
1413 * Perform a transpose SOR preconditioning in-place. <tt>omega</tt> is the
1414 * relaxation parameter.
1415 */
1416 template <typename somenumber>
1417 void
1418 TSOR(Vector<somenumber> &v, const number omega = 1.) const;
1419
1420 /**
1421 * Perform a permuted SOR preconditioning in-place.
1422 *
1423 * The standard SOR method is applied in the order prescribed by
1424 * <tt>permutation</tt>, that is, first the row <tt>permutation[0]</tt>,
1425 * then <tt>permutation[1]</tt> and so on. For efficiency reasons, the
1426 * permutation as well as its inverse are required.
1427 *
1428 * <tt>omega</tt> is the relaxation parameter.
1429 */
1430 template <typename somenumber>
1431 void
1432 PSOR(Vector<somenumber> &v,
1433 const std::vector<size_type> &permutation,
1434 const std::vector<size_type> &inverse_permutation,
1435 const number omega = 1.) const;
1436
1437 /**
1438 * Perform a transposed permuted SOR preconditioning in-place.
1439 *
1440 * The transposed SOR method is applied in the order prescribed by
1441 * <tt>permutation</tt>, that is, first the row <tt>permutation[m()-1]</tt>,
1442 * then <tt>permutation[m()-2]</tt> and so on. For efficiency reasons, the
1443 * permutation as well as its inverse are required.
1444 *
1445 * <tt>omega</tt> is the relaxation parameter.
1446 */
1447 template <typename somenumber>
1448 void
1449 TPSOR(Vector<somenumber> &v,
1450 const std::vector<size_type> &permutation,
1451 const std::vector<size_type> &inverse_permutation,
1452 const number omega = 1.) const;
1453
1454 /**
1455 * Do one Jacobi step on <tt>v</tt>. Performs a direct Jacobi step with
1456 * right hand side <tt>b</tt>. This function will need an auxiliary vector,
1457 * which is acquired from GrowingVectorMemory.
1458 */
1459 template <typename somenumber>
1460 void
1461 Jacobi_step(Vector<somenumber> &v,
1462 const Vector<somenumber> &b,
1463 const number omega = 1.) const;
1464
1465 /**
1466 * Do one SOR step on <tt>v</tt>. Performs a direct SOR step with right
1467 * hand side <tt>b</tt>.
1468 */
1469 template <typename somenumber>
1470 void
1471 SOR_step(Vector<somenumber> &v,
1472 const Vector<somenumber> &b,
1473 const number omega = 1.) const;
1474
1475 /**
1476 * Do one adjoint SOR step on <tt>v</tt>. Performs a direct TSOR step with
1477 * right hand side <tt>b</tt>.
1478 */
1479 template <typename somenumber>
1480 void
1481 TSOR_step(Vector<somenumber> &v,
1482 const Vector<somenumber> &b,
1483 const number omega = 1.) const;
1484
1485 /**
1486 * Do one SSOR step on <tt>v</tt>. Performs a direct SSOR step with right
1487 * hand side <tt>b</tt> by performing TSOR after SOR.
1488 */
1489 template <typename somenumber>
1490 void
1491 SSOR_step(Vector<somenumber> &v,
1492 const Vector<somenumber> &b,
1493 const number omega = 1.) const;
1494 /** @} */
1495 /**
1496 * @name Iterators
1497 */
1498 /** @{ */
1499
1500 /**
1501 * Return an iterator pointing to the first element of the matrix.
1502 *
1503 * Note the discussion in the general documentation of this class about the
1504 * order in which elements are accessed.
1505 */
1506 const_iterator
1507 begin() const;
1508
1509 /**
1510 * Like the function above, but for non-const matrices.
1511 */
1512 iterator
1513 begin();
1514
1515 /**
1516 * Return an iterator pointing the element past the last one of this matrix.
1517 */
1518 const_iterator
1519 end() const;
1520
1521 /**
1522 * Like the function above, but for non-const matrices.
1523 */
1524 iterator
1525 end();
1526
1527 /**
1528 * Return an iterator pointing to the first element of row @p r.
1529 *
1530 * Note that if the given row is empty, i.e. does not contain any nonzero
1531 * entries, then the iterator returned by this function equals
1532 * <tt>end(r)</tt>. The returned iterator may not be dereferenceable in that
1533 * case if neither row @p r nor any of the following rows contain any
1534 * nonzero entries.
1535 */
1536 const_iterator
1537 begin(const size_type r) const;
1538
1539 /**
1540 * Like the function above, but for non-const matrices.
1541 */
1542 iterator
1543 begin(const size_type r);
1544
1545 /**
1546 * Return an iterator pointing the element past the last one of row @p r ,
1547 * or past the end of the entire sparsity pattern if none of the rows after
1548 * @p r contain any entries at all.
1549 *
1550 * Note that the end iterator is not necessarily dereferenceable. This is in
1551 * particular the case if it is the end iterator for the last row of a
1552 * matrix.
1553 */
1554 const_iterator
1555 end(const size_type r) const;
1556
1557 /**
1558 * Like the function above, but for non-const matrices.
1559 */
1560 iterator
1561 end(const size_type r);
1562 /** @} */
1563 /**
1564 * @name Input/Output
1565 */
1566 /** @{ */
1567
1568 /**
1569 * Print the matrix to the given stream, using the format <tt>(row,column)
1570 * value</tt>, i.e. one nonzero entry of the matrix per line. If
1571 * <tt>across</tt> is true, print all entries on a single line, using the
1572 * format row,column:value.
1573 *
1574 * If the argument <tt>diagonal_first</tt> is true, diagonal elements of
1575 * quadratic matrices are printed first in their row, corresponding to the
1576 * internal storage scheme. If it is false, the elements in a row are
1577 * written in ascending column order.
1578 */
1579 template <typename StreamType>
1580 void
1581 print(StreamType &out,
1582 const bool across = false,
1583 const bool diagonal_first = true) const;
1584
1585 /**
1586 * Print the matrix in the usual format, i.e., as a matrix and not as a list
1587 * of nonzero elements. For better readability, elements not in the matrix
1588 * are displayed as empty space, while matrix elements which are explicitly
1589 * set to zero are displayed as such.
1590 *
1591 * The parameters allow for a flexible setting of the output format:
1592 * @p precision and @p scientific are used to determine the number format,
1593 * where <code>scientific = false</code> means fixed point notation. A zero
1594 * entry for @p width makes the function compute a width, but it may be
1595 * changed to a positive value, if output is crude.
1596 *
1597 * Additionally, a character for an empty value may be specified in
1598 * @p zero_string, and a character to separate row entries can be set in
1599 * @p separator.
1600 *
1601 * Finally, the whole matrix can be multiplied with a common @p denominator
1602 * to produce more readable output, even integers.
1603 *
1604 * @attention This function may produce @em large amounts of output if
1605 * applied to a large matrix!
1606 */
1607 void
1608 print_formatted(std::ostream &out,
1609 const unsigned int precision = 3,
1610 const bool scientific = true,
1611 const unsigned int width = 0,
1612 const char *zero_string = " ",
1613 const double denominator = 1.,
1614 const char *separator = " ") const;
1615
1616 /**
1617 * Print the actual pattern of the matrix. For each entry with an absolute
1618 * value larger than threshold, a '*' is printed, a ':' for every value
1619 * smaller and a '.' for every entry not allocated.
1620 */
1621 void
1622 print_pattern(std::ostream &out, const double threshold = 0.) const;
1623
1624 /**
1625 * Print the matrix to the output stream @p out in a format that can be
1626 * read by numpy::readtxt(). To load the matrix in python just do
1627 * <code>
1628 * [data, row, column] = numpy.loadtxt('my_matrix.txt')
1629 * sparse_matrix = scipy.sparse.csr_matrix((data, (row, column)))
1630 * </code>
1631 */
1632 void
1633 print_as_numpy_arrays(std::ostream &out,
1634 const unsigned int precision = 9) const;
1635
1636 /**
1637 * Write the data of this object en bloc to a file. This is done in a binary
1638 * mode, so the output is neither readable by humans nor (probably) by other
1639 * computers using a different operating system of number format.
1640 *
1641 * The purpose of this function is that you can swap out matrices and
1642 * sparsity pattern if you are short of memory, want to communicate between
1643 * different programs, or allow objects to be persistent across different
1644 * runs of the program.
1645 */
1646 void
1647 block_write(std::ostream &out) const;
1648
1649 /**
1650 * Read data that has previously been written by block_write() from a file.
1651 * This is done using the inverse operations to the above function, so it is
1652 * reasonably fast because the bitstream is not interpreted except for a few
1653 * numbers up front.
1654 *
1655 * The object is resized on this operation, and all previous contents are
1656 * lost. Note, however, that no checks are performed whether new data and
1657 * the underlying SparsityPattern object fit together. It is your
1658 * responsibility to make sure that the sparsity pattern and the data to be
1659 * read match.
1660 *
1661 * A primitive form of error checking is performed which will recognize the
1662 * bluntest attempts to interpret some data as a matrix stored bitwise to a
1663 * file that wasn't actually created that way, but not more.
1664 */
1665 void
1666 block_read(std::istream &in);
1667 /** @} */
1668 /**
1669 * @addtogroup Exceptions
1670 * @{
1671 */
1672
1673 /**
1674 * Exception
1675 */
1676 DeclException2(ExcInvalidIndex,
1677 int,
1678 int,
1679 << "You are trying to access the matrix entry with index <"
1680 << arg1 << ',' << arg2
1681 << ">, but this entry does not exist in the sparsity pattern "
1682 "of this matrix."
1683 "\n\n"
1684 "The most common cause for this problem is that you used "
1685 "a method to build the sparsity pattern that did not "
1686 "(completely) take into account all of the entries you "
1687 "will later try to write into. An example would be "
1688 "building a sparsity pattern that does not include "
1689 "the entries you will write into due to constraints "
1690 "on degrees of freedom such as hanging nodes or periodic "
1691 "boundary conditions. In such cases, building the "
1692 "sparsity pattern will succeed, but you will get errors "
1693 "such as the current one at one point or other when "
1694 "trying to write into the entries of the matrix.");
1695 /**
1696 * Exception
1697 */
1698 DeclExceptionMsg(ExcDifferentSparsityPatterns,
1699 "When copying one sparse matrix into another, "
1700 "or when adding one sparse matrix to another, "
1701 "both matrices need to refer to the same "
1702 "sparsity pattern.");
1703 /**
1704 * Exception
1705 */
1706 DeclException2(ExcIteratorRange,
1707 int,
1708 int,
1709 << "The iterators denote a range of " << arg1
1710 << " elements, but the given number of rows was " << arg2);
1711 /**
1712 * Exception
1713 */
1714 DeclExceptionMsg(ExcSourceEqualsDestination,
1715 "You are attempting an operation on two vectors that "
1716 "are the same object, but the operation requires that the "
1717 "two objects are in fact different.");
1718 /** @} */
1719
1720 protected:
1721 /**
1722 * For some matrix storage formats, in particular for the PETSc distributed
1723 * blockmatrices, set and add operations on individual elements can not be
1724 * freely mixed. Rather, one has to synchronize operations when one wants to
1725 * switch from setting elements to adding to elements. BlockMatrixBase
1726 * automatically synchronizes the access by calling this helper function for
1727 * each block. This function ensures that the matrix is in a state that
1728 * allows adding elements; if it previously already was in this state, the
1729 * function does nothing.
1730 */
1731 void
1732 prepare_add();
1733
1734 /**
1735 * Same as prepare_add() but prepare the matrix for setting elements if the
1736 * representation of elements in this class requires such an operation.
1737 */
1738 void
1739 prepare_set();
1740
1741 private:
1742 /**
1743 * Pointer to the sparsity pattern used for this matrix. In order to
1744 * guarantee that it is not deleted while still in use, we subscribe to it
1745 * using the ObserverPointer class.
1746 */
1747 ObserverPointer<const SparsityPattern, SparseMatrix<number>> cols;
1748
1749 /**
1750 * Array of values for all the nonzero entries. The position of an
1751 * entry within the matrix, i.e., the row and column number for a
1752 * given value in this array can only be deduced using the sparsity
1753 * pattern. The same holds for the more common operation of finding
1754 * an entry by its coordinates.
1755 */
1756 std::unique_ptr<number[]> val;
1757
1758 /**
1759 * Allocated size of #val. This can be larger than the actually used part if
1760 * the size of the matrix was reduced sometime in the past by associating a
1761 * sparsity pattern with a smaller size to this object, using the reinit()
1762 * function.
1763 */
1764 std::size_t max_len;
1765
1766 // make all other sparse matrices friends
1767 template <typename somenumber>
1768 friend class SparseMatrix;
1769 template <typename somenumber>
1770 friend class SparseLUDecomposition;
1771 template <typename>
1772 friend class SparseILU;
1773
1774 // To allow it calling private prepare_add() and prepare_set().
1775 template <typename>
1776 friend class BlockMatrixBase;
1777
1778 // Also give access to internal details to the iterator/accessor classes.
1779 template <typename, bool>
1780 friend class SparseMatrixIterators::Iterator;
1781 template <typename, bool>
1782 friend class SparseMatrixIterators::Accessor;
1783
1784 #ifdef DEAL_II_WITH_MPI
1785 // Give access to internal datastructures to perform MPI operations.
1786 template <typename Number>
1787 friend void
1788 Utilities::MPI::sum(const SparseMatrix<Number> &,
1789 const MPI_Comm,
1790 SparseMatrix<Number> &);
1791 #endif
1792 };
1793
1794 #ifndef DOXYGEN
1795 /*---------------------- Inline functions -----------------------------------*/
1796
1797
1798
1799 template <typename number>
1800 template <typename number2>
1801 void
1802 SparseMatrix<number>::reinit(const SparseMatrix<number2> &sparse_matrix)
1803 {
1804 this->reinit(sparse_matrix.get_sparsity_pattern());
1805 }
1806
1807
1808
1809 template <typename number>
1810 inline typename SparseMatrix<number>::size_type
1811 SparseMatrix<number>::m() const
1812 {
1813 Assert(cols != nullptr, ExcNeedsSparsityPattern());
1814 return cols->rows;
1815 }
1816
1817
1818
1819 template <typename number>
1820 inline typename SparseMatrix<number>::size_type
1821 SparseMatrix<number>::n() const
1822 {
1823 Assert(cols != nullptr, ExcNeedsSparsityPattern());
1824 return cols->cols;
1825 }
1826
1827
1828
1829 template <typename number>
1830 inline const SparsityPattern &
1831 SparseMatrix<number>::get_sparsity_pattern() const
1832 {
1833 Assert(cols != nullptr, ExcNeedsSparsityPattern());
1834 return *cols;
1835 }
1836
1837
1838
1839 // Inline the set() and add() functions, since they will be called frequently.
1840 template <typename number>
1841 inline void
1842 SparseMatrix<number>::set(const size_type i,
1843 const size_type j,
1844 const number value)
1845 {
1846 AssertIsFinite(value);
1847
1848 const size_type index = cols->operator()(i, j);
1849
1850 // it is allowed to set elements of the matrix that are not part of the
1851 // sparsity pattern, if the value to which we set it is zero
1852 if (index == SparsityPattern::invalid_entry)
1853 {
1854 Assert((index != SparsityPattern::invalid_entry) || (value == number()),
1855 ExcInvalidIndex(i, j));
1856 return;
1857 }
1858
1859 val[index] = value;
1860 }
1861
1862
1863
1864 template <typename number>
1865 template <typename number2>
1866 inline void
1867 SparseMatrix<number>::set(const std::vector<size_type> &indices,
1868 const FullMatrix<number2> &values,
1869 const bool elide_zero_values)
1870 {
1871 Assert(indices.size() == values.m(),
1872 ExcDimensionMismatch(indices.size(), values.m()));
1873 Assert(values.m() == values.n(), ExcNotQuadratic());
1874
1875 for (size_type i = 0; i < indices.size(); ++i)
1876 set(indices[i],
1877 indices.size(),
1878 indices.data(),
1879 &values(i, 0),
1880 elide_zero_values);
1881 }
1882
1883
1884
1885 template <typename number>
1886 template <typename number2>
1887 inline void
1888 SparseMatrix<number>::set(const std::vector<size_type> &row_indices,
1889 const std::vector<size_type> &col_indices,
1890 const FullMatrix<number2> &values,
1891 const bool elide_zero_values)
1892 {
1893 Assert(row_indices.size() == values.m(),
1894 ExcDimensionMismatch(row_indices.size(), values.m()));
1895 Assert(col_indices.size() == values.n(),
1896 ExcDimensionMismatch(col_indices.size(), values.n()));
1897
1898 for (size_type i = 0; i < row_indices.size(); ++i)
1899 set(row_indices[i],
1900 col_indices.size(),
1901 col_indices.data(),
1902 &values(i, 0),
1903 elide_zero_values);
1904 }
1905
1906
1907
1908 template <typename number>
1909 template <typename number2>
1910 inline void
1911 SparseMatrix<number>::set(const size_type row,
1912 const std::vector<size_type> &col_indices,
1913 const std::vector<number2> &values,
1914 const bool elide_zero_values)
1915 {
1916 Assert(col_indices.size() == values.size(),
1917 ExcDimensionMismatch(col_indices.size(), values.size()));
1918
1919 set(row,
1920 col_indices.size(),
1921 col_indices.data(),
1922 values.data(),
1923 elide_zero_values);
1924 }
1925
1926
1927
1928 template <typename number>
1929 inline void
1930 SparseMatrix<number>::add(const size_type i,
1931 const size_type j,
1932 const number value)
1933 {
1934 AssertIsFinite(value);
1935
1936 if (value == number())
1937 return;
1938
1939 const size_type index = cols->operator()(i, j);
1940
1941 // it is allowed to add elements to the matrix that are not part of the
1942 // sparsity pattern, if the value to which we set it is zero
1943 if (index == SparsityPattern::invalid_entry)
1944 {
1945 Assert((index != SparsityPattern::invalid_entry) || (value == number()),
1946 ExcInvalidIndex(i, j));
1947 return;
1948 }
1949
1950 val[index] += value;
1951 }
1952
1953
1954
1955 template <typename number>
1956 template <typename number2>
1957 inline void
1958 SparseMatrix<number>::add(const std::vector<size_type> &indices,
1959 const FullMatrix<number2> &values,
1960 const bool elide_zero_values)
1961 {
1962 Assert(indices.size() == values.m(),
1963 ExcDimensionMismatch(indices.size(), values.m()));
1964 Assert(values.m() == values.n(), ExcNotQuadratic());
1965
1966 for (size_type i = 0; i < indices.size(); ++i)
1967 add(indices[i],
1968 indices.size(),
1969 indices.data(),
1970 &values(i, 0),
1971 elide_zero_values);
1972 }
1973
1974
1975
1976 template <typename number>
1977 template <typename number2>
1978 inline void
1979 SparseMatrix<number>::add(const std::vector<size_type> &row_indices,
1980 const std::vector<size_type> &col_indices,
1981 const FullMatrix<number2> &values,
1982 const bool elide_zero_values)
1983 {
1984 Assert(row_indices.size() == values.m(),
1985 ExcDimensionMismatch(row_indices.size(), values.m()));
1986 Assert(col_indices.size() == values.n(),
1987 ExcDimensionMismatch(col_indices.size(), values.n()));
1988
1989 for (size_type i = 0; i < row_indices.size(); ++i)
1990 add(row_indices[i],
1991 col_indices.size(),
1992 col_indices.data(),
1993 &values(i, 0),
1994 elide_zero_values);
1995 }
1996
1997
1998
1999 template <typename number>
2000 template <typename number2>
2001 inline void
2002 SparseMatrix<number>::add(const size_type row,
2003 const std::vector<size_type> &col_indices,
2004 const std::vector<number2> &values,
2005 const bool elide_zero_values)
2006 {
2007 Assert(col_indices.size() == values.size(),
2008 ExcDimensionMismatch(col_indices.size(), values.size()));
2009
2010 add(row,
2011 col_indices.size(),
2012 col_indices.data(),
2013 values.data(),
2014 elide_zero_values,
2015 std::is_sorted(col_indices.begin(), col_indices.end()));
2016 }
2017
2018
2019
2020 template <typename number>
2021 inline SparseMatrix<number> &
2022 SparseMatrix<number>::operator*=(const number factor)
2023 {
2024 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2025 Assert(val != nullptr, ExcNotInitialized());
2026
2027 number *val_ptr = val.get();
2028 const number *const end_ptr = val.get() + cols->n_nonzero_elements();
2029
2030 while (val_ptr != end_ptr)
2031 *val_ptr++ *= factor;
2032
2033 return *this;
2034 }
2035
2036
2037
2038 template <typename number>
2039 inline SparseMatrix<number> &
2040 SparseMatrix<number>::operator/=(const number factor)
2041 {
2042 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2043 Assert(val != nullptr, ExcNotInitialized());
2044 Assert(factor != number(), ExcDivideByZero());
2045
2046 const number factor_inv = number(1.) / factor;
2047
2048 number *val_ptr = val.get();
2049 const number *const end_ptr = val.get() + cols->n_nonzero_elements();
2050
2051 while (val_ptr != end_ptr)
2052 *val_ptr++ *= factor_inv;
2053
2054 return *this;
2055 }
2056
2057
2058
2059 template <typename number>
2060 inline const number &
2061 SparseMatrix<number>::operator()(const size_type i, const size_type j) const
2062 {
2063 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2064 Assert(cols->operator()(i, j) != SparsityPattern::invalid_entry,
2065 ExcInvalidIndex(i, j));
2066 return val[cols->operator()(i, j)];
2067 }
2068
2069
2070
2071 template <typename number>
2072 inline number &
2073 SparseMatrix<number>::operator()(const size_type i, const size_type j)
2074 {
2075 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2076 Assert(cols->operator()(i, j) != SparsityPattern::invalid_entry,
2077 ExcInvalidIndex(i, j));
2078 return val[cols->operator()(i, j)];
2079 }
2080
2081
2082
2083 template <typename number>
2084 inline number
2085 SparseMatrix<number>::el(const size_type i, const size_type j) const
2086 {
2087 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2088 const size_type index = cols->operator()(i, j);
2089
2090 if (index != SparsityPattern::invalid_entry)
2091 return val[index];
2092 else
2093 return 0;
2094 }
2095
2096
2097
2098 template <typename number>
2099 inline number
2100 SparseMatrix<number>::diag_element(const size_type i) const
2101 {
2102 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2103 Assert(m() == n(), ExcNotQuadratic());
2104 AssertIndexRange(i, m());
2105
2106 // Use that the first element in each row of a quadratic matrix is the main
2107 // diagonal
2108 return val[cols->rowstart[i]];
2109 }
2110
2111
2112
2113 template <typename number>
2114 inline number &
2115 SparseMatrix<number>::diag_element(const size_type i)
2116 {
2117 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2118 Assert(m() == n(), ExcNotQuadratic());
2119 AssertIndexRange(i, m());
2120
2121 // Use that the first element in each row of a quadratic matrix is the main
2122 // diagonal
2123 return val[cols->rowstart[i]];
2124 }
2125
2126
2127
2128 template <typename number>
2129 template <typename ForwardIterator>
2130 void
2131 SparseMatrix<number>::copy_from(const ForwardIterator begin,
2132 const ForwardIterator end)
2133 {
2134 Assert(static_cast<size_type>(std::distance(begin, end)) == m(),
2135 ExcIteratorRange(std::distance(begin, end), m()));
2136
2137 // for use in the inner loop, we define an alias to the type of the inner
2138 // iterators
2139 using inner_iterator =
2140 typename std::iterator_traits<ForwardIterator>::value_type::const_iterator;
2141 size_type row = 0;
2142 for (ForwardIterator i = begin; i != end; ++i, ++row)
2143 {
2144 const inner_iterator end_of_row = i->end();
2145 for (inner_iterator j = i->begin(); j != end_of_row; ++j)
2146 // write entries
2147 set(row, j->first, j->second);
2148 };
2149 }
2150
2151
2152 //---------------------------------------------------------------------------
2153
2154
2155 namespace SparseMatrixIterators
2156 {
2157 template <typename number>
2158 inline Accessor<number, true>::Accessor(const MatrixType *matrix,
2159 const std::size_t index_within_matrix)
2160 : SparsityPatternIterators::Accessor(&matrix->get_sparsity_pattern(),
2161 index_within_matrix)
2162 , matrix(matrix)
2163 {}
2164
2165
2166
2167 template <typename number>
2168 inline Accessor<number, true>::Accessor(const MatrixType *matrix)
2169 : SparsityPatternIterators::Accessor(&matrix->get_sparsity_pattern())
2170 , matrix(matrix)
2171 {}
2172
2173
2174
2175 template <typename number>
2176 inline Accessor<number, true>::Accessor(
2177 const SparseMatrixIterators::Accessor<number, false> &a)
2178 : SparsityPatternIterators::Accessor(a)
2179 , matrix(&a.get_matrix())
2180 {}
2181
2182
2183
2184 template <typename number>
2185 inline number
2186 Accessor<number, true>::value() const
2187 {
2188 AssertIndexRange(linear_index, matrix->n_nonzero_elements());
2189 return matrix->val[linear_index];
2190 }
2191
2192
2193
2194 template <typename number>
2195 inline const typename Accessor<number, true>::MatrixType &
2196 Accessor<number, true>::get_matrix() const
2197 {
2198 return *matrix;
2199 }
2200
2201
2202
2203 template <typename number>
2204 inline Accessor<number, false>::Reference::Reference(const Accessor *accessor,
2205 const bool)
2206 : accessor(accessor)
2207 {}
2208
2209
2210 template <typename number>
2211 inline Accessor<number, false>::Reference::operator number() const
2212 {
2213 AssertIndexRange(accessor->linear_index,
2214 accessor->matrix->n_nonzero_elements());
2215 return accessor->matrix->val[accessor->linear_index];
2216 }
2217
2218
2219
2220 template <typename number>
2221 inline const typename Accessor<number, false>::Reference &
2222 Accessor<number, false>::Reference::operator=(const number n) const
2223 {
2224 AssertIndexRange(accessor->linear_index,
2225 accessor->matrix->n_nonzero_elements());
2226 accessor->matrix->val[accessor->linear_index] = n;
2227 return *this;
2228 }
2229
2230
2231
2232 template <typename number>
2233 inline const typename Accessor<number, false>::Reference &
2234 Accessor<number, false>::Reference::operator+=(const number n) const
2235 {
2236 AssertIndexRange(accessor->linear_index,
2237 accessor->matrix->n_nonzero_elements());
2238 accessor->matrix->val[accessor->linear_index] += n;
2239 return *this;
2240 }
2241
2242
2243
2244 template <typename number>
2245 inline const typename Accessor<number, false>::Reference &
2246 Accessor<number, false>::Reference::operator-=(const number n) const
2247 {
2248 AssertIndexRange(accessor->linear_index,
2249 accessor->matrix->n_nonzero_elements());
2250 accessor->matrix->val[accessor->linear_index] -= n;
2251 return *this;
2252 }
2253
2254
2255
2256 template <typename number>
2257 inline const typename Accessor<number, false>::Reference &
2258 Accessor<number, false>::Reference::operator*=(const number n) const
2259 {
2260 AssertIndexRange(accessor->linear_index,
2261 accessor->matrix->n_nonzero_elements());
2262 accessor->matrix->val[accessor->linear_index] *= n;
2263 return *this;
2264 }
2265
2266
2267
2268 template <typename number>
2269 inline const typename Accessor<number, false>::Reference &
2270 Accessor<number, false>::Reference::operator/=(const number n) const
2271 {
2272 AssertIndexRange(accessor->linear_index,
2273 accessor->matrix->n_nonzero_elements());
2274 accessor->matrix->val[accessor->linear_index] /= n;
2275 return *this;
2276 }
2277
2278
2279
2280 template <typename number>
2281 inline Accessor<number, false>::Accessor(MatrixType *matrix,
2282 const std::size_t index)
2283 : SparsityPatternIterators::Accessor(&matrix->get_sparsity_pattern(), index)
2284 , matrix(matrix)
2285 {}
2286
2287
2288
2289 template <typename number>
2290 inline Accessor<number, false>::Accessor(MatrixType *matrix)
2291 : SparsityPatternIterators::Accessor(&matrix->get_sparsity_pattern())
2292 , matrix(matrix)
2293 {}
2294
2295
2296
2297 template <typename number>
2298 inline typename Accessor<number, false>::Reference
2299 Accessor<number, false>::value() const
2300 {
2301 return Reference(this, true);
2302 }
2303
2304
2305
2306 template <typename number>
2307 inline typename Accessor<number, false>::MatrixType &
2308 Accessor<number, false>::get_matrix() const
2309 {
2310 return *matrix;
2311 }
2312
2313
2314
2315 template <typename number, bool Constness>
2316 inline Iterator<number, Constness>::Iterator(MatrixType *matrix,
2317 const std::size_t index)
2318 : accessor(matrix, index)
2319 {}
2320
2321
2322
2323 template <typename number, bool Constness>
2324 inline Iterator<number, Constness>::Iterator(MatrixType *matrix)
2325 : accessor(matrix)
2326 {}
2327
2328
2329
2330 template <typename number, bool Constness>
2331 inline Iterator<number, Constness>::Iterator(
2332 const SparseMatrixIterators::Iterator<number, false> &i)
2333 : accessor(*i)
2334 {}
2335
2336
2337
2338 template <typename number, bool Constness>
2339 inline const Iterator<number, Constness> &
2340 Iterator<number, Constness>::operator=(
2341 const SparseMatrixIterators::Iterator<number, false> &i)
2342 {
2343 accessor = *i;
2344 return *this;
2345 }
2346
2347
2348
2349 template <typename number, bool Constness>
2350 inline Iterator<number, Constness> &
2351 Iterator<number, Constness>::operator++()
2352 {
2353 accessor.advance();
2354 return *this;
2355 }
2356
2357
2358 template <typename number, bool Constness>
2359 inline Iterator<number, Constness>
2360 Iterator<number, Constness>::operator++(int)
2361 {
2362 const Iterator iter = *this;
2363 accessor.advance();
2364 return iter;
2365 }
2366
2367
2368 template <typename number, bool Constness>
2369 inline const Accessor<number, Constness> &
2370 Iterator<number, Constness>::operator*() const
2371 {
2372 return accessor;
2373 }
2374
2375
2376 template <typename number, bool Constness>
2377 inline const Accessor<number, Constness> *
2378 Iterator<number, Constness>::operator->() const
2379 {
2380 return &accessor;
2381 }
2382
2383
2384 template <typename number, bool Constness>
2385 inline bool
2386 Iterator<number, Constness>::operator==(const Iterator &other) const
2387 {
2388 return (accessor == other.accessor);
2389 }
2390
2391
2392 template <typename number, bool Constness>
2393 inline bool
2394 Iterator<number, Constness>::operator!=(const Iterator &other) const
2395 {
2396 return !(*this == other);
2397 }
2398
2399
2400 template <typename number, bool Constness>
2401 inline bool
2402 Iterator<number, Constness>::operator<(const Iterator &other) const
2403 {
2404 Assert(&accessor.get_matrix() == &other.accessor.get_matrix(),
2405 ExcInternalError());
2406
2407 return (accessor < other.accessor);
2408 }
2409
2410
2411 template <typename number, bool Constness>
2412 inline bool
2413 Iterator<number, Constness>::operator>(const Iterator &other) const
2414 {
2415 return (other < *this);
2416 }
2417
2418
2419 template <typename number, bool Constness>
2420 inline int
2421 Iterator<number, Constness>::operator-(const Iterator &other) const
2422 {
2423 Assert(&accessor.get_matrix() == &other.accessor.get_matrix(),
2424 ExcInternalError());
2425
2426 return (*this)->linear_index - other->linear_index;
2427 }
2428
2429
2430
2431 template <typename number, bool Constness>
2432 inline Iterator<number, Constness>
2433 Iterator<number, Constness>::operator+(const size_type n) const
2434 {
2435 Iterator x = *this;
2436 for (size_type i = 0; i < n; ++i)
2437 ++x;
2438
2439 return x;
2440 }
2441
2442 } // namespace SparseMatrixIterators
2443
2444
2445
2446 template <typename number>
2447 inline typename SparseMatrix<number>::const_iterator
2448 SparseMatrix<number>::begin() const
2449 {
2450 return const_iterator(this, 0);
2451 }
2452
2453
2454 template <typename number>
2455 inline typename SparseMatrix<number>::const_iterator
2456 SparseMatrix<number>::end() const
2457 {
2458 return const_iterator(this);
2459 }
2460
2461
2462 template <typename number>
2463 inline typename SparseMatrix<number>::iterator
2464 SparseMatrix<number>::begin()
2465 {
2466 return iterator(this, 0);
2467 }
2468
2469
2470 template <typename number>
2471 inline typename SparseMatrix<number>::iterator
2472 SparseMatrix<number>::end()
2473 {
2474 return iterator(this, cols->rowstart[cols->rows]);
2475 }
2476
2477
2478 template <typename number>
2479 inline typename SparseMatrix<number>::const_iterator
2480 SparseMatrix<number>::begin(const size_type r) const
2481 {
2482 AssertIndexRange(r, m());
2483
2484 return const_iterator(this, cols->rowstart[r]);
2485 }
2486
2487
2488
2489 template <typename number>
2490 inline typename SparseMatrix<number>::const_iterator
2491 SparseMatrix<number>::end(const size_type r) const
2492 {
2493 AssertIndexRange(r, m());
2494
2495 return const_iterator(this, cols->rowstart[r + 1]);
2496 }
2497
2498
2499
2500 template <typename number>
2501 inline typename SparseMatrix<number>::iterator
2502 SparseMatrix<number>::begin(const size_type r)
2503 {
2504 AssertIndexRange(r, m());
2505
2506 return iterator(this, cols->rowstart[r]);
2507 }
2508
2509
2510
2511 template <typename number>
2512 inline typename SparseMatrix<number>::iterator
2513 SparseMatrix<number>::end(const size_type r)
2514 {
2515 AssertIndexRange(r, m());
2516
2517 return iterator(this, cols->rowstart[r + 1]);
2518 }
2519
2520
2521
2522 template <typename number>
2523 template <typename StreamType>
2524 inline void
2525 SparseMatrix<number>::print(StreamType &out,
2526 const bool across,
2527 const bool diagonal_first) const
2528 {
2529 Assert(cols != nullptr, ExcNeedsSparsityPattern());
2530 Assert(val != nullptr, ExcNotInitialized());
2531
2532 bool hanging_diagonal = false;
2533 number diagonal = number();
2534
2535 for (size_type i = 0; i < cols->rows; ++i)
2536 {
2537 for (size_type j = cols->rowstart[i]; j < cols->rowstart[i + 1]; ++j)
2538 {
2539 if (!diagonal_first && i == cols->colnums[j])
2540 {
2541 diagonal = val[j];
2542 hanging_diagonal = true;
2543 }
2544 else
2545 {
2546 if (hanging_diagonal && cols->colnums[j] > i)
2547 {
2548 if (across)
2549 out << ' ' << i << ',' << i << ':' << diagonal;
2550 else
2551 out << '(' << i << ',' << i << ") " << diagonal
2552 << std::endl;
2553 hanging_diagonal = false;
2554 }
2555 if (across)
2556 out << ' ' << i << ',' << cols->colnums[j] << ':' << val[j];
2557 else
2558 out << '(' << i << ',' << cols->colnums[j] << ") " << val[j]
2559 << std::endl;
2560 }
2561 }
2562 if (hanging_diagonal)
2563 {
2564 if (across)
2565 out << ' ' << i << ',' << i << ':' << diagonal;
2566 else
2567 out << '(' << i << ',' << i << ") " << diagonal << std::endl;
2568 hanging_diagonal = false;
2569 }
2570 }
2571 if (across)
2572 out << std::endl;
2573 }
2574
2575
2576 template <typename number>
2577 inline void
2578 SparseMatrix<number>::prepare_add()
2579 {
2580 // nothing to do here
2581 }
2582
2583
2584
2585 template <typename number>
2586 inline void
2587 SparseMatrix<number>::prepare_set()
2588 {
2589 // nothing to do here
2590 }
2591
2592 #endif // DOXYGEN
2593
2594
2595 DEAL_II_NAMESPACE_CLOSE
2596
2597 #endif