Debian Codegraph @

include/deal.II/lac/petsc_vector_base.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2004 - 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_petsc_vector_base_h
16 #define dealii_petsc_vector_base_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_PETSC
22
23 # include <deal.II/base/index_set.h>
24
25 # include <deal.II/lac/exceptions.h>
26 # include <deal.II/lac/vector.h>
27 # include <deal.II/lac/vector_operation.h>
28
29 # include <boost/serialization/split_member.hpp>
30 # include <boost/serialization/utility.hpp>
31
32 # include <petscvec.h>
33
34 # include <utility>
35 # include <vector>
36
37 DEAL_II_NAMESPACE_OPEN
38
39 // forward declaration
40 # ifndef DOXYGEN
41 template <typename number>
42 class Vector;
43
44 namespace PETScWrappers
45 {
46 class VectorBase;
47 }
48 # endif
49
50 /**
51 * A namespace in which wrapper classes for PETSc objects reside.
52 *
53 * @ingroup PETScWrappers
54 * @ingroup Vectors
55 */
56 namespace PETScWrappers
57 {
58 /**
59 * @cond internal
60 */
61
62 /**
63 * A namespace for internal implementation details of the PETScWrapper
64 * members.
65 * @ingroup PETScWrappers
66 */
67 namespace internal
68 {
69 /**
70 * Since access to PETSc vectors only goes through functions, rather than
71 * by obtaining a reference to a vector element, we need a wrapper class
72 * that acts as if it was a reference, and basically redirects all
73 * accesses (read and write) to member functions of this class.
74 *
75 * This class implements such a wrapper: it is initialized with a vector
76 * and an element within it, and has a conversion operator to extract the
77 * scalar value of this element. It also has a variety of assignment
78 * operator for writing to this one element.
79 * @ingroup PETScWrappers
80 */
81 class VectorReference
82 {
83 public:
84 /**
85 * Declare type for container size.
86 */
87 using size_type = types::global_dof_index;
88
89 private:
90 /**
91 * Constructor. It is made private so as to only allow the actual vector
92 * class to create it.
93 */
94 VectorReference(const VectorBase &vector, const size_type index);
95
96 public:
97 /*
98 * Copy constructor.
99 */
100 VectorReference(const VectorReference &vector) = default;
101
102 /**
103 * This looks like a copy operator, but does something different than
104 * usual. In particular, it does not copy the member variables of this
105 * reference. Rather, it handles the situation where we have two vectors
106 * @p v and @p w, and assign elements like in <tt>v(i)=w(i)</tt>. Here,
107 * both left and right hand side of the assignment have data type
108 * VectorReference, but what we really mean is to assign the vector
109 * elements represented by the two references. This operator implements
110 * this operation. Note also that this allows us to make the assignment
111 * operator const.
112 */
113 const VectorReference &
114 operator=(const VectorReference &r) const;
115
116 /**
117 * The same function as above, but for non-const reference objects. The
118 * function is needed since the compiler might otherwise automatically
119 * generate a copy operator for non-const 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 PetscScalar &s) const;
129
130 /**
131 * Add <tt>s</tt> to the referenced element of the vector.
132 */
133 const VectorReference &
134 operator+=(const PetscScalar &s) const;
135
136 /**
137 * Subtract <tt>s</tt> from the referenced element of the vector.
138 */
139 const VectorReference &
140 operator-=(const PetscScalar &s) const;
141
142 /**
143 * Multiply the referenced element of the vector by <tt>s</tt>.
144 */
145 const VectorReference &
146 operator*=(const PetscScalar &s) const;
147
148 /**
149 * Divide the referenced element of the vector by <tt>s</tt>.
150 */
151 const VectorReference &
152 operator/=(const PetscScalar &s) const;
153
154 /**
155 * Return the real part of the value of the referenced element.
156 */
157 PetscReal
158 real() const;
159
160 /**
161 * Return the imaginary part of the value of the referenced element.
162 *
163 * @note This operation is not defined for real numbers and an exception
164 * is thrown.
165 */
166 PetscReal
167 imag() const;
168
169 /**
170 * Convert the reference to an actual value, i.e. return the value of
171 * the referenced element of the vector.
172 */
173 operator PetscScalar() const;
174 /**
175 * Exception
176 */
177 DeclException3(
178 ExcAccessToNonlocalElement,
179 int,
180 int,
181 int,
182 << "You tried to access element " << arg1
183 << " of a distributed vector, but only elements in range [" << arg2
184 << ',' << arg3 << "] are stored locally and can be accessed."
185 << "\n\n"
186 << "A common source for this kind of problem is that you "
187 << "are passing a 'fully distributed' vector into a function "
188 << "that needs read access to vector elements that correspond "
189 << "to degrees of freedom on ghost cells (or at least to "
190 << "'locally active' degrees of freedom that are not also "
191 << "'locally owned'). You need to pass a vector that has these "
192 << "elements as ghost entries.");
193 /**
194 * Exception.
195 */
196 DeclException2(ExcWrongMode,
197 int,
198 int,
199 << "You tried to do a "
200 << (arg1 == 1 ? "'set'" : (arg1 == 2 ? "'add'" : "???"))
201 << " operation but the vector is currently in "
202 << (arg2 == 1 ? "'set'" : (arg2 == 2 ? "'add'" : "???"))
203 << " mode. You first have to call 'compress()'.");
204
205 private:
206 /**
207 * Point to the vector we are referencing.
208 */
209 const VectorBase &vector;
210
211 /**
212 * Index of the referenced element of the vector.
213 */
214 const size_type index;
215
216 // Make the vector class a friend, so that it can create objects of the
217 // present type.
218 friend class ::dealii::PETScWrappers::VectorBase;
219 };
220 } // namespace internal
221 /**
222 * @endcond
223 */
224
225
226 /**
227 * Base class for all vector classes that are implemented on top of the
228 * PETSc vector types. Since in PETSc all vector types (i.e. sequential and
229 * parallel ones) are built by filling the contents of an abstract object
230 * that is only referenced through a pointer of a type that is independent
231 * of the actual vector type, we can implement almost all functionality of
232 * vectors in this base class. As such, this class can also be used as a
233 * deal.II-compatible wrapper for a PETSc <code>Vec</code> object of any
234 * type. Derived classes will then only have to provide the functionality to
235 * create one or the other kind of vector.
236 *
237 * The interface of this class is modeled after the existing Vector class in
238 * deal.II. It has almost the same member functions, and is often
239 * exchangeable. However, since PETSc only supports a single scalar type
240 * (either double, float, or a complex data type), it is not templated, and
241 * only works with whatever your PETSc installation has defined the data
242 * type @p PetscScalar to.
243 *
244 * Note that PETSc only guarantees that operations do what you expect if the
245 * functions @p VecAssemblyBegin and @p VecAssemblyEnd have been called
246 * after vector assembly. Therefore, you need to call Vector::compress()
247 * before you actually use the vector.
248 *
249 * @ingroup PETScWrappers
250 */
251 class VectorBase : public ReadVector<PetscScalar>
252 {
253 public:
254 /**
255 * Declare some of the standard types used in all containers. These types
256 * parallel those in the <tt>C++</tt> standard libraries
257 * <tt>vector<...></tt> class.
258 */
259 using value_type = PetscScalar;
260 using real_type = PetscReal;
261 using size_type = types::global_dof_index;
262 using reference = internal::VectorReference;
263 using const_reference = const internal::VectorReference;
264
265 /**
266 * Default constructor. It doesn't do anything, derived classes will have
267 * to initialize the data.
268 */
269 VectorBase();
270
271 /**
272 * Copy constructor. Sets the dimension to that of the given vector, and
273 * copies all elements.
274 */
275 VectorBase(const VectorBase &v);
276
277 /**
278 * Initialize a Vector from a PETSc Vec object. Note that we do not copy
279 * the vector.
280 */
281 explicit VectorBase(const Vec &v);
282
283 /**
284 * Destructor.
285 */
286 virtual ~VectorBase() override;
287
288 /**
289 * Release all memory and return to a state just like after having called
290 * the default constructor.
291 */
292 virtual void
293 clear();
294
295 /**
296 * Compress the underlying representation of the PETSc object, i.e. flush
297 * the buffers of the vector object if it has any. This function is
298 * necessary after writing into a vector element-by-element and before
299 * anything else can be done on it.
300 *
301 * See
302 * @ref GlossCompress "Compressing distributed objects"
303 * for more information.
304 */
305 void
306 compress(const VectorOperation::values operation);
307
308 /**
309 * The copy assignment operator.
310 */
311 VectorBase &
312 operator=(const VectorBase &);
313
314 /**
315 * Set all components of the vector to the given number @p s. Simply pass
316 * this down to the individual block objects, but we still need to declare
317 * this function to make the example given in the discussion about making
318 * the constructor explicit work.
319 *
320 *
321 * Since the semantics of assigning a scalar to a vector are not
322 * immediately clear, this operator should really only be used if you want
323 * to set the entire vector to zero. This allows the intuitive notation
324 * <tt>v=0</tt>. Assigning other values is deprecated and may be
325 * disallowed in the future.
326 */
327 VectorBase &
328 operator=(const PetscScalar s);
329
330 /**
331 * This method associates the PETSc Vec to the instance of the class.
332 * This is particularly useful when performing PETSc to Deal.II operations
333 * since it allows to reuse the Deal.II VectorBase and the PETSc Vec
334 * without incurring in memory copies.
335 */
336 void
337 reinit(Vec v);
338
339 /**
340 * Test for equality. This function assumes that the present vector and
341 * the one to compare with have the same size already, since comparing
342 * vectors of different sizes makes not much sense anyway.
343 */
344 bool
345 operator==(const VectorBase &v) const;
346
347 /**
348 * Test for inequality. This function assumes that the present vector and
349 * the one to compare with have the same size already, since comparing
350 * vectors of different sizes makes not much sense anyway.
351 */
352 bool
353 operator!=(const VectorBase &v) const;
354
355 /**
356 * Return the global dimension of the vector.
357 */
358 size_type
359 size() const override;
360
361 /**
362 * Return the local dimension of the vector, i.e. the number of elements
363 * stored on the present MPI process. For sequential vectors, this number
364 * is the same as size(), but for parallel vectors it may be smaller.
365 *
366 * To figure out which elements exactly are stored locally, use
367 * local_range() or locally_owned_elements().
368 */
369 size_type
370 locally_owned_size() const;
371
372 /**
373 * Return a pair of indices indicating which elements of this vector are
374 * stored locally. The first number is the index of the first element
375 * stored, the second the index of the one past the last one that is
376 * stored locally. If this is a sequential vector, then the result will be
377 * the pair (0,N), otherwise it will be a pair (i,i+n), where
378 * <tt>n=locally_owned_size()</tt>.
379 */
380 std::pair<size_type, size_type>
381 local_range() const;
382
383 /**
384 * Return whether @p index is in the local range or not, see also
385 * local_range().
386 */
387 bool
388 in_local_range(const size_type index) const;
389
390 /**
391 * Return an index set that describes which elements of this vector are
392 * owned by the current processor. Note that this index set does not
393 * include elements this vector may store locally as ghost elements but
394 * that are in fact owned by another processor. As a consequence, the
395 * index sets returned on different processors if this is a distributed
396 * vector will form disjoint sets that add up to the complete index set.
397 * Obviously, if a vector is created on only one processor, then the
398 * result would satisfy
399 * @code
400 * vec.locally_owned_elements() == complete_index_set (vec.size())
401 * @endcode
402 */
403 IndexSet
404 locally_owned_elements() const;
405
406 /**
407 * Return if the vector contains ghost elements.
408 *
409 * @see
410 * @ref GlossGhostedVector "vectors with ghost elements"
411 */
412 bool
413 has_ghost_elements() const;
414
415 /**
416 * Return the IndexSet of ghost elements.
417 */
418 const IndexSet &
419 ghost_elements() const;
420
421 /**
422 * Update ghosted elements.
423 */
424 void
425 update_ghost_values() const;
426
427 /**
428 * Provide access to a given element, both read and write.
429 */
430 reference
431 operator()(const size_type index);
432
433 /**
434 * Provide read-only access to an element.
435 */
436 PetscScalar
437 operator()(const size_type index) const;
438
439 /**
440 * Provide access to a given element, both read and write.
441 *
442 * Exactly the same as operator().
443 */
444 reference
445 operator[](const size_type index);
446
447 /**
448 * Provide read-only access to an element.
449 *
450 * Exactly the same as operator().
451 */
452 PetscScalar
453 operator[](const size_type index) const;
454
455 /**
456 * A collective set operation: instead of setting individual elements of a
457 * vector, this function allows to set a whole set of elements at once.
458 * The indices of the elements to be set are stated in the first argument,
459 * the corresponding values in the second.
460 */
461 void
462 set(const std::vector<size_type> &indices,
463 const std::vector<PetscScalar> &values);
464
465 /**
466 * Instead of getting individual elements of a vector via operator(),
467 * this function allows getting a whole set of elements at once. The
468 * indices of the elements to be read are stated in the first argument, the
469 * corresponding values are returned in the second.
470 *
471 * If the current vector is called @p v, then this function is the equivalent
472 * to the code
473 * @code
474 * for (unsigned int i=0; i<indices.size(); ++i)
475 * values[i] = v[indices[i]];
476 * @endcode
477 *
478 * @pre The sizes of the @p indices and @p values arrays must be identical.
479 */
480 void
481 extract_subvector_to(const std::vector<size_type> &indices,
482 std::vector<PetscScalar> &values) const;
483
484 /**
485 * Extract a range of elements all at once.
486 */
487 virtual void
488 extract_subvector_to(
489 const ArrayView<const types::global_dof_index> &indices,
490 const ArrayView<PetscScalar> &elements) const override;
491
492 /**
493 * Instead of getting individual elements of a vector via operator(),
494 * this function allows getting a whole set of elements at once. In
495 * contrast to the previous function, this function obtains the
496 * indices of the elements by dereferencing all elements of the iterator
497 * range provided by the first two arguments, and puts the vector
498 * values into memory locations obtained by dereferencing a range
499 * of iterators starting at the location pointed to by the third
500 * argument.
501 *
502 * If the current vector is called @p v, then this function is the equivalent
503 * to the code
504 * @code
505 * ForwardIterator indices_p = indices_begin;
506 * OutputIterator values_p = values_begin;
507 * while (indices_p != indices_end)
508 * {
509 * *values_p = v[*indices_p];
510 * ++indices_p;
511 * ++values_p;
512 * }
513 * @endcode
514 *
515 * @pre It must be possible to write into as many memory locations
516 * starting at @p values_begin as there are iterators between
517 * @p indices_begin and @p indices_end.
518 */
519 template <typename ForwardIterator, typename OutputIterator>
520 void
521 extract_subvector_to(const ForwardIterator indices_begin,
522 const ForwardIterator indices_end,
523 OutputIterator values_begin) const;
524
525 /**
526 * A collective add operation: This function adds a whole set of values
527 * stored in @p values to the vector components specified by @p indices.
528 */
529 void
530 add(const std::vector<size_type> &indices,
531 const std::vector<PetscScalar> &values);
532
533 /**
534 * This is a second collective add operation. As a difference, this
535 * function takes a deal.II vector of values.
536 */
537 void
538 add(const std::vector<size_type> &indices,
539 const ::dealii::Vector<PetscScalar> &values);
540
541 /**
542 * Take an address where <tt>n_elements</tt> are stored contiguously and
543 * add them into the vector. Handles all cases which are not covered by
544 * the other two <tt>add()</tt> functions above.
545 */
546 void
547 add(const size_type n_elements,
548 const size_type *indices,
549 const PetscScalar *values);
550
551 /**
552 * Return the scalar product of two vectors. The vectors must have the
553 * same size.
554 *
555 * For complex valued vector, this gives$\left(v^\ast,vec\right)$.
556 */
557 PetscScalar
558 operator*(const VectorBase &vec) const;
559
560 /**
561 * Return the square of the $l_2$-norm.
562 */
563 real_type
564 norm_sqr() const;
565
566 /**
567 * Return the mean value of the elements of this vector.
568 */
569 PetscScalar
570 mean_value() const;
571
572 /**
573 * $l_1$-norm of the vector. The sum of the absolute values.
574 *
575 * @note In complex-valued PETSc priori to 3.7.0 this norm is implemented
576 * as the sum of absolute values of real and imaginary parts of elements
577 * of a complex vector.
578 */
579 real_type
580 l1_norm() const;
581
582 /**
583 * $l_2$-norm of the vector. The square root of the sum of the squares of
584 * the elements.
585 */
586 real_type
587 l2_norm() const;
588
589 /**
590 * $l_p$-norm of the vector. The pth root of the sum of the pth powers of
591 * the absolute values of the elements.
592 */
593 real_type
594 lp_norm(const real_type p) const;
595
596 /**
597 * $l_\infty$-norm of the vector. Return the value of the vector element
598 * with the maximum absolute value.
599 */
600 real_type
601 linfty_norm() const;
602
603 /**
604 * Performs a combined operation of a vector addition and a subsequent
605 * inner product, returning the value of the inner product. In other
606 * words, the result of this function is the same as if the user called
607 * @code
608 * this->add(a, V);
609 * return_value = *this * W;
610 * @endcode
611 *
612 * The reason this function exists is for compatibility with deal.II's own
613 * vector classes which can implement this functionality with less memory
614 * transfer. However, for PETSc vectors such a combined operation is not
615 * natively supported and thus the cost is completely equivalent as
616 * calling the two methods separately.
617 *
618 * For complex-valued vectors, the scalar product in the second step is
619 * implemented as
620 * $\left<v,w\right>=\sum_i v_i \bar{w_i}$.
621 */
622 PetscScalar
623 add_and_dot(const PetscScalar a, const VectorBase &V, const VectorBase &W);
624
625 /**
626 * Return whether the vector contains only elements with value zero. This
627 * is a @ref GlossCollectiveOperation "collective operation". This function is expensive, because
628 * potentially all elements have to be checked.
629 */
630 bool
631 all_zero() const;
632
633 /**
634 * Multiply the entire vector by a fixed factor.
635 */
636 VectorBase &
637 operator*=(const PetscScalar factor);
638
639 /**
640 * Divide the entire vector by a fixed factor.
641 */
642 VectorBase &
643 operator/=(const PetscScalar factor);
644
645 /**
646 * Add the given vector to the present one.
647 */
648 VectorBase &
649 operator+=(const VectorBase &V);
650
651 /**
652 * Subtract the given vector from the present one.
653 */
654 VectorBase &
655 operator-=(const VectorBase &V);
656
657 /**
658 * Addition of @p s to all components. Note that @p s is a scalar and not
659 * a vector.
660 */
661 void
662 add(const PetscScalar s);
663
664 /**
665 * Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>.
666 */
667 void
668 add(const PetscScalar a, const VectorBase &V);
669
670 /**
671 * Multiple addition of scaled vectors, i.e. <tt>*this += a*V+b*W</tt>.
672 */
673 void
674 add(const PetscScalar a,
675 const VectorBase &V,
676 const PetscScalar b,
677 const VectorBase &W);
678
679 /**
680 * Scaling and simple vector addition, i.e. <tt>*this = s*(*this)+V</tt>.
681 */
682 void
683 sadd(const PetscScalar s, const VectorBase &V);
684
685 /**
686 * Scaling and simple addition, i.e. <tt>*this = s*(*this)+a*V</tt>.
687 */
688 void
689 sadd(const PetscScalar s, const PetscScalar a, const VectorBase &V);
690
691 /**
692 * Scale each element of this vector by the corresponding element in the
693 * argument. This function is mostly meant to simulate multiplication (and
694 * immediate re-assignment) by a diagonal scaling matrix.
695 */
696 void
697 scale(const VectorBase &scaling_factors);
698
699 /**
700 * Assignment <tt>*this = a*V</tt>.
701 */
702 void
703 equ(const PetscScalar a, const VectorBase &V);
704
705 /**
706 * Prints the PETSc vector object values using PETSc internal vector
707 * viewer function <tt>VecView</tt>. The default format prints the
708 * vector's contents, including indices of vector elements. For other
709 * valid view formats, consult
710 * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecView.html
711 */
712 void
713 write_ascii(const PetscViewerFormat format = PETSC_VIEWER_DEFAULT);
714
715 /**
716 * Print to a stream. @p precision denotes the desired precision with
717 * which values shall be printed, @p scientific whether scientific
718 * notation shall be used. If @p across is @p true then the vector is
719 * printed in a line, while if @p false then the elements are printed on a
720 * separate line each.
721 */
722 void
723 print(std::ostream &out,
724 const unsigned int precision = 3,
725 const bool scientific = true,
726 const bool across = true) const;
727
728 /**
729 * Write the data of this object to a stream for the purpose of
730 * serialization using the [BOOST serialization
731 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
732 *
733 * @note Each processor only serializes its own locally owned values.
734 */
735 template <class Archive>
736 void
737 save(Archive &ar, const unsigned int version) const;
738
739 /**
740 * Read the data of this object from a stream for the purpose of
741 * serialization using the [BOOST serialization
742 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
743 */
744 template <class Archive>
745 void
746 load(Archive &ar, const unsigned int version);
747
748 # ifdef DOXYGEN
749 /**
750 * Write and read the data of this object from a stream for the purpose
751 * of serialization using the [BOOST serialization
752 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
753 */
754 template <class Archive>
755 void
756 serialize(Archive &archive, const unsigned int version);
757 # else
758 // This macro defines the serialize() method that is compatible with
759 // the templated save() and load() method that have been implemented.
760 BOOST_SERIALIZATION_SPLIT_MEMBER()
761 # endif
762
763 /**
764 * Swap the contents of this vector and the other vector @p v. One could
765 * do this operation with a temporary variable and copying over the data
766 * elements, but this function is significantly more efficient since it
767 * only swaps the pointers to the data of the two vectors and therefore
768 * does not need to allocate temporary storage and move data around.
769 *
770 * This function is analogous to the @p swap function of all C++
771 * standard containers. Also, there is a global function
772 * <tt>swap(u,v)</tt> that simply calls <tt>u.swap(v)</tt>, again in
773 * analogy to standard functions.
774 */
775 void
776 swap(VectorBase &v) noexcept;
777
778 /**
779 * Conversion operator to gain access to the underlying PETSc type. If you
780 * do this, you cut this class off some information it may need, so this
781 * conversion operator should only be used if you know what you do. In
782 * particular, it should only be used for read-only operations into the
783 * vector.
784 */
785 operator const Vec &() const;
786
787 /**
788 * Return a reference to the underlying PETSc type. It can be used to
789 * modify the underlying data, so use it only when you know what you
790 * are doing.
791 */
792 Vec &
793 petsc_vector();
794
795 /**
796 * Estimate for the memory consumption (not implemented for this class).
797 */
798 std::size_t
799 memory_consumption() const;
800
801 /**
802 * Return the underlying MPI communicator.
803 */
804 MPI_Comm
805 get_mpi_communicator() const;
806
807 protected:
808 /**
809 * A generic vector object in PETSc. The actual type, a sequential vector,
810 * is set in the constructor.
811 */
812 Vec vector;
813
814 /**
815 * Denotes if this vector has ghost indices associated with it. This means
816 * that at least one of the processes in a parallel program has at least
817 * one ghost index.
818 */
819 bool ghosted;
820
821 /**
822 * This vector contains the global indices of the ghost values. The
823 * location in this vector denotes the local numbering, which is used in
824 * PETSc.
825 */
826 IndexSet ghost_indices;
827
828 /**
829 * Store whether the last action was a write or add operation. This
830 * variable is @p mutable so that the accessor classes can write to it,
831 * even though the vector object they refer to is constant.
832 */
833 mutable VectorOperation::values last_action;
834
835 // Make the reference class a friend.
836 friend class internal::VectorReference;
837
838 /**
839 * Collective set or add operation: This function is invoked by the
840 * collective @p set and @p add with the @p add_values flag set to the
841 * corresponding value.
842 */
843 void
844 do_set_add_operation(const size_type n_elements,
845 const size_type *indices,
846 const PetscScalar *values,
847 const bool add_values);
848
849 /**
850 * Determine ghost indices from the internal PETSc Vec
851 */
852 void
853 determine_ghost_indices();
854 };
855
856
857
858 // ------------------- inline and template functions --------------
859
860 /**
861 * Global function @p swap which overloads the default implementation of the
862 * C++ standard library which uses a temporary object. The function simply
863 * exchanges the data of the two vectors.
864 *
865 * @relatesalso PETScWrappers::VectorBase
866 */
867 inline void
868 swap(VectorBase &u, VectorBase &v) noexcept
869 {
870 u.swap(v);
871 }
872
873 # ifndef DOXYGEN
874 namespace internal
875 {
876 inline VectorReference::VectorReference(const VectorBase &vector,
877 const size_type index)
878 : vector(vector)
879 , index(index)
880 {}
881
882
883 inline const VectorReference &
884 VectorReference::operator=(const VectorReference &r) const
885 {
886 // as explained in the class
887 // documentation, this is not the copy
888 // operator. so simply pass on to the
889 // "correct" assignment operator
890 *this = static_cast<PetscScalar>(r);
891
892 return *this;
893 }
894
895
896
897 inline VectorReference &
898 VectorReference::operator=(const VectorReference &r)
899 {
900 // as explained in the class
901 // documentation, this is not the copy
902 // operator. so simply pass on to the
903 // "correct" assignment operator
904 *this = static_cast<PetscScalar>(r);
905
906 return *this;
907 }
908
909
910
911 inline const VectorReference &
912 VectorReference::operator=(const PetscScalar &value) const
913 {
914 Assert((vector.last_action == VectorOperation::insert) ||
915 (vector.last_action == VectorOperation::unknown),
916 ExcWrongMode(VectorOperation::insert, vector.last_action));
917
918 Assert(!vector.has_ghost_elements(), ExcGhostsPresent());
919
920 const PetscInt petsc_i = index;
921
922 const PetscErrorCode ierr =
923 VecSetValues(vector, 1, &petsc_i, &value, INSERT_VALUES);
924 AssertThrow(ierr == 0, ExcPETScError(ierr));
925
926 vector.last_action = VectorOperation::insert;
927
928 return *this;
929 }
930
931
932
933 inline const VectorReference &
934 VectorReference::operator+=(const PetscScalar &value) const
935 {
936 Assert((vector.last_action == VectorOperation::add) ||
937 (vector.last_action == VectorOperation::unknown),
938 ExcWrongMode(VectorOperation::add, vector.last_action));
939
940 Assert(!vector.has_ghost_elements(), ExcGhostsPresent());
941
942 vector.last_action = VectorOperation::add;
943
944 // we have to do above actions in any
945 // case to be consistent with the MPI
946 // communication model (see the
947 // comments in the documentation of
948 // PETScWrappers::MPI::Vector), but we
949 // can save some work if the addend is
950 // zero
951 if (value == PetscScalar())
952 return *this;
953
954 // use the PETSc function to add something
955 const PetscInt petsc_i = index;
956 const PetscErrorCode ierr =
957 VecSetValues(vector, 1, &petsc_i, &value, ADD_VALUES);
958 AssertThrow(ierr == 0, ExcPETScError(ierr));
959
960
961 return *this;
962 }
963
964
965
966 inline const VectorReference &
967 VectorReference::operator-=(const PetscScalar &value) const
968 {
969 Assert((vector.last_action == VectorOperation::add) ||
970 (vector.last_action == VectorOperation::unknown),
971 ExcWrongMode(VectorOperation::add, vector.last_action));
972
973 Assert(!vector.has_ghost_elements(), ExcGhostsPresent());
974
975 vector.last_action = VectorOperation::add;
976
977 // we have to do above actions in any
978 // case to be consistent with the MPI
979 // communication model (see the
980 // comments in the documentation of
981 // PETScWrappers::MPI::Vector), but we
982 // can save some work if the addend is
983 // zero
984 if (value == PetscScalar())
985 return *this;
986
987 // use the PETSc function to
988 // add something
989 const PetscInt petsc_i = index;
990 const PetscScalar subtractand = -value;
991 const PetscErrorCode ierr =
992 VecSetValues(vector, 1, &petsc_i, &subtractand, ADD_VALUES);
993 AssertThrow(ierr == 0, ExcPETScError(ierr));
994
995 return *this;
996 }
997
998
999
1000 inline const VectorReference &
1001 VectorReference::operator*=(const PetscScalar &value) const
1002 {
1003 Assert((vector.last_action == VectorOperation::insert) ||
1004 (vector.last_action == VectorOperation::unknown),
1005 ExcWrongMode(VectorOperation::insert, vector.last_action));
1006
1007 Assert(!vector.has_ghost_elements(), ExcGhostsPresent());
1008
1009 vector.last_action = VectorOperation::insert;
1010
1011 // we have to do above actions in any
1012 // case to be consistent with the MPI
1013 // communication model (see the
1014 // comments in the documentation of
1015 // PETScWrappers::MPI::Vector), but we
1016 // can save some work if the factor is
1017 // one
1018 if (value == 1.)
1019 return *this;
1020
1021 const PetscInt petsc_i = index;
1022 const PetscScalar new_value = static_cast<PetscScalar>(*this) * value;
1023
1024 const PetscErrorCode ierr =
1025 VecSetValues(vector, 1, &petsc_i, &new_value, INSERT_VALUES);
1026 AssertThrow(ierr == 0, ExcPETScError(ierr));
1027
1028 return *this;
1029 }
1030
1031
1032
1033 inline const VectorReference &
1034 VectorReference::operator/=(const PetscScalar &value) const
1035 {
1036 Assert((vector.last_action == VectorOperation::insert) ||
1037 (vector.last_action == VectorOperation::unknown),
1038 ExcWrongMode(VectorOperation::insert, vector.last_action));
1039
1040 Assert(!vector.has_ghost_elements(), ExcGhostsPresent());
1041
1042 vector.last_action = VectorOperation::insert;
1043
1044 // we have to do above actions in any
1045 // case to be consistent with the MPI
1046 // communication model (see the
1047 // comments in the documentation of
1048 // PETScWrappers::MPI::Vector), but we
1049 // can save some work if the factor is
1050 // one
1051 if (value == 1.)
1052 return *this;
1053
1054 const PetscInt petsc_i = index;
1055 const PetscScalar new_value = static_cast<PetscScalar>(*this) / value;
1056
1057 const PetscErrorCode ierr =
1058 VecSetValues(vector, 1, &petsc_i, &new_value, INSERT_VALUES);
1059 AssertThrow(ierr == 0, ExcPETScError(ierr));
1060
1061 return *this;
1062 }
1063
1064
1065
1066 inline PetscReal
1067 VectorReference::real() const
1068 {
1069 # ifndef PETSC_USE_COMPLEX
1070 return static_cast<PetscScalar>(*this);
1071 # else
1072 return PetscRealPart(static_cast<PetscScalar>(*this));
1073 # endif
1074 }
1075
1076
1077
1078 inline PetscReal
1079 VectorReference::imag() const
1080 {
1081 # ifndef PETSC_USE_COMPLEX
1082 return PetscReal(0);
1083 # else
1084 return PetscImaginaryPart(static_cast<PetscScalar>(*this));
1085 # endif
1086 }
1087
1088 } // namespace internal
1089
1090 inline bool
1091 VectorBase::in_local_range(const size_type index) const
1092 {
1093 PetscInt begin, end;
1094 const PetscErrorCode ierr =
1095 VecGetOwnershipRange(static_cast<const Vec &>(vector), &begin, &end);
1096 AssertThrow(ierr == 0, ExcPETScError(ierr));
1097
1098 return ((index >= static_cast<size_type>(begin)) &&
1099 (index < static_cast<size_type>(end)));
1100 }
1101
1102
1103 inline IndexSet
1104 VectorBase::locally_owned_elements() const
1105 {
1106 IndexSet is(size());
1107
1108 // PETSc only allows for contiguous local ranges, so this is simple
1109 const std::pair<size_type, size_type> x = local_range();
1110 is.add_range(x.first, x.second);
1111 return is;
1112 }
1113
1114
1115
1116 inline bool
1117 VectorBase::has_ghost_elements() const
1118 {
1119 return ghosted;
1120 }
1121
1122
1123 inline const IndexSet &
1124 VectorBase::ghost_elements() const
1125 {
1126 return ghost_indices;
1127 }
1128
1129
1130 inline void
1131 VectorBase::update_ghost_values() const
1132 {
1133 if (ghosted)
1134 {
1135 PetscErrorCode ierr;
1136
1137 ierr = VecGhostUpdateBegin(vector, INSERT_VALUES, SCATTER_FORWARD);
1138 AssertThrow(ierr == 0, ExcPETScError(ierr));
1139 ierr = VecGhostUpdateEnd(vector, INSERT_VALUES, SCATTER_FORWARD);
1140 AssertThrow(ierr == 0, ExcPETScError(ierr));
1141 }
1142 }
1143
1144
1145
1146 inline internal::VectorReference
1147 VectorBase::operator()(const size_type index)
1148 {
1149 return internal::VectorReference(*this, index);
1150 }
1151
1152
1153
1154 inline PetscScalar
1155 VectorBase::operator()(const size_type index) const
1156 {
1157 return static_cast<PetscScalar>(internal::VectorReference(*this, index));
1158 }
1159
1160
1161
1162 inline internal::VectorReference
1163 VectorBase::operator[](const size_type index)
1164 {
1165 return operator()(index);
1166 }
1167
1168
1169
1170 inline PetscScalar
1171 VectorBase::operator[](const size_type index) const
1172 {
1173 return operator()(index);
1174 }
1175
1176 inline MPI_Comm
1177 VectorBase::get_mpi_communicator() const
1178 {
1179 return PetscObjectComm(reinterpret_cast<PetscObject>(vector));
1180 }
1181
1182 inline void
1183 VectorBase::extract_subvector_to(const std::vector<size_type> &indices,
1184 std::vector<PetscScalar> &values) const
1185 {
1186 Assert(indices.size() <= values.size(),
1187 ExcDimensionMismatch(indices.size(), values.size()));
1188 extract_subvector_to(indices.begin(), indices.end(), values.begin());
1189 }
1190
1191 inline void
1192 VectorBase::extract_subvector_to(
1193 const ArrayView<const types::global_dof_index> &indices,
1194 const ArrayView<PetscScalar> &elements) const
1195 {
1196 AssertDimension(indices.size(), elements.size());
1197 extract_subvector_to(indices.begin(), indices.end(), elements.begin());
1198 }
1199
1200
1201 template <typename ForwardIterator, typename OutputIterator>
1202 inline void
1203 VectorBase::extract_subvector_to(const ForwardIterator indices_begin,
1204 const ForwardIterator indices_end,
1205 OutputIterator values_begin) const
1206 {
1207 if (indices_begin == indices_end)
1208 return;
1209
1210 // if we are dealing
1211 // with a parallel vector
1212 if (ghosted)
1213 {
1214 // there is the possibility
1215 // that the vector has
1216 // ghost elements. in that
1217 // case, we first need to
1218 // figure out which
1219 // elements we own locally,
1220 // then get a pointer to
1221 // the elements that are
1222 // stored here (both the
1223 // ones we own as well as
1224 // the ghost elements). in
1225 // this array, the locally
1226 // owned elements come
1227 // first followed by the
1228 // ghost elements whose
1229 // position we can get from
1230 // an index set
1231 PetscInt begin, end;
1232 PetscErrorCode ierr = VecGetOwnershipRange(vector, &begin, &end);
1233 AssertThrow(ierr == 0, ExcPETScError(ierr));
1234
1235 Vec locally_stored_elements = nullptr;
1236 ierr = VecGhostGetLocalForm(vector, &locally_stored_elements);
1237 AssertThrow(ierr == 0, ExcPETScError(ierr));
1238
1239 PetscInt lsize;
1240 ierr = VecGetSize(locally_stored_elements, &lsize);
1241 AssertThrow(ierr == 0, ExcPETScError(ierr));
1242
1243 const PetscScalar *ptr;
1244 ierr = VecGetArrayRead(locally_stored_elements, &ptr);
1245 AssertThrow(ierr == 0, ExcPETScError(ierr));
1246
1247 auto input = indices_begin;
1248 auto output = values_begin;
1249 while (input != indices_end)
1250 {
1251 const auto index = static_cast<PetscInt>(*input);
1252 AssertIntegerConversion(index, *input);
1253 if (index >= begin && index < end)
1254 {
1255 // local entry
1256 *output = *(ptr + index - begin);
1257 }
1258 else
1259 {
1260 // ghost entry
1261 const auto ghost_index = ghost_indices.index_within_set(*input);
1262
1263 AssertIndexRange(ghost_index + end - begin, lsize);
1264 *output = *(ptr + ghost_index + end - begin);
1265 }
1266
1267 ++input;
1268 ++output;
1269 }
1270
1271 ierr = VecRestoreArrayRead(locally_stored_elements, &ptr);
1272 AssertThrow(ierr == 0, ExcPETScError(ierr));
1273
1274 ierr = VecGhostRestoreLocalForm(vector, &locally_stored_elements);
1275 AssertThrow(ierr == 0, ExcPETScError(ierr));
1276 }
1277 // if the vector is local or the
1278 // caller, then simply access the
1279 // element we are interested in
1280 else
1281 {
1282 PetscInt begin, end;
1283 PetscErrorCode ierr = VecGetOwnershipRange(vector, &begin, &end);
1284 AssertThrow(ierr == 0, ExcPETScError(ierr));
1285
1286 const PetscScalar *ptr;
1287 ierr = VecGetArrayRead(vector, &ptr);
1288 AssertThrow(ierr == 0, ExcPETScError(ierr));
1289
1290 auto input = indices_begin;
1291 auto output = values_begin;
1292 while (input != indices_end)
1293 {
1294 const auto index = static_cast<PetscInt>(*input);
1295 AssertIntegerConversion(index, *input);
1296
1297 Assert(index >= begin && index < end,
1298 ExcMessage("You are accessing elements of a vector without "
1299 "ghost elements that are not actually owned by "
1300 "this vector. A typical case where this may "
1301 "happen is if you are passing a non-ghosted "
1302 "(completely distributed) vector to a function "
1303 "that expects a vector that stores ghost "
1304 "elements for all locally relevant or locally "
1305 "active vector entries."));
1306
1307 *output = *(ptr + index - begin);
1308
1309 ++input;
1310 ++output;
1311 }
1312
1313 ierr = VecRestoreArrayRead(vector, &ptr);
1314 AssertThrow(ierr == 0, ExcPETScError(ierr));
1315 }
1316 }
1317
1318 template <class Archive>
1319 inline void
1320 VectorBase::save(Archive &ar, const unsigned int) const
1321 {
1322 // forward to serialization function in the base class.
1323 ar &static_cast<const EnableObserverPointer &>(*this);
1324 ar &size();
1325 ar &local_range();
1326
1327 const PetscScalar *array = nullptr;
1328 int ierr = VecGetArrayRead(*this, &array);
1329 AssertThrow(ierr == 0, ExcPETScError(ierr));
1330
1331 boost::serialization::array_wrapper<const PetscScalar> wrapper(
1332 array, locally_owned_size());
1333 ar &wrapper;
1334
1335 ierr = VecRestoreArrayRead(*this, &array);
1336 AssertThrow(ierr == 0, ExcPETScError(ierr));
1337 }
1338
1339
1340
1341 template <class Archive>
1342 inline void
1343 VectorBase::load(Archive &ar, const unsigned int)
1344 {
1345 ar &static_cast<EnableObserverPointer &>(*this);
1346
1347 size_type size = 0;
1348 std::pair<size_type, size_type> local_range;
1349
1350 ar &size;
1351 Assert(size == this->size(),
1352 ExcMessage("The serialized value of size (" + std::to_string(size) +
1353 ") does not match the current size (" +
1354 std::to_string(this->size()) + ")"));
1355 ar &local_range;
1356 Assert(local_range == this->local_range(),
1357 ExcMessage("The serialized value of local_range (" +
1358 std::to_string(local_range.first) + ", " +
1359 std::to_string(local_range.second) +
1360 ") does not match the current local_range (" +
1361 std::to_string(this->local_range().first) + ", " +
1362 std::to_string(this->local_range().second) + ")"));
1363
1364 PetscScalar *array = nullptr;
1365 int ierr = VecGetArray(petsc_vector(), &array);
1366 AssertThrow(ierr == 0, ExcPETScError(ierr));
1367
1368 boost::serialization::array_wrapper<PetscScalar> wrapper(
1369 array, locally_owned_size());
1370 ar &wrapper;
1371
1372 ierr = VecRestoreArray(petsc_vector(), &array);
1373 AssertThrow(ierr == 0, ExcPETScError(ierr));
1374 }
1375 # endif // DOXYGEN
1376 } // namespace PETScWrappers
1377
1378 DEAL_II_NAMESPACE_CLOSE
1379
1380 #else
1381
1382 // Make sure the scripts that create the C++20 module input files have
1383 // something to latch on if the preprocessor #ifdef above would
1384 // otherwise lead to an empty content of the file.
1385 DEAL_II_NAMESPACE_OPEN
1386 DEAL_II_NAMESPACE_CLOSE
1387
1388 #endif // DEAL_II_WITH_PETSC
1389
1390 #endif