Debian Codegraph @

include/deal.II/lac/trilinos_sparse_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2008 - 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_sparse_matrix_h
16 # define dealii_trilinos_sparse_matrix_h
17
18
19 # include <deal.II/base/config.h>
20
21 # ifdef DEAL_II_WITH_TRILINOS
22
23 # include <deal.II/base/enable_observer_pointer.h>
24 # include <deal.II/base/index_set.h>
25 # include <deal.II/base/mpi_stub.h>
26
27 # include <deal.II/lac/exceptions.h>
28 # include <deal.II/lac/full_matrix.h>
29 # include <deal.II/lac/trilinos_epetra_vector.h>
30 # include <deal.II/lac/trilinos_index_access.h>
31 # include <deal.II/lac/trilinos_tpetra_vector.h>
32 # include <deal.II/lac/trilinos_vector.h>
33 # include <deal.II/lac/vector_memory.h>
34 # include <deal.II/lac/vector_operation.h>
35
36 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
37 # include <Epetra_Comm.h>
38 # include <Epetra_CrsGraph.h>
39 # include <Epetra_Export.h>
40 # include <Epetra_FECrsMatrix.h>
41 # include <Epetra_Map.h>
42 # include <Epetra_MpiComm.h>
43 # include <Epetra_MultiVector.h>
44 # include <Epetra_Operator.h>
45 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
46
47 # include <cmath>
48 # include <iterator>
49 # include <memory>
50 # include <type_traits>
51 # include <vector>
52
53 DEAL_II_NAMESPACE_OPEN
54
55 // forward declarations
56 # ifndef DOXYGEN
57 template <typename MatrixType>
58 class BlockMatrixBase;
59
60 template <typename number>
61 class SparseMatrix;
62 class SparsityPattern;
63 class DynamicSparsityPattern;
64
65 namespace TrilinosWrappers
66 {
67 class SparseMatrix;
68 class SparsityPattern;
69
70 namespace SparseMatrixIterators
71 {
72 template <bool Constness>
73 class Iterator;
74 }
75 } // namespace TrilinosWrappers
76 # endif
77
78 namespace TrilinosWrappers
79 {
80 /**
81 * Iterators for Trilinos matrices
82 */
83 namespace SparseMatrixIterators
84 {
85 /**
86 * Exception
87 */
88 DeclException0(ExcBeyondEndOfMatrix);
89
90 /**
91 * Exception
92 */
93 DeclException3(ExcAccessToNonlocalRow,
94 std::size_t,
95 std::size_t,
96 std::size_t,
97 << "You tried to access row " << arg1
98 << " of a distributed sparsity pattern, "
99 << " but only rows " << arg2 << " through " << arg3
100 << " are stored locally and can be accessed.");
101
102 /**
103 * Handling of indices for both constant and non constant Accessor objects
104 *
105 * For a regular dealii::SparseMatrix, we would use an accessor for the
106 * sparsity pattern. For Trilinos matrices, this does not seem so simple,
107 * therefore, we write a little base class here.
108 */
109 class AccessorBase
110 {
111 public:
112 /**
113 * Declare the type for container size.
114 */
115 using size_type = dealii::types::global_dof_index;
116
117 /**
118 * Constructor.
119 */
120 AccessorBase(SparseMatrix *matrix,
121 const size_type row,
122 const size_type index);
123
124 /**
125 * Row number of the element represented by this object.
126 */
127 size_type
128 row() const;
129
130 /**
131 * Index in row of the element represented by this object.
132 */
133 size_type
134 index() const;
135
136 /**
137 * Column number of the element represented by this object.
138 */
139 size_type
140 column() const;
141
142 protected:
143 /**
144 * Pointer to the matrix object. This object should be handled as a
145 * const pointer or non-const by the appropriate derived classes. In
146 * order to be able to implement both, it is not const here, so handle
147 * with care!
148 */
149 mutable SparseMatrix *matrix;
150 /**
151 * Current row number.
152 */
153 size_type a_row;
154
155 /**
156 * Current index in row.
157 */
158 size_type a_index;
159
160 /**
161 * Discard the old row caches (they may still be used by other
162 * accessors) and generate new ones for the row pointed to presently by
163 * this accessor.
164 */
165 void
166 visit_present_row();
167
168 /**
169 * Cache where we store the column indices of the present row. This is
170 * necessary, since Trilinos makes access to the elements of its
171 * matrices rather hard, and it is much more efficient to copy all
172 * column entries of a row once when we enter it than repeatedly asking
173 * Trilinos for individual ones. This also makes some sense since it is
174 * likely that we will access them sequentially anyway.
175 *
176 * In order to make copying of iterators/accessor of acceptable
177 * performance, we keep a shared pointer to these entries so that more
178 * than one accessor can access this data if necessary.
179 */
180 std::shared_ptr<std::vector<size_type>> colnum_cache;
181
182 /**
183 * Cache for the values of this row.
184 */
185 std::shared_ptr<std::vector<TrilinosScalar>> value_cache;
186 };
187
188 /**
189 * General template for sparse matrix accessors. The first template
190 * argument denotes the underlying numeric type, the second the constness
191 * of the matrix.
192 *
193 * The general template is not implemented, only the specializations for
194 * the two possible values of the second template argument. Therefore, the
195 * interface listed here only serves as a template provided since doxygen
196 * does not link the specializations.
197 */
198 template <bool Constess>
199 class Accessor : public AccessorBase
200 {
201 /**
202 * Value of this matrix entry.
203 */
204 TrilinosScalar
205 value() const;
206
207 /**
208 * Value of this matrix entry.
209 */
210 TrilinosScalar &
211 value();
212 };
213
214
215
216 /**
217 * The specialization for a const Accessor.
218 */
219 template <>
220 class Accessor<true> : public AccessorBase
221 {
222 public:
223 /**
224 * Typedef for the type (including constness) of the matrix to be used
225 * here.
226 */
227 using MatrixType = const SparseMatrix;
228
229 /**
230 * Constructor. Since we use accessors only for read access, a const
231 * matrix pointer is sufficient.
232 */
233 Accessor(MatrixType *matrix, const size_type row, const size_type index);
234
235 /**
236 * Copy constructor to get from a const or non-const accessor to a const
237 * accessor.
238 */
239 template <bool Other>
240 Accessor(const Accessor<Other> &a);
241
242 /**
243 * Value of this matrix entry.
244 */
245 TrilinosScalar
246 value() const;
247
248 private:
249 // Make iterator class a friend.
250 template <bool>
251 friend class Iterator;
252 };
253
254 /**
255 * The specialization for a mutable Accessor.
256 */
257 template <>
258 class Accessor<false> : public AccessorBase
259 {
260 class Reference
261 {
262 public:
263 /**
264 * Constructor.
265 */
266 Reference(const Accessor<false> &accessor);
267
268 /**
269 * Conversion operator to the data type of the matrix.
270 */
271 operator TrilinosScalar() const;
272
273 /**
274 * Set the element of the matrix we presently point to to @p n.
275 */
276 const Reference &
277 operator=(const TrilinosScalar n) const;
278
279 /**
280 * Add @p n to the element of the matrix we presently point to.
281 */
282 const Reference &
283 operator+=(const TrilinosScalar n) const;
284
285 /**
286 * Subtract @p n from the element of the matrix we presently point to.
287 */
288 const Reference &
289 operator-=(const TrilinosScalar n) const;
290
291 /**
292 * Multiply the element of the matrix we presently point to by @p n.
293 */
294 const Reference &
295 operator*=(const TrilinosScalar n) const;
296
297 /**
298 * Divide the element of the matrix we presently point to by @p n.
299 */
300 const Reference &
301 operator/=(const TrilinosScalar n) const;
302
303 private:
304 /**
305 * Pointer to the accessor that denotes which element we presently
306 * point to.
307 */
308 Accessor &accessor;
309 };
310
311 public:
312 /**
313 * Typedef for the type (including constness) of the matrix to be used
314 * here.
315 */
316 using MatrixType = SparseMatrix;
317
318 /**
319 * Constructor. Since we use accessors only for read access, a const
320 * matrix pointer is sufficient.
321 */
322 Accessor(MatrixType *matrix, const size_type row, const size_type index);
323
324 /**
325 * Value of this matrix entry.
326 */
327 Reference
328 value() const;
329
330 private:
331 // Make iterator class a friend.
332 template <bool>
333 friend class Iterator;
334
335 // Make Reference object a friend.
336 friend class Reference;
337 };
338
339 /**
340 * This class acts as an iterator walking over the elements of Trilinos
341 * matrices. The implementation of this class is similar to the one for
342 * PETSc matrices.
343 *
344 * Note that Trilinos stores the elements within each row in ascending
345 * order. This is opposed to the deal.II sparse matrix style where the
346 * diagonal element (if it exists) is stored before all other values, and
347 * the PETSc sparse matrices, where one can't guarantee a certain order of
348 * the elements.
349 *
350 * @ingroup TrilinosWrappers
351 */
352 template <bool Constness>
353 class Iterator
354 {
355 public:
356 /**
357 * Declare type for container size.
358 */
359 using size_type = dealii::types::global_dof_index;
360
361 /**
362 * A type that denotes what data types is used to express the difference
363 * between two iterators.
364 */
365 using difference_type = dealii::types::global_dof_index;
366
367 /**
368 * An alias for the type you get when you dereference an iterator of the
369 * current kind.
370 */
371 using value_type = TrilinosScalar;
372
373 /**
374 * Typedef for the matrix type (including constness) we are to operate
375 * on.
376 */
377 using MatrixType = typename Accessor<Constness>::MatrixType;
378
379 /**
380 * Constructor. Create an iterator into the matrix @p matrix for the
381 * given row and the index within it.
382 */
383 Iterator(MatrixType *matrix, const size_type row, const size_type index);
384
385 /**
386 * Copy constructor with optional change of constness.
387 */
388 template <bool Other>
389 Iterator(const Iterator<Other> &other);
390
391 /**
392 * Prefix increment.
393 */
394 Iterator<Constness> &
395 operator++();
396
397 /**
398 * Postfix increment.
399 */
400 Iterator<Constness>
401 operator++(int);
402
403 /**
404 * Dereferencing operator.
405 */
406 const Accessor<Constness> &
407 operator*() const;
408
409 /**
410 * Dereferencing operator.
411 */
412 const Accessor<Constness> *
413 operator->() const;
414
415 /**
416 * Comparison. True, if both iterators point to the same matrix
417 * position.
418 */
419 template <bool OtherConstness>
420 bool
421 operator==(const Iterator<OtherConstness> &) const;
422
423 /**
424 * Inverse of <tt>==</tt>.
425 */
426 template <bool OtherConstness>
427 bool
428 operator!=(const Iterator<OtherConstness> &) const;
429
430 /**
431 * Comparison operator. Result is true if either the first row number is
432 * smaller or if the row numbers are equal and the first index is
433 * smaller.
434 */
435 template <bool OtherConstness>
436 bool
437 operator<(const Iterator<OtherConstness> &) const;
438
439 /**
440 * Comparison operator. The opposite of the previous operator
441 */
442 template <bool OtherConstness>
443 bool
444 operator>(const Iterator<OtherConstness> &) const;
445
446 /**
447 * Exception
448 */
449 DeclException2(ExcInvalidIndexWithinRow,
450 size_type,
451 size_type,
452 << "Attempt to access element " << arg2 << " of row "
453 << arg1 << " which doesn't have that many elements.");
454
455 private:
456 /**
457 * Store an object of the accessor class.
458 */
459 Accessor<Constness> accessor;
460
461 template <bool Other>
462 friend class Iterator;
463 };
464
465 } // namespace SparseMatrixIterators
466 } // namespace TrilinosWrappers
467
468 DEAL_II_NAMESPACE_CLOSE // Do not convert for module purposes
469
470 namespace std
471 {
472 template <bool Constness>
473 struct iterator_traits<
474 dealii::TrilinosWrappers::SparseMatrixIterators::Iterator<Constness>>
475 {
476 using iterator_category = forward_iterator_tag;
477 using value_type =
478 typename dealii::TrilinosWrappers::SparseMatrixIterators::Iterator<
479 Constness>::value_type;
480 using difference_type =
481 typename dealii::TrilinosWrappers::SparseMatrixIterators::Iterator<
482 Constness>::difference_type;
483 };
484 } // namespace std
485
486 DEAL_II_NAMESPACE_OPEN // Do not convert for module purposes
487
488
489 namespace TrilinosWrappers
490 {
491 /**
492 * This class implements a wrapper to use the Trilinos distributed sparse
493 * matrix class Epetra_FECrsMatrix. This is precisely the kind of matrix we
494 * deal with all the time - we most likely get it from some assembly
495 * process, where also entries not locally owned might need to be written
496 * and hence need to be forwarded to the owner process. This class is
497 * designed to be used in a distributed memory architecture with an MPI
498 * compiler on the bottom, but works equally well also for serial processes.
499 * The only requirement for this class to work is that Trilinos has been
500 * installed with the same compiler as is used for generating deal.II.
501 *
502 * The interface of this class is modeled after the existing SparseMatrix
503 * class in deal.II. It has almost the same member functions, and is often
504 * exchangeable. However, since Trilinos only supports a single scalar type
505 * (double), it is not templated, and only works with doubles.
506 *
507 * Note that Trilinos only guarantees that operations do what you expect if
508 * the functions @p GlobalAssemble has been called after matrix assembly.
509 * Therefore, you need to call SparseMatrix::compress() before you actually
510 * use the matrix. This also calls @p FillComplete that compresses the
511 * storage format for sparse matrices by discarding unused elements.
512 * Trilinos allows to continue with assembling the matrix after calls to
513 * these functions, though.
514 *
515 * <h3>Thread safety of Trilinos matrices</h3>
516 *
517 * When writing into Trilinos matrices from several threads in shared
518 * memory, several things must be kept in mind as there is no built-in locks
519 * in this class to prevent data races. Simultaneous access to the same
520 * matrix row at the same time can lead to data races and must be explicitly
521 * avoided by the user. However, it is possible to access <b>different</b>
522 * rows of the matrix from several threads simultaneously under the
523 * following three conditions:
524 * <ul>
525 * <li> The matrix uses only one MPI process.
526 * <li> The matrix has been initialized with the reinit() method with a
527 * DynamicSparsityPattern (that includes the set of locally relevant rows,
528 * i.e., the rows that an assembly routine will possibly write into).
529 * <li> The matrix has been initialized from a
530 * TrilinosWrappers::SparsityPattern object that in turn has been
531 * initialized with the reinit function specifying three index sets, one for
532 * the rows, one for the columns and for the larger set of @p
533 * writeable_rows, and the operation is an addition. At some point in the
534 * future, Trilinos support might be complete enough such that initializing
535 * from a TrilinosWrappers::SparsityPattern that has been filled by a
536 * function similar to DoFTools::make_sparsity_pattern always results in a
537 * matrix that allows several processes to write into the same matrix row.
538 * However, Trilinos until version at least 11.12 does not correctly support
539 * this feature.
540 * </ul>
541 *
542 * Note that all other reinit methods and constructors of
543 * TrilinosWrappers::SparsityPattern will result in a matrix that needs to
544 * allocate off-processor entries on demand, which breaks thread-safety. Of
545 * course, using the respective reinit method for the block Trilinos
546 * sparsity pattern and block matrix also results in thread-safety.
547 *
548 * @ingroup TrilinosWrappers
549 * @ingroup Matrix1
550 */
551 class SparseMatrix : public EnableObserverPointer
552 {
553 public:
554 /**
555 * Declare the type for container size.
556 */
557 using size_type = dealii::types::global_dof_index;
558
559 /**
560 * Exception
561 */
562 DeclException1(ExcAccessToNonlocalRow,
563 std::size_t,
564 << "You tried to access row " << arg1
565 << " of a non-contiguous locally owned row set."
566 << " The row " << arg1
567 << " is not stored locally and can't be accessed.");
568
569 /**
570 * A structure that describes some of the traits of this class in terms of
571 * its run-time behavior. Some other classes (such as the block matrix
572 * classes) that take one or other of the matrix classes as its template
573 * parameters can tune their behavior based on the variables in this
574 * class.
575 */
576 struct Traits
577 {
578 /**
579 * It is safe to elide additions of zeros to individual elements of this
580 * matrix.
581 */
582 static const bool zero_addition_can_be_elided = true;
583 };
584
585 /**
586 * Declare an alias for the iterator class.
587 */
588 using iterator = SparseMatrixIterators::Iterator<false>;
589
590 /**
591 * Declare an alias for the const iterator class.
592 */
593 using const_iterator = SparseMatrixIterators::Iterator<true>;
594
595 /**
596 * Declare an alias in analogy to all the other container classes.
597 */
598 using value_type = TrilinosScalar;
599
600 /**
601 * @name Constructors and initialization.
602 */
603 /** @{ */
604 /**
605 * Default constructor. Generates an empty (zero-size) matrix.
606 */
607 SparseMatrix();
608
609 /**
610 * Generate a matrix that is completely stored locally, having #m rows and
611 * #n columns.
612 *
613 * The number of columns entries per row is specified as the maximum
614 * number of entries argument.
615 */
616 SparseMatrix(const size_type m,
617 const size_type n,
618 const unsigned int n_max_entries_per_row);
619
620 /**
621 * Generate a matrix that is completely stored locally, having #m rows and
622 * #n columns.
623 *
624 * The vector <tt>n_entries_per_row</tt> specifies the number of entries
625 * in each row.
626 */
627 SparseMatrix(const size_type m,
628 const size_type n,
629 const std::vector<unsigned int> &n_entries_per_row);
630
631 /**
632 * Generate a matrix from a Trilinos sparsity pattern object.
633 */
634 SparseMatrix(const SparsityPattern &InputSparsityPattern);
635
636 /**
637 * Move constructor. Create a new sparse matrix by stealing the internal
638 * data.
639 */
640 SparseMatrix(SparseMatrix &&other) noexcept;
641
642 /**
643 * Copy constructor is deleted.
644 */
645 SparseMatrix(const SparseMatrix &) = delete;
646
647 /**
648 * operator= is deleted.
649 */
650 SparseMatrix &
651 operator=(const SparseMatrix &) = delete;
652
653 /**
654 * Destructor. Made virtual so that one can use pointers to this class.
655 */
656 virtual ~SparseMatrix() override = default;
657
658 /**
659 * This function initializes the Trilinos matrix with a deal.II sparsity
660 * pattern, i.e. it makes the Trilinos Epetra matrix know the position of
661 * nonzero entries according to the sparsity pattern. This function is
662 * meant for use in serial programs, where there is no need to specify how
663 * the matrix is going to be distributed among different processors. This
664 * function works in %parallel, too, but it is recommended to manually
665 * specify the %parallel partitioning of the matrix using an Epetra_Map.
666 * When run in %parallel, it is currently necessary that each processor
667 * holds the sparsity_pattern structure because each processor sets its
668 * rows.
669 *
670 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
671 * processors in order to avoid a dead lock.
672 */
673 template <typename SparsityPatternType>
674 void
675 reinit(const SparsityPatternType &sparsity_pattern);
676
677 /**
678 * This function reinitializes the Trilinos sparse matrix from a (possibly
679 * distributed) Trilinos sparsity pattern.
680 *
681 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
682 * processors in order to avoid a dead lock.
683 *
684 * If you want to write to the matrix from several threads and use MPI,
685 * you need to use this reinit method with a sparsity pattern that has
686 * been created with explicitly stating writeable rows. In all other
687 * cases, you cannot mix MPI with multithreaded writing into the matrix.
688 */
689 void
690 reinit(const SparsityPattern &sparsity_pattern);
691
692 /**
693 * This function copies the layout of @p sparse_matrix to the calling
694 * matrix. The values are not copied, but you can use copy_from() for
695 * this.
696 *
697 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
698 * processors in order to avoid a dead lock.
699 */
700 void
701 reinit(const SparseMatrix &sparse_matrix);
702
703 /**
704 * This function initializes the Trilinos matrix using the deal.II sparse
705 * matrix and the entries stored therein. It uses a threshold to copy only
706 * elements with modulus larger than the threshold (so zeros in the
707 * deal.II matrix can be filtered away).
708 *
709 * The optional parameter <tt>copy_values</tt> decides whether only the
710 * sparsity structure of the input matrix should be used or the matrix
711 * entries should be copied, too.
712 *
713 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
714 * processors in order to avoid a deadlock.
715 *
716 * @note If a different sparsity pattern is given in the last argument
717 * (i.e., one that differs from the one used in the sparse matrix given in
718 * the first argument), then the resulting Trilinos matrix will have the
719 * sparsity pattern so given. This of course also means that all entries
720 * in the given matrix that are not part of this separate sparsity pattern
721 * will in fact be dropped.
722 */
723 template <typename number>
724 void
725 reinit(const ::dealii::SparseMatrix<number> &dealii_sparse_matrix,
726 const double drop_tolerance = 1e-13,
727 const bool copy_values = true,
728 const ::dealii::SparsityPattern *use_this_sparsity = nullptr);
729
730 /**
731 * This reinit function takes as input a Trilinos Epetra_CrsMatrix and
732 * copies its sparsity pattern. If so requested, even the content (values)
733 * will be copied.
734 */
735 void
736 reinit(const Epetra_CrsMatrix &input_matrix, const bool copy_values = true);
737 /** @} */
738
739 /**
740 * @name Constructors and initialization using an IndexSet description
741 */
742 /** @{ */
743 /**
744 * Constructor using an IndexSet and an MPI communicator to describe the
745 * %parallel partitioning. The parameter @p n_max_entries_per_row sets the
746 * number of nonzero entries in each row that will be allocated. Note that
747 * this number does not need to be exact, and it is even allowed that the
748 * actual matrix structure has more nonzero entries than specified in the
749 * constructor. However it is still advantageous to provide good estimates
750 * here since this will considerably increase the performance of the
751 * matrix setup. However, there is no effect in the performance of
752 * matrix-vector products, since Trilinos reorganizes the matrix memory
753 * prior to use (in the compress() step).
754 */
755 SparseMatrix(const IndexSet &parallel_partitioning,
756 const MPI_Comm communicator = MPI_COMM_WORLD,
757 const unsigned int n_max_entries_per_row = 0);
758
759 /**
760 * Same as before, but now set the number of nonzeros in each matrix row
761 * separately. Since we know the number of elements in the matrix exactly
762 * in this case, we can already allocate the right amount of memory, which
763 * makes the creation process including the insertion of nonzero elements
764 * by the respective SparseMatrix::reinit call considerably faster.
765 */
766 SparseMatrix(const IndexSet &parallel_partitioning,
767 const MPI_Comm communicator,
768 const std::vector<unsigned int> &n_entries_per_row);
769
770 /**
771 * This constructor is similar to the one above, but it now takes two
772 * different IndexSet partitions for row and columns. This interface is
773 * meant to be used for generating rectangular matrices, where the first
774 * index set describes the %parallel partitioning of the degrees of
775 * freedom associated with the matrix rows and the second one the
776 * partitioning of the matrix columns. The second index set specifies the
777 * partitioning of the vectors this matrix is to be multiplied with, not
778 * the distribution of the elements that actually appear in the matrix.
779 *
780 * The parameter @p n_max_entries_per_row defines how much memory will be
781 * allocated for each row. This number does not need to be accurate, as
782 * the structure is reorganized in the compress() call.
783 */
784 SparseMatrix(const IndexSet &row_parallel_partitioning,
785 const IndexSet &col_parallel_partitioning,
786 const MPI_Comm communicator = MPI_COMM_WORLD,
787 const size_type n_max_entries_per_row = 0);
788
789 /**
790 * This constructor is similar to the one above, but it now takes two
791 * different Epetra maps for rows and columns. This interface is meant to
792 * be used for generating rectangular matrices, where one map specifies
793 * the %parallel distribution of degrees of freedom associated with matrix
794 * rows and the second one specifies the %parallel distribution the dofs
795 * associated with columns in the matrix. The second map also provides
796 * information for the internal arrangement in matrix vector products
797 * (i.e., the distribution of vector this matrix is to be multiplied
798 * with), but is not used for the distribution of the columns &ndash;
799 * rather, all column elements of a row are stored on the same processor
800 * in any case. The vector <tt>n_entries_per_row</tt> specifies the number
801 * of entries in each row of the newly generated matrix.
802 */
803 SparseMatrix(const IndexSet &row_parallel_partitioning,
804 const IndexSet &col_parallel_partitioning,
805 const MPI_Comm communicator,
806 const std::vector<unsigned int> &n_entries_per_row);
807
808 /**
809 * This function is initializes the Trilinos Epetra matrix according to
810 * the specified sparsity_pattern, and also reassigns the matrix rows to
811 * different processes according to a user-supplied index set and
812 * %parallel communicator. In programs following the style of the tutorial
813 * programs, this function (and the respective call for a rectangular
814 * matrix) are the natural way to initialize the matrix size, its
815 * distribution among the MPI processes (if run in %parallel) as well as
816 * the location of non-zero elements. Trilinos stores the sparsity pattern
817 * internally, so it won't be needed any more after this call, in contrast
818 * to the deal.II own object. The optional argument @p exchange_data can
819 * be used for reinitialization with a sparsity pattern that is not fully
820 * constructed. This feature is only implemented for input sparsity
821 * patterns of type DynamicSparsityPattern. If the flag is not set, each
822 * processor just sets the elements in the sparsity pattern that belong to
823 * its rows.
824 *
825 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
826 * processors in order to avoid a dead lock.
827 */
828 template <typename SparsityPatternType>
829 void
830 reinit(const IndexSet &parallel_partitioning,
831 const SparsityPatternType &sparsity_pattern,
832 const MPI_Comm communicator = MPI_COMM_WORLD,
833 const bool exchange_data = false);
834
835 /**
836 * This function is similar to the other initialization function above,
837 * but now also reassigns the matrix rows and columns according to two
838 * user-supplied index sets. To be used for rectangular matrices. The
839 * optional argument @p exchange_data can be used for reinitialization
840 * with a sparsity pattern that is not fully constructed. This feature is
841 * only implemented for input sparsity patterns of type
842 * DynamicSparsityPattern.
843 *
844 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
845 * processors in order to avoid a dead lock.
846 */
847 template <typename SparsityPatternType>
848 std::enable_if_t<
849 !std::is_same_v<SparsityPatternType, dealii::SparseMatrix<double>>>
850 reinit(const IndexSet &row_parallel_partitioning,
851 const IndexSet &col_parallel_partitioning,
852 const SparsityPatternType &sparsity_pattern,
853 const MPI_Comm communicator = MPI_COMM_WORLD,
854 const bool exchange_data = false);
855
856 /**
857 * This function initializes the Trilinos matrix using the deal.II sparse
858 * matrix and the entries stored therein. It uses a threshold to copy only
859 * elements with modulus larger than the threshold (so zeros in the
860 * deal.II matrix can be filtered away). In contrast to the other reinit
861 * function with deal.II sparse matrix argument, this function takes a
862 * %parallel partitioning specified by the user instead of internally
863 * generating it.
864 *
865 * The optional parameter <tt>copy_values</tt> decides whether only the
866 * sparsity structure of the input matrix should be used or the matrix
867 * entries should be copied, too.
868 *
869 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
870 * processors in order to avoid a dead lock.
871 */
872 template <typename number>
873 void
874 reinit(const IndexSet &parallel_partitioning,
875 const ::dealii::SparseMatrix<number> &dealii_sparse_matrix,
876 const MPI_Comm communicator = MPI_COMM_WORLD,
877 const double drop_tolerance = 1e-13,
878 const bool copy_values = true,
879 const ::dealii::SparsityPattern *use_this_sparsity = nullptr);
880
881 /**
882 * This function is similar to the other initialization function with
883 * deal.II sparse matrix input above, but now takes index sets for both
884 * the rows and the columns of the matrix. Chosen for rectangular
885 * matrices.
886 *
887 * The optional parameter <tt>copy_values</tt> decides whether only the
888 * sparsity structure of the input matrix should be used or the matrix
889 * entries should be copied, too.
890 *
891 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
892 * processors in order to avoid a dead lock.
893 */
894 template <typename number>
895 void
896 reinit(const IndexSet &row_parallel_partitioning,
897 const IndexSet &col_parallel_partitioning,
898 const ::dealii::SparseMatrix<number> &dealii_sparse_matrix,
899 const MPI_Comm communicator = MPI_COMM_WORLD,
900 const double drop_tolerance = 1e-13,
901 const bool copy_values = true,
902 const ::dealii::SparsityPattern *use_this_sparsity = nullptr);
903 /** @} */
904 /**
905 * @name Information on the matrix
906 */
907 /** @{ */
908
909 /**
910 * Return the number of rows in this matrix.
911 */
912 size_type
913 m() const;
914
915 /**
916 * Return the number of columns in this matrix.
917 */
918 size_type
919 n() const;
920
921 /**
922 * Return the local dimension of the matrix, i.e. the number of rows
923 * stored on the present MPI process. For sequential matrices, this number
924 * is the same as m(), but for %parallel matrices it may be smaller.
925 *
926 * To figure out which elements exactly are stored locally, use
927 * local_range().
928 */
929 unsigned int
930 local_size() const;
931
932 /**
933 * Return a pair of indices indicating which rows of this matrix are
934 * stored locally. The first number is the index of the first row stored,
935 * the second the index of the one past the last one that is stored
936 * locally. If this is a sequential matrix, then the result will be the
937 * pair (0,m()), otherwise it will be a pair (i,i+n), where
938 * <tt>n=local_size()</tt>.
939 */
940 std::pair<size_type, size_type>
941 local_range() const;
942
943 /**
944 * Return whether @p index is in the local range or not, see also
945 * local_range().
946 */
947 bool
948 in_local_range(const size_type index) const;
949
950 /**
951 * Return the total number of nonzero elements of this matrix (summed
952 * over all MPI processes).
953 */
954 std::uint64_t
955 n_nonzero_elements() const;
956
957 /**
958 * Number of entries in a specific row.
959 */
960 unsigned int
961 row_length(const size_type row) const;
962
963 /**
964 * Return the state of the matrix, i.e., whether compress() needs to be
965 * called after an operation requiring data exchange. A call to compress()
966 * is also needed when the method set() has been called (even when working
967 * in serial).
968 */
969 bool
970 is_compressed() const;
971
972 /**
973 * Determine an estimate for the memory consumption (in bytes) of this
974 * object. Note that only the memory reserved on the current processor is
975 * returned in case this is called in an MPI-based program.
976 */
977 size_type
978 memory_consumption() const;
979
980 /**
981 * Return the underlying MPI communicator.
982 */
983 MPI_Comm
984 get_mpi_communicator() const;
985
986 /** @} */
987 /**
988 * @name Modifying entries
989 */
990 /** @{ */
991
992 /**
993 * This operator assigns a scalar to a matrix. Since this does usually not
994 * make much sense (should we set all matrix entries to this value? Only
995 * the nonzero entries of the sparsity pattern?), this operation is only
996 * allowed if the actual value to be assigned is zero. This operator only
997 * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
998 * all elements of the matrix to zero, but keeps the sparsity pattern
999 * previously used.
1000 */
1001 SparseMatrix &
1002 operator=(const double d);
1003
1004 /**
1005 * Release all memory and return to a state just like after having called
1006 * the default constructor.
1007 *
1008 * This is a @ref GlossCollectiveOperation "collective operation" that needs to be called on all
1009 * processors in order to avoid a dead lock.
1010 */
1011 void
1012 clear();
1013
1014 /**
1015 * This command does two things:
1016 * <ul>
1017 * <li> If the matrix was initialized without a sparsity pattern, elements
1018 * have been added manually using the set() command. When this process is
1019 * completed, a call to compress() reorganizes the internal data
1020 * structures (sparsity pattern) so that a fast access to data is possible
1021 * in matrix-vector products.
1022 * <li> If the matrix structure has already been fixed (either by
1023 * initialization with a sparsity pattern or by calling compress() during
1024 * the setup phase), this command does the %parallel exchange of data.
1025 * This is necessary when we perform assembly on more than one (MPI)
1026 * process, because then some non-local row data will accumulate on nodes
1027 * that belong to the current's processor element, but are actually held
1028 * by another. This command is usually called after all elements have been
1029 * traversed.
1030 * </ul>
1031 *
1032 * In both cases, this function compresses the data structures and allows
1033 * the resulting matrix to be used in all other operations like
1034 * matrix-vector products. This is a @ref GlossCollectiveOperation "collective operation", i.e., it needs to
1035 * be run on all processors when used in %parallel.
1036 *
1037 * See
1038 * @ref GlossCompress "Compressing distributed objects"
1039 * for more information.
1040 */
1041 void
1042 compress(VectorOperation::values operation);
1043
1044 /**
1045 * Set the element (<i>i,j</i>) to @p value.
1046 *
1047 * This function is able to insert new elements into the matrix as long as
1048 * compress() has not been called, so the sparsity pattern will be
1049 * extended. When compress() is called for the first time (or in case the
1050 * matrix is initialized from a sparsity pattern), no new elements can be
1051 * added and an insertion of elements at positions which have not been
1052 * initialized will throw an exception.
1053 *
1054 * For the case that the matrix is constructed without a sparsity pattern
1055 * and new matrix entries are added on demand, please note the following
1056 * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
1057 * If the same matrix entry is inserted more than once, the matrix entries
1058 * will be added upon calling compress() (since Epetra does not track
1059 * values to the same entry before the final compress() is called), even
1060 * if VectorOperation::insert is specified as argument to compress(). In
1061 * the case you cannot make sure that matrix entries are only set once,
1062 * initialize the matrix with a sparsity pattern to fix the matrix
1063 * structure before inserting elements.
1064 */
1065 void
1066 set(const size_type i, const size_type j, const TrilinosScalar value);
1067
1068 /**
1069 * Set all elements given in a FullMatrix<double> into the sparse matrix
1070 * locations given by <tt>indices</tt>. In other words, this function
1071 * writes the elements in <tt>full_matrix</tt> into the calling matrix,
1072 * using the local-to-global indexing specified by <tt>indices</tt> for
1073 * both the rows and the columns of the matrix. This function assumes a
1074 * quadratic sparse matrix and a quadratic full_matrix, the usual
1075 * situation in FE calculations.
1076 *
1077 * This function is able to insert new elements into the matrix as long as
1078 * compress() has not been called, so the sparsity pattern will be
1079 * extended. After compress() has been called for the first time or the
1080 * matrix has been initialized from a sparsity pattern, extending the
1081 * sparsity pattern is no longer possible and an insertion of elements at
1082 * positions which have not been initialized will throw an exception.
1083 *
1084 * The optional parameter <tt>elide_zero_values</tt> can be used to
1085 * specify whether zero values should be inserted anyway or they should be
1086 * filtered away. The default value is <tt>false</tt>, i.e., even zero
1087 * values are inserted/replaced.
1088 *
1089 * For the case that the matrix is constructed without a sparsity pattern
1090 * and new matrix entries are added on demand, please note the following
1091 * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
1092 * If the same matrix entry is inserted more than once, the matrix entries
1093 * will be added upon calling compress() (since Epetra does not track
1094 * values to the same entry before the final compress() is called), even
1095 * if VectorOperation::insert is specified as argument to compress(). In
1096 * the case you cannot make sure that matrix entries are only set once,
1097 * initialize the matrix with a sparsity pattern to fix the matrix
1098 * structure before inserting elements.
1099 */
1100 void
1101 set(const std::vector<size_type> &indices,
1102 const FullMatrix<TrilinosScalar> &full_matrix,
1103 const bool elide_zero_values = false);
1104
1105 /**
1106 * Same function as before, but now including the possibility to use
1107 * rectangular full_matrices and different local-to-global indexing on
1108 * rows and columns, respectively.
1109 */
1110 void
1111 set(const std::vector<size_type> &row_indices,
1112 const std::vector<size_type> &col_indices,
1113 const FullMatrix<TrilinosScalar> &full_matrix,
1114 const bool elide_zero_values = false);
1115
1116 /**
1117 * Set several elements in the specified row of the matrix with column
1118 * indices as given by <tt>col_indices</tt> to the respective value.
1119 *
1120 * This function is able to insert new elements into the matrix as long as
1121 * compress() has not been called, so the sparsity pattern will be
1122 * extended. After compress() has been called for the first time or the
1123 * matrix has been initialized from a sparsity pattern, extending the
1124 * sparsity pattern is no longer possible and an insertion of elements at
1125 * positions which have not been initialized will throw an exception.
1126 *
1127 * The optional parameter <tt>elide_zero_values</tt> can be used to
1128 * specify whether zero values should be inserted anyway or they should be
1129 * filtered away. The default value is <tt>false</tt>, i.e., even zero
1130 * values are inserted/replaced.
1131 *
1132 * For the case that the matrix is constructed without a sparsity pattern
1133 * and new matrix entries are added on demand, please note the following
1134 * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
1135 * If the same matrix entry is inserted more than once, the matrix entries
1136 * will be added upon calling compress() (since Epetra does not track
1137 * values to the same entry before the final compress() is called), even
1138 * if VectorOperation::insert is specified as argument to compress(). In
1139 * the case you cannot make sure that matrix entries are only set once,
1140 * initialize the matrix with a sparsity pattern to fix the matrix
1141 * structure before inserting elements.
1142 */
1143 void
1144 set(const size_type row,
1145 const std::vector<size_type> &col_indices,
1146 const std::vector<TrilinosScalar> &values,
1147 const bool elide_zero_values = false);
1148
1149 /**
1150 * Set several elements to values given by <tt>values</tt> in a given row
1151 * in columns given by col_indices into the sparse matrix.
1152 *
1153 * This function is able to insert new elements into the matrix as long as
1154 * compress() has not been called, so the sparsity pattern will be
1155 * extended. After compress() has been called for the first time or the
1156 * matrix has been initialized from a sparsity pattern, extending the
1157 * sparsity pattern is no longer possible and an insertion of elements at
1158 * positions which have not been initialized will throw an exception.
1159 *
1160 * The optional parameter <tt>elide_zero_values</tt> can be used to
1161 * specify whether zero values should be inserted anyway or they should be
1162 * filtered away. The default value is <tt>false</tt>, i.e., even zero
1163 * values are inserted/replaced.
1164 *
1165 * For the case that the matrix is constructed without a sparsity pattern
1166 * and new matrix entries are added on demand, please note the following
1167 * behavior imposed by the underlying Epetra_FECrsMatrix data structure:
1168 * If the same matrix entry is inserted more than once, the matrix entries
1169 * will be added upon calling compress() (since Epetra does not track
1170 * values to the same entry before the final compress() is called), even
1171 * if VectorOperation::insert is specified as argument to compress(). In
1172 * the case you cannot make sure that matrix entries are only set once,
1173 * initialize the matrix with a sparsity pattern to fix the matrix
1174 * structure before inserting elements.
1175 */
1176 template <typename Number>
1177 void
1178 set(const size_type row,
1179 const size_type n_cols,
1180 const size_type *col_indices,
1181 const Number *values,
1182 const bool elide_zero_values = false);
1183
1184 /**
1185 * Add @p value to the element (<i>i,j</i>).
1186 *
1187 * Just as the respective call in deal.II SparseMatrix<Number> class (but
1188 * in contrast to the situation for PETSc based matrices), this function
1189 * throws an exception if an entry does not exist in the sparsity pattern.
1190 * Moreover, if <tt>value</tt> is not a finite number an exception is
1191 * thrown.
1192 */
1193 void
1194 add(const size_type i, const size_type j, const TrilinosScalar value);
1195
1196 /**
1197 * Add all elements given in a FullMatrix<double> into sparse matrix
1198 * locations given by <tt>indices</tt>. In other words, this function adds
1199 * the elements in <tt>full_matrix</tt> to the respective entries in
1200 * calling matrix, using the local-to-global indexing specified by
1201 * <tt>indices</tt> for both the rows and the columns of the matrix. This
1202 * function assumes a quadratic sparse matrix and a quadratic full_matrix,
1203 * the usual situation in FE calculations.
1204 *
1205 * Just as the respective call in deal.II SparseMatrix<Number> class (but
1206 * in contrast to the situation for PETSc based matrices), this function
1207 * throws an exception if an entry does not exist in the sparsity pattern.
1208 *
1209 * The optional parameter <tt>elide_zero_values</tt> can be used to
1210 * specify whether zero values should be added anyway or these should be
1211 * filtered away and only non-zero data is added. The default value is
1212 * <tt>true</tt>, i.e., zero values won't be added into the matrix.
1213 */
1214 void
1215 add(const std::vector<size_type> &indices,
1216 const FullMatrix<TrilinosScalar> &full_matrix,
1217 const bool elide_zero_values = true);
1218
1219 /**
1220 * Same function as before, but now including the possibility to use
1221 * rectangular full_matrices and different local-to-global indexing on
1222 * rows and columns, respectively.
1223 */
1224 void
1225 add(const std::vector<size_type> &row_indices,
1226 const std::vector<size_type> &col_indices,
1227 const FullMatrix<TrilinosScalar> &full_matrix,
1228 const bool elide_zero_values = true);
1229
1230 /**
1231 * Set several elements in the specified row of the matrix with column
1232 * indices as given by <tt>col_indices</tt> to the respective value.
1233 *
1234 * Just as the respective call in deal.II SparseMatrix<Number> class (but
1235 * in contrast to the situation for PETSc based matrices), this function
1236 * throws an exception if an entry does not exist in the sparsity pattern.
1237 *
1238 * The optional parameter <tt>elide_zero_values</tt> can be used to
1239 * specify whether zero values should be added anyway or these should be
1240 * filtered away and only non-zero data is added. The default value is
1241 * <tt>true</tt>, i.e., zero values won't be added into the matrix.
1242 */
1243 void
1244 add(const size_type row,
1245 const std::vector<size_type> &col_indices,
1246 const std::vector<TrilinosScalar> &values,
1247 const bool elide_zero_values = true);
1248
1249 /**
1250 * Add an array of values given by <tt>values</tt> in the given global
1251 * matrix row at columns specified by col_indices in the sparse matrix.
1252 *
1253 * Just as the respective call in deal.II SparseMatrix<Number> class (but
1254 * in contrast to the situation for PETSc based matrices), this function
1255 * throws an exception if an entry does not exist in the sparsity pattern.
1256 *
1257 * The optional parameter <tt>elide_zero_values</tt> can be used to
1258 * specify whether zero values should be added anyway or these should be
1259 * filtered away and only non-zero data is added. The default value is
1260 * <tt>true</tt>, i.e., zero values won't be added into the matrix.
1261 */
1262 void
1263 add(const size_type row,
1264 const size_type n_cols,
1265 const size_type *col_indices,
1266 const TrilinosScalar *values,
1267 const bool elide_zero_values = true,
1268 const bool col_indices_are_sorted = false);
1269
1270 /**
1271 * Multiply the entire matrix by a fixed factor.
1272 */
1273 SparseMatrix &
1274 operator*=(const TrilinosScalar factor);
1275
1276 /**
1277 * Divide the entire matrix by a fixed factor.
1278 */
1279 SparseMatrix &
1280 operator/=(const TrilinosScalar factor);
1281
1282 /**
1283 * Copy the given (Trilinos) matrix (sparsity pattern and entries).
1284 */
1285 void
1286 copy_from(const SparseMatrix &source);
1287
1288 /**
1289 * Add <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
1290 * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. If the
1291 * sparsity pattern of the calling matrix does not contain all the
1292 * elements in the sparsity pattern of the input matrix, this function
1293 * will throw an exception.
1294 */
1295 void
1296 add(const TrilinosScalar factor, const SparseMatrix &matrix);
1297
1298 /**
1299 * Remove all elements from this <tt>row</tt> by setting them to zero. The
1300 * function does not modify the number of allocated nonzero entries, it
1301 * only sets the entries to zero.
1302 *
1303 * This operation is used in eliminating constraints (e.g. due to hanging
1304 * nodes) and makes sure that we can write this modification to the matrix
1305 * without having to read entries (such as the locations of non-zero
1306 * elements) from it &mdash; without this operation, removing constraints
1307 * on %parallel matrices is a rather complicated procedure.
1308 *
1309 * The second parameter can be used to set the diagonal entry of this row
1310 * to a value different from zero. The default is to set it to zero.
1311 *
1312 * @note If the matrix is stored in parallel across multiple processors
1313 * using MPI, this function only touches rows that are locally stored and
1314 * simply ignores all other row indices. Further, in the context of
1315 * parallel computations, you will get into trouble if you clear a row
1316 * while other processors still have pending writes or additions into the
1317 * same row. In other words, if another processor still wants to add
1318 * something to an element of a row and you call this function to zero out
1319 * the row, then the next time you call compress() may add the remote
1320 * value to the zero you just created. Consequently, you will want to call
1321 * compress() after you made the last modifications to a matrix and before
1322 * starting to clear rows.
1323 */
1324 void
1325 clear_row(const size_type row, const TrilinosScalar new_diag_value = 0);
1326
1327 /**
1328 * Same as clear_row(), except that it works on a number of rows at once.
1329 *
1330 * The second parameter can be used to set the diagonal entries of all
1331 * cleared rows to something different from zero. Note that all of these
1332 * diagonal entries get the same value -- if you want different values for
1333 * the diagonal entries, you have to set them by hand.
1334 *
1335 * @note If the matrix is stored in parallel across multiple processors
1336 * using MPI, this function only touches rows that are locally stored and
1337 * simply ignores all other row indices. Further, in the context of
1338 * parallel computations, you will get into trouble if you clear a row
1339 * while other processors still have pending writes or additions into the
1340 * same row. In other words, if another processor still wants to add
1341 * something to an element of a row and you call this function to zero out
1342 * the row, then the next time you call compress() may add the remote
1343 * value to the zero you just created. Consequently, you will want to call
1344 * compress() after you made the last modifications to a matrix and before
1345 * starting to clear rows.
1346 */
1347 void
1348 clear_rows(const ArrayView<const size_type> &rows,
1349 const TrilinosScalar new_diag_value = 0);
1350
1351 /**
1352 * Sets an internal flag so that all operations performed by the matrix,
1353 * i.e., multiplications, are done in transposed order. However, this does
1354 * not reshape the matrix to transposed form directly, so care should be
1355 * taken when using this flag.
1356 *
1357 * @note Calling this function any even number of times in succession will
1358 * return the object to its original state.
1359 */
1360 void
1361 transpose();
1362
1363 /** @} */
1364 /**
1365 * @name Entry Access
1366 */
1367 /** @{ */
1368
1369 /**
1370 * Return the value of the entry (<i>i,j</i>). This may be an expensive
1371 * operation and you should always take care where to call this function.
1372 * As in the deal.II sparse matrix class, we throw an exception if the
1373 * respective entry doesn't exist in the sparsity pattern of this class,
1374 * which is requested from Trilinos. Moreover, an exception will be thrown
1375 * when the requested element is not saved on the calling process.
1376 */
1377 TrilinosScalar
1378 operator()(const size_type i, const size_type j) const;
1379
1380 /**
1381 * Return the value of the matrix entry (<i>i,j</i>). If this entry does
1382 * not exist in the sparsity pattern, then zero is returned. While this
1383 * may be convenient in some cases, note that it is simple to write
1384 * algorithms that are slow compared to an optimal solution, since the
1385 * sparsity of the matrix is not used. On the other hand, if you want to
1386 * be sure the entry exists, you should use operator() instead.
1387 *
1388 * The lack of error checking in this function can also yield surprising
1389 * results if you have a parallel matrix. In that case, just because you
1390 * get a zero result from this function does not mean that either the
1391 * entry does not exist in the sparsity pattern or that it does but has a
1392 * value of zero. Rather, it could also be that it simply isn't stored on
1393 * the current processor; in that case, it may be stored on a different
1394 * processor, and possibly so with a nonzero value.
1395 */
1396 TrilinosScalar
1397 el(const size_type i, const size_type j) const;
1398
1399 /**
1400 * Return the main diagonal element in the <i>i</i>th row. This function
1401 * throws an error if the matrix is not quadratic and it also throws an
1402 * error if <i>(i,i)</i> is not element of the local matrix. See also the
1403 * comment in trilinos_sparse_matrix.cc.
1404 */
1405 TrilinosScalar
1406 diag_element(const size_type i) const;
1407
1408 /** @} */
1409 /**
1410 * @name Multiplications
1411 */
1412 /** @{ */
1413
1414 /**
1415 * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
1416 * being this matrix.
1417 *
1418 * Source and destination must not be the same vector.
1419 *
1420 * This function can be called with several types of vector objects,
1421 * namely @p VectorType can be
1422 * <ul>
1423 * <li> TrilinosWrappers::MPI::Vector,
1424 * <li> LinearAlgebra::EpetraWrappers::Vector,
1425 * <li> LinearAlgebra::TpetraWrappers::Vector,
1426 * <li> Vector<double>,
1427 * <li> LinearAlgebra::distributed::Vector<double>.
1428 * </ul>
1429 *
1430 * When using vectors of type TrilinosWrappers::MPI::Vector, the vector
1431 * @p dst has to be initialized with the same IndexSet that was used for
1432 * the row indices of the matrix and the vector @p src has to be
1433 * initialized with the same IndexSet that was used for the column indices
1434 * of the matrix.
1435 *
1436 * This function will be called when the underlying number type for the
1437 * matrix object and the one for the vector object are the same.
1438 * Despite looking complicated, the return type is just `void`.
1439 *
1440 * In case of a serial vector, this function will only work when
1441 * running on one processor, since the matrix object is inherently
1442 * distributed. Otherwise, an exception will be thrown.
1443 */
1444 template <typename VectorType>
1445 std::enable_if_t<
1446 std::is_same_v<typename VectorType::value_type, TrilinosScalar>>
1447 vmult(VectorType &dst, const VectorType &src) const;
1448
1449 /**
1450 * Same as the function above for the case that the underlying number type
1451 * for the matrix object and the one for the vector object do not coincide.
1452 * This case is not implemented. Calling it will result in a runtime error.
1453 * Despite looking complicated, the return type is just `void`.
1454 */
1455 template <typename VectorType>
1456 std::enable_if_t<
1457 !std::is_same_v<typename VectorType::value_type, TrilinosScalar>>
1458 vmult(VectorType &dst, const VectorType &src) const;
1459
1460 /**
1461 * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
1462 * <i>M</i> being this matrix. This function does the same as vmult() but
1463 * takes the transposed matrix.
1464 *
1465 * Source and destination must not be the same vector.
1466 *
1467 * This function can be called with several types of vector objects,
1468 * see the discussion about @p VectorType in vmult().
1469 *
1470 * This function will be called when the underlying number type for the
1471 * matrix object and the one for the vector object are the same.
1472 * Despite looking complicated, the return type is just `void`.
1473 */
1474 template <typename VectorType>
1475 std::enable_if_t<
1476 std::is_same_v<typename VectorType::value_type, TrilinosScalar>>
1477 Tvmult(VectorType &dst, const VectorType &src) const;
1478
1479 /**
1480 * Same as the function above for the case that the underlying number type
1481 * for the matrix object and the one for the vector object do not coincide.
1482 * This case is not implemented. Calling it will result in a runtime error.
1483 * Despite looking complicated, the return type is just `void`.
1484 */
1485 template <typename VectorType>
1486 std::enable_if_t<
1487 !std::is_same_v<typename VectorType::value_type, TrilinosScalar>>
1488 Tvmult(VectorType &dst, const VectorType &src) const;
1489
1490 /**
1491 * Adding matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
1492 * with <i>M</i> being this matrix.
1493 *
1494 * Source and destination must not be the same vector.
1495 *
1496 * This function can be called with several types of vector objects,
1497 * see the discussion about @p VectorType in vmult().
1498 */
1499 template <typename VectorType>
1500 void
1501 vmult_add(VectorType &dst, const VectorType &src) const;
1502
1503 /**
1504 * Adding matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
1505 * <i>dst</i> with <i>M</i> being this matrix. This function does the same
1506 * as vmult_add() but takes the transposed matrix.
1507 *
1508 * Source and destination must not be the same vector.
1509 *
1510 * This function can be called with several types of vector objects,
1511 * see the discussion about @p VectorType in vmult().
1512 */
1513 template <typename VectorType>
1514 void
1515 Tvmult_add(VectorType &dst, const VectorType &src) const;
1516
1517 /**
1518 * Return the square of the norm of the vector $v$ with respect to the
1519 * norm induced by this matrix, i.e., $\left(v,Mv\right)$. This is useful,
1520 * e.g. in the finite element context, where the $L_2$ norm of a function
1521 * equals the matrix norm with respect to the @ref GlossMassMatrix "mass matrix" of the vector
1522 * representing the nodal values of the finite element function.
1523 *
1524 * Obviously, the matrix needs to be quadratic for this operation.
1525 *
1526 * The implementation of this function is not as efficient as the one in
1527 * the @p SparseMatrix class used in deal.II (i.e. the original one, not
1528 * the Trilinos wrapper class) since Trilinos doesn't support this
1529 * operation and needs a temporary vector.
1530 *
1531 * The vector has to be initialized with the same IndexSet the matrix
1532 * was initialized with.
1533 *
1534 * In case of a localized Vector, this function will only work when
1535 * running on one processor, since the matrix object is inherently
1536 * distributed. Otherwise, an exception will be thrown.
1537 */
1538 TrilinosScalar
1539 matrix_norm_square(const MPI::Vector &v) const;
1540
1541 /**
1542 * Compute the matrix scalar product $\left(u,Mv\right)$.
1543 *
1544 * The implementation of this function is not as efficient as the one in
1545 * the @p SparseMatrix class used in deal.II (i.e. the original one, not
1546 * the Trilinos wrapper class) since Trilinos doesn't support this
1547 * operation and needs a temporary vector.
1548 *
1549 * The vector @p u has to be initialized with the same IndexSet that
1550 * was used for the row indices of the matrix and the vector @p v has
1551 * to be initialized with the same IndexSet that was used for the
1552 * column indices of the matrix.
1553 *
1554 * In case of a localized Vector, this function will only work when
1555 * running on one processor, since the matrix object is inherently
1556 * distributed. Otherwise, an exception will be thrown.
1557 *
1558 * This function is only implemented for square matrices.
1559 */
1560 TrilinosScalar
1561 matrix_scalar_product(const MPI::Vector &u, const MPI::Vector &v) const;
1562
1563 /**
1564 * Compute the residual of an equation <i>Mx=b</i>, where the residual is
1565 * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
1566 * <i>l<sub>2</sub></i> norm of the residual vector is returned.
1567 *
1568 * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
1569 *
1570 * The vectors @p dst and @p b have to be initialized with the same
1571 * IndexSet that was used for the row indices of the matrix and the vector
1572 * @p x has to be initialized with the same IndexSet that was used for the
1573 * column indices of the matrix.
1574 *
1575 * In case of a localized Vector, this function will only work when
1576 * running on one processor, since the matrix object is inherently
1577 * distributed. Otherwise, an exception will be thrown.
1578 */
1579 template <typename VectorType>
1580 TrilinosScalar
1581 residual(VectorType &dst, const VectorType &x, const VectorType &b) const;
1582
1583 /**
1584 * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
1585 * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
1586 * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
1587 *
1588 * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
1589 * have compatible sizes. The size of <tt>C</tt> will be set within this
1590 * function.
1591 *
1592 * The content as well as the sparsity pattern of the matrix C will be
1593 * changed by this function, so make sure that the sparsity pattern is not
1594 * used somewhere else in your program. This is an expensive operation, so
1595 * think twice before you use this function.
1596 */
1597 void
1598 mmult(SparseMatrix &C,
1599 const SparseMatrix &B,
1600 const MPI::Vector &V = MPI::Vector()) const;
1601
1602
1603 /**
1604 * Perform the matrix-matrix multiplication with the transpose of
1605 * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
1606 * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>,
1607 * where <tt>diag(V)</tt> defines a diagonal matrix with the vector
1608 * entries.
1609 *
1610 * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
1611 * have compatible sizes. The size of <tt>C</tt> will be set within this
1612 * function.
1613 *
1614 * The content as well as the sparsity pattern of the matrix C will be
1615 * changed by this function, so make sure that the sparsity pattern is not
1616 * used somewhere else in your program. This is an expensive operation, so
1617 * think twice before you use this function.
1618 */
1619 void
1620 Tmmult(SparseMatrix &C,
1621 const SparseMatrix &B,
1622 const MPI::Vector &V = MPI::Vector()) const;
1623
1624 /** @} */
1625 /**
1626 * @name Matrix norms
1627 */
1628 /** @{ */
1629
1630 /**
1631 * Return the <i>l</i><sub>1</sub>-norm of the matrix, that is $|M|_1=
1632 * \max_{\mathrm{all\ columns\ } j} \sum_{\mathrm{all\ rows\ } i}
1633 * |M_{ij}|$, (max. sum of columns). This is the natural matrix norm that
1634 * is compatible to the l1-norm for vectors, i.e. $|Mv|_1 \leq |M|_1
1635 * |v|_1$. (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
1636 */
1637 TrilinosScalar
1638 l1_norm() const;
1639
1640 /**
1641 * Return the linfty-norm of the matrix, that is
1642 * $|M|_\infty=\max_{\mathrm{all\ rows\ } i}\sum_{\mathrm{all\ columns\ }
1643 * j} |M_{ij}|$, (max. sum of rows). This is the natural matrix norm that
1644 * is compatible to the linfty-norm of vectors, i.e. $|Mv|_\infty \leq
1645 * |M|_\infty |v|_\infty$. (cf. Haemmerlin-Hoffmann: Numerische
1646 * Mathematik)
1647 */
1648 TrilinosScalar
1649 linfty_norm() const;
1650
1651 /**
1652 * Return the frobenius norm of the matrix, i.e. the square root of the
1653 * sum of squares of all entries in the matrix.
1654 */
1655 TrilinosScalar
1656 frobenius_norm() const;
1657
1658 /** @} */
1659 /**
1660 * @name Access to underlying Trilinos data
1661 */
1662 /** @{ */
1663
1664 /**
1665 * Return a const reference to the underlying Trilinos Epetra_CrsMatrix
1666 * data.
1667 */
1668 const Epetra_CrsMatrix &
1669 trilinos_matrix() const;
1670
1671 /**
1672 * Return a const reference to the underlying Trilinos Epetra_CrsGraph
1673 * data that stores the sparsity pattern of the matrix.
1674 */
1675 const Epetra_CrsGraph &
1676 trilinos_sparsity_pattern() const;
1677
1678 /** @} */
1679
1680 /**
1681 * @name Partitioners
1682 */
1683 /** @{ */
1684
1685 /**
1686 * Return the partitioning of the domain space of this matrix, i.e., the
1687 * partitioning of the vectors this matrix has to be multiplied with.
1688 */
1689 IndexSet
1690 locally_owned_domain_indices() const;
1691
1692 /**
1693 * Return the partitioning of the range space of this matrix, i.e., the
1694 * partitioning of the vectors that are result from matrix-vector
1695 * products.
1696 */
1697 IndexSet
1698 locally_owned_range_indices() const;
1699
1700 /** @} */
1701
1702 /**
1703 * @name Iterators
1704 */
1705 /** @{ */
1706
1707 /**
1708 * Return an iterator pointing to the first element of the matrix.
1709 *
1710 * The elements accessed by iterators within each row are ordered in the
1711 * way in which Trilinos stores them, though the implementation guarantees
1712 * that all elements of one row are accessed before the elements of the
1713 * next row. If your algorithm relies on visiting elements within one row,
1714 * you will need to consult with the Trilinos documentation on the order
1715 * in which it stores data. It is, however, generally not a good and
1716 * long-term stable idea to rely on the order in which receive elements if
1717 * you iterate over them.
1718 *
1719 * When you iterate over the elements of a parallel matrix, you will only
1720 * be able to access the locally owned rows. (You can access the other
1721 * rows as well, but they will look empty.) In that case, you probably
1722 * want to call the begin() function that takes the row as an argument to
1723 * limit the range of elements to loop over.
1724 */
1725 const_iterator
1726 begin() const;
1727
1728 /**
1729 * Like the function above, but for non-const matrices.
1730 */
1731 iterator
1732 begin();
1733
1734 /**
1735 * Return an iterator pointing the element past the last one of this
1736 * matrix.
1737 */
1738 const_iterator
1739 end() const;
1740
1741 /**
1742 * Like the function above, but for non-const matrices.
1743 */
1744 iterator
1745 end();
1746
1747 /**
1748 * Return an iterator pointing to the first element of row @p r.
1749 *
1750 * Note that if the given row is empty, i.e. does not contain any nonzero
1751 * entries, then the iterator returned by this function equals
1752 * <tt>end(r)</tt>. The returned iterator may not be dereferenceable in
1753 * that case if neither row @p r nor any of the following rows contain any
1754 * nonzero entries.
1755 *
1756 * The elements accessed by iterators within each row are ordered in the
1757 * way in which Trilinos stores them, though the implementation guarantees
1758 * that all elements of one row are accessed before the elements of the
1759 * next row. If your algorithm relies on visiting elements within one row,
1760 * you will need to consult with the Trilinos documentation on the order
1761 * in which it stores data. It is, however, generally not a good and
1762 * long-term stable idea to rely on the order in which receive elements if
1763 * you iterate over them.
1764 *
1765 * @note When you access the elements of a parallel matrix, you can only
1766 * access the elements of rows that are actually stored locally. (You can
1767 * access the other rows as well, but they will look empty.) Even then, if
1768 * another processor has since written into, or added to, an element of
1769 * the matrix that is stored on the current processor, then you will still
1770 * see the old value of this entry unless you have called compress()
1771 * between modifying the matrix element on the remote processor and
1772 * accessing it on the current processor. See the documentation of the
1773 * compress() function for more information.
1774 */
1775 const_iterator
1776 begin(const size_type r) const;
1777
1778 /**
1779 * Like the function above, but for non-const matrices.
1780 */
1781 iterator
1782 begin(const size_type r);
1783
1784 /**
1785 * Return an iterator pointing the element past the last one of row @p r ,
1786 * or past the end of the entire sparsity pattern if none of the rows
1787 * after @p r contain any entries at all.
1788 *
1789 * Note that the end iterator is not necessarily dereferenceable. This is
1790 * in particular the case if it is the end iterator for the last row of a
1791 * matrix.
1792 */
1793 const_iterator
1794 end(const size_type r) const;
1795
1796 /**
1797 * Like the function above, but for non-const matrices.
1798 */
1799 iterator
1800 end(const size_type r);
1801
1802 /** @} */
1803 /**
1804 * @name Input/Output
1805 */
1806 /** @{ */
1807
1808 /**
1809 * Abstract Trilinos object that helps view in ASCII other Trilinos
1810 * objects. Currently this function is not implemented. TODO: Not
1811 * implemented.
1812 */
1813 void
1814 write_ascii();
1815
1816 /**
1817 * Print the matrix to the given stream, using the format <tt>(line,col)
1818 * value</tt>, i.e. one nonzero entry of the matrix per line. The optional
1819 * flag outputs the sparsity pattern in Trilinos style, where the data is
1820 * sorted according to the processor number when printed to the stream, as
1821 * well as a summary of the matrix like the global size.
1822 */
1823 void
1824 print(std::ostream &out,
1825 const bool write_extended_trilinos_info = false) const;
1826
1827 /** @} */
1828 /**
1829 * @addtogroup Exceptions
1830 */
1831 /** @{ */
1832 /**
1833 * Exception
1834 */
1835 DeclException1(
1836 ExcTrilinosError,
1837 int,
1838 << "An error with error number " << arg1
1839 << " occurred while calling a Trilinos function. "
1840 "\n\n"
1841 "For historical reasons, many Trilinos functions express "
1842 "errors by returning specific integer values to indicate "
1843 "certain errors. Unfortunately, different Trilinos functions "
1844 "often use the same integer values for different kinds of "
1845 "errors, and in most cases it is also not documented what "
1846 "each error code actually means. As a consequence, it is often "
1847 "difficult to say what a particular error (in this case, "
1848 "the error with integer code '"
1849 << arg1
1850 << "') represents and how one should fix a code to avoid it. "
1851 "The best one can often do is to look up the call stack to "
1852 "see which deal.II function generated the error, and which "
1853 "Trilinos function the error code had originated from; "
1854 "then look up the Trilinos source code of that function (for "
1855 "example on github) to see what code path set that error "
1856 "code. Short of going through all of that, the only other "
1857 "option is to guess the cause of the error from "
1858 "the context in which the error appeared.");
1859
1860
1861 /**
1862 * Exception
1863 */
1864 DeclException2(ExcInvalidIndex,
1865 size_type,
1866 size_type,
1867 << "The entry with index <" << arg1 << ',' << arg2
1868 << "> does not exist.");
1869
1870 /**
1871 * Exception
1872 */
1873 DeclExceptionMsg(ExcSourceEqualsDestination,
1874 "You are attempting an operation on two vectors that "
1875 "are the same object, but the operation requires that the "
1876 "two objects are in fact different.");
1877
1878 /**
1879 * Exception
1880 */
1881 DeclException0(ExcMatrixNotCompressed);
1882
1883 /**
1884 * Exception
1885 */
1886 DeclException4(ExcAccessToNonLocalElement,
1887 size_type,
1888 size_type,
1889 size_type,
1890 size_type,
1891 << "You tried to access element (" << arg1 << '/' << arg2
1892 << ')'
1893 << " of a distributed matrix, but only rows in range ["
1894 << arg3 << ',' << arg4
1895 << "] are stored locally and can be accessed.");
1896
1897 /**
1898 * Exception
1899 */
1900 DeclException2(ExcAccessToNonPresentElement,
1901 size_type,
1902 size_type,
1903 << "You tried to access element (" << arg1 << '/' << arg2
1904 << ')' << " of a sparse matrix, but it appears to not"
1905 << " exist in the Trilinos sparsity pattern.");
1906 /** @} */
1907
1908
1909
1910 protected:
1911 private:
1912 /**
1913 * Pointer to the user-supplied Epetra Trilinos mapping of the matrix
1914 * columns that assigns parts of the matrix to the individual processes.
1915 */
1916 std::unique_ptr<Epetra_Map> column_space_map;
1917
1918 /**
1919 * A sparse matrix object in Trilinos to be used for finite element based
1920 * problems which allows for assembling into non-local elements. The
1921 * actual type, a sparse matrix, is set in the constructor.
1922 */
1923 std::unique_ptr<Epetra_FECrsMatrix> matrix;
1924
1925 /**
1926 * A sparse matrix object in Trilinos to be used for collecting the
1927 * non-local elements if the matrix was constructed from a Trilinos sparsity
1928 * pattern with the respective option.
1929 */
1930 std::unique_ptr<Epetra_CrsMatrix> nonlocal_matrix;
1931
1932 /**
1933 * An export object used to communicate the nonlocal matrix.
1934 */
1935 std::unique_ptr<Epetra_Export> nonlocal_matrix_exporter;
1936
1937 /**
1938 * Trilinos doesn't allow to mix additions to matrix entries and
1939 * overwriting them (to make synchronization of %parallel computations
1940 * simpler). The way we do it is to, for each access operation, store
1941 * whether it is an insertion or an addition. If the previous one was of
1942 * different type, then we first have to flush the Trilinos buffers;
1943 * otherwise, we can simply go on. Luckily, Trilinos has an object for
1944 * this which does already all the %parallel communications in such a
1945 * case, so we simply use their model, which stores whether the last
1946 * operation was an addition or an insertion.
1947 */
1948 Epetra_CombineMode last_action;
1949
1950 /**
1951 * A boolean variable to hold information on whether the vector is
1952 * compressed or not.
1953 */
1954 bool compressed;
1955
1956 /**
1957 * For some matrix storage formats, in particular for the PETSc
1958 * distributed blockmatrices, set and add operations on individual
1959 * elements can not be freely mixed. Rather, one has to synchronize
1960 * operations when one wants to switch from setting elements to adding to
1961 * elements. BlockMatrixBase automatically synchronizes the access by
1962 * calling this helper function for each block. This function ensures
1963 * that the matrix is in a state that allows adding elements; if it
1964 * previously already was in this state, the function does nothing.
1965 *
1966 * This function is called from BlockMatrixBase.
1967 */
1968 void
1969 prepare_add();
1970
1971 /**
1972 * Same as prepare_add() but prepare the matrix for setting elements if
1973 * the representation of elements in this class requires such an
1974 * operation.
1975 *
1976 * This function is called from BlockMatrixBase.
1977 */
1978 void
1979 prepare_set();
1980
1981 // To allow calling protected prepare_add() and prepare_set().
1982 friend class BlockMatrixBase<SparseMatrix>;
1983 };
1984
1985
1986
1987 // forwards declarations
1988 class SolverBase;
1989 class PreconditionBase;
1990
1991 namespace internal
1992 {
1993 inline void
1994 check_vector_map_equality(const Epetra_CrsMatrix &mtrx,
1995 const Epetra_MultiVector &src,
1996 const Epetra_MultiVector &dst,
1997 const bool transpose)
1998 {
1999 if (transpose == false)
2000 {
2001 Assert(src.Map().SameAs(mtrx.DomainMap()) == true,
2002 ExcMessage(
2003 "Column map of matrix does not fit with vector map!"));
2004 Assert(dst.Map().SameAs(mtrx.RangeMap()) == true,
2005 ExcMessage("Row map of matrix does not fit with vector map!"));
2006 }
2007 else
2008 {
2009 Assert(src.Map().SameAs(mtrx.RangeMap()) == true,
2010 ExcMessage(
2011 "Column map of matrix does not fit with vector map!"));
2012 Assert(dst.Map().SameAs(mtrx.DomainMap()) == true,
2013 ExcMessage("Row map of matrix does not fit with vector map!"));
2014 }
2015 }
2016
2017 inline void
2018 check_vector_map_equality(const Epetra_Operator &op,
2019 const Epetra_MultiVector &src,
2020 const Epetra_MultiVector &dst,
2021 const bool transpose)
2022 {
2023 if (transpose == false)
2024 {
2025 Assert(src.Map().SameAs(op.OperatorDomainMap()) == true,
2026 ExcMessage(
2027 "Column map of operator does not fit with vector map!"));
2028 Assert(dst.Map().SameAs(op.OperatorRangeMap()) == true,
2029 ExcMessage(
2030 "Row map of operator does not fit with vector map!"));
2031 }
2032 else
2033 {
2034 Assert(src.Map().SameAs(op.OperatorRangeMap()) == true,
2035 ExcMessage(
2036 "Column map of operator does not fit with vector map!"));
2037 Assert(dst.Map().SameAs(op.OperatorDomainMap()) == true,
2038 ExcMessage(
2039 "Row map of operator does not fit with vector map!"));
2040 }
2041 }
2042
2043
2044 namespace LinearOperatorImplementation
2045 {
2046 /**
2047 * This is an extension class to LinearOperators for Trilinos sparse
2048 * matrix and preconditioner types. It provides the interface to
2049 * performing basic operations (<tt>vmult</tt> and <tt>Tvmult</tt>) on
2050 * Trilinos vector types. It fulfills the requirements necessary for
2051 * wrapping a Trilinos solver, which calls Epetra_Operator functions, as a
2052 * LinearOperator.
2053 *
2054 * @note The TrilinosWrappers::SparseMatrix or
2055 * TrilinosWrappers::PreconditionBase that this payload wraps is passed by
2056 * reference to the <tt>vmult</tt> and <tt>Tvmult</tt> functions. This
2057 * object is not thread-safe when the transpose flag is set on it or the
2058 * Trilinos object to which it refers. See the documentation for the
2059 * TrilinosWrappers::internal::LinearOperatorImplementation::TrilinosPayload::SetUseTranspose()
2060 * function for further details.
2061 *
2062 *
2063 * @ingroup TrilinosWrappers
2064 */
2065 class TrilinosPayload : public Epetra_Operator
2066 {
2067 public:
2068 /**
2069 * Definition for the internally supported vector type.
2070 */
2071 using VectorType = Epetra_MultiVector;
2072
2073 /**
2074 * Definition for the vector type for the domain space of the operator.
2075 */
2076 using Range = VectorType;
2077
2078 /**
2079 * Definition for the vector type for the range space of the operator.
2080 */
2081 using Domain = VectorType;
2082
2083 /**
2084 * Index of the referenced element of the vector.
2085 */
2086 using size_type = dealii::types::global_dof_index;
2087
2088 /**
2089 * @name Constructors / destructor
2090 */
2091 /** @{ */
2092
2093 /**
2094 * Default constructor
2095 *
2096 * @note By design, the resulting object is inoperable since there is
2097 * insufficient information with which to construct the domain and
2098 * range maps.
2099 */
2100 TrilinosPayload();
2101
2102 /**
2103 * Constructor for a sparse matrix based on an exemplary matrix
2104 */
2105 TrilinosPayload(const TrilinosWrappers::SparseMatrix &matrix_exemplar,
2106 const TrilinosWrappers::SparseMatrix &matrix);
2107
2108 /**
2109 * Constructor for a sparse matrix based on an exemplary payload
2110 */
2111 TrilinosPayload(const TrilinosPayload &payload_exemplar,
2112 const TrilinosWrappers::SparseMatrix &matrix);
2113
2114 /**
2115 * Constructor for a preconditioner based on an exemplary matrix
2116 */
2117 TrilinosPayload(
2118 const TrilinosWrappers::SparseMatrix &matrix_exemplar,
2119 const TrilinosWrappers::PreconditionBase &preconditioner);
2120
2121 /**
2122 * Constructor for a preconditioner based on an exemplary preconditioner
2123 */
2124 TrilinosPayload(
2125 const TrilinosWrappers::PreconditionBase &preconditioner_exemplar,
2126 const TrilinosWrappers::PreconditionBase &preconditioner);
2127
2128 /**
2129 * Constructor for a preconditioner based on an exemplary payload
2130 */
2131 TrilinosPayload(
2132 const TrilinosPayload &payload_exemplar,
2133 const TrilinosWrappers::PreconditionBase &preconditioner);
2134
2135 /**
2136 * Default copy constructor
2137 */
2138 TrilinosPayload(const TrilinosPayload &payload);
2139
2140 /**
2141 * Composite copy constructor
2142 *
2143 * This is required for PackagedOperations as it sets up the domain and
2144 * range maps, and composite <tt>vmult</tt> and <tt>Tvmult</tt>
2145 * operations based on the combined operation of both operations
2146 */
2147 TrilinosPayload(const TrilinosPayload &first_op,
2148 const TrilinosPayload &second_op);
2149
2150 /**
2151 * Destructor
2152 */
2153 virtual ~TrilinosPayload() override = default;
2154
2155 /**
2156 * Return a payload configured for identity operations
2157 */
2158 TrilinosPayload
2159 identity_payload() const;
2160
2161 /**
2162 * Return a payload configured for null operations
2163 */
2164 TrilinosPayload
2165 null_payload() const;
2166
2167 /**
2168 * Return a payload configured for transpose operations
2169 */
2170 TrilinosPayload
2171 transpose_payload() const;
2172
2173 /**
2174 * Return a payload configured for inverse operations
2175 *
2176 * Invoking this factory function will configure two additional
2177 * functions, namely <tt>inv_vmult</tt> and <tt>inv_Tvmult</tt>, both of
2178 * which wrap inverse operations. The <tt>vmult</tt> and <tt>Tvmult</tt>
2179 * operations retain the standard
2180 * definitions inherited from @p op.
2181 *
2182 * @note This function is enabled only if the solver and preconditioner
2183 * derive from the respective TrilinosWrappers base classes.
2184 * The C++ compiler will therefore only consider this function if the
2185 * following criterion are satisfied:
2186 * 1. the @p Solver derives from TrilinosWrappers::SolverBase, and
2187 * 2. the @p Preconditioner derives from TrilinosWrappers::PreconditionBase.
2188 */
2189 template <typename Solver, typename Preconditioner>
2190 std::enable_if_t<
2191 std::is_base_of_v<TrilinosWrappers::SolverBase, Solver> &&
2192 std::is_base_of_v<TrilinosWrappers::PreconditionBase,
2193 Preconditioner>,
2194 TrilinosPayload>
2195 inverse_payload(Solver &, const Preconditioner &) const;
2196
2197 /**
2198 * Return a payload configured for inverse operations
2199 *
2200 * Invoking this factory function will configure two additional
2201 * functions, namely <tt>inv_vmult</tt> and <tt>inv_Tvmult</tt>, both of
2202 * which
2203 * are disabled because the @p Solver or @p Preconditioner are not
2204 * compatible with Epetra_MultiVector.
2205 * The <tt>vmult</tt> and <tt>Tvmult</tt> operations retain the standard
2206 * definitions inherited from @p op.
2207 *
2208 * @note The C++ compiler will only consider this function if the
2209 * following criterion are satisfied:
2210 * 1. the @p Solver does not derive from TrilinosWrappers::SolverBase, and
2211 * 2. the @p Preconditioner does not derive from
2212 * TrilinosWrappers::PreconditionBase.
2213 */
2214 template <typename Solver, typename Preconditioner>
2215 std::enable_if_t<
2216 !(std::is_base_of_v<TrilinosWrappers::SolverBase, Solver> &&
2217 std::is_base_of_v<TrilinosWrappers::PreconditionBase,
2218 Preconditioner>),
2219 TrilinosPayload>
2220 inverse_payload(Solver &, const Preconditioner &) const;
2221
2222 /** @} */
2223
2224 /**
2225 * @name LinearOperator functionality
2226 */
2227 /** @{ */
2228
2229 /**
2230 * Return an IndexSet that defines the partitioning of the domain space
2231 * of this matrix, i.e., the partitioning of the vectors this matrix has
2232 * to be multiplied with / operate on.
2233 */
2234 IndexSet
2235 locally_owned_domain_indices() const;
2236
2237 /**
2238 * Return an IndexSet that defines the partitioning of the range space
2239 * of this matrix, i.e., the partitioning of the vectors that result
2240 * from matrix-vector products.
2241 */
2242 IndexSet
2243 locally_owned_range_indices() const;
2244
2245 /**
2246 * Return the MPI communicator object in use with this Payload.
2247 */
2248 MPI_Comm
2249 get_mpi_communicator() const;
2250
2251 /**
2252 * Sets an internal flag so that all operations performed by the matrix,
2253 * i.e., multiplications, are done in transposed order.
2254 * @note This does not reshape the matrix to transposed form directly,
2255 * so care should be taken when using this flag.
2256 */
2257 void
2258 transpose();
2259
2260 /**
2261 * The standard matrix-vector operation to be performed by the payload
2262 * when Apply is called.
2263 *
2264 * @note This is not called by a LinearOperator, but rather by Trilinos
2265 * functions that expect this to mimic the action of the LinearOperator.
2266 */
2267 std::function<void(VectorType &, const VectorType &)> vmult;
2268
2269 /**
2270 * The standard transpose matrix-vector operation to be performed by
2271 * the payload when Apply is called.
2272 *
2273 * @note This is not called by a LinearOperator, but rather by Trilinos
2274 * functions that expect this to mimic the action of the LinearOperator.
2275 */
2276 std::function<void(VectorType &, const VectorType &)> Tvmult;
2277
2278 /**
2279 * The inverse matrix-vector operation to be performed by the payload
2280 * when ApplyInverse is called.
2281 *
2282 * @note This is not called by a LinearOperator, but rather by Trilinos
2283 * functions that expect this to mimic the action of the
2284 * InverseOperator.
2285 */
2286 std::function<void(VectorType &, const VectorType &)> inv_vmult;
2287
2288 /**
2289 * The inverse transpose matrix-vector operation to be performed by
2290 * the payload when ApplyInverse is called.
2291 *
2292 * @note This is not called by a LinearOperator, but rather by Trilinos
2293 * functions that expect this to mimic the action of the
2294 * InverseOperator.
2295 */
2296 std::function<void(VectorType &, const VectorType &)> inv_Tvmult;
2297
2298 /** @} */
2299
2300 /**
2301 * @name Core Epetra_Operator functionality
2302 */
2303 /** @{ */
2304
2305 /**
2306 * Return the status of the transpose flag for this operator
2307 *
2308 * This overloads the same function from the Trilinos class
2309 * Epetra_Operator.
2310 */
2311 virtual bool
2312 UseTranspose() const override;
2313
2314 /**
2315 * Sets an internal flag so that all operations performed by the matrix,
2316 * i.e., multiplications, are done in transposed order.
2317 *
2318 * This overloads the same function from the Trilinos class
2319 * Epetra_Operator.
2320 *
2321 * @note This does not reshape the matrix to transposed form directly,
2322 * so care should be taken when using this flag. When the flag is set to
2323 * true (either here or directly on the underlying Trilinos object
2324 * itself), this object is no longer thread-safe. In essence, it is not
2325 * possible ensure that the transposed state of the LinearOperator and
2326 * the underlying Trilinos object remain synchronized throughout all
2327 * operations that may occur on different threads simultaneously.
2328 */
2329 virtual int
2330 SetUseTranspose(bool UseTranspose) override;
2331
2332 /**
2333 * Apply the vmult operation on a vector @p X (of internally defined
2334 * type VectorType) and store the result in the vector @p Y.
2335 *
2336 * This overloads the same function from the Trilinos class
2337 * Epetra_Operator.
2338 *
2339 * @note The intended operation depends on the status of the internal
2340 * transpose flag. If this flag is set to true, the result will be
2341 * the equivalent of performing a Tvmult operation.
2342 */
2343 virtual int
2344 Apply(const VectorType &X, VectorType &Y) const override;
2345
2346 /**
2347 * Apply the vmult inverse operation on a vector @p X (of internally
2348 * defined type VectorType) and store the result in the vector @p Y.
2349 *
2350 * In practise, this function is only called from a Trilinos solver if
2351 * the wrapped object is to act as a preconditioner.
2352 *
2353 * This overloads the same function from the Trilinos class
2354 * Epetra_Operator.
2355 *
2356 * @note This function will only be operable if the payload has been
2357 * initialized with an InverseOperator, or is a wrapper to a
2358 * preconditioner. If not, then using this function will lead to an
2359 * error being thrown.
2360 * @note The intended operation depends on the status of the internal
2361 * transpose flag. If this flag is set to true, the result will be
2362 * the equivalent of performing a Tvmult operation.
2363 */
2364 virtual int
2365 ApplyInverse(const VectorType &Y, VectorType &X) const override;
2366 /** @} */
2367
2368 /**
2369 * @name Additional Epetra_Operator functionality
2370 */
2371 /** @{ */
2372
2373 /**
2374 * Return a label to describe this class.
2375 *
2376 * This overloads the same function from the Trilinos class
2377 * Epetra_Operator.
2378 */
2379 virtual const char *
2380 Label() const override;
2381
2382 /**
2383 * Return a reference to the underlying MPI communicator for
2384 * this object.
2385 *
2386 * This overloads the same function from the Trilinos class
2387 * Epetra_Operator.
2388 */
2389 virtual const Epetra_Comm &
2390 Comm() const override;
2391
2392 /**
2393 * Return the partitioning of the domain space of this matrix, i.e., the
2394 * partitioning of the vectors this matrix has to be multiplied with.
2395 *
2396 * This overloads the same function from the Trilinos class
2397 * Epetra_Operator.
2398 */
2399 virtual const Epetra_Map &
2400 OperatorDomainMap() const override;
2401
2402 /**
2403 * Return the partitioning of the range space of this matrix, i.e., the
2404 * partitioning of the vectors that are result from matrix-vector
2405 * products.
2406 *
2407 * This overloads the same function from the Trilinos class
2408 * Epetra_Operator.
2409 */
2410 virtual const Epetra_Map &
2411 OperatorRangeMap() const override;
2412 /** @} */
2413
2414 private:
2415 /**
2416 * A generic constructor.
2417 *
2418 * This constructor allows the payload to be configured from any
2419 * objects that can be cast to an Epetra operation. The
2420 * @p supports_inverse_operations flag indicates that the
2421 * @p op can be used to compute inverse operations; preconditioners
2422 * have such a facility.
2423 */
2424 template <typename EpetraOpType>
2425 TrilinosPayload(EpetraOpType &op,
2426 const bool supports_inverse_operations,
2427 const bool use_transpose,
2428 const MPI_Comm mpi_communicator,
2429 const IndexSet &locally_owned_domain_indices,
2430 const IndexSet &locally_owned_range_indices);
2431
2432 /**
2433 * A flag recording whether the operator is to perform standard
2434 * matrix-vector multiplication, or the transpose operation.
2435 */
2436 bool use_transpose;
2437
2438 /**
2439 * Internal communication pattern in case the matrix needs to be copied
2440 * from deal.II format.
2441 */
2442 Epetra_MpiComm communicator;
2443
2444 /**
2445 * Epetra_Map that sets the partitioning of the domain space of
2446 * this operator.
2447 */
2448 Epetra_Map domain_map;
2449
2450 /**
2451 * Epetra_Map that sets the partitioning of the range space of
2452 * this operator.
2453 */
2454 Epetra_Map range_map;
2455
2456 /**
2457 * Return a flag that describes whether this operator can return the
2458 * computation of the infinity norm. Since in general this is not the
2459 * case, this always returns a negative result.
2460 *
2461 * This overloads the same function from the Trilinos class
2462 * Epetra_Operator.
2463 */
2464 virtual bool
2465 HasNormInf() const override;
2466
2467 /**
2468 * Return the infinity norm of this operator.
2469 * Throws an error since, in general, we cannot compute this value.
2470 *
2471 * This overloads the same function from the Trilinos class
2472 * Epetra_Operator.
2473 */
2474 virtual double
2475 NormInf() const override;
2476 };
2477
2478 /**
2479 * Return an operator that returns a payload configured to support the
2480 * addition of two LinearOperators
2481 */
2482 TrilinosPayload
2483 operator+(const TrilinosPayload &first_op,
2484 const TrilinosPayload &second_op);
2485
2486 /**
2487 * Return an operator that returns a payload configured to support the
2488 * multiplication of two LinearOperators
2489 */
2490 TrilinosPayload
2491 operator*(const TrilinosPayload &first_op,
2492 const TrilinosPayload &second_op);
2493
2494 } // namespace LinearOperatorImplementation
2495 } /* namespace internal */
2496
2497
2498
2499 // ----------------------- inline and template functions --------------------
2500
2501 # ifndef DOXYGEN
2502
2503 namespace SparseMatrixIterators
2504 {
2505 inline AccessorBase::AccessorBase(SparseMatrix *matrix,
2506 size_type row,
2507 size_type index)
2508 : matrix(matrix)
2509 , a_row(row)
2510 , a_index(index)
2511 {
2512 visit_present_row();
2513 }
2514
2515
2516 inline AccessorBase::size_type
2517 AccessorBase::row() const
2518 {
2519 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
2520 return a_row;
2521 }
2522
2523
2524 inline AccessorBase::size_type
2525 AccessorBase::column() const
2526 {
2527 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
2528 return (*colnum_cache)[a_index];
2529 }
2530
2531
2532 inline AccessorBase::size_type
2533 AccessorBase::index() const
2534 {
2535 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
2536 return a_index;
2537 }
2538
2539
2540 inline Accessor<true>::Accessor(MatrixType *matrix,
2541 const size_type row,
2542 const size_type index)
2543 : AccessorBase(const_cast<SparseMatrix *>(matrix), row, index)
2544 {}
2545
2546
2547 template <bool Other>
2548 inline Accessor<true>::Accessor(const Accessor<Other> &other)
2549 : AccessorBase(other)
2550 {}
2551
2552
2553 inline TrilinosScalar
2554 Accessor<true>::value() const
2555 {
2556 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
2557 return (*value_cache)[a_index];
2558 }
2559
2560
2561 inline Accessor<false>::Reference::Reference(const Accessor<false> &acc)
2562 : accessor(const_cast<Accessor<false> &>(acc))
2563 {}
2564
2565
2566 inline Accessor<false>::Reference::operator TrilinosScalar() const
2567 {
2568 return (*accessor.value_cache)[accessor.a_index];
2569 }
2570
2571 inline const Accessor<false>::Reference &
2572 Accessor<false>::Reference::operator=(const TrilinosScalar n) const
2573 {
2574 (*accessor.value_cache)[accessor.a_index] = n;
2575 accessor.matrix->set(accessor.row(),
2576 accessor.column(),
2577 static_cast<TrilinosScalar>(*this));
2578 return *this;
2579 }
2580
2581
2582 inline const Accessor<false>::Reference &
2583 Accessor<false>::Reference::operator+=(const TrilinosScalar n) const
2584 {
2585 (*accessor.value_cache)[accessor.a_index] += n;
2586 accessor.matrix->set(accessor.row(),
2587 accessor.column(),
2588 static_cast<TrilinosScalar>(*this));
2589 return *this;
2590 }
2591
2592
2593 inline const Accessor<false>::Reference &
2594 Accessor<false>::Reference::operator-=(const TrilinosScalar n) const
2595 {
2596 (*accessor.value_cache)[accessor.a_index] -= n;
2597 accessor.matrix->set(accessor.row(),
2598 accessor.column(),
2599 static_cast<TrilinosScalar>(*this));
2600 return *this;
2601 }
2602
2603
2604 inline const Accessor<false>::Reference &
2605 Accessor<false>::Reference::operator*=(const TrilinosScalar n) const
2606 {
2607 (*accessor.value_cache)[accessor.a_index] *= n;
2608 accessor.matrix->set(accessor.row(),
2609 accessor.column(),
2610 static_cast<TrilinosScalar>(*this));
2611 return *this;
2612 }
2613
2614
2615 inline const Accessor<false>::Reference &
2616 Accessor<false>::Reference::operator/=(const TrilinosScalar n) const
2617 {
2618 (*accessor.value_cache)[accessor.a_index] /= n;
2619 accessor.matrix->set(accessor.row(),
2620 accessor.column(),
2621 static_cast<TrilinosScalar>(*this));
2622 return *this;
2623 }
2624
2625
2626 inline Accessor<false>::Accessor(MatrixType *matrix,
2627 const size_type row,
2628 const size_type index)
2629 : AccessorBase(matrix, row, index)
2630 {}
2631
2632
2633 inline Accessor<false>::Reference
2634 Accessor<false>::value() const
2635 {
2636 Assert(a_row < matrix->m(), ExcBeyondEndOfMatrix());
2637 return {*this};
2638 }
2639
2640
2641
2642 template <bool Constness>
2643 inline Iterator<Constness>::Iterator(MatrixType *matrix,
2644 const size_type row,
2645 const size_type index)
2646 : accessor(matrix, row, index)
2647 {}
2648
2649
2650 template <bool Constness>
2651 template <bool Other>
2652 inline Iterator<Constness>::Iterator(const Iterator<Other> &other)
2653 : accessor(other.accessor)
2654 {}
2655
2656
2657 template <bool Constness>
2658 inline Iterator<Constness> &
2659 Iterator<Constness>::operator++()
2660 {
2661 Assert(accessor.a_row < accessor.matrix->m(), ExcIteratorPastEnd());
2662
2663 ++accessor.a_index;
2664
2665 // If at end of line: do one
2666 // step, then cycle until we
2667 // find a row with a nonzero
2668 // number of entries.
2669 if (accessor.a_index >= accessor.colnum_cache->size())
2670 {
2671 accessor.a_index = 0;
2672 ++accessor.a_row;
2673
2674 while ((accessor.a_row < accessor.matrix->m()) &&
2675 ((accessor.matrix->in_local_range(accessor.a_row) == false) ||
2676 (accessor.matrix->row_length(accessor.a_row) == 0)))
2677 ++accessor.a_row;
2678
2679 accessor.visit_present_row();
2680 }
2681 return *this;
2682 }
2683
2684
2685 template <bool Constness>
2686 inline Iterator<Constness>
2687 Iterator<Constness>::operator++(int)
2688 {
2689 const Iterator<Constness> old_state = *this;
2690 ++(*this);
2691 return old_state;
2692 }
2693
2694
2695
2696 template <bool Constness>
2697 inline const Accessor<Constness> &
2698 Iterator<Constness>::operator*() const
2699 {
2700 return accessor;
2701 }
2702
2703
2704
2705 template <bool Constness>
2706 inline const Accessor<Constness> *
2707 Iterator<Constness>::operator->() const
2708 {
2709 return &accessor;
2710 }
2711
2712
2713
2714 template <bool Constness>
2715 template <bool OtherConstness>
2716 inline bool
2717 Iterator<Constness>::operator==(const Iterator<OtherConstness> &other) const
2718 {
2719 return (accessor.a_row == other.accessor.a_row &&
2720 accessor.a_index == other.accessor.a_index);
2721 }
2722
2723
2724
2725 template <bool Constness>
2726 template <bool OtherConstness>
2727 inline bool
2728 Iterator<Constness>::operator!=(const Iterator<OtherConstness> &other) const
2729 {
2730 return !(*this == other);
2731 }
2732
2733
2734
2735 template <bool Constness>
2736 template <bool OtherConstness>
2737 inline bool
2738 Iterator<Constness>::operator<(const Iterator<OtherConstness> &other) const
2739 {
2740 return (accessor.row() < other.accessor.row() ||
2741 (accessor.row() == other.accessor.row() &&
2742 accessor.index() < other.accessor.index()));
2743 }
2744
2745
2746 template <bool Constness>
2747 template <bool OtherConstness>
2748 inline bool
2749 Iterator<Constness>::operator>(const Iterator<OtherConstness> &other) const
2750 {
2751 return (other < *this);
2752 }
2753
2754 } // namespace SparseMatrixIterators
2755
2756
2757
2758 inline SparseMatrix::const_iterator SparseMatrix::begin() const
2759 {
2760 return begin(0);
2761 }
2762
2763
2764
2765 inline SparseMatrix::const_iterator SparseMatrix::end() const
2766 {
2767 return const_iterator(this, m(), 0);
2768 }
2769
2770
2771
2772 inline SparseMatrix::const_iterator SparseMatrix::begin(const size_type r)
2773 const
2774 {
2775 AssertIndexRange(r, m());
2776 if (in_local_range(r) && (row_length(r) > 0))
2777 return const_iterator(this, r, 0);
2778 else
2779 return end(r);
2780 }
2781
2782
2783
2784 inline SparseMatrix::const_iterator SparseMatrix::end(const size_type r) const
2785 {
2786 AssertIndexRange(r, m());
2787
2788 // place the iterator on the first entry
2789 // past this line, or at the end of the
2790 // matrix
2791 for (size_type i = r + 1; i < m(); ++i)
2792 if (in_local_range(i) && (row_length(i) > 0))
2793 return const_iterator(this, i, 0);
2794
2795 // if there is no such line, then take the
2796 // end iterator of the matrix
2797 return end();
2798 }
2799
2800
2801
2802 inline SparseMatrix::iterator SparseMatrix::begin()
2803 {
2804 return begin(0);
2805 }
2806
2807
2808
2809 inline SparseMatrix::iterator SparseMatrix::end()
2810 {
2811 return iterator(this, m(), 0);
2812 }
2813
2814
2815
2816 inline SparseMatrix::iterator SparseMatrix::begin(const size_type r)
2817 {
2818 AssertIndexRange(r, m());
2819 if (in_local_range(r) && (row_length(r) > 0))
2820 return iterator(this, r, 0);
2821 else
2822 return end(r);
2823 }
2824
2825
2826
2827 inline SparseMatrix::iterator SparseMatrix::end(const size_type r)
2828 {
2829 AssertIndexRange(r, m());
2830
2831 // place the iterator on the first entry
2832 // past this line, or at the end of the
2833 // matrix
2834 for (size_type i = r + 1; i < m(); ++i)
2835 if (in_local_range(i) && (row_length(i) > 0))
2836 return iterator(this, i, 0);
2837
2838 // if there is no such line, then take the
2839 // end iterator of the matrix
2840 return end();
2841 }
2842
2843
2844
2845 inline bool SparseMatrix::in_local_range(const size_type index) const
2846 {
2847 TrilinosWrappers::types::int_type begin, end;
2848 # ifndef DEAL_II_WITH_64BIT_INDICES
2849 begin = matrix->RowMap().MinMyGID();
2850 end = matrix->RowMap().MaxMyGID() + 1;
2851 # else
2852 begin = matrix->RowMap().MinMyGID64();
2853 end = matrix->RowMap().MaxMyGID64() + 1;
2854 # endif
2855
2856 return ((index >= static_cast<size_type>(begin)) &&
2857 (index < static_cast<size_type>(end)));
2858 }
2859
2860
2861
2862 inline bool SparseMatrix::is_compressed() const
2863 {
2864 return compressed;
2865 }
2866
2867
2868
2869 // Inline the set() and add() functions, since they will be called
2870 // frequently, and the compiler can optimize away some unnecessary loops
2871 // when the sizes are given at compile time.
2872 template <>
2873 void SparseMatrix::set<TrilinosScalar>(const size_type row,
2874 const size_type n_cols,
2875 const size_type *col_indices,
2876 const TrilinosScalar *values,
2877 const bool elide_zero_values);
2878
2879
2880
2881 template <typename Number>
2882 void SparseMatrix::set(const size_type row,
2883 const size_type n_cols,
2884 const size_type *col_indices,
2885 const Number *values,
2886 const bool elide_zero_values)
2887 {
2888 std::vector<TrilinosScalar> trilinos_values(n_cols);
2889 std::copy(values, values + n_cols, trilinos_values.begin());
2890 this->set(
2891 row, n_cols, col_indices, trilinos_values.data(), elide_zero_values);
2892 }
2893
2894
2895
2896 inline void SparseMatrix::set(const size_type i,
2897 const size_type j,
2898 const TrilinosScalar value)
2899 {
2900 AssertIsFinite(value);
2901
2902 set(i, 1, &j, &value, false);
2903 }
2904
2905
2906
2907 inline void SparseMatrix::set(const std::vector<size_type> &indices,
2908 const FullMatrix<TrilinosScalar> &values,
2909 const bool elide_zero_values)
2910 {
2911 Assert(indices.size() == values.m(),
2912 ExcDimensionMismatch(indices.size(), values.m()));
2913 Assert(values.m() == values.n(), ExcNotQuadratic());
2914
2915 for (size_type i = 0; i < indices.size(); ++i)
2916 set(indices[i],
2917 indices.size(),
2918 indices.data(),
2919 &values(i, 0),
2920 elide_zero_values);
2921 }
2922
2923
2924
2925 inline void SparseMatrix::add(const size_type i,
2926 const size_type j,
2927 const TrilinosScalar value)
2928 {
2929 AssertIsFinite(value);
2930
2931 if (value == 0)
2932 {
2933 // we have to check after Insert/Add in any case to be consistent
2934 // with the MPI communication model, but we can save some
2935 // work if the addend is zero. However, these actions are done in case
2936 // we pass on to the other function.
2937
2938 // TODO: fix this (do not run compress here, but fail)
2939 if (last_action == Insert)
2940 {
2941 const int ierr = matrix->GlobalAssemble(*column_space_map,
2942 matrix->RowMap(),
2943 false);
2944
2945 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
2946 }
2947
2948 last_action = Add;
2949
2950 return;
2951 }
2952 else
2953 add(i, 1, &j, &value, false);
2954 }
2955
2956
2957
2958 // inline "simple" functions that are called frequently and do only involve
2959 // a call to some Trilinos function.
2960 inline SparseMatrix::size_type SparseMatrix::m() const
2961 {
2962 # ifndef DEAL_II_WITH_64BIT_INDICES
2963 return matrix->NumGlobalRows();
2964 # else
2965 return matrix->NumGlobalRows64();
2966 # endif
2967 }
2968
2969
2970
2971 inline SparseMatrix::size_type SparseMatrix::n() const
2972 {
2973 // If the matrix structure has not been fixed (i.e., we did not have a
2974 // sparsity pattern), it does not know about the number of columns so we
2975 // must always take this from the additional column space map
2976 Assert(column_space_map.get() != nullptr, ExcInternalError());
2977 return n_global_elements(*column_space_map);
2978 }
2979
2980
2981
2982 inline unsigned int SparseMatrix::local_size() const
2983 {
2984 return matrix->NumMyRows();
2985 }
2986
2987
2988
2989 inline std::pair<SparseMatrix::size_type, SparseMatrix::size_type>
2990 SparseMatrix::local_range() const
2991 {
2992 size_type begin, end;
2993 # ifndef DEAL_II_WITH_64BIT_INDICES
2994 begin = matrix->RowMap().MinMyGID();
2995 end = matrix->RowMap().MaxMyGID() + 1;
2996 # else
2997 begin = matrix->RowMap().MinMyGID64();
2998 end = matrix->RowMap().MaxMyGID64() + 1;
2999 # endif
3000
3001 return std::make_pair(begin, end);
3002 }
3003
3004
3005
3006 inline std::uint64_t SparseMatrix::n_nonzero_elements() const
3007 {
3008 // Trilinos uses 64bit functions internally for attribute access, which
3009 // return `long long`. They also offer 32bit variants that return `int`,
3010 // however those call the 64bit version and convert the values to 32bit.
3011 // There is no necessity in using the 32bit versions at all.
3012 return static_cast<std::uint64_t>(matrix->NumGlobalNonzeros64());
3013 }
3014
3015
3016
3017 template <typename SparsityPatternType>
3018 inline void SparseMatrix::reinit(const IndexSet &parallel_partitioning,
3019 const SparsityPatternType &sparsity_pattern,
3020 const MPI_Comm communicator,
3021 const bool exchange_data)
3022 {
3023 reinit(parallel_partitioning,
3024 parallel_partitioning,
3025 sparsity_pattern,
3026 communicator,
3027 exchange_data);
3028 }
3029
3030
3031
3032 template <typename number>
3033 inline void SparseMatrix::reinit(
3034 const IndexSet &parallel_partitioning,
3035 const ::dealii::SparseMatrix<number> &sparse_matrix,
3036 const MPI_Comm communicator,
3037 const double drop_tolerance,
3038 const bool copy_values,
3039 const ::dealii::SparsityPattern *use_this_sparsity)
3040 {
3041 Epetra_Map map =
3042 parallel_partitioning.make_trilinos_map(communicator, false);
3043 reinit(parallel_partitioning,
3044 parallel_partitioning,
3045 sparse_matrix,
3046 drop_tolerance,
3047 copy_values,
3048 use_this_sparsity);
3049 }
3050
3051
3052
3053 inline const Epetra_CrsMatrix &SparseMatrix::trilinos_matrix() const
3054 {
3055 return static_cast<const Epetra_CrsMatrix &>(*matrix);
3056 }
3057
3058
3059
3060 inline const Epetra_CrsGraph &SparseMatrix::trilinos_sparsity_pattern() const
3061 {
3062 return matrix->Graph();
3063 }
3064
3065
3066
3067 inline IndexSet SparseMatrix::locally_owned_domain_indices() const
3068 {
3069 return IndexSet(matrix->DomainMap());
3070 }
3071
3072
3073
3074 inline IndexSet SparseMatrix::locally_owned_range_indices() const
3075 {
3076 return IndexSet(matrix->RangeMap());
3077 }
3078
3079
3080
3081 inline void SparseMatrix::prepare_add()
3082 {
3083 // nothing to do here
3084 }
3085
3086
3087
3088 inline void SparseMatrix::prepare_set()
3089 {
3090 // nothing to do here
3091 }
3092
3093
3094
3095 template <typename VectorType>
3096 inline TrilinosScalar SparseMatrix::residual(VectorType & dst,
3097 const VectorType &x,
3098 const VectorType &b) const
3099 {
3100 vmult(dst, x);
3101 dst -= b;
3102 dst *= -1.;
3103
3104 return dst.l2_norm();
3105 }
3106
3107
3108 namespace internal
3109 {
3110 namespace LinearOperatorImplementation
3111 {
3112 template <typename EpetraOpType>
3113 TrilinosPayload::TrilinosPayload(
3114 EpetraOpType &op,
3115 const bool supports_inverse_operations,
3116 const bool use_transpose,
3117 const MPI_Comm mpi_communicator,
3118 const IndexSet &locally_owned_domain_indices,
3119 const IndexSet &locally_owned_range_indices)
3120 : use_transpose(use_transpose)
3121 , communicator(mpi_communicator)
3122 , domain_map(
3123 locally_owned_domain_indices.make_trilinos_map(communicator.Comm()))
3124 , range_map(
3125 locally_owned_range_indices.make_trilinos_map(communicator.Comm()))
3126 {
3127 vmult = [&op](Range &tril_dst, const Domain &tril_src) {
3128 // Duplicated from TrilinosWrappers::PreconditionBase::vmult
3129 // as well as from TrilinosWrappers::SparseMatrix::Tvmult
3130 Assert(&tril_src != &tril_dst,
3131 TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination());
3132 internal::check_vector_map_equality(op,
3133 tril_src,
3134 tril_dst,
3135 op.UseTranspose());
3136
3137 const int ierr = op.Apply(tril_src, tril_dst);
3138 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
3139 };
3140
3141 Tvmult = [&op](Domain &tril_dst, const Range &tril_src) {
3142 // Duplicated from TrilinosWrappers::PreconditionBase::vmult
3143 // as well as from TrilinosWrappers::SparseMatrix::Tvmult
3144 Assert(&tril_src != &tril_dst,
3145 TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination());
3146 internal::check_vector_map_equality(op,
3147 tril_src,
3148 tril_dst,
3149 !op.UseTranspose());
3150
3151 op.SetUseTranspose(!op.UseTranspose());
3152 const int ierr = op.Apply(tril_src, tril_dst);
3153 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
3154 op.SetUseTranspose(!op.UseTranspose());
3155 };
3156
3157 if (supports_inverse_operations)
3158 {
3159 inv_vmult = [&op](Domain &tril_dst, const Range &tril_src) {
3160 // Duplicated from TrilinosWrappers::PreconditionBase::vmult
3161 // as well as from TrilinosWrappers::SparseMatrix::Tvmult
3162 Assert(
3163 &tril_src != &tril_dst,
3164 TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination());
3165 internal::check_vector_map_equality(op,
3166 tril_src,
3167 tril_dst,
3168 !op.UseTranspose());
3169
3170 const int ierr = op.ApplyInverse(tril_src, tril_dst);
3171 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
3172 };
3173
3174 inv_Tvmult = [&op](Range &tril_dst, const Domain &tril_src) {
3175 // Duplicated from TrilinosWrappers::PreconditionBase::vmult
3176 // as well as from TrilinosWrappers::SparseMatrix::Tvmult
3177 Assert(
3178 &tril_src != &tril_dst,
3179 TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination());
3180 internal::check_vector_map_equality(op,
3181 tril_src,
3182 tril_dst,
3183 op.UseTranspose());
3184
3185 op.SetUseTranspose(!op.UseTranspose());
3186 const int ierr = op.ApplyInverse(tril_src, tril_dst);
3187 AssertThrow(ierr == 0, ExcTrilinosError(ierr));
3188 op.SetUseTranspose(!op.UseTranspose());
3189 };
3190 }
3191 else
3192 {
3193 inv_vmult = [](Domain &, const Range &) {
3194 Assert(false,
3195 ExcMessage(
3196 "Uninitialized TrilinosPayload::inv_vmult called. "
3197 "The operator does not support inverse operations."));
3198 };
3199
3200 inv_Tvmult = [](Range &, const Domain &) {
3201 Assert(false,
3202 ExcMessage(
3203 "Uninitialized TrilinosPayload::inv_Tvmult called. "
3204 "The operator does not support inverse operations."));
3205 };
3206 }
3207 }
3208
3209
3210 template <typename Solver, typename Preconditioner>
3211 std::enable_if_t<
3212 std::is_base_of_v<TrilinosWrappers::SolverBase, Solver> &&
3213 std::is_base_of_v<TrilinosWrappers::PreconditionBase, Preconditioner>,
3214 TrilinosPayload>
3215 TrilinosPayload::inverse_payload(
3216 Solver &solver,
3217 const Preconditioner &preconditioner) const
3218 {
3219 const auto &payload = *this;
3220
3221 TrilinosPayload return_op(payload);
3222
3223 // Capture by copy so the payloads are always valid
3224
3225 return_op.inv_vmult = [payload, &solver, &preconditioner](
3226 TrilinosPayload::Domain &tril_dst,
3227 const TrilinosPayload::Range &tril_src) {
3228 // Duplicated from TrilinosWrappers::PreconditionBase::vmult
3229 // as well as from TrilinosWrappers::SparseMatrix::Tvmult
3230 Assert(&tril_src != &tril_dst,
3231 TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination());
3232 internal::check_vector_map_equality(payload,
3233 tril_src,
3234 tril_dst,
3235 !payload.UseTranspose());
3236 solver.solve(payload, tril_dst, tril_src, preconditioner);
3237 };
3238
3239 return_op.inv_Tvmult = [payload, &solver, &preconditioner](
3240 TrilinosPayload::Range &tril_dst,
3241 const TrilinosPayload::Domain &tril_src) {
3242 // Duplicated from TrilinosWrappers::PreconditionBase::vmult
3243 // as well as from TrilinosWrappers::SparseMatrix::Tvmult
3244 Assert(&tril_src != &tril_dst,
3245 TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination());
3246 internal::check_vector_map_equality(payload,
3247 tril_src,
3248 tril_dst,
3249 payload.UseTranspose());
3250
3251 const_cast<TrilinosPayload &>(payload).transpose();
3252 solver.solve(payload, tril_dst, tril_src, preconditioner);
3253 const_cast<TrilinosPayload &>(payload).transpose();
3254 };
3255
3256 // If the input operator is already setup for transpose operations, then
3257 // we must do similar with its inverse.
3258 if (return_op.UseTranspose() == true)
3259 std::swap(return_op.inv_vmult, return_op.inv_Tvmult);
3260
3261 return return_op;
3262 }
3263
3264 template <typename Solver, typename Preconditioner>
3265 std::enable_if_t<
3266 !(std::is_base_of_v<TrilinosWrappers::SolverBase, Solver> &&
3267 std::is_base_of_v<TrilinosWrappers::PreconditionBase,
3268 Preconditioner>),
3269 TrilinosPayload>
3270 TrilinosPayload::inverse_payload(Solver &, const Preconditioner &) const
3271 {
3272 TrilinosPayload return_op(*this);
3273
3274 return_op.inv_vmult = [](TrilinosPayload::Domain &,
3275 const TrilinosPayload::Range &) {
3276 AssertThrow(false,
3277 ExcMessage("Payload inv_vmult disabled because of "
3278 "incompatible solver/preconditioner choice."));
3279 };
3280
3281 return_op.inv_Tvmult = [](TrilinosPayload::Range &,
3282 const TrilinosPayload::Domain &) {
3283 AssertThrow(false,
3284 ExcMessage("Payload inv_vmult disabled because of "
3285 "incompatible solver/preconditioner choice."));
3286 };
3287
3288 return return_op;
3289 }
3290 } // namespace LinearOperatorImplementation
3291 } // namespace internal
3292
3293 template <>
3294 void SparseMatrix::set<TrilinosScalar>(const size_type row,
3295 const size_type n_cols,
3296 const size_type *col_indices,
3297 const TrilinosScalar *values,
3298 const bool elide_zero_values);
3299 # endif // DOXYGEN
3300
3301 } /* namespace TrilinosWrappers */
3302
3303
3304 DEAL_II_NAMESPACE_CLOSE
3305
3306
3307 # else
3308
3309 // Make sure the scripts that create the C++20 module input files have
3310 // something to latch on if the preprocessor #ifdef above would
3311 // otherwise lead to an empty content of the file.
3312 DEAL_II_NAMESPACE_OPEN
3313 DEAL_II_NAMESPACE_CLOSE
3314
3315 # endif // DEAL_II_WITH_TRILINOS
3316
3317
3318 /*----------------------- trilinos_sparse_matrix.h --------------------*/
3319
3320 #endif
3321 /*----------------------- trilinos_sparse_matrix.h --------------------*/