Debian Codegraph @

include/deal.II/lac/trilinos_epetra_vector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2016 - 2024 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_epetra_vector_h
16 #define dealii_trilinos_epetra_vector_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_TRILINOS
22
23 # include <deal.II/base/index_set.h>
24 # include <deal.II/base/mpi_stub.h>
25
26 # include <deal.II/lac/read_vector.h>
27 # include <deal.II/lac/trilinos_epetra_communication_pattern.h>
28 # include <deal.II/lac/vector_operation.h>
29 # include <deal.II/lac/vector_type_traits.h>
30
31 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
32 # include <Epetra_FEVector.h>
33 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
34
35 # include <memory>
36
37 DEAL_II_NAMESPACE_OPEN
38
39 namespace LinearAlgebra
40 {
41 // Forward declaration
42 template <typename Number>
43 class ReadWriteVector;
44
45 /**
46 * A namespace for classes that provide wrappers for Trilinos' Epetra vectors.
47 *
48 * This namespace provides wrappers for the Epetra_FEVector class from the
49 * Epetra package (https://trilinos.github.io/epetra.html) that is part of
50 * Trilinos.
51 */
52 namespace EpetraWrappers
53 {
54 /**
55 * This class defines type aliases that are used in vector classes
56 * within the EpetraWrappers namespace.
57 */
58 class VectorTraits
59 {
60 public:
61 using value_type = double;
62 using size_type = dealii::types::global_dof_index;
63 };
64
65 /**
66 * @cond internal
67 */
68
69 /**
70 * A namespace for internal implementation details of the TrilinosWrapper
71 * members.
72 *
73 * @ingroup TrilinosWrappers
74 */
75 namespace internal
76 {
77 /**
78 * This class implements a wrapper for accessing the Trilinos Epetra
79 * vector in the same way as we access deal.II objects: it is initialized
80 * with a vector and an element within it, and has a conversion operator
81 * to extract the scalar value of this element. It also has a variety of
82 * assignment operator for writing to this one element.
83 *
84 * @ingroup TrilinosWrappers
85 */
86 class VectorReference
87 {
88 private:
89 using value_type = VectorTraits::value_type;
90 using size_type = VectorTraits::size_type;
91
92 /**
93 * Constructor. It is made private so as to only allow the actual vector
94 * class to create it.
95 */
96 VectorReference(Vector &vector, const size_type index);
97
98 public:
99 /**
100 * Copy constructor.
101 */
102 VectorReference(const VectorReference &) = default;
103
104 /**
105 * This looks like a copy operator, but does something different than
106 * usual. In particular, it does not copy the member variables of this
107 * reference. Rather, it handles the situation where we have two vectors
108 * @p v and @p w, and assign elements like in <tt>v(i)=w(i)</tt>. Here,
109 * both left and right hand side of the assignment have data type
110 * VectorReference, but what we really mean is to assign the vector
111 * elements represented by the two references. This operator implements
112 * this operation. Note also that this allows us to make the assignment
113 * operator const.
114 */
115 const VectorReference &
116 operator=(const VectorReference &r) const;
117
118 /**
119 * Same as above but for non-const reference objects.
120 */
121 VectorReference &
122 operator=(const VectorReference &r);
123
124 /**
125 * Set the referenced element of the vector to <tt>s</tt>.
126 */
127 const VectorReference &
128 operator=(const value_type &s) const;
129
130 /**
131 * Add <tt>s</tt> to the referenced element of the vector->
132 */
133 const VectorReference &
134 operator+=(const value_type &s) const;
135
136 /**
137 * Subtract <tt>s</tt> from the referenced element of the vector->
138 */
139 const VectorReference &
140 operator-=(const value_type &s) const;
141
142 /**
143 * Multiply the referenced element of the vector by <tt>s</tt>.
144 */
145 const VectorReference &
146 operator*=(const value_type &s) const;
147
148 /**
149 * Divide the referenced element of the vector by <tt>s</tt>.
150 */
151 const VectorReference &
152 operator/=(const value_type &s) const;
153
154 /**
155 * Convert the reference to an actual value, i.e. return the value of
156 * the referenced element of the vector.
157 */
158 operator value_type() const;
159
160 /**
161 * Exception
162 */
163 DeclException1(ExcTrilinosError,
164 int,
165 << "An error with error number " << arg1
166 << " occurred while calling a Trilinos function");
167
168 /*
169 * Access to a an element that is not (locally-)owned.
170 *
171 * @ingroup Exceptions
172 */
173 DeclException4(
174 ExcAccessToNonLocalElement,
175 size_type,
176 size_type,
177 size_type,
178 size_type,
179 << "You are trying to access element " << arg1
180 << " of a distributed vector, but this element is not stored "
181 << "on the current processor. Note: There are " << arg2
182 << " elements stored "
183 << "on the current processor from within the range [" << arg3 << ','
184 << arg4 << "] but Trilinos vectors need not store contiguous "
185 << "ranges on each processor, and not every element in "
186 << "this range may in fact be stored locally."
187 << "\n\n"
188 << "A common source for this kind of problem is that you "
189 << "are passing a 'fully distributed' vector into a function "
190 << "that needs read access to vector elements that correspond "
191 << "to degrees of freedom on ghost cells (or at least to "
192 << "'locally active' degrees of freedom that are not also "
193 << "'locally owned'). You need to pass a vector that has these "
194 << "elements as ghost entries.");
195
196 private:
197 /**
198 * Point to the vector we are referencing.
199 */
200 Vector &vector;
201
202 /**
203 * Index of the referenced element of the vector.
204 */
205 const size_type index;
206
207 // Make the vector class a friend, so that it can create objects of the
208 // present type.
209 friend class ::dealii::LinearAlgebra::EpetraWrappers::Vector;
210 }; // class VectorReference
211
212 } // namespace internal
213 /**
214 * @endcond
215 */
216
217
218 /**
219 * This class implements a wrapper to the Trilinos distributed vector
220 * class Epetra_FEVector. This class requires Trilinos to be compiled
221 * with MPI support.
222 *
223 * @ingroup TrilinosWrappers
224 * @ingroup Vectors
225 */
226 class Vector : public ReadVector<VectorTraits::value_type>
227 {
228 public:
229 using value_type = VectorTraits::value_type;
230 using size_type = VectorTraits::size_type;
231 using real_type = value_type;
232 using reference = internal::VectorReference;
233 using const_reference = const internal::VectorReference;
234
235 /**
236 * @name 1: Basic Object-handling
237 */
238 /** @{ */
239
240 /**
241 * Constructor. Create a vector of dimension zero.
242 */
243 Vector();
244
245 /**
246 * Copy constructor. Sets the dimension and the partitioning to that of
247 * the given vector and copies all elements.
248 */
249 Vector(const Vector &V);
250
251 /**
252 * This constructor takes an IndexSet that defines how to distribute the
253 * individual components among the MPI processors. Since it also
254 * includes information about the size of the vector, this is all we
255 * need to generate a %parallel vector.
256 */
257 explicit Vector(const IndexSet &parallel_partitioner,
258 const MPI_Comm communicator);
259
260 /**
261 * Reinit functionality. This function destroys the old vector content
262 * and generates a new one based on the input partitioning. The flag
263 * <tt>omit_zeroing_entries</tt> determines whether the vector should be
264 * filled with zeros (`false`) or left in an undetermined state (`true`).
265 */
266 void
267 reinit(const IndexSet &parallel_partitioner,
268 const MPI_Comm communicator,
269 const bool omit_zeroing_entries = false);
270
271 /**
272 * Change the dimension to that of the vector @p V. The elements of @p V are not
273 * copied.
274 */
275 void
276 reinit(const Vector &V, const bool omit_zeroing_entries = false);
277
278 /**
279 * Extract a range of elements all at once.
280 */
281 virtual void
282 extract_subvector_to(
283 const ArrayView<const types::global_dof_index> &indices,
284 const ArrayView<double> &elements) const override;
285
286 /**
287 * Copy function. This function takes a Vector and copies all the
288 * elements. The Vector will have the same parallel distribution as @p
289 * V.
290 *
291 * The semantics of this operator are complex. If the two vectors have
292 * the same size, and
293 * if either the left or right hand side vector of the assignment (i.e.,
294 * either the input vector on the right hand side, or the calling vector
295 * to the left of the assignment operator) currently has ghost elements,
296 * then the left hand side vector will also have ghost values and will
297 * consequently be a read-only vector (see also the
298 * @ref GlossGhostedVector "glossary entry" on the issue). Otherwise, the
299 * left hand vector will be a writable vector after this operation.
300 * These semantics facilitate having a vector with ghost elements on the
301 * left hand side of the assignment, and a vector without ghost elements
302 * on the right hand side, with the resulting left hand side vector
303 * having the correct values in both its locally owned and its ghost
304 * elements.
305 *
306 * On the other hand, if the left hand side vector does not have the
307 * correct size yet, or is perhaps an entirely uninitialized vector,
308 * then the assignment is simply a copy operation in the usual sense:
309 * In that case, if the right hand side has no ghost elements (i.e.,
310 * is a completely distributed vector), then the left hand side will
311 * have no ghost elements either. And if the right hand side has
312 * ghost elements (and is consequently read-only), then the left
313 * hand side will have these same properties after the operation.
314 */
315 Vector &
316 operator=(const Vector &V);
317
318 /**
319 * Sets all elements of the vector to the scalar @p s. This operation is
320 * only allowed if @p s is equal to zero.
321 */
322 Vector &
323 operator=(const double s);
324
325 /**
326 * Imports all the elements present in the vector's IndexSet from the
327 * input vector @p V. VectorOperation::values @p operation is used to decide if
328 * the elements in @p V should be added to the current vector or replace the
329 * current elements. The last parameter can be used if the same
330 * communication pattern is used multiple times. This can be used to
331 * improve performance.
332 */
333 void
334 import_elements(
335 const ReadWriteVector<double> &V,
336 VectorOperation::values operation,
337 const std::shared_ptr<const Utilities::MPI::CommunicationPatternBase>
338 &communication_pattern = {});
339
340 /**
341 * @deprecated Use import_elements() instead.
342 */
343 DEAL_II_DEPRECATED
344 void
345 import(
346 const ReadWriteVector<double> &V,
347 const VectorOperation::values operation,
348 const std::shared_ptr<const Utilities::MPI::CommunicationPatternBase>
349 &communication_pattern = {})
350 {
351 import_elements(V, operation, communication_pattern);
352 }
353
354 /** @} */
355
356
357 /**
358 * @name 2: Data-Access
359 */
360 /** @{ */
361
362 /**
363 * Provide access to a given element, both read and write.
364 *
365 * When using a vector distributed with MPI, this operation only makes
366 * sense for elements that are actually present on the calling processor.
367 * Otherwise, an exception is thrown.
368 */
369 reference
370 operator()(const size_type index);
371
372 /**
373 * Provide read-only access to an element.
374 *
375 * When using a vector distributed with MPI, this operation only makes
376 * sense for elements that are actually present on the calling processor.
377 * Otherwise, an exception is thrown.
378 */
379 value_type
380 operator()(const size_type index) const;
381
382 /**
383 * Provide access to a given element, both read and write.
384 *
385 * Exactly the same as operator().
386 */
387 reference
388 operator[](const size_type index);
389
390 /**
391 * Provide read-only access to an element.
392 *
393 * Exactly the same as operator().
394 */
395 value_type
396 operator[](const size_type index) const;
397
398 /** @} */
399
400 /**
401 * @name 3: Modification of vectors
402 */
403 /** @{ */
404
405 /**
406 * Multiply the entire vector by a fixed factor.
407 */
408 Vector &
409 operator*=(const double factor);
410
411 /**
412 * Divide the entire vector by a fixed factor.
413 */
414 Vector &
415 operator/=(const double factor);
416
417 /**
418 * Add the vector @p V to the present one.
419 */
420 Vector &
421 operator+=(const Vector &V);
422
423 /**
424 * Subtract the vector @p V from the present one.
425 */
426 Vector &
427 operator-=(const Vector &V);
428
429 /**
430 * Return the scalar product of two vectors. The vectors need to have the
431 * same layout.
432 */
433 double
434 operator*(const Vector &V) const;
435
436 /**
437 * Add @p a to all components. Note that @p is a scalar not a vector.
438 */
439 void
440 add(const double a);
441
442 /**
443 * Simple addition of a multiple of a vector, i.e. <tt>*this +=
444 * a*V</tt>. The vectors need to have the same layout.
445 */
446 void
447 add(const double a, const Vector &V);
448
449 /**
450 * Multiple addition of multiple of a vector, i.e. <tt>*this> +=
451 * a*V+b*W</tt>. The vectors need to have the same layout.
452 */
453 void
454 add(const double a, const Vector &V, const double b, const Vector &W);
455
456 /**
457 * Scaling and simple addition of a multiple of a vector, i.e. <tt>*this
458 * = s*(*this)+a*V</tt>.
459 */
460 void
461 sadd(const double s, const double a, const Vector &V);
462
463 /**
464 * Scale each element of this vector by the corresponding element in the
465 * argument. This function is mostly meant to simulate multiplication
466 * (and immediate re-assignment) by a diagonal scaling matrix. The
467 * vectors need to have the same layout.
468 */
469 void
470 scale(const Vector &scaling_factors);
471
472 /**
473 * Assignment <tt>*this = a*V</tt>.
474 */
475 void
476 equ(const double a, const Vector &V);
477
478 /**
479 * Return whether the vector contains only elements with value zero.
480 */
481 bool
482 all_zero() const;
483
484 /** @} */
485
486
487 /**
488 * @name 4: Scalar products, norms and related operations
489 */
490 /** @{ */
491
492 /**
493 * Return the mean value of the element of this vector.
494 */
495 double
496 mean_value() const;
497
498 /**
499 * Return the l<sub>1</sub> norm of the vector (i.e., the sum of the
500 * absolute values of all entries among all processors).
501 */
502 double
503 l1_norm() const;
504
505 /**
506 * Return the l<sub>2</sub> norm of the vector (i.e., the square root of
507 * the sum of the square of all entries among all processors).
508 */
509 double
510 l2_norm() const;
511
512 /**
513 * Return the maximum norm of the vector (i.e., the maximum absolute value
514 * among all entries and among all processors).
515 */
516 double
517 linfty_norm() const;
518
519 /**
520 * Performs a combined operation of a vector addition and a subsequent
521 * inner product, returning the value of the inner product. In other
522 * words, the result of this function is the same as if the user called
523 * @code
524 * this->add(a, V);
525 * return_value = *this * W;
526 * @endcode
527 *
528 * The reason this function exists is that this operation involves less
529 * memory transfer than calling the two functions separately. This
530 * method only needs to load three vectors, @p this, @p V, @p W, whereas
531 * calling separate methods means to load the calling vector @p this
532 * twice. Since most vector operations are memory transfer limited, this
533 * reduces the time by 25\% (or 50\% if @p W equals @p this).
534 *
535 * The vectors need to have the same layout.
536 *
537 * For complex-valued vectors, the scalar product in the second step is
538 * implemented as
539 * $\left<v,w\right>=\sum_i v_i \bar{w_i}$.
540 */
541 double
542 add_and_dot(const double a, const Vector &V, const Vector &W);
543
544 /** @} */
545
546 /**
547 * @name 5: Scalar products, norms and related operations
548 */
549 /** @{ */
550
551 /**
552 * This function always returns false and is present only for backward
553 * compatibility.
554 */
555 bool
556 has_ghost_elements() const;
557
558 /**
559 * Return the global size of the vector, equal to the sum of the number of
560 * locally owned indices among all processors.
561 */
562 virtual size_type
563 size() const override;
564
565 /**
566 * Return the local size of the vector, i.e., the number of indices
567 * owned locally.
568 */
569 size_type
570 locally_owned_size() const;
571
572 /**
573 * Return the underlying MPI communicator.
574 */
575 MPI_Comm
576 get_mpi_communicator() const;
577
578 /**
579 * Return an index set that describes which elements of this vector are
580 * owned by the current processor. As a consequence, the index sets
581 * returned on different processors if this is a distributed vector will
582 * form disjoint sets that add up to the complete index set. Obviously, if
583 * a vector is created on only one processor, then the result would
584 * satisfy
585 * @code
586 * vec.locally_owned_elements() == complete_index_set(vec.size())
587 * @endcode
588 */
589 ::dealii::IndexSet
590 locally_owned_elements() const;
591
592 /** @} */
593
594
595 /**
596 * @name 6: Mixed stuff
597 */
598 /** @{ */
599
600 /**
601 * Compress the underlying representation of the Trilinos object, i.e.
602 * flush the buffers of the vector object if it has any. This function is
603 * necessary after writing into a vector element-by-element and before
604 * anything else can be done on it.
605 *
606 * See
607 * @ref GlossCompress "Compressing distributed objects"
608 * for more information.
609 */
610 void
611 compress(const VectorOperation::values operation);
612
613 /**
614 * Return a const reference to the underlying Trilinos
615 * Epetra_FEVector class.
616 */
617 const Epetra_FEVector &
618 trilinos_vector() const;
619
620 /**
621 * Return a (modifiable) reference to the underlying Trilinos
622 * Epetra_FEVector class.
623 */
624 Epetra_FEVector &
625 trilinos_vector();
626
627 /**
628 * Prints the vector to the output stream @p out.
629 */
630 void
631 print(std::ostream &out,
632 const unsigned int precision = 3,
633 const bool scientific = true,
634 const bool across = true) const;
635
636 /**
637 * Return the memory consumption of this class in bytes.
638 */
639 std::size_t
640 memory_consumption() const;
641
642 /** @} */
643
644 /**
645 * The vectors have different partitioning, i.e. their IndexSet objects
646 * don't represent the same indices.
647 */
648 DeclException0(ExcDifferentParallelPartitioning);
649
650 /**
651 * Attempt to perform an operation between two incompatible vector types.
652 *
653 * @ingroup Exceptions
654 */
655 DeclException0(ExcVectorTypeNotCompatible);
656
657 /**
658 * Exception thrown by an error in Trilinos.
659 *
660 * @ingroup Exceptions
661 */
662 DeclException1(ExcTrilinosError,
663 int,
664 << "An error with error number " << arg1
665 << " occurred while calling a Trilinos function");
666
667 private:
668 /**
669 * Create the CommunicationPattern for the communication between the
670 * IndexSet @p source_index_set and the current vector based
671 * on the communicator @p mpi_comm.
672 */
673 void
674 create_epetra_comm_pattern(const IndexSet &source_index_set,
675 const MPI_Comm mpi_comm);
676
677 /**
678 * Pointer to the actual Epetra vector object.
679 */
680 std::unique_ptr<Epetra_FEVector> vector;
681
682 /**
683 * IndexSet of the elements of the last imported vector.
684 */
685 ::dealii::IndexSet source_stored_elements;
686
687 /**
688 * CommunicationPattern for the communication between the
689 * source_stored_elements IndexSet and the current vector.
690 */
691 std::shared_ptr<const CommunicationPattern> epetra_comm_pattern;
692
693 // Make the reference class a friend.
694 friend class internal::VectorReference;
695 };
696
697 # ifndef DOXYGEN
698
699 // VectorReference
700 namespace internal
701 {
702 inline VectorReference::VectorReference(Vector &vector,
703 const size_type index)
704 : vector(vector)
705 , index(index)
706 {}
707
708
709
710 inline const VectorReference &
711 VectorReference::operator=(const VectorReference &r) const
712 {
713 // as explained in the class
714 // documentation, this is not the copy
715 // operator. so simply pass on to the
716 // "correct" assignment operator
717 *this = static_cast<value_type>(r);
718
719 return *this;
720 }
721
722
723
724 inline VectorReference &
725 VectorReference::operator=(const VectorReference &r)
726 {
727 // as above
728 *this = static_cast<value_type>(r);
729
730 return *this;
731 }
732
733
734
735 inline const VectorReference &
736 VectorReference::operator=(const value_type &value) const
737 {
738 (*vector.vector)[0][index] = value;
739
740 return *this;
741 }
742
743
744
745 inline const VectorReference &
746 VectorReference::operator+=(const value_type &value) const
747 {
748 value_type new_value = static_cast<value_type>(*this) + value;
749 (*vector.vector)[0][index] = new_value;
750
751 return *this;
752 }
753
754
755
756 inline const VectorReference &
757 VectorReference::operator-=(const value_type &value) const
758 {
759 value_type new_value = static_cast<value_type>(*this) - value;
760 (*vector.vector)[0][index] = new_value;
761
762 return *this;
763 }
764
765
766
767 inline const VectorReference &
768 VectorReference::operator*=(const value_type &value) const
769 {
770 value_type new_value = static_cast<value_type>(*this) * value;
771 (*vector.vector)[0][index] = new_value;
772
773 return *this;
774 }
775
776
777
778 inline const VectorReference &
779 VectorReference::operator/=(const value_type &value) const
780 {
781 value_type new_value = static_cast<value_type>(*this) / value;
782 (*vector.vector)[0][index] = new_value;
783
784 return *this;
785 }
786 } // namespace internal
787
788 # endif /* DOXYGEN */
789
790
791 inline internal::VectorReference
792 Vector::operator()(const size_type index)
793 {
794 return internal::VectorReference(*this, index);
795 }
796
797 inline internal::VectorReference
798 Vector::operator[](const size_type index)
799 {
800 return operator()(index);
801 }
802
803 inline Vector::value_type
804 Vector::operator[](const size_type index) const
805 {
806 return operator()(index);
807 }
808
809
810 inline bool
811 Vector::has_ghost_elements() const
812 {
813 return false;
814 }
815 } // namespace EpetraWrappers
816 } // namespace LinearAlgebra
817
818
819 /**
820 * Declare dealii::LinearAlgebra::EpetraWrappers::Vector as distributed vector.
821 */
822 template <>
823 struct is_serial_vector<LinearAlgebra::EpetraWrappers::Vector> : std::false_type
824 {};
825
826 DEAL_II_NAMESPACE_CLOSE
827
828 #else
829
830 // Make sure the scripts that create the C++20 module input files have
831 // something to latch on if the preprocessor #ifdef above would
832 // otherwise lead to an empty content of the file.
833 DEAL_II_NAMESPACE_OPEN
834 DEAL_II_NAMESPACE_CLOSE
835
836 #endif
837
838 #endif