Debian Codegraph @

include/deal.II/lac/trilinos_tpetra_sparse_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2024 - 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_trilinos_tpetra_sparse_matrix_h
16 #define dealii_trilinos_tpetra_sparse_matrix_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_TRILINOS_WITH_TPETRA
21
22 # include <deal.II/base/enable_observer_pointer.h>
23 # include <deal.II/base/index_set.h>
24 # include <deal.II/base/trilinos_utilities.h>
25
26 # include <deal.II/lac/sparse_matrix.h>
27 # include <deal.II/lac/sparsity_pattern.h>
28 # include <deal.II/lac/trilinos_tpetra_sparsity_pattern.h>
29 # include <deal.II/lac/trilinos_tpetra_vector.h>
30 # include <deal.II/lac/vector.h>
31
32 // Tpetra includes
33 # include <Tpetra_Core.hpp>
34 # include <Tpetra_CrsMatrix.hpp>
35
36 # include <type_traits>
37
38
39 DEAL_II_NAMESPACE_OPEN
40
41 // forward declarations
42
43 template <typename Number>
44 class SparseMatrix;
45
46 # ifndef DOXYGEN
47 template <typename MatrixType>
48 class BlockMatrixBase;
49
50 namespace LinearAlgebra
51 {
52 namespace TpetraWrappers
53 {
54 template <typename MemorySpace>
55 class SparsityPattern;
56
57 namespace SparseMatrixIterators
58 {
59 template <typename Number, typename MemorySpace, bool Constness>
60 class Iterator;
61 }
62 } // namespace TpetraWrappers
63 } // namespace LinearAlgebra
64 # endif
65
66 namespace LinearAlgebra
67 {
68
69 namespace TpetraWrappers
70 {
71 /**
72 * This class implements a wrapper to use the Trilinos distributed sparse
73 * matrix class
74 * <a
75 * href="https://docs.trilinos.org/dev/packages/tpetra/doc/html/classTpetra_1_1CrsMatrix.html">Tpetra::CrsMatrix</a>.
76 * This is precisely the kind of matrix we deal with all the time - we
77 * most likely get it from some assembly process, where also entries not
78 * locally owned might need to be written and hence need to be forwarded
79 * to the owner process. This class is designed to be used in a distributed
80 * memory architecture with an MPI compiler on the bottom, but it works
81 * equally well for serial processes. The only requirement for this class to
82 * work is that Trilinos has been installed with the same compiler as is
83 * used for generating deal.II.
84 *
85 * Moreover, this class takes an optional template argument for
86 * Kokkos::Nodes, allowing the usage of different Kokkos::Nodes.
87 * Kokkos allows the writing of portable applications targeting,
88 * for example, CUDA, OpenMP, Serial, or Threads, as backends for
89 * the execution and memory spaces. The backend is chosen by
90 * choosing the corresponding Kokkos Node.
91 *
92 * The interface of this class is modeled after the existing SparseMatrix
93 * class in deal.II. It has almost the same member functions and is often
94 * exchangeable. This class is templated and can be used with different
95 * scalar types. However, Trilinos need to be installed with complex support
96 * for usage with complex scalar types.
97 *
98 * @note You need to call SparseMatrix::compress() before you actually use
99 * the matrix. This calls
100 * <a
101 * href="https://docs.trilinos.org/dev/packages/tpetra/doc/html/classTpetra_1_1CrsMatrix.html#aa985b225a24d2f74602e25b38b4430af">Tpetra::fillComplete</a>
102 * that compresses the storage format for sparse matrices by discarding
103 * unused elements and prepares the matrix for further usage
104 * (e.g., for matrix-vector products).
105 * However, to continue assembling the matrix, you need to call
106 * SparseMatrix::resume_fill() first. Once you finish modifying
107 * the matrix, you must call SparseMatrix::compress() again.
108 */
109 template <typename Number, typename MemorySpace = dealii::MemorySpace::Host>
110 class SparseMatrix : public EnableObserverPointer
111 {
112 public:
113 /**
114 * Declare the type for container size.
115 */
116 using size_type = dealii::types::global_dof_index;
117
118 /**
119 * Exception
120 */
121 DeclException1(ExcAccessToNonlocalRow,
122 std::size_t,
123 << "You tried to access row " << arg1
124 << " of a non-contiguous locally owned row set."
125 << " The row " << arg1
126 << " is not stored locally and can't be accessed.");
127
128 /**
129 * A structure that describes some of the traits of this class in terms of
130 * its run-time behavior. Some other classes (such as the block matrix
131 * classes) that take one or other of the matrix classes as its template
132 * parameters can tune their behavior based on the variables in this
133 * class.
134 */
135 struct Traits
136 {
137 /**
138 * It is safe to elide additions of zeros to individual elements of this
139 * matrix.
140 */
141 static const bool zero_addition_can_be_elided = true;
142 };
143
144 /**
145 * Declare an alias for the iterator class.
146 */
147 using iterator =
148 SparseMatrixIterators::Iterator<Number, MemorySpace, false>;
149
150 /**
151 * Declare an alias for the const iterator class.
152 */
153 using const_iterator =
154 SparseMatrixIterators::Iterator<Number, MemorySpace, true>;
155
156 /**
157 * Declare an alias for the type used to store matrix elements, in analogy
158 * to all the other container classes.
159 */
160 using value_type = Number;
161
162 /**
163 * @name Constructors and initialization.
164 */
165 /** @{ */
166 /**
167 * Default constructor. Generates an empty (zero-size) matrix.
168 */
169 SparseMatrix();
170
171 /**
172 * Generate a matrix from a TpetraWrappers::SparsityPattern object.
173 */
174 SparseMatrix(const SparsityPattern<MemorySpace> &sparsity_pattern);
175
176 /**
177 * Generate a matrix that is completely stored locally, having #m rows and
178 * #n columns.
179 *
180 * The number of columns entries per row is specified as the maximum
181 * number of entries argument.
182 */
183 SparseMatrix(const size_type m,
184 const size_type n,
185 const unsigned int n_max_entries_per_row);
186
187 /**
188 * Generate a matrix that is completely stored locally, having #m rows and
189 * #n columns.
190 *
191 * The vector <tt>n_entries_per_row</tt> specifies the number of entries
192 * in each row.
193 */
194 SparseMatrix(const size_type m,
195 const size_type n,
196 const std::vector<unsigned int> &n_entries_per_row);
197
198 /**
199 * Move constructor. Create a new sparse matrix by stealing the internal
200 * data of the `other` object.
201 */
202 SparseMatrix(SparseMatrix<Number, MemorySpace> &&other) noexcept;
203
204 /**
205 * Copy constructor is deleted.
206 */
207 SparseMatrix(const SparseMatrix<Number, MemorySpace> &) = delete;
208
209 /**
210 * operator= is deleted.
211 */
212 SparseMatrix<Number, MemorySpace> &
213 operator=(const SparseMatrix<Number, MemorySpace> &) = delete;
214
215 /**
216 * Move assignment operator.
217 */
218 SparseMatrix<Number, MemorySpace> &
219 operator=(SparseMatrix<Number, MemorySpace> &&other) noexcept;
220
221 /**
222 * Destructor. Made virtual so that one can use pointers to objects of
223 * this class.
224 */
225 virtual ~SparseMatrix() override = default;
226
227 /**
228 * This function initializes the Trilinos matrix with a deal.II sparsity
229 * pattern, i.e. it makes the underlying Trilinos Tpetra::CrsMatrix know
230 * the position of nonzero entries according to the sparsity pattern. This
231 * function is meant for use in serial programs, where there is no need to
232 * specify how the matrix is going to be distributed among different
233 * processors. This function works in %parallel, too, but it is
234 * recommended to manually specify the %parallel partitioning of the
235 * matrix using a Tpetra::Map. When run in %parallel, it is currently
236 * necessary that each processor holds the sparsity_pattern structure
237 * because each processor sets its rows.
238 *
239 * This is a collective operation that needs to be called on all
240 * processors in order to avoid a dead lock.
241 */
242 template <typename SparsityPatternType>
243 void
244 reinit(const SparsityPatternType &sparsity_pattern);
245
246 /**
247 * This function reinitializes the Trilinos sparse matrix from a
248 * (possibly distributed) Trilinos sparsity pattern. It also works
249 * in parallel. In that case, the partitioning of the Trilinos
250 * sparsity pattern is used.
251 *
252 * This is a collective operation that needs to be called on all
253 * processors in order to avoid a dead lock.
254 */
255 void
256 reinit(const SparsityPattern<MemorySpace> &sparsity_pattern);
257 /** @} */
258
259 /**
260 * @name Constructors and initialization using an IndexSet description
261 */
262 /** @{ */
263 /**
264 * Constructor using an IndexSet and an MPI communicator to describe the
265 * %parallel partitioning. The parameter @p n_max_entries_per_row sets the
266 * number of nonzero entries in each row that will be allocated. Note that
267 * this number does not need to be exact, and it is even allowed that the
268 * actual matrix structure has more nonzero entries than specified in the
269 * constructor. However it is still advantageous to provide good estimates
270 * here since this will considerably increase the performance of the
271 * matrix setup. However, there is no effect in the performance of
272 * matrix-vector products, since Trilinos reorganizes the matrix memory
273 * prior to use (in the compress() step).
274 */
275 SparseMatrix(const IndexSet &parallel_partitioning,
276 const MPI_Comm communicator = MPI_COMM_WORLD,
277 const unsigned int n_max_entries_per_row = 0);
278
279 /**
280 * Same as before, but now set the number of non-zero entries in each
281 * matrix row separately. Since we know the number of elements in the
282 * matrix exactly in this case, we can already allocate the right amount
283 * of memory, which makes the creation process including the insertion of
284 * nonzero elements by the respective SparseMatrix::reinit call
285 * considerably faster.
286 */
287 SparseMatrix(const IndexSet &parallel_partitioning,
288 const MPI_Comm communicator,
289 const std::vector<unsigned int> &n_entries_per_row);
290
291 /**
292 * This constructor is similar to the one above, but it now takes two
293 * different IndexSet partitions for row and columns. This interface is
294 * meant to be used for generating rectangular matrices, where the first
295 * index set describes the %parallel partitioning of the degrees of
296 * freedom associated with the matrix rows and the second one the
297 * partitioning of the matrix columns. The second index set specifies the
298 * partitioning of the vectors this matrix is to be multiplied with, not
299 * the distribution of the elements that actually appear in the matrix.
300 *
301 * The parameter @p n_max_entries_per_row defines how much memory will be
302 * allocated for each row. This number does not need to be accurate, as
303 * the structure is reorganized in the compress() call.
304 */
305 SparseMatrix(const IndexSet &row_parallel_partitioning,
306 const IndexSet &col_parallel_partitioning,
307 const MPI_Comm communicator = MPI_COMM_WORLD,
308 const size_type n_max_entries_per_row = 0);
309
310 /**
311 * Same as before, but now set the number of non-zero entries in each
312 * matrix row separately. Since we know the number of elements in the
313 * matrix exactly in this case, we can already allocate the right amount
314 * of memory, which makes the creation process including the insertion of
315 * nonzero elements by the respective SparseMatrix::reinit call
316 * considerably faster.
317 */
318 SparseMatrix(const IndexSet &row_parallel_partitioning,
319 const IndexSet &col_parallel_partitioning,
320 const MPI_Comm communicator,
321 const std::vector<unsigned int> &n_entries_per_row);
322
323 /**
324 * This function is initializes the Trilinos Tpetra matrix according to
325 * the specified @p sparsity_pattern, and also reassigns the matrix rows to
326 * different processes according to the user-supplied index set @p parallel_partitioning and
327 * %parallel communicator. In programs following the style of the tutorial
328 * programs, this function (and the respective call for a rectangular
329 * matrix) are the natural way to initialize the matrix size, its
330 * distribution among the MPI processes (if run in %parallel) as well as
331 * the location of non-zero elements. Trilinos stores the sparsity pattern
332 * internally, so it won't be needed any more after this call, in contrast
333 * to the deal.II own object. The optional argument @p exchange_data can
334 * be used for reinitialization with a sparsity pattern that is not fully
335 * constructed. If the flag is not set, each
336 * processor just sets the elements in the sparsity pattern that belong to
337 * its rows.
338 *
339 * This is a collective operation that needs to be called on all
340 * processors in order to avoid a dead lock.
341 */
342 template <typename SparsityPatternType>
343 std::enable_if_t<
344 !std::is_same_v<SparsityPatternType, dealii::SparseMatrix<double>>>
345 reinit(const IndexSet &parallel_partitioning,
346 const SparsityPatternType &sparsity_pattern,
347 const MPI_Comm communicator = MPI_COMM_WORLD,
348 const bool exchange_data = false);
349
350 /**
351 * This function is similar to the other initialization function above,
352 * but now also reassigns the matrix rows and columns according to two
353 * user-supplied index sets. To be used for rectangular matrices. The
354 * optional argument @p exchange_data can be used for reinitialization
355 * with a sparsity pattern that is not fully constructed. This feature is
356 * only implemented for input sparsity patterns of type
357 * DynamicSparsityPattern.
358 *
359 * This is a collective operation that needs to be called on all
360 * processors in order to avoid a dead lock.
361 */
362 template <typename SparsityPatternType>
363 std::enable_if_t<
364 !std::is_same_v<SparsityPatternType, dealii::SparseMatrix<double>>>
365 reinit(const IndexSet &row_parallel_partitioning,
366 const IndexSet &col_parallel_partitioning,
367 const SparsityPatternType &sparsity_pattern,
368 const MPI_Comm communicator = MPI_COMM_WORLD,
369 const bool exchange_data = false);
370
371 /**
372 * This function initializes the Trilinos matrix using the deal.II sparse
373 * matrix and the entries stored therein. It uses a threshold to copy only
374 * elements with modulus larger than the threshold (so zeros in the
375 * deal.II matrix can be filtered away). In contrast to the other reinit
376 * function with deal.II sparse matrix argument, this function takes a
377 * %parallel partitioning specified by the user instead of internally
378 * generating it.
379 *
380 * The optional parameter <tt>copy_values</tt> decides whether only the
381 * sparsity structure of the input matrix should be used or the matrix
382 * entries should be copied, too.
383 *
384 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
385 * processors in order to avoid a dead lock.
386 */
387 void
388 reinit(const IndexSet &row_parallel_partitioning,
389 const IndexSet &col_parallel_partitioning,
390 const dealii::SparseMatrix<Number> &dealii_sparse_matrix,
391 const MPI_Comm communicator = MPI_COMM_WORLD,
392 const double drop_tolerance = 1e-13,
393 const bool copy_values = true,
394 const dealii::SparsityPattern *use_this_sparsity = nullptr);
395
396 /** @} */
397
398 /**
399 * @name Information on the matrix
400 */
401 /** @{ */
402 /**
403 * Return the number of rows in this matrix.
404 */
405 size_type
406 m() const;
407
408 /**
409 * Return the number of columns in this matrix.
410 */
411 size_type
412 n() const;
413
414
415 /**
416 * Return the local dimension of the matrix, i.e. the number of rows
417 * stored on the present MPI process. For sequential matrices, this number
418 * is the same as m(), but for %parallel matrices it may be smaller.
419 *
420 * To figure out which elements exactly are stored locally, use
421 * local_range().
422 */
423 unsigned int
424 local_size() const;
425
426 /**
427 * Return a pair of indices indicating which rows of this matrix are
428 * stored locally. The first number is the index of the first row stored,
429 * the second the index of the one past the last one that is stored
430 * locally. If this is a sequential matrix, then the result will be the
431 * pair (0,m()), otherwise it will be a pair (i,i+n), where
432 * <tt>n=local_size()</tt>.
433 */
434 std::pair<size_type, size_type>
435 local_range() const;
436
437 /**
438 * Return whether @p index is in the local range or not, see also
439 * local_range().
440 */
441 bool
442 in_local_range(const size_type index) const;
443
444 /**
445 * Return the total number of nonzero elements of this matrix (summed
446 * over all MPI processes).
447 */
448 size_t
449 n_nonzero_elements() const;
450
451 /**
452 * Number of entries in a specific row.
453 */
454 unsigned int
455 row_length(const size_type row) const;
456
457 /**
458 * Return the state of the matrix, i.e., whether compress() needs to be
459 * called after an operation requiring data exchange. A call to compress()
460 * is also needed when the method set() has been called (even when working
461 * in serial).
462 */
463 bool
464 is_compressed() const;
465
466 /**
467 * Return the underlying MPI communicator.
468 */
469 MPI_Comm
470 get_mpi_communicator() const;
471 /** @} */
472
473 /**
474 * @name Modifying entries
475 */
476 /** @{ */
477 /**
478 * This operator assigns a scalar to a matrix. Since this does usually not
479 * make much sense (should we set all matrix entries to this value? Only
480 * the nonzero entries of the sparsity pattern?), this operation is only
481 * allowed if the actual value to be assigned is zero. This operator only
482 * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
483 * all elements of the matrix to zero, but keeps the sparsity pattern
484 * previously used.
485 */
486 SparseMatrix &
487 operator=(const double d);
488
489 /**
490 * Multiply the entire matrix by a fixed factor.
491 */
492 SparseMatrix &
493 operator*=(const Number factor);
494
495 /**
496 * Divide the entire matrix by a fixed factor.
497 */
498 SparseMatrix &
499 operator/=(const Number factor);
500
501 /**
502 * Copy the given (Trilinos) matrix (sparsity pattern and entries).
503 */
504 void
505 copy_from(const SparseMatrix<Number, MemorySpace> &source);
506
507 /**
508 * Add @p value to the element (<i>i,j</i>).
509 * Just as the respective call in deal.II SparseMatrix<Number,
510 * MemorySpace> class. Moreover, if <tt>value</tt> is not a finite number
511 * an exception is thrown.
512 *
513 * @note When add is called on a compressed matrix, the matrix is set
514 * back to an uncompressed state.
515 */
516 void
517 add(const size_type i, const size_type j, const Number value);
518
519 /**
520 * Add an array of values given by <tt>values</tt> in the given global
521 * matrix row at columns specified by col_indices in the sparse matrix.
522 * Just as the respective call in deal.II SparseMatrix<Number,
523 * MemorySpace> class. The optional parameter <tt>elide_zero_values</tt>
524 * can be used to specify whether zero values should be added anyway or
525 * these should be filtered away and only non-zero data is added. The
526 * default value is <tt>true</tt>, i.e., zero values won't be added into
527 * the matrix.
528 *
529 * @note When add is called on a compressed matrix, the matrix is set
530 * back to an uncompressed state.
531 */
532 void
533 add(const size_type row,
534 const size_type n_cols,
535 const size_type *col_indices,
536 const Number *values,
537 const bool elide_zero_values = true,
538 const bool col_indices_are_sorted = false);
539
540 /**
541 * Add <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
542 * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. If the
543 * sparsity pattern of the calling matrix does not contain all the
544 * elements in the sparsity pattern of the input matrix, this function
545 * will throw an exception.
546 */
547 void
548 add(const Number factor, const SparseMatrix<Number, MemorySpace> &matrix);
549
550 /**
551 * Set the element (<i>i,j</i>) to @p value.
552 *
553 * This function is able to insert new elements into the matrix as long as
554 * compress() has not been called, so the sparsity pattern will be
555 * extended. When compress() is called for the first time (or in case the
556 * matrix is initialized from a sparsity pattern), no new elements can be
557 * added and an insertion of elements at positions which have not been
558 * initialized will throw an exception.
559 *
560 * For the case that the matrix is constructed without a sparsity pattern
561 * and new matrix entries are added on demand, please note the following
562 * behavior imposed by the underlying Tpetra::CrsMatrix data structure:
563 * If the same matrix entry is inserted more than once, the matrix entries
564 * will be added upon calling compress() (since Tpetra does not track
565 * values to the same entry before the final compress() is called), even
566 * if VectorOperation::insert is specified as argument to compress(). In
567 * the case you cannot make sure that matrix entries are only set once,
568 * initialize the matrix with a sparsity pattern to fix the matrix
569 * structure before inserting elements.
570 */
571 void
572 set(const size_type i, const size_type j, const Number value);
573
574 /**
575 * Set all elements given in a FullMatrix<double> into the sparse matrix
576 * locations given by <tt>indices</tt>. In other words, this function
577 * writes the elements in <tt>full_matrix</tt> into the calling matrix,
578 * using the local-to-global indexing specified by <tt>indices</tt> for
579 * both the rows and the columns of the matrix. This function assumes a
580 * quadratic sparse matrix and a quadratic full_matrix, the usual
581 * situation in FE calculations.
582 *
583 * This function is able to insert new elements into the matrix as long as
584 * compress() has not been called, so the sparsity pattern will be
585 * extended. After compress() has been called for the first time or the
586 * matrix has been initialized from a sparsity pattern, extending the
587 * sparsity pattern is no longer possible and an insertion of elements at
588 * positions which have not been initialized will throw an exception.
589 *
590 * The optional parameter <tt>elide_zero_values</tt> can be used to
591 * specify whether zero values should be inserted anyway or they should be
592 * filtered away. The default value is <tt>false</tt>, i.e., even zero
593 * values are inserted/replaced.
594 *
595 * For the case that the matrix is constructed without a sparsity pattern
596 * and new matrix entries are added on demand, please note the following
597 * behavior imposed by the underlying Tpetra::CrsMatrix data structure:
598 * If the same matrix entry is inserted more than once, the matrix entries
599 * will be added upon calling compress() (since Epetra does not track
600 * values to the same entry before the final compress() is called), even
601 * if VectorOperation::insert is specified as argument to compress(). In
602 * the case you cannot make sure that matrix entries are only set once,
603 * initialize the matrix with a sparsity pattern to fix the matrix
604 * structure before inserting elements.
605 */
606 void
607 set(const std::vector<size_type> &indices,
608 const FullMatrix<Number> &full_matrix,
609 const bool elide_zero_values = false);
610
611 /**
612 * Same function as before, but now including the possibility to use
613 * rectangular full_matrices and different local-to-global indexing on
614 * rows and columns, respectively.
615 */
616 void
617 set(const std::vector<size_type> &row_indices,
618 const std::vector<size_type> &col_indices,
619 const FullMatrix<Number> &full_matrix,
620 const bool elide_zero_values = false);
621
622 /**
623 * Set several elements in the specified row of the matrix with column
624 * indices as given by <tt>col_indices</tt> to the respective value.
625 *
626 * This function is able to insert new elements into the matrix as long as
627 * compress() has not been called, so the sparsity pattern will be
628 * extended. After compress() has been called for the first time or the
629 * matrix has been initialized from a sparsity pattern, extending the
630 * sparsity pattern is no longer possible and an insertion of elements at
631 * positions which have not been initialized will throw an exception.
632 *
633 * The optional parameter <tt>elide_zero_values</tt> can be used to
634 * specify whether zero values should be inserted anyway or they should be
635 * filtered away. The default value is <tt>false</tt>, i.e., even zero
636 * values are inserted/replaced.
637 *
638 * For the case that the matrix is constructed without a sparsity pattern
639 * and new matrix entries are added on demand, please note the following
640 * behavior imposed by the underlying Tpetra::CrsMatrix data structure:
641 * If the same matrix entry is inserted more than once, the matrix entries
642 * will be added upon calling compress() (since Epetra does not track
643 * values to the same entry before the final compress() is called), even
644 * if VectorOperation::insert is specified as argument to compress(). In
645 * the case you cannot make sure that matrix entries are only set once,
646 * initialize the matrix with a sparsity pattern to fix the matrix
647 * structure before inserting elements.
648 */
649 void
650 set(const size_type row,
651 const std::vector<size_type> &col_indices,
652 const std::vector<Number> &values,
653 const bool elide_zero_values = false);
654
655 /**
656 * Set several elements to values given by <tt>values</tt> in a given row
657 * in columns given by col_indices into the sparse matrix.
658 *
659 * This function is able to insert new elements into the matrix as long as
660 * compress() has not been called, so the sparsity pattern will be
661 * extended. After compress() has been called for the first time or the
662 * matrix has been initialized from a sparsity pattern, extending the
663 * sparsity pattern is no longer possible and an insertion of elements at
664 * positions which have not been initialized will throw an exception.
665 *
666 * The optional parameter <tt>elide_zero_values</tt> can be used to
667 * specify whether zero values should be inserted anyway or they should be
668 * filtered away. The default value is <tt>false</tt>, i.e., even zero
669 * values are inserted/replaced.
670 *
671 * For the case that the matrix is constructed without a sparsity pattern
672 * and new matrix entries are added on demand, please note the following
673 * behavior imposed by the underlying Tpetra::CrsMatrix data structure:
674 * If the same matrix entry is inserted more than once, the matrix entries
675 * will be added upon calling compress() (since Epetra does not track
676 * values to the same entry before the final compress() is called), even
677 * if VectorOperation::insert is specified as argument to compress(). In
678 * the case you cannot make sure that matrix entries are only set once,
679 * initialize the matrix with a sparsity pattern to fix the matrix
680 * structure before inserting elements.
681 */
682 void
683 set(const size_type row,
684 const size_type n_cols,
685 const size_type *col_indices,
686 const Number *values,
687 const bool elide_zero_values = false);
688
689 /**
690 * Remove all elements from this <tt>row</tt> by setting them to zero. The
691 * function does not modify the number of allocated nonzero entries, it
692 * only sets the entries to zero.
693 *
694 * This operation is used in eliminating constraints (e.g. due to hanging
695 * nodes) and makes sure that we can write this modification to the matrix
696 * without having to read entries (such as the locations of non-zero
697 * elements) from it &mdash; without this operation, removing constraints
698 * on %parallel matrices is a rather complicated procedure.
699 *
700 * The second parameter can be used to set the diagonal entry of this row
701 * to a value different from zero. The default is to set it to zero.
702 *
703 * @note If the matrix is stored in parallel across multiple processors
704 * using MPI, this function only touches rows that are locally stored and
705 * simply ignores all other row indices. Further, in the context of
706 * parallel computations, you will get into trouble if you clear a row
707 * while other processors still have pending writes or additions into the
708 * same row. In other words, if another processor still wants to add
709 * something to an element of a row and you call this function to zero out
710 * the row, then the next time you call compress() may add the remote
711 * value to the zero you just created. Consequently, you will want to call
712 * compress() after you made the last modifications to a matrix and before
713 * starting to clear rows.
714 */
715 void
716 clear_row(const size_type row, const Number new_diag_value = 0);
717
718 /**
719 * Same as clear_row(), except that it works on a number of rows at once.
720 *
721 * The second parameter can be used to set the diagonal entries of all
722 * cleared rows to something different from zero. Note that all of these
723 * diagonal entries get the same value -- if you want different values for
724 * the diagonal entries, you have to set them by hand.
725 *
726 * @note If the matrix is stored in parallel across multiple processors
727 * using MPI, this function only touches rows that are locally stored and
728 * simply ignores all other row indices. Further, in the context of
729 * parallel computations, you will get into trouble if you clear a row
730 * while other processors still have pending writes or additions into the
731 * same row. In other words, if another processor still wants to add
732 * something to an element of a row and you call this function to zero out
733 * the row, then the next time you call compress() may add the remote
734 * value to the zero you just created. Consequently, you will want to call
735 * compress() after you made the last modifications to a matrix and before
736 * starting to clear rows.
737 */
738 void
739 clear_rows(const ArrayView<const size_type> &rows,
740 const Number new_diag_value = 0);
741
742 /**
743 * Release all memory and return to a state just like after having called
744 * the default constructor.
745 *
746 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
747 * processors in order to avoid a dead lock.
748 */
749 void
750 clear();
751
752 /** @} */
753 /**
754 * @name Entry Access
755 */
756 /** @{ */
757
758 /**
759 * Return the value of the entry (<i>i,j</i>). This may be an expensive
760 * operation and you should always take care where to call this function.
761 * As in the deal.II sparse matrix class, we throw an exception if the
762 * respective entry doesn't exist in the sparsity pattern of this class,
763 * which is requested from Trilinos. Moreover, an exception will be thrown
764 * when the requested element is not saved on the calling process.
765 */
766 Number
767 operator()(const size_type i, const size_type j) const;
768
769 /**
770 * Return the value of the matrix entry (<i>i,j</i>). If this entry does
771 * not exist in the sparsity pattern, then zero is returned. While this
772 * may be convenient in some cases, note that it is simple to write
773 * algorithms that are slow compared to an optimal solution, since the
774 * sparsity of the matrix is not used. On the other hand, if you want to
775 * be sure the entry exists, you should use operator() instead.
776 *
777 * The lack of error checking in this function can also yield surprising
778 * results if you have a parallel matrix. In that case, just because you
779 * get a zero result from this function does not mean that either the
780 * entry does not exist in the sparsity pattern or that it does but has a
781 * value of zero. Rather, it could also be that it simply isn't stored on
782 * the current processor; in that case, it may be stored on a different
783 * processor, and possibly so with a nonzero value.
784 */
785 Number
786 el(const size_type i, const size_type j) const;
787
788 /**
789 * Return the main diagonal element in the <i>i</i>th row. This function
790 * throws an error if the matrix is not quadratic and it also throws an
791 * error if <i>(i,i)</i> is not element of the local matrix.
792 */
793 Number
794 diag_element(const size_type i) const;
795
796 /** @} */
797 /**
798 * @name Multiplications
799 */
800 /** @{ */
801 /*
802 * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
803 * being this matrix.
804 *
805 * Source and destination must not be the same vector.
806 *
807 * The vector @p dst has to be initialized with the same IndexSet that was
808 * used for the row indices of the matrix and the vector @p src has to be
809 * initialized with the same IndexSet that was used for the column indices
810 * of the matrix.
811 */
812 template <typename InputVectorType>
813 void
814 vmult(InputVectorType &dst, const InputVectorType &src) const;
815
816 /*
817 * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
818 * <i>M</i> being this matrix. This function does the same as vmult() but
819 * takes the transposed matrix.
820 *
821 * Source and destination must not be the same vector.
822 */
823 template <typename InputVectorType>
824 void
825 Tvmult(InputVectorType &dst, const InputVectorType &src) const;
826
827 /**
828 * Adding matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
829 * with <i>M</i> being this matrix.
830 *
831 * Source and destination must not be the same vector.
832 */
833 template <typename InputVectorType>
834 void
835 vmult_add(InputVectorType &dst, const InputVectorType &src) const;
836
837 /**
838 * Adding matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
839 * <i>dst</i> with <i>M</i> being this matrix. This function does the same
840 * as vmult_add() but takes the transposed matrix.
841 *
842 * Source and destination must not be the same vector.
843 */
844 template <typename InputVectorType>
845 void
846 Tvmult_add(InputVectorType &dst, const InputVectorType &src) const;
847
848 /**
849 * Return the square of the norm of the vector $v$ with respect to the
850 * norm induced by this matrix, i.e., $\left(v,Mv\right)$. This is useful,
851 * e.g. in the finite element context, where the $L_2$ norm of a function
852 * equals the matrix norm with respect to the @ref GlossMassMatrix "mass matrix" of the vector
853 * representing the nodal values of the finite element function.
854 *
855 * Obviously, the matrix needs to be quadratic for this operation.
856 *
857 * The implementation of this function is not as efficient as the one in
858 * the @p SparseMatrix class used in deal.II (i.e. the original one, not
859 * the Trilinos wrapper class) since Trilinos doesn't support this
860 * operation and needs a temporary vector.
861 *
862 * The vector has to be initialized with the same IndexSet the matrix
863 * was initialized with.
864 *
865 * In case of a localized Vector, this function will only work when
866 * running on one processor, since the matrix object is inherently
867 * distributed. Otherwise, an exception will be thrown.
868 */
869 Number
870 matrix_norm_square(const Vector<Number, MemorySpace> &v) const;
871
872 /**
873 * Compute the matrix scalar product $\left(u,Mv\right)$.
874 *
875 * The implementation of this function is not as efficient as the one in
876 * the @p SparseMatrix class used in deal.II (i.e. the original one, not
877 * the Trilinos wrapper class) since Trilinos doesn't support this
878 * operation and needs a temporary vector.
879 *
880 * The vector @p u has to be initialized with the same IndexSet that
881 * was used for the row indices of the matrix and the vector @p v has
882 * to be initialized with the same IndexSet that was used for the
883 * column indices of the matrix.
884 *
885 * In case of a localized Vector, this function will only work when
886 * running on one processor, since the matrix object is inherently
887 * distributed. Otherwise, an exception will be thrown.
888 *
889 * This function is only implemented for square matrices.
890 */
891 Number
892 matrix_scalar_product(const Vector<Number, MemorySpace> &u,
893 const Vector<Number, MemorySpace> &v) const;
894
895 /**
896 * Compute the residual of an equation <i>Mx=b</i>, where the residual is
897 * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
898 * <i>l<sub>2</sub></i> norm of the residual vector is returned.
899 *
900 * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
901 *
902 * The vectors @p dst and @p b have to be initialized with the same
903 * IndexSet that was used for the row indices of the matrix and the vector
904 * @p x has to be initialized with the same IndexSet that was used for the
905 * column indices of the matrix.
906 *
907 * In case of a localized Vector, this function will only work when
908 * running on one processor, since the matrix object is inherently
909 * distributed. Otherwise, an exception will be thrown.
910 */
911 Number
912 residual(Vector<Number, MemorySpace> &dst,
913 const Vector<Number, MemorySpace> &x,
914 const Vector<Number, MemorySpace> &b) const;
915
916 /** @} */
917
918 /**
919 * @name Matrix norms
920 */
921 /** @{ */
922
923 /**
924 * Return the frobenius norm of the matrix, i.e. the square root of the
925 * sum of squares of all entries in the matrix.
926 */
927 Number
928 frobenius_norm() const;
929
930 /** @} */
931
932 /**
933 * @name Mixed Stuff
934 */
935 /** @{ */
936 /**
937 * Print the matrix to the given stream, using the format (line,col)
938 * value, i.e. one nonzero entry of the matrix per line. The optional flag
939 * outputs the sparsity pattern in Trilinos style, where the data is
940 * sorted according to the processor number when printed to the stream, as
941 * well as a summary of the matrix like the global size.
942 */
943 void
944 print(std::ostream &out,
945 const bool print_detailed_trilinos_information = false) const;
946
947 /**
948 * This command does two things:
949 * <ul>
950 * <li> If the matrix was initialized without a sparsity pattern, elements
951 * have been added manually using the set() command. When this process is
952 * completed, a call to compress() reorganizes the internal data
953 * structures (sparsity pattern) so that a fast access to data is possible
954 * in matrix-vector products.
955 * <li> If the matrix structure has already been fixed (either by
956 * initialization with a sparsity pattern or by calling compress() during
957 * the setup phase), this command does the %parallel exchange of data.
958 * This is necessary when we perform assembly on more than one (MPI)
959 * process, because then some non-local row data will accumulate on nodes
960 * that belong to the current's processor element, but are actually held
961 * by another. This command is usually called after all elements have been
962 * traversed.
963 * </ul>
964 *
965 * In both cases, this function compresses the data structures and allows
966 * the resulting matrix to be used in all other operations like matrix-
967 * vector products. This is a collective operation, i.e., it needs to be
968 * run on all processors when used in %parallel.
969 *
970 * See
971 * @ref GlossCompress "Compressing distributed objects"
972 * for more information.
973 *
974 * @note The @p operation can be safely omitted, as that parameter is not
975 * used at all and is only present to ensure compatibility with other
976 * SparseMatrix classes.
977 */
978 void
979 compress(VectorOperation::values operation);
980
981 /**
982 * This function must be called to allow for changes to the structure
983 * of the matrix again after compress() was called.
984 * Once you are done modifying the matrix structure, you must call
985 * compress() again.
986 */
987 void
988 resume_fill();
989
990 /**
991 * Return a const reference to the underlying Trilinos
992 * <a
993 * href="https://docs.trilinos.org/dev/packages/tpetra/doc/html/classTpetra_1_1CrsMatrix.html">Tpetra::CrsMatrix</a>
994 * class.
995 */
996 const TpetraTypes::MatrixType<Number, MemorySpace> &
997 trilinos_matrix() const;
998
999 /**
1000 * Return a (modifiable) reference to the underlying Trilinos
1001 * <a
1002 * href="https://docs.trilinos.org/dev/packages/tpetra/doc/html/classTpetra_1_1CrsMatrix.html">Tpetra::CrsMatrix</a>
1003 * class.
1004 */
1005 TpetraTypes::MatrixType<Number, MemorySpace> &
1006 trilinos_matrix();
1007
1008 /**
1009 * Return a const
1010 * <a
1011 * href="https://docs.trilinos.org/dev/packages/teuchos/doc/html/classTeuchos_1_1RCP.html">Teuchos::RCP</a>
1012 * to the underlying Trilinos
1013 * <a
1014 * href="https://docs.trilinos.org/dev/packages/tpetra/doc/html/classTpetra_1_1CrsMatrix.html">Tpetra::CrsMatrix</a>
1015 * class.
1016 */
1017 Teuchos::RCP<const TpetraTypes::MatrixType<Number, MemorySpace>>
1018 trilinos_rcp() const;
1019
1020 /**
1021 * Return a (modifiable)
1022 * <a
1023 * href="https://docs.trilinos.org/dev/packages/teuchos/doc/html/classTeuchos_1_1RCP.html">Teuchos::RCP</a>
1024 * to the underlying Trilinos
1025 * <a
1026 * href="https://docs.trilinos.org/dev/packages/tpetra/doc/html/classTpetra_1_1CrsMatrix.html">Tpetra::CrsMatrix</a>
1027 * class.
1028 */
1029 Teuchos::RCP<TpetraTypes::MatrixType<Number, MemorySpace>>
1030 trilinos_rcp();
1031 /** @} */
1032
1033 /**
1034 * @name Partitioners
1035 */
1036 /** @{ */
1037
1038 /**
1039 * Return the partitioning of the domain space of this matrix, i.e., the
1040 * partitioning of the vectors this matrix has to be multiplied with.
1041 */
1042 IndexSet
1043 locally_owned_domain_indices() const;
1044
1045 /**
1046 * Return the partitioning of the range space of this matrix, i.e., the
1047 * partitioning of the vectors that are result from matrix-vector
1048 * products.
1049 */
1050 IndexSet
1051 locally_owned_range_indices() const;
1052
1053 /** @} */
1054
1055 /**
1056 * @name Iterators
1057 */
1058 /** @{ */
1059
1060 /**
1061 * Return an iterator pointing to the first element of the matrix.
1062 *
1063 * The elements accessed by iterators within each row are ordered in the
1064 * way in which Trilinos stores them, though the implementation guarantees
1065 * that all elements of one row are accessed before the elements of the
1066 * next row. If your algorithm relies on visiting elements within one row,
1067 * you will need to consult with the Trilinos documentation on the order
1068 * in which it stores data. It is, however, generally not a good and
1069 * long-term stable idea to rely on the order in which receive elements if
1070 * you iterate over them.
1071 *
1072 * When you iterate over the elements of a parallel matrix, you will only
1073 * be able to access the locally owned rows. (You can access the other
1074 * rows as well, but they will look empty.) In that case, you probably
1075 * want to call the begin() function that takes the row as an argument to
1076 * limit the range of elements to loop over.
1077 */
1078 const_iterator
1079 begin() const;
1080
1081 /**
1082 * Like the function above, but for non-const matrices.
1083 */
1084 iterator
1085 begin();
1086
1087 /**
1088 * Return an iterator pointing the element past the last one of this
1089 * matrix.
1090 */
1091 const_iterator
1092 end() const;
1093
1094 /**
1095 * Like the function above, but for non-const matrices.
1096 */
1097 iterator
1098 end();
1099
1100 /**
1101 * Return an iterator pointing to the first element of row @p r.
1102 *
1103 * Note that if the given row is empty, i.e. does not contain any nonzero
1104 * entries, then the iterator returned by this function equals
1105 * <tt>end(r)</tt>. The returned iterator may not be dereferenceable in
1106 * that case if neither row @p r nor any of the following rows contain any
1107 * nonzero entries.
1108 *
1109 * The elements accessed by iterators within each row are ordered in the
1110 * way in which Trilinos stores them, though the implementation guarantees
1111 * that all elements of one row are accessed before the elements of the
1112 * next row. If your algorithm relies on visiting elements within one row,
1113 * you will need to consult with the Trilinos documentation on the order
1114 * in which it stores data. It is, however, generally not a good and
1115 * long-term stable idea to rely on the order in which receive elements if
1116 * you iterate over them.
1117 *
1118 * @note When you access the elements of a parallel matrix, you can only
1119 * access the elements of rows that are actually stored locally. (You can
1120 * access the other rows as well, but they will look empty.) Even then, if
1121 * another processor has since written into, or added to, an element of
1122 * the matrix that is stored on the current processor, then you will still
1123 * see the old value of this entry unless you have called compress()
1124 * between modifying the matrix element on the remote processor and
1125 * accessing it on the current processor. See the documentation of the
1126 * compress() function for more information.
1127 */
1128 const_iterator
1129 begin(const size_type r) const;
1130
1131 /**
1132 * Like the function above, but for non-const matrices.
1133 */
1134 iterator
1135 begin(const size_type r);
1136
1137 /**
1138 * Return an iterator pointing the element past the last one of row @p r ,
1139 * or past the end of the entire sparsity pattern if none of the rows
1140 * after @p r contain any entries at all.
1141 *
1142 * Note that the end iterator is not necessarily dereferenceable. This is
1143 * in particular the case if it is the end iterator for the last row of a
1144 * matrix.
1145 */
1146 const_iterator
1147 end(const size_type r) const;
1148
1149 /**
1150 * Like the function above, but for non-const matrices.
1151 */
1152 iterator
1153 end(const size_type r);
1154
1155 /** @} */
1156 /**
1157 * @addtogroup Exceptions
1158 */
1159 /** @{ */
1160
1161 /**
1162 * Exception
1163 */
1164 DeclException0(ExcMatrixNotCompressed);
1165
1166 /**
1167 * Exception
1168 */
1169 DeclExceptionMsg(
1170 ExcSourceEqualsDestination,
1171 "You are attempting an operation on two vectors that "
1172 "are the same object, but the operation requires that the "
1173 "two objects are in fact different.");
1174
1175 /*
1176 * Exception
1177 */
1178 DeclExceptionMsg(ExcColMapMismatch,
1179 "The column partitioning of a matrix does not match "
1180 "the partitioning of a vector you are trying to "
1181 "multiply it with. Are you multiplying the "
1182 "matrix with a vector that has ghost elements?");
1183
1184 /*
1185 * Exception
1186 */
1187 DeclExceptionMsg(ExcDomainMapMismatch,
1188 "The row partitioning of a matrix does not match "
1189 "the partitioning of a vector you are trying to "
1190 "put the result of a matrix-vector product in. "
1191 "Are you trying to put the product of the "
1192 "matrix with a vector into a vector that has "
1193 "ghost elements?");
1194
1195 /**
1196 * Exception
1197 */
1198 DeclException2(ExcInvalidIndex,
1199 size_type,
1200 size_type,
1201 << "The entry with index <" << arg1 << ',' << arg2
1202 << "> does not exist.");
1203
1204 /**
1205 * Exception
1206 */
1207 DeclException4(ExcAccessToNonLocalElement,
1208 size_type,
1209 size_type,
1210 size_type,
1211 size_type,
1212 << "You tried to access element (" << arg1 << '/' << arg2
1213 << ')'
1214 << " of a distributed matrix, but only rows in range ["
1215 << arg3 << ',' << arg4
1216 << "] are stored locally and can be accessed.");
1217
1218 /** @} */
1219
1220 private:
1221 /**
1222 * Helper function for operator() and el().
1223 */
1224 Number
1225 element(const size_type i, const size_type j, const bool no_error) const;
1226
1227 /**
1228 * Pointer to the user-supplied Tpetra Trilinos mapping of the matrix
1229 * columns that assigns parts of the matrix to the individual processes.
1230 *
1231 * @note The Trilinos matrix is row-oriented, and the row_space_map is
1232 * therefore stored in the Trilinos matrix itself. The additional
1233 * information from the column space map is used to speed up the
1234 * assembly process.
1235 */
1236 Teuchos::RCP<TpetraTypes::MapType<MemorySpace>> column_space_map;
1237
1238 /**
1239 * A sparse matrix object in Trilinos to be used for finite element based
1240 * problems which allows for assembling into non-local elements. The
1241 * actual type, a sparse matrix, is set in the constructor.
1242 */
1243 Teuchos::RCP<TpetraTypes::MatrixType<Number, MemorySpace>> matrix;
1244
1245 /**
1246 * A boolean variable to hold information on whether the matrix is
1247 * fill complete or if the matrix is in compute mode.
1248 */
1249 bool compressed;
1250
1251 /**
1252 * For some matrix storage formats, in particular for the PETSc
1253 * distributed blockmatrices, set and add operations on individual
1254 * elements can not be freely mixed. Rather, one has to synchronize
1255 * operations when one wants to switch from setting elements to adding to
1256 * elements. BlockMatrixBase automatically synchronizes the access by
1257 * calling this helper function for each block. This function ensures
1258 * that the matrix is in a state that allows adding elements; if it
1259 * previously already was in this state, the function does nothing.
1260 *
1261 * This function is called from BlockMatrixBase.
1262 */
1263 void
1264 prepare_add();
1265
1266 /**
1267 * Same as prepare_add() but prepare the matrix for setting elements if
1268 * the representation of elements in this class requires such an
1269 * operation.
1270 *
1271 * This function is called from BlockMatrixBase.
1272 */
1273 void
1274 prepare_set();
1275
1276 // To allow calling protected prepare_add() and prepare_set().
1277 friend class BlockMatrixBase<SparseMatrix<Number, MemorySpace>>;
1278 }; // class SparseMatrix
1279
1280 /**
1281 * Iterators for Trilinos matrices
1282 */
1283 namespace SparseMatrixIterators
1284 {
1285 /**
1286 * Exception
1287 */
1288 DeclException0(ExcBeyondEndOfMatrix);
1289
1290 /**
1291 * Handling of indices for both constant and non constant Accessor objects
1292 *
1293 * For a regular dealii::SparseMatrix, we would use an accessor for the
1294 * sparsity pattern. For Trilinos matrices, this does not seem so simple,
1295 * therefore, we write a little base class here.
1296 */
1297 template <typename Number, typename MemorySpace>
1298 class AccessorBase
1299 {
1300 public:
1301 /**
1302 * Declare the type for container size.
1303 */
1304 using size_type = dealii::types::global_dof_index;
1305
1306 /**
1307 * Constructor.
1308 */
1309 AccessorBase(SparseMatrix<Number, MemorySpace> *matrix,
1310 const size_type row,
1311 const size_type index);
1312
1313 /**
1314 * Row number of the element represented by this object.
1315 */
1316 size_type
1317 row() const;
1318
1319 /**
1320 * Index in row of the element represented by this object.
1321 */
1322 size_type
1323 index() const;
1324
1325 /**
1326 * Column number of the element represented by this object.
1327 */
1328 size_type
1329 column() const;
1330
1331 protected:
1332 /**
1333 * Pointer to the matrix object. This object should be handled as a
1334 * const pointer or non-const by the appropriate derived classes. In
1335 * order to be able to implement both, it is not const here, so handle
1336 * with care!
1337 */
1338 mutable SparseMatrix<Number, MemorySpace> *matrix;
1339 /**
1340 * Current row number.
1341 */
1342 size_type a_row;
1343
1344 /**
1345 * Current index in row.
1346 */
1347 size_type a_index;
1348
1349 /**
1350 * Discard the old row caches (they may still be used by other
1351 * accessors) and generate new ones for the row pointed to presently by
1352 * this accessor.
1353 */
1354 void
1355 visit_present_row();
1356
1357 /**
1358 * Cache where we store the column indices of the present row. This is
1359 * necessary, since Trilinos makes access to the elements of its
1360 * matrices rather hard, and it is much more efficient to copy all
1361 * column entries of a row once when we enter it than repeatedly asking
1362 * Trilinos for individual ones. This also makes some sense since it is
1363 * likely that we will access them sequentially anyway.
1364 *
1365 * In order to make copying of iterators/accessor of acceptable
1366 * performance, we keep a shared pointer to these entries so that more
1367 * than one accessor can access this data if necessary.
1368 */
1369 std::shared_ptr<std::vector<dealii::types::signed_global_dof_index>>
1370 colnum_cache;
1371
1372 /**
1373 * Cache for the values of this row.
1374 */
1375 std::shared_ptr<std::vector<Number>> value_cache;
1376
1377 private:
1378 friend class Iterator<Number, MemorySpace, false>;
1379 friend class Iterator<Number, MemorySpace, true>;
1380 };
1381
1382 /**
1383 * General template for sparse matrix accessors. The first template
1384 * argument denotes the underlying numeric type, the second the constness
1385 * of the matrix.
1386 *
1387 * The general template is not implemented, only the specializations for
1388 * the two possible values of the second template argument. Therefore, the
1389 * interface listed here only serves as a template provided since doxygen
1390 * does not link the specializations.
1391 */
1392 template <typename Number, typename MemorySpace, bool Constness>
1393 class Accessor : public AccessorBase<Number, MemorySpace>
1394 {
1395 /**
1396 * Value of this matrix entry.
1397 */
1398 Number
1399 value() const;
1400
1401 /**
1402 * Value of this matrix entry.
1403 */
1404 Number &
1405 value();
1406 };
1407
1408 /**
1409 * The specialization for a const Accessor.
1410 */
1411 template <typename Number, typename MemorySpace>
1412 class Accessor<Number, MemorySpace, true>
1413 : public AccessorBase<Number, MemorySpace>
1414 {
1415 public:
1416 /**
1417 * Typedef for the type (including constness) of the matrix to be used
1418 * here.
1419 */
1420 using MatrixType = const SparseMatrix<Number, MemorySpace>;
1421
1422 /**
1423 * Typedef for the size type of the matrix to be used here.
1424 */
1425 using size_type = typename AccessorBase<Number, MemorySpace>::size_type;
1426
1427 /**
1428 * Constructor. Since we use accessors only for read access, a const
1429 * matrix pointer is sufficient.
1430 */
1431 Accessor(MatrixType *matrix,
1432 const size_type row,
1433 const size_type index);
1434
1435 /**
1436 * Copy constructor to get from a const or non-const accessor to a const
1437 * accessor.
1438 */
1439 template <bool Other>
1440 Accessor(const Accessor<Number, MemorySpace, Other> &a);
1441
1442 /**
1443 * Value of this matrix entry.
1444 */
1445 Number
1446 value() const;
1447 };
1448
1449 /**
1450 * The specialization for a mutable Accessor.
1451 */
1452 template <typename Number, typename MemorySpace>
1453 class Accessor<Number, MemorySpace, false>
1454 : public AccessorBase<Number, MemorySpace>
1455 {
1456 class Reference
1457 {
1458 public:
1459 /**
1460 * Constructor.
1461 */
1462 Reference(const Accessor<Number, MemorySpace, false> &accessor);
1463
1464 /**
1465 * Conversion operator to the data type of the matrix.
1466 */
1467 operator Number() const;
1468
1469 /**
1470 * Set the element of the matrix we presently point to to @p n.
1471 */
1472 const Reference &
1473 operator=(const Number n) const;
1474
1475 /**
1476 * Add @p n to the element of the matrix we presently point to.
1477 */
1478 const Reference &
1479 operator+=(const Number n) const;
1480
1481 /**
1482 * Subtract @p n from the element of the matrix we presently point to.
1483 */
1484 const Reference &
1485 operator-=(const Number n) const;
1486
1487 /**
1488 * Multiply the element of the matrix we presently point to by @p n.
1489 */
1490 const Reference &
1491 operator*=(const Number n) const;
1492
1493 /**
1494 * Divide the element of the matrix we presently point to by @p n.
1495 */
1496 const Reference &
1497 operator/=(const Number n) const;
1498
1499 private:
1500 /**
1501 * Pointer to the accessor that denotes which element we presently
1502 * point to.
1503 */
1504 Accessor &accessor;
1505 };
1506
1507 public:
1508 /**
1509 * Typedef for the type (including constness) of the matrix to be used
1510 * here.
1511 */
1512 using MatrixType = SparseMatrix<Number, MemorySpace>;
1513
1514 /**
1515 * Typedef for the size type of the matrix to be used here.
1516 */
1517 using size_type = typename AccessorBase<Number, MemorySpace>::size_type;
1518
1519 /**
1520 * Constructor. Since we use accessors only for read access, a const
1521 * matrix pointer is sufficient.
1522 */
1523 Accessor(MatrixType *matrix,
1524 const size_type row,
1525 const size_type index);
1526
1527 /**
1528 * Value of this matrix entry.
1529 */
1530 Reference
1531 value() const;
1532
1533 private:
1534 // Make Reference object a friend.
1535 friend class Reference;
1536 };
1537
1538 /**
1539 * This class acts as an iterator walking over the elements of Trilinos
1540 * matrices. The implementation of this class is similar to the one for
1541 * PETSc matrices.
1542 *
1543 * Note that Trilinos stores the elements within each row in ascending
1544 * order. This is opposed to the deal.II sparse matrix style where the
1545 * diagonal element (if it exists) is stored before all other values, and
1546 * the PETSc sparse matrices, where one can't guarantee a certain order of
1547 * the elements.
1548 *
1549 * @ingroup TpetraWrappers
1550 */
1551 template <typename Number, typename MemorySpace, bool Constness>
1552 class Iterator
1553 {
1554 public:
1555 /**
1556 * Declare type for container size.
1557 */
1558 using size_type = dealii::types::global_dof_index;
1559
1560 /**
1561 * A type that denotes what data types is used to express the difference
1562 * between two iterators.
1563 */
1564 using difference_type = dealii::types::global_dof_index;
1565
1566 /**
1567 * An alias for the type you get when you dereference an iterator of the
1568 * current kind.
1569 */
1570 using value_type = Number;
1571
1572 /**
1573 * Typedef for the matrix type (including constness) we are to operate
1574 * on.
1575 */
1576 using MatrixType =
1577 typename Accessor<Number, MemorySpace, Constness>::MatrixType;
1578
1579 /**
1580 * Constructor. Create an iterator into the matrix @p matrix for the
1581 * given row and the index within it.
1582 */
1583 Iterator(MatrixType *matrix,
1584 const size_type row,
1585 const size_type index);
1586
1587 /**
1588 * Copy constructor with optional change of constness.
1589 */
1590 template <bool Other>
1591 Iterator(const Iterator<Number, MemorySpace, Other> &other);
1592
1593 /**
1594 * Prefix increment.
1595 */
1596 Iterator<Number, MemorySpace, Constness> &
1597 operator++();
1598
1599 /**
1600 * Postfix increment.
1601 */
1602 Iterator<Number, MemorySpace, Constness>
1603 operator++(int);
1604
1605 /**
1606 * Dereferencing operator.
1607 */
1608 const Accessor<Number, MemorySpace, Constness> &
1609 operator*() const;
1610
1611 /**
1612 * Dereferencing operator.
1613 */
1614 const Accessor<Number, MemorySpace, Constness> *
1615 operator->() const;
1616
1617 /**
1618 * Comparison. True, if both iterators point to the same matrix
1619 * position.
1620 */
1621 template <bool OtherConstness>
1622 bool
1623 operator==(const Iterator<Number, MemorySpace, OtherConstness> &) const;
1624
1625 /**
1626 * Inverse of <tt>==</tt>.
1627 */
1628 template <bool OtherConstness>
1629 bool
1630 operator!=(const Iterator<Number, MemorySpace, OtherConstness> &) const;
1631
1632 /**
1633 * Comparison operator. Result is true if either the first row number is
1634 * smaller or if the row numbers are equal and the first index is
1635 * smaller.
1636 */
1637 template <bool OtherConstness>
1638 bool
1639 operator<(const Iterator<Number, MemorySpace, OtherConstness> &) const;
1640
1641 /**
1642 * Comparison operator. The opposite of the previous operator
1643 */
1644 template <bool OtherConstness>
1645 bool
1646 operator>(const Iterator<Number, MemorySpace, OtherConstness> &) const;
1647
1648 /**
1649 * Exception
1650 */
1651 DeclException2(ExcInvalidIndexWithinRow,
1652 size_type,
1653 size_type,
1654 << "Attempt to access element " << arg2 << " of row "
1655 << arg1 << " which doesn't have that many elements.");
1656
1657 private:
1658 /**
1659 * Store an object of the accessor class.
1660 */
1661 Accessor<Number, MemorySpace, Constness> accessor;
1662
1663 friend class Iterator<Number, MemorySpace, true>;
1664 friend class Iterator<Number, MemorySpace, false>;
1665 };
1666 } // namespace SparseMatrixIterators
1667
1668 } // namespace TpetraWrappers
1669
1670 } // namespace LinearAlgebra
1671
1672
1673 DEAL_II_NAMESPACE_CLOSE
1674
1675 namespace std
1676 {
1677 template <typename Number, typename MemorySpace, bool Constness>
1678 struct iterator_traits<
1679 dealii::LinearAlgebra::TpetraWrappers::SparseMatrixIterators::
1680 Iterator<Number, MemorySpace, Constness>>
1681 {
1682 using iterator_category = forward_iterator_tag;
1683 using value_type =
1684 typename dealii::LinearAlgebra::TpetraWrappers::SparseMatrixIterators::
1685 Iterator<Number, MemorySpace, Constness>::value_type;
1686 using difference_type =
1687 typename dealii::LinearAlgebra::TpetraWrappers::SparseMatrixIterators::
1688 Iterator<Number, MemorySpace, Constness>::difference_type;
1689 };
1690 } // namespace std
1691
1692 /* ------------------------- Inline functions ---------------------- */
1693
1694
1695 DEAL_II_NAMESPACE_OPEN
1696
1697 namespace LinearAlgebra
1698 {
1699
1700 namespace TpetraWrappers
1701 {
1702 template <typename Number, typename MemorySpace>
1703 inline void
1704 SparseMatrix<Number, MemorySpace>::set(const size_type i,
1705 const size_type j,
1706 const Number value)
1707 {
1708 set(i, 1, &j, &value, false);
1709 }
1710
1711
1712
1713 template <typename Number, typename MemorySpace>
1714 inline void
1715 SparseMatrix<Number, MemorySpace>::add(const size_type i,
1716 const size_type j,
1717 const Number value)
1718 {
1719 add(i, 1, &j, &value, false);
1720 }
1721
1722
1723
1724 template <typename Number, typename MemorySpace>
1725 inline Number
1726 SparseMatrix<Number, MemorySpace>::residual(
1727 Vector<Number, MemorySpace> &dst,
1728 const Vector<Number, MemorySpace> &x,
1729 const Vector<Number, MemorySpace> &b) const
1730 {
1731 vmult(dst, x);
1732 dst -= b;
1733 dst *= -1.;
1734
1735 return dst.l2_norm();
1736 }
1737
1738
1739
1740 template <typename Number, typename MemorySpace>
1741 inline typename SparseMatrix<Number, MemorySpace>::size_type
1742 SparseMatrix<Number, MemorySpace>::m() const
1743 {
1744 return matrix->getRowMap()->getGlobalNumElements();
1745 }
1746
1747
1748
1749 template <typename Number, typename MemorySpace>
1750 inline typename SparseMatrix<Number, MemorySpace>::size_type
1751 SparseMatrix<Number, MemorySpace>::n() const
1752 {
1753 // If the matrix structure has not been fixed (i.e., we did not have a
1754 // sparsity pattern), it does not know about the number of columns, so we
1755 // must always take this from the additional column space map
1756 Assert(column_space_map.get() != nullptr, ExcInternalError());
1757 return column_space_map->getGlobalNumElements();
1758 }
1759
1760
1761
1762 template <typename Number, typename MemorySpace>
1763 inline bool
1764 SparseMatrix<Number, MemorySpace>::is_compressed() const
1765 {
1766 return compressed;
1767 }
1768
1769
1770
1771 template <typename Number, typename MemorySpace>
1772 inline typename SparseMatrix<Number, MemorySpace>::const_iterator
1773 SparseMatrix<Number, MemorySpace>::begin() const
1774 {
1775 return begin(0);
1776 }
1777
1778
1779
1780 template <typename Number, typename MemorySpace>
1781 inline typename SparseMatrix<Number, MemorySpace>::const_iterator
1782 SparseMatrix<Number, MemorySpace>::end() const
1783 {
1784 return const_iterator(this, m(), 0);
1785 }
1786
1787
1788
1789 template <typename Number, typename MemorySpace>
1790 inline typename SparseMatrix<Number, MemorySpace>::const_iterator
1791 SparseMatrix<Number, MemorySpace>::begin(const size_type r) const
1792 {
1793 AssertIndexRange(r, m());
1794 if (in_local_range(r) && (row_length(r) > 0))
1795 return const_iterator(this, r, 0);
1796 else
1797 return end(r);
1798 }
1799
1800
1801 template <typename Number, typename MemorySpace>
1802 inline typename SparseMatrix<Number, MemorySpace>::const_iterator
1803 SparseMatrix<Number, MemorySpace>::end(const size_type r) const
1804 {
1805 AssertIndexRange(r, m());
1806
1807 // place the iterator on the first entry
1808 // past this line, or at the end of the
1809 // matrix
1810 for (size_type i = r + 1; i < m(); ++i)
1811 if (in_local_range(i) && (row_length(i) > 0))
1812 return const_iterator(this, i, 0);
1813
1814 // if there is no such line, then take the
1815 // end iterator of the matrix
1816 return end();
1817 }
1818
1819
1820
1821 template <typename Number, typename MemorySpace>
1822 inline typename SparseMatrix<Number, MemorySpace>::iterator
1823 SparseMatrix<Number, MemorySpace>::begin()
1824 {
1825 return begin(0);
1826 }
1827
1828
1829
1830 template <typename Number, typename MemorySpace>
1831 inline typename SparseMatrix<Number, MemorySpace>::iterator
1832 SparseMatrix<Number, MemorySpace>::end()
1833 {
1834 return iterator(this, m(), 0);
1835 }
1836
1837
1838
1839 template <typename Number, typename MemorySpace>
1840 inline typename SparseMatrix<Number, MemorySpace>::iterator
1841 SparseMatrix<Number, MemorySpace>::begin(const size_type r)
1842 {
1843 AssertIndexRange(r, m());
1844 if (in_local_range(r) && (row_length(r) > 0))
1845 return iterator(this, r, 0);
1846 else
1847 return end(r);
1848 }
1849
1850
1851
1852 template <typename Number, typename MemorySpace>
1853 inline typename SparseMatrix<Number, MemorySpace>::iterator
1854 SparseMatrix<Number, MemorySpace>::end(const size_type r)
1855 {
1856 AssertIndexRange(r, m());
1857
1858 // place the iterator on the first entry
1859 // past this line, or at the end of the
1860 // matrix
1861 for (size_type i = r + 1; i < m(); ++i)
1862 if (in_local_range(i) && (row_length(i) > 0))
1863 return iterator(this, i, 0);
1864
1865 // if there is no such line, then take the
1866 // end iterator of the matrix
1867 return end();
1868 }
1869
1870
1871
1872 template <typename Number, typename MemorySpace>
1873 inline bool
1874 SparseMatrix<Number, MemorySpace>::in_local_range(
1875 const size_type index) const
1876 {
1877 const size_type begin = matrix->getRowMap()->getMinGlobalIndex();
1878 const size_type end = matrix->getRowMap()->getMaxGlobalIndex() + 1;
1879
1880 return ((index >= begin) && (index < end));
1881 }
1882
1883
1884
1885 template <typename Number, typename MemorySpace>
1886 unsigned int
1887 SparseMatrix<Number, MemorySpace>::row_length(const size_type row) const
1888 {
1889 auto n_entries = matrix->getNumEntriesInGlobalRow(row);
1890 Assert(n_entries !=
1891 Teuchos::OrdinalTraits<decltype(n_entries)>::invalid(),
1892 ExcAccessToNonlocalRow(row));
1893
1894 return n_entries;
1895 }
1896
1897
1898
1899 template <typename Number, typename MemorySpace>
1900 inline void
1901 SparseMatrix<Number, MemorySpace>::prepare_add()
1902 {
1903 // nothing to do here
1904 }
1905
1906
1907
1908 template <typename Number, typename MemorySpace>
1909 inline void
1910 SparseMatrix<Number, MemorySpace>::prepare_set()
1911 {
1912 // nothing to do here
1913 }
1914
1915
1916
1917 template <typename Number, typename MemorySpace>
1918 inline const TpetraTypes::MatrixType<Number, MemorySpace> &
1919 SparseMatrix<Number, MemorySpace>::trilinos_matrix() const
1920 {
1921 return *matrix;
1922 }
1923
1924
1925
1926 template <typename Number, typename MemorySpace>
1927 inline TpetraTypes::MatrixType<Number, MemorySpace> &
1928 SparseMatrix<Number, MemorySpace>::trilinos_matrix()
1929 {
1930 return *matrix;
1931 }
1932
1933
1934
1935 template <typename Number, typename MemorySpace>
1936 inline Teuchos::RCP<const TpetraTypes::MatrixType<Number, MemorySpace>>
1937 SparseMatrix<Number, MemorySpace>::trilinos_rcp() const
1938 {
1939 return matrix.getConst();
1940 }
1941
1942
1943
1944 template <typename Number, typename MemorySpace>
1945 inline Teuchos::RCP<TpetraTypes::MatrixType<Number, MemorySpace>>
1946 SparseMatrix<Number, MemorySpace>::trilinos_rcp()
1947 {
1948 return matrix;
1949 }
1950
1951
1952
1953 template <typename Number, typename MemorySpace>
1954 inline IndexSet
1955 SparseMatrix<Number, MemorySpace>::locally_owned_domain_indices() const
1956 {
1957 return IndexSet(matrix->getDomainMap());
1958 }
1959
1960
1961
1962 template <typename Number, typename MemorySpace>
1963 inline IndexSet
1964 SparseMatrix<Number, MemorySpace>::locally_owned_range_indices() const
1965 {
1966 return IndexSet(matrix->getRangeMap());
1967 }
1968
1969
1970 namespace SparseMatrixIterators
1971 {
1972 template <typename Number, typename MemorySpace>
1973 inline AccessorBase<Number, MemorySpace>::AccessorBase(
1974 SparseMatrix<Number, MemorySpace> *matrix,
1975 size_type row,
1976 size_type index)
1977 : matrix(matrix)
1978 , a_row(row)
1979 , a_index(index)
1980 {
1981 visit_present_row();
1982 }
1983
1984
1985 template <typename Number, typename MemorySpace>
1986 inline typename AccessorBase<Number, MemorySpace>::size_type
1987 AccessorBase<Number, MemorySpace>::row() const
1988 {
1989 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
1990 return a_row;
1991 }
1992
1993
1994 template <typename Number, typename MemorySpace>
1995 inline typename AccessorBase<Number, MemorySpace>::size_type
1996 AccessorBase<Number, MemorySpace>::column() const
1997 {
1998 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
1999 return (*colnum_cache)[a_index];
2000 }
2001
2002
2003 template <typename Number, typename MemorySpace>
2004 inline typename AccessorBase<Number, MemorySpace>::size_type
2005 AccessorBase<Number, MemorySpace>::index() const
2006 {
2007 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
2008 return a_index;
2009 }
2010
2011
2012
2013 template <typename Number, typename MemorySpace>
2014 void
2015 AccessorBase<Number, MemorySpace>::visit_present_row()
2016 {
2017 // if we are asked to visit the past-the-end line, then simply
2018 // release all our caches and go on with life.
2019 //
2020 // do the same if the row we're supposed to visit is not locally
2021 // owned. this is simply going to make non-locally owned rows
2022 // look like they're empty
2023 if ((this->a_row == matrix->m()) ||
2024 (matrix->in_local_range(this->a_row) == false))
2025 {
2026 colnum_cache.reset();
2027 value_cache.reset();
2028
2029 return;
2030 }
2031
2032 // get a representation of the present row
2033 size_t ncols;
2034 TrilinosWrappers::types::int_type colnums =
2035 matrix->row_length(this->a_row);
2036 if (value_cache.get() == nullptr)
2037 {
2038 value_cache = std::make_shared<std::vector<Number>>(colnums);
2039 colnum_cache = std::make_shared<
2040 std::vector<dealii::types::signed_global_dof_index>>(colnums);
2041 }
2042 else
2043 {
2044 value_cache->resize(colnums);
2045 colnum_cache->resize(colnums);
2046 }
2047
2048 typename TpetraTypes::MatrixType<Number, MemorySpace>::
2049 nonconst_global_inds_host_view_type col_indices(colnum_cache->data(),
2050 colnums);
2051 typename TpetraTypes::MatrixType<Number, MemorySpace>::
2052 nonconst_values_host_view_type values(value_cache->data(), colnums);
2053
2054 matrix->trilinos_matrix().getGlobalRowCopy(this->a_row,
2055 col_indices,
2056 values,
2057 ncols);
2058
2059 AssertDimension(ncols, colnums);
2060
2061 // copy it into our caches if the
2062 // line isn't empty. if it is, then
2063 // we've done something wrong, since
2064 // we shouldn't have initialized an
2065 // iterator for an empty line (what
2066 // would it point to?)
2067 }
2068
2069
2070
2071 template <typename Number, typename MemorySpace>
2072 inline Accessor<Number, MemorySpace, true>::Accessor(
2073 MatrixType *matrix,
2074 const size_type row,
2075 const size_type index)
2076 : AccessorBase<Number, MemorySpace>(
2077 const_cast<SparseMatrix<Number, MemorySpace> *>(matrix),
2078 row,
2079 index)
2080 {}
2081
2082
2083
2084 template <typename Number, typename MemorySpace>
2085 template <bool Other>
2086 inline Accessor<Number, MemorySpace, true>::Accessor(
2087 const Accessor<Number, MemorySpace, Other> &other)
2088 : AccessorBase<Number, MemorySpace>(other)
2089 {}
2090
2091
2092
2093 template <typename Number, typename MemorySpace>
2094 inline Number
2095 Accessor<Number, MemorySpace, true>::value() const
2096 {
2097 Assert((AccessorBase<Number, MemorySpace>::a_row <
2098 AccessorBase<Number, MemorySpace>::matrix->m()),
2099 ExcBeyondEndOfMatrix());
2100 return (*AccessorBase<Number, MemorySpace>::value_cache)
2101 [AccessorBase<Number, MemorySpace>::a_index];
2102 }
2103
2104
2105
2106 template <typename Number, typename MemorySpace>
2107 inline Accessor<Number, MemorySpace, false>::Reference::Reference(
2108 const Accessor<Number, MemorySpace, false> &acc)
2109 : accessor(const_cast<Accessor<Number, MemorySpace, false> &>(acc))
2110 {}
2111
2112
2113
2114 template <typename Number, typename MemorySpace>
2115 inline Accessor<Number, MemorySpace, false>::Reference::operator Number()
2116 const
2117 {
2118 return (*accessor.value_cache)[accessor.a_index];
2119 }
2120
2121
2122
2123 template <typename Number, typename MemorySpace>
2124 inline const typename Accessor<Number, MemorySpace, false>::Reference &
2125 Accessor<Number, MemorySpace, false>::Reference::operator=(
2126 const Number n) const
2127 {
2128 (*accessor.value_cache)[accessor.a_index] = n;
2129 accessor.matrix->set(accessor.row(),
2130 accessor.column(),
2131 static_cast<Number>(*this));
2132 return *this;
2133 }
2134
2135
2136
2137 template <typename Number, typename MemorySpace>
2138 inline const typename Accessor<Number, MemorySpace, false>::Reference &
2139 Accessor<Number, MemorySpace, false>::Reference::operator+=(
2140 const Number n) const
2141 {
2142 (*accessor.value_cache)[accessor.a_index] += n;
2143 accessor.matrix->set(accessor.row(),
2144 accessor.column(),
2145 static_cast<Number>(*this));
2146 return *this;
2147 }
2148
2149
2150
2151 template <typename Number, typename MemorySpace>
2152 inline const typename Accessor<Number, MemorySpace, false>::Reference &
2153 Accessor<Number, MemorySpace, false>::Reference::operator-=(
2154 const Number n) const
2155 {
2156 (*accessor.value_cache)[accessor.a_index] -= n;
2157 accessor.matrix->set(accessor.row(),
2158 accessor.column(),
2159 static_cast<Number>(*this));
2160 return *this;
2161 }
2162
2163
2164 template <typename Number, typename MemorySpace>
2165 inline const typename Accessor<Number, MemorySpace, false>::Reference &
2166 Accessor<Number, MemorySpace, false>::Reference::operator*=(
2167 const Number n) const
2168 {
2169 (*accessor.value_cache)[accessor.a_index] *= n;
2170 accessor.matrix->set(accessor.row(),
2171 accessor.column(),
2172 static_cast<Number>(*this));
2173 return *this;
2174 }
2175
2176
2177 template <typename Number, typename MemorySpace>
2178 inline const typename Accessor<Number, MemorySpace, false>::Reference &
2179 Accessor<Number, MemorySpace, false>::Reference::operator/=(
2180 const Number n) const
2181 {
2182 (*accessor.value_cache)[accessor.a_index] /= n;
2183 accessor.matrix->set(accessor.row(),
2184 accessor.column(),
2185 static_cast<Number>(*this));
2186 return *this;
2187 }
2188
2189
2190 template <typename Number, typename MemorySpace>
2191 inline Accessor<Number, MemorySpace, false>::Accessor(
2192 MatrixType *matrix,
2193 const size_type row,
2194 const size_type index)
2195 : AccessorBase<Number, MemorySpace>(matrix, row, index)
2196 {}
2197
2198
2199 template <typename Number, typename MemorySpace>
2200 inline typename Accessor<Number, MemorySpace, false>::Reference
2201 Accessor<Number, MemorySpace, false>::value() const
2202 {
2203 Assert((AccessorBase<Number, MemorySpace>::a_row <
2204 AccessorBase<Number, MemorySpace>::matrix->m()),
2205 ExcBeyondEndOfMatrix());
2206 return {*this};
2207 }
2208
2209
2210
2211 template <typename Number, typename MemorySpace, bool Constness>
2212 inline Iterator<Number, MemorySpace, Constness>::Iterator(
2213 MatrixType *matrix,
2214 const size_type row,
2215 const size_type index)
2216 : accessor(matrix, row, index)
2217 {}
2218
2219
2220 template <typename Number, typename MemorySpace, bool Constness>
2221 template <bool Other>
2222 inline Iterator<Number, MemorySpace, Constness>::Iterator(
2223 const Iterator<Number, MemorySpace, Other> &other)
2224 : accessor(other.accessor)
2225 {}
2226
2227
2228
2229 template <typename Number, typename MemorySpace, bool Constness>
2230 inline Iterator<Number, MemorySpace, Constness> &
2231 Iterator<Number, MemorySpace, Constness>::operator++()
2232 {
2233 Assert(accessor.a_row < accessor.matrix->m(), ExcIteratorPastEnd());
2234
2235 ++accessor.a_index;
2236
2237 // If at end of line: do one
2238 // step, then cycle until we
2239 // find a row with a nonzero
2240 // number of entries.
2241 if (accessor.a_index >= accessor.colnum_cache->size())
2242 {
2243 accessor.a_index = 0;
2244 ++accessor.a_row;
2245
2246 while (
2247 (accessor.a_row < accessor.matrix->m()) &&
2248 ((accessor.matrix->in_local_range(accessor.a_row) == false) ||
2249 (accessor.matrix->row_length(accessor.a_row) == 0)))
2250 ++accessor.a_row;
2251
2252 accessor.visit_present_row();
2253 }
2254 return *this;
2255 }
2256
2257
2258 template <typename Number, typename MemorySpace, bool Constness>
2259 inline Iterator<Number, MemorySpace, Constness>
2260 Iterator<Number, MemorySpace, Constness>::operator++(int)
2261 {
2262 const Iterator<Number, MemorySpace, Constness> old_state = *this;
2263 ++(*this);
2264 return old_state;
2265 }
2266
2267
2268
2269 template <typename Number, typename MemorySpace, bool Constness>
2270 inline const Accessor<Number, MemorySpace, Constness> &
2271 Iterator<Number, MemorySpace, Constness>::operator*() const
2272 {
2273 return accessor;
2274 }
2275
2276
2277
2278 template <typename Number, typename MemorySpace, bool Constness>
2279 inline const Accessor<Number, MemorySpace, Constness> *
2280 Iterator<Number, MemorySpace, Constness>::operator->() const
2281 {
2282 return &accessor;
2283 }
2284
2285
2286
2287 template <typename Number, typename MemorySpace, bool Constness>
2288 template <bool OtherConstness>
2289 inline bool
2290 Iterator<Number, MemorySpace, Constness>::operator==(
2291 const Iterator<Number, MemorySpace, OtherConstness> &other) const
2292 {
2293 return (accessor.a_row == other.accessor.a_row &&
2294 accessor.a_index == other.accessor.a_index);
2295 }
2296
2297
2298
2299 template <typename Number, typename MemorySpace, bool Constness>
2300 template <bool OtherConstness>
2301 inline bool
2302 Iterator<Number, MemorySpace, Constness>::operator!=(
2303 const Iterator<Number, MemorySpace, OtherConstness> &other) const
2304 {
2305 return !(*this == other);
2306 }
2307
2308
2309
2310 template <typename Number, typename MemorySpace, bool Constness>
2311 template <bool OtherConstness>
2312 inline bool
2313 Iterator<Number, MemorySpace, Constness>::operator<(
2314 const Iterator<Number, MemorySpace, OtherConstness> &other) const
2315 {
2316 return (accessor.row() < other.accessor.row() ||
2317 (accessor.row() == other.accessor.row() &&
2318 accessor.index() < other.accessor.index()));
2319 }
2320
2321
2322 template <typename Number, typename MemorySpace, bool Constness>
2323 template <bool OtherConstness>
2324 inline bool
2325 Iterator<Number, MemorySpace, Constness>::operator>(
2326 const Iterator<Number, MemorySpace, OtherConstness> &other) const
2327 {
2328 return (other < *this);
2329 }
2330
2331 } // namespace SparseMatrixIterators
2332 } // namespace TpetraWrappers
2333
2334 } // namespace LinearAlgebra
2335
2336 DEAL_II_NAMESPACE_CLOSE
2337
2338 #else
2339
2340 // Make sure the scripts that create the C++20 module input files have
2341 // something to latch on if the preprocessor #ifdef above would
2342 // otherwise lead to an empty content of the file.
2343 DEAL_II_NAMESPACE_OPEN
2344 DEAL_II_NAMESPACE_CLOSE
2345
2346 #endif // DEAL_II_TRILINOS_WITH_TPETRA
2347
2348 #endif // dealii_trilinos_tpetra_sparse_matrix_h