Debian Codegraph @

include/deal.II/sundials/n_vector.templates.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 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
16 #ifndef dealii_sundials_n_vector_templates_h
17 #define dealii_sundials_n_vector_templates_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/sundials/n_vector.h>
22 #include <deal.II/sundials/sundials_types.h>
23
24 #ifdef DEAL_II_WITH_SUNDIALS
25
26 # include <deal.II/base/exceptions.h>
27 # include <deal.II/base/mpi.templates.h>
28
29 # include <deal.II/lac/block_vector.h>
30 # include <deal.II/lac/la_parallel_block_vector.h>
31 # include <deal.II/lac/la_parallel_vector.h>
32 # include <deal.II/lac/petsc_block_vector.h>
33 # include <deal.II/lac/petsc_vector.h>
34 # include <deal.II/lac/trilinos_parallel_block_vector.h>
35 # include <deal.II/lac/trilinos_vector.h>
36 # include <deal.II/lac/vector_memory.h>
37
38 # include <sundials/sundials_nvector.h>
39
40 # include <limits>
41
42 DEAL_II_NAMESPACE_OPEN
43
44 namespace SUNDIALS
45 {
46 namespace internal
47 {
48 /**
49 * An internal class that stores a pointer to a vector and manages the
50 * memory if necessary. Objects of this class are used as the `content`
51 * field in the SUNDIALS N_Vector module. In addition, this class has a
52 * flag to store whether the stored vector should be treated as const. When
53 * get() is called on a non-const object of this class the flag is checked
54 * and an exception is thrown if the vector is actually const. Thus, we
55 * retain a kind of "runtime const correctness" although the static const
56 * correctness is lost because SUNDIALS N_Vector does not support constness.
57 */
58 template <typename VectorType>
59 class NVectorContent
60 {
61 public:
62 /**
63 * Create a non-owning content with an existing @p vector.
64 * @param vector The underlying vector to wrap in this object.
65 */
66 NVectorContent(VectorType *vector);
67
68 /**
69 * Create a non-owning content with an existing const @p vector. If this
70 * constructor is used, access is only allowed via the get() const method.
71 * @param vector The underlying vector to wrap in this object.
72 */
73 NVectorContent(const VectorType *vector);
74
75 /**
76 * Allocate a new (non-const) vector wrapped in a new content object. The
77 * vector will be deallocated automatically when this object is destroyed.
78 *
79 * @note This constructor is intended for the N_VClone() call of SUNDIALS.
80 */
81 NVectorContent(const MPI_Comm comm);
82
83 /**
84 * Non-const access to the stored vector. Only allowed if a constructor
85 * different than NVectorContent(const VectorType *vector) was used.
86 * @return
87 */
88 VectorType *
89 get();
90
91 /**
92 * Const access to the stored vector. Always allowed.
93 */
94 const VectorType *
95 get() const;
96
97 /**
98 * Return a reference to a copy of the communicator the vector uses.
99 * This function exists because the N_Vector
100 * interface requires a function that returns a `void*` pointing
101 * to the communicator object -- so somewhere, we need to have an
102 * address to point to. The issue is that our vectors typically
103 * return a *copy* of the communicator, rather than a reference to
104 * the communicator they use, and so there is only a temporary
105 * object and no address we can point to. To work around this
106 * requirement, this class stores a copy of the communicator,
107 * and this function here returns a reference to this copy.
108 */
109 const MPI_Comm &
110 get_mpi_communicator() const;
111
112 private:
113 using PointerType =
114 std::unique_ptr<VectorType, std::function<void(VectorType *)>>;
115
116 /**
117 * Vector memory which might be used to allocate storage if
118 * NVectorContent() is called.
119 */
120 GrowingVectorMemory<VectorType> mem;
121
122 /**
123 * Actually stored vector content.
124 */
125 PointerType vector;
126
127 /**
128 * A copy of the communicator the vector uses, initialized in the
129 * constructor of this class. We store this because the N_Vector
130 * interface requires a function that returns a `void*` pointing
131 * to the communicator object -- so somewhere, we need to have an
132 * address to point to. The issue is that our vectors typically
133 * return a *copy* of the communicator, rather than a reference to
134 * the communicator they use, and so there is only a temporary
135 * object and no address we can point to.
136 */
137 MPI_Comm comm;
138
139 /**
140 * Flag storing whether the stored pointer is to be treated as const. If
141 * the pointer passed in the constructor was indeed const, it is cast away
142 * but this flag will be set to true. Access to the pointer must then
143 * check that this flag is set correctly.
144 */
145 const bool is_const;
146 };
147
148 /**
149 * Helper to create a vector with all operations and the given @p content.
150 *
151 * @param content The vector content to attach to the N_Vector.
152 * @return A new N_Vector
153 */
154 template <typename VectorType>
155 N_Vector
156 create_nvector(NVectorContent<VectorType> *content
157 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
158 ,
159 SUNContext nvector_context
160 # endif
161 );
162
163 /**
164 * Helper to create an empty vector with all operations but no content.
165 * @return A new N_Vector
166 */
167 template <typename VectorType>
168 N_Vector
169 create_empty_nvector(
170 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
171 SUNContext nvector_context
172 # endif
173 );
174
175
176 /**
177 * Variable template that is true for distributed deal.II vectors and false
178 * otherwise.
179 */
180 template <typename VectorType>
181 constexpr bool is_dealii_compatible_distributed_vector =
182 std::is_same_v<
183 VectorType,
184 LinearAlgebra::distributed::Vector<typename VectorType::value_type,
185 MemorySpace::Host>> ||
186 std::is_same_v<VectorType,
187 LinearAlgebra::distributed::BlockVector<
188 typename VectorType::value_type>>;
189
190 template <typename VectorType,
191 std::enable_if_t<!IsBlockVector<VectorType>::value> * = nullptr>
192 unsigned int
193 n_blocks(const VectorType &)
194 {
195 return 1;
196 }
197
198
199
200 template <typename VectorType,
201 std::enable_if_t<IsBlockVector<VectorType>::value> * = nullptr>
202 unsigned int
203 n_blocks(const VectorType &vector)
204 {
205 return vector.n_blocks();
206 }
207
208
209
210 template <typename VectorType,
211 std::enable_if_t<!IsBlockVector<VectorType>::value> * = nullptr>
212 VectorType &
213 block(VectorType &vector, const unsigned int b)
214 {
215 AssertDimension(b, 0);
216 (void)b;
217 return vector;
218 }
219
220
221
222 template <typename VectorType,
223 std::enable_if_t<!IsBlockVector<VectorType>::value> * = nullptr>
224 const VectorType &
225 block(const VectorType &vector, const unsigned int b)
226 {
227 AssertDimension(b, 0);
228 (void)b;
229 return vector;
230 }
231
232
233
234 template <typename VectorType,
235 std::enable_if_t<IsBlockVector<VectorType>::value> * = nullptr>
236 typename VectorType::BlockType &
237 block(VectorType &vector, const unsigned int b)
238 {
239 return vector.block(b);
240 }
241
242
243
244 template <typename VectorType,
245 std::enable_if_t<IsBlockVector<VectorType>::value> * = nullptr>
246 const typename VectorType::BlockType &
247 block(const VectorType &vector, const unsigned int b)
248 {
249 return vector.block(b);
250 }
251
252
253 /**
254 * Collection of all operations specified by SUNDIALS N_Vector
255 * documentation. These functions are attached to the generic N_Vector
256 * structure.
257 */
258 namespace NVectorOperations
259 {
260 N_Vector_ID
261 get_vector_id(N_Vector v);
262
263 N_Vector
264 clone_empty(N_Vector w);
265
266 template <typename VectorType>
267 N_Vector
268 clone(N_Vector w);
269
270 template <typename VectorType>
271 void
272 destroy(N_Vector v);
273
274 template <typename VectorType>
275 sunindextype
276 get_global_length(N_Vector v);
277
278 template <typename VectorType>
279 void
280 linear_sum(SUNDIALS::realtype a,
281 N_Vector x,
282 SUNDIALS::realtype b,
283 N_Vector y,
284 N_Vector z);
285
286 template <
287 typename VectorType,
288 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>>
289 * = nullptr>
290 int
291 linear_combination(int nv, realtype *c, N_Vector *x, N_Vector z);
292
293 template <typename VectorType>
294 SUNDIALS::realtype
295 dot_product(N_Vector x, N_Vector y);
296
297 template <
298 typename VectorType,
299 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>>
300 * = nullptr>
301 int
302 dot_product_multi(int nv, N_Vector x, N_Vector *Y, realtype *d);
303
304 template <
305 typename VectorType,
306 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>>
307 * = nullptr>
308 int
309 dot_product_multi_local(int nv, N_Vector x, N_Vector *y, realtype *d);
310
311
312 template <
313 typename VectorType,
314 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>>
315 * = nullptr>
316 int
317 dot_product_multi_all_reduce(int nv, N_Vector x, realtype *d);
318
319 template <typename VectorType>
320 SUNDIALS::realtype
321 weighted_l2_norm(N_Vector x, N_Vector y);
322
323 template <typename VectorType>
324 SUNDIALS::realtype
325 l1_norm(N_Vector x);
326
327 template <typename VectorType>
328 void
329 elementwise_product(N_Vector x, N_Vector y, N_Vector z);
330
331 template <typename VectorType,
332 std::enable_if_t<!IsBlockVector<VectorType>::value, int> = 0>
333 void
334 elementwise_div(N_Vector x, N_Vector y, N_Vector z);
335
336 template <typename VectorType,
337 std::enable_if_t<IsBlockVector<VectorType>::value, int> = 0>
338 void
339 elementwise_div(N_Vector x, N_Vector y, N_Vector z);
340
341 template <typename VectorType,
342 std::enable_if_t<!IsBlockVector<VectorType>::value, int> = 0>
343 void
344 elementwise_inv(N_Vector x, N_Vector z);
345
346 template <typename VectorType,
347 std::enable_if_t<IsBlockVector<VectorType>::value, int> = 0>
348 void
349 elementwise_inv(N_Vector x, N_Vector z);
350
351 template <typename VectorType,
352 std::enable_if_t<!IsBlockVector<VectorType>::value, int> = 0>
353 void
354 elementwise_abs(N_Vector x, N_Vector z);
355
356 template <typename VectorType,
357 std::enable_if_t<IsBlockVector<VectorType>::value, int> = 0>
358 void
359 elementwise_abs(N_Vector x, N_Vector z);
360
361 template <typename VectorType>
362 SUNDIALS::realtype
363 weighted_rms_norm(N_Vector x, N_Vector w);
364
365 template <typename VectorType>
366 SUNDIALS::realtype
367 weighted_rms_norm_mask(N_Vector x, N_Vector w, N_Vector mask);
368
369 template <typename VectorType>
370 SUNDIALS::realtype
371 max_norm(N_Vector x);
372
373 template <typename VectorType,
374 std::enable_if_t<is_serial_vector<VectorType>::value, int> = 0>
375 SUNDIALS::realtype
376 min_element(N_Vector x);
377
378 template <typename VectorType,
379 std::enable_if_t<!is_serial_vector<VectorType>::value &&
380 !IsBlockVector<VectorType>::value,
381 int> = 0>
382 SUNDIALS::realtype
383 min_element(N_Vector x);
384
385 template <typename VectorType,
386 std::enable_if_t<!is_serial_vector<VectorType>::value &&
387 IsBlockVector<VectorType>::value,
388 int> = 0>
389 SUNDIALS::realtype
390 min_element(N_Vector x);
391
392 template <typename VectorType>
393 void
394 scale(SUNDIALS::realtype c, N_Vector x, N_Vector z);
395
396 template <typename VectorType>
397 void
398 set_constant(SUNDIALS::realtype c, N_Vector v);
399
400 template <typename VectorType>
401 void
402 add_constant(N_Vector x, SUNDIALS::realtype b, N_Vector z);
403
404 template <typename VectorType>
405 const MPI_Comm &
406 get_mpi_communicator(N_Vector v);
407
408 # if DEAL_II_SUNDIALS_VERSION_GTE(7, 0, 0)
409 /**
410 * Sundials likes their own communicator type by value.
411 */
412 template <typename VectorType>
413 inline SUNComm
414 get_mpi_communicator_by_value(N_Vector v);
415 # else
416 /**
417 * Sundials likes a void* but we want to use the above functions
418 * internally with a safe type.
419 */
420 template <typename VectorType>
421 inline void *
422 get_mpi_communicator_as_void_ptr(N_Vector v);
423 # endif
424 } // namespace NVectorOperations
425 } // namespace internal
426 } // namespace SUNDIALS
427
428
429
430 // -------------- Implementation of the functions declared above ---------
431
432 namespace SUNDIALS
433 {
434 namespace internal
435 {
436 template <typename VectorType,
437 std::enable_if_t<is_serial_vector<VectorType>::value, int> = 0>
438 MPI_Comm
439 get_mpi_communicator_from_vector(const VectorType &)
440 {
441 return MPI_COMM_SELF;
442 }
443
444
445
446 template <typename VectorType,
447 std::enable_if_t<!is_serial_vector<VectorType>::value &&
448 !IsBlockVector<VectorType>::value,
449 int> = 0>
450 MPI_Comm
451 get_mpi_communicator_from_vector(const VectorType &v)
452 {
453 # ifndef DEAL_II_WITH_MPI
454 (void)v;
455 return MPI_COMM_SELF;
456 # else
457 return v.get_mpi_communicator();
458 # endif
459 }
460
461
462
463 template <typename VectorType,
464 std::enable_if_t<!is_serial_vector<VectorType>::value &&
465 IsBlockVector<VectorType>::value,
466 int> = 0>
467 MPI_Comm
468 get_mpi_communicator_from_vector(const VectorType &v)
469 {
470 # ifndef DEAL_II_WITH_MPI
471 (void)v;
472 return MPI_COMM_SELF;
473 # else
474 Assert(v.n_blocks() > 0,
475 ExcMessage("You cannot ask a block vector without blocks "
476 "for its MPI communicator."));
477 return v.block(0).get_mpi_communicator();
478 # endif
479 }
480
481
482 template <typename VectorType>
483 NVectorContent<VectorType>::NVectorContent(const MPI_Comm comm)
484 : vector(typename VectorMemory<VectorType>::Pointer(mem))
485 , comm(comm)
486 , is_const(false)
487 {}
488
489
490 template <typename VectorType>
491 NVectorContent<VectorType>::NVectorContent(VectorType *vector)
492 : vector(vector,
493 [](VectorType *) { /* not owning memory -> don't free*/ })
494 , comm(get_mpi_communicator_from_vector(*vector))
495 , is_const(false)
496 {}
497
498
499
500 template <typename VectorType>
501 NVectorContent<VectorType>::NVectorContent(const VectorType *vector)
502 : vector(const_cast<VectorType *>(vector),
503 [](VectorType *) { /* not owning memory -> don't free*/ })
504 , comm(get_mpi_communicator_from_vector(*vector))
505 , is_const(true)
506 {}
507
508
509
510 template <typename VectorType>
511 VectorType *
512 NVectorContent<VectorType>::get()
513 {
514 AssertThrow(
515 !is_const,
516 ExcMessage(
517 "Tried to access a constant vector content as non-const."
518 " This most likely happened because a vector that is passed to a"
519 " NVectorView() call should not be const.\n"
520 "Alternatively, if you tried to access the vector, use"
521 " unwrap_nvector_const() for this vector."));
522 return vector.get();
523 }
524
525
526
527 template <typename VectorType>
528 const VectorType *
529 NVectorContent<VectorType>::get() const
530 {
531 return vector.get();
532 }
533
534
535
536 template <typename VectorType>
537 const MPI_Comm &
538 NVectorContent<VectorType>::get_mpi_communicator() const
539 {
540 return comm;
541 }
542
543
544 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
545 template <typename VectorType>
546 NVectorView<VectorType>
547 make_nvector_view(VectorType &vector, SUNContext nvector_context)
548 {
549 return NVectorView<VectorType>(vector, nvector_context);
550 }
551 # else
552 template <typename VectorType>
553 NVectorView<VectorType>
554 make_nvector_view(VectorType &vector)
555 {
556 return NVectorView<VectorType>(vector);
557 }
558 # endif
559
560
561
562 template <typename VectorType>
563 VectorType *
564 unwrap_nvector(N_Vector v)
565 {
566 Assert(v != nullptr, ExcInternalError());
567 Assert(v->content != nullptr, ExcInternalError());
568 auto *pContent =
569 reinterpret_cast<NVectorContent<VectorType> *>(v->content);
570 return pContent->get();
571 }
572
573
574
575 template <typename VectorType>
576 const VectorType *
577 unwrap_nvector_const(N_Vector v)
578 {
579 Assert(v != nullptr, ExcInternalError());
580 Assert(v->content != nullptr, ExcInternalError());
581 const auto *pContent =
582 reinterpret_cast<const NVectorContent<VectorType> *>(v->content);
583 return pContent->get();
584 }
585
586
587
588 template <typename VectorType>
589 NVectorView<VectorType>::NVectorView(VectorType &vector
590 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
591 ,
592 SUNContext nvector_context
593 # endif
594 )
595 : vector_ptr(
596 create_nvector(new NVectorContent<std::remove_const_t<VectorType>>(
597 &vector)
598 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
599 ,
600 nvector_context
601 # endif
602 ),
603 [](N_Vector v) { N_VDestroy(v); })
604 {}
605
606
607
608 template <typename VectorType>
609 NVectorView<VectorType>::operator N_Vector() const
610 {
611 Assert(vector_ptr != nullptr, ExcNotInitialized());
612 return vector_ptr.get();
613 }
614
615
616
617 template <typename VectorType>
618 N_Vector
619 NVectorView<VectorType>::operator->() const
620 {
621 Assert(vector_ptr != nullptr, ExcNotInitialized());
622 return vector_ptr.get();
623 }
624
625
626
627 template <typename VectorType>
628 N_Vector
629 create_nvector(NVectorContent<VectorType> *content
630 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
631 ,
632 SUNContext nvector_context
633 # endif
634 )
635 {
636 // Create an N_Vector with operators attached and empty content
637 # if DEAL_II_SUNDIALS_VERSION_LT(6, 0, 0)
638 N_Vector v = create_empty_nvector<VectorType>();
639 # else
640 N_Vector v = create_empty_nvector<VectorType>(nvector_context);
641 # endif
642 Assert(v != nullptr, ExcInternalError());
643
644 v->content = content;
645 Assert(v->content != nullptr, ExcInternalError());
646 return (v);
647 }
648
649
650
651 namespace NVectorOperations
652 {
653 N_Vector_ID
654 get_vector_id(N_Vector)
655 {
656 return SUNDIALS_NVEC_CUSTOM;
657 }
658
659
660
661 N_Vector
662 clone_empty(N_Vector w)
663 {
664 Assert(w != nullptr, ExcInternalError());
665 # if DEAL_II_SUNDIALS_VERSION_LT(6, 0, 0)
666 N_Vector v = N_VNewEmpty();
667 # else
668 N_Vector v = N_VNewEmpty(w->sunctx);
669 # endif
670 Assert(v != nullptr, ExcInternalError());
671
672 int status = N_VCopyOps(w, v);
673 Assert(status == 0, ExcInternalError());
674 (void)status;
675
676 return v;
677 }
678
679
680
681 template <typename VectorType>
682 N_Vector
683 clone(N_Vector w)
684 {
685 N_Vector v = clone_empty(w);
686
687 auto *w_dealii = unwrap_nvector_const<VectorType>(w);
688
689 // Create the vector; the corresponding delete is called in destroy()
690 auto cloned = new NVectorContent<VectorType>(
691 get_mpi_communicator_from_vector(*w_dealii));
692
693 // Then also copy the structure and values:
694 *cloned->get() = *w_dealii;
695
696 // Finally set the cloned object in 'v':
697 v->content = cloned;
698 return v;
699 }
700
701
702
703 template <typename VectorType>
704 void
705 destroy(N_Vector v)
706 {
707 // support destroying a nullptr because SUNDIALS vectors also do it
708 if (v == nullptr)
709 return;
710
711 if (v->content != nullptr)
712 {
713 auto *content =
714 reinterpret_cast<NVectorContent<VectorType> *>(v->content);
715 // the NVectorContent knows if it owns the memory and will free
716 // correctly
717 delete content;
718 v->content = nullptr;
719 }
720
721 N_VFreeEmpty(v);
722 }
723
724
725
726 template <typename VectorType>
727 const MPI_Comm &
728 get_mpi_communicator(N_Vector v)
729 {
730 Assert(v != nullptr, ExcInternalError());
731 Assert(v->content != nullptr, ExcInternalError());
732 auto *pContent =
733 reinterpret_cast<NVectorContent<VectorType> *>(v->content);
734 return pContent->get_mpi_communicator();
735 }
736
737
738
739 # if DEAL_II_SUNDIALS_VERSION_GTE(7, 0, 0)
740 template <typename VectorType>
741 SUNComm
742 get_mpi_communicator_by_value(N_Vector v)
743 {
744 # ifndef DEAL_II_WITH_MPI
745 (void)v;
746 return SUN_COMM_NULL;
747 # else
748 if (is_serial_vector<VectorType>::value == false)
749 // SUNDIALS asks for a `SUNComm` object, which is a MPI-aware typedef
750 // for `MPI_Comm` or `int`. To be clear, we adopt the SUNDIALS
751 // interface here.
752 //
753 // Further, we need to cast away const here, as SUNDIALS demands the
754 // communicator by value.
755 return const_cast<SUNComm &>(get_mpi_communicator<VectorType>(v));
756 else
757 return SUN_COMM_NULL;
758 # endif
759 }
760 # else
761 template <typename VectorType>
762 void *
763 get_mpi_communicator_as_void_ptr(N_Vector v)
764 {
765 # ifndef DEAL_II_WITH_MPI
766 (void)v;
767 return nullptr;
768 # else
769 if (is_serial_vector<VectorType>::value == false)
770 // We need to cast away const here, as SUNDIALS demands a pure
771 // `void*`.
772 return &(const_cast<MPI_Comm &>(get_mpi_communicator<VectorType>(v)));
773 else
774 return nullptr;
775 # endif
776 }
777 # endif
778
779
780
781 template <typename VectorType>
782 sunindextype
783 get_global_length(N_Vector v)
784 {
785 return unwrap_nvector_const<VectorType>(v)->size();
786 }
787
788
789
790 template <typename VectorType>
791 void
792 linear_sum(SUNDIALS::realtype a,
793 N_Vector x,
794 SUNDIALS::realtype b,
795 N_Vector y,
796 N_Vector z)
797 {
798 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
799 auto *y_dealii = unwrap_nvector_const<VectorType>(y);
800 auto *z_dealii = unwrap_nvector<VectorType>(z);
801
802 if (z_dealii == x_dealii)
803 z_dealii->sadd(a, b, *y_dealii);
804 else if (z_dealii == y_dealii)
805 z_dealii->sadd(b, a, *x_dealii);
806 else
807 {
808 *z_dealii = 0;
809 z_dealii->add(a, *x_dealii, b, *y_dealii);
810 }
811 }
812
813
814
815 template <
816 typename VectorType,
817 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>> *>
818 int
819 linear_combination(int nv, realtype *c, N_Vector *x, N_Vector z)
820 {
821 std::vector<const VectorType *> unwrapped_vectors(nv);
822 for (int i = 0; i < nv; ++i)
823 unwrapped_vectors[i] = unwrap_nvector_const<VectorType>(x[i]);
824 auto *z_dealii = unwrap_nvector<VectorType>(z);
825
826 // N.B. The first pointer may alias with z.
827 for (unsigned int b = 0; b < n_blocks(*z_dealii); ++b)
828 for (unsigned int j = 0; j < block(*z_dealii, b).locally_owned_size();
829 ++j)
830 {
831 double temp = 0.;
832 for (int i = 0; i < nv; ++i)
833 temp += block(*unwrapped_vectors[i], b).local_element(j) * c[i];
834 block(*z_dealii, b).local_element(j) = temp;
835 }
836
837 return 0;
838 }
839
840
841
842 template <typename VectorType>
843 SUNDIALS::realtype
844 dot_product(N_Vector x, N_Vector y)
845 {
846 return *unwrap_nvector_const<VectorType>(x) *
847 *unwrap_nvector_const<VectorType>(y);
848 }
849
850
851
852 template <
853 typename VectorType,
854 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>> *>
855 int
856 dot_product_multi(int nv, N_Vector x, N_Vector *y, realtype *d)
857 {
858 const int status = dot_product_multi_local<VectorType>(nv, x, y, d);
859 if (status != 0)
860 return status;
861
862 return dot_product_multi_all_reduce<VectorType>(nv, x, d);
863 }
864
865
866
867 template <
868 typename VectorType,
869 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>> *>
870 int
871 dot_product_multi_local(int nv, N_Vector x, N_Vector *y, realtype *d)
872 {
873 std::vector<const VectorType *> unwrapped_vectors(nv);
874 for (int i = 0; i < nv; ++i)
875 unwrapped_vectors[i] = unwrap_nvector_const<VectorType>(y[i]);
876 const VectorType *x_dealii = unwrap_nvector_const<VectorType>(x);
877
878 std::fill(d, d + nv, 0.);
879
880 for (unsigned int b = 0; b < n_blocks(*x_dealii); ++b)
881 for (unsigned int j = 0; j < block(*x_dealii, b).locally_owned_size();
882 ++j)
883 {
884 for (int i = 0; i < nv; ++i)
885 d[i] += block(*x_dealii, b).local_element(j) *
886 block(*unwrapped_vectors[i], b).local_element(j);
887 }
888 return 0;
889 }
890
891
892
893 template <
894 typename VectorType,
895 std::enable_if_t<is_dealii_compatible_distributed_vector<VectorType>> *>
896 int
897 dot_product_multi_all_reduce(int nv, N_Vector x, realtype *d)
898 {
899 ArrayView<realtype> products(d, nv);
900 Utilities::MPI::sum(products,
901 get_mpi_communicator<VectorType>(x),
902 products);
903 return 0;
904 }
905
906
907
908 template <typename VectorType>
909 SUNDIALS::realtype
910 weighted_l2_norm(N_Vector x, N_Vector w)
911 {
912 // TODO copy can be avoided by a custom kernel
913 VectorType tmp = *unwrap_nvector_const<VectorType>(x);
914 auto *w_dealii = unwrap_nvector_const<VectorType>(w);
915 tmp.scale(*w_dealii);
916 return tmp.l2_norm();
917 }
918
919
920
921 template <typename VectorType>
922 SUNDIALS::realtype
923 l1_norm(N_Vector x)
924 {
925 return unwrap_nvector_const<VectorType>(x)->l1_norm();
926 }
927
928
929
930 template <typename VectorType>
931 void
932 set_constant(SUNDIALS::realtype c, N_Vector v)
933 {
934 auto *v_dealii = unwrap_nvector<VectorType>(v);
935 *v_dealii = c;
936 }
937
938
939
940 template <typename VectorType>
941 void
942 add_constant(N_Vector x, SUNDIALS::realtype b, N_Vector z)
943 {
944 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
945 auto *z_dealii = unwrap_nvector<VectorType>(z);
946
947 if (x_dealii == z_dealii)
948 z_dealii->add(b);
949 else
950 {
951 *z_dealii = *x_dealii;
952 z_dealii->add(b);
953 }
954 }
955
956
957
958 template <typename VectorType>
959 void
960 elementwise_product(N_Vector x, N_Vector y, N_Vector z)
961 {
962 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
963 auto *y_dealii = unwrap_nvector_const<VectorType>(y);
964 auto *z_dealii = unwrap_nvector<VectorType>(z);
965 if (z_dealii == x_dealii)
966 z_dealii->scale(*y_dealii);
967 else if (z_dealii == y_dealii)
968 z_dealii->scale(*x_dealii);
969 else
970 {
971 *z_dealii = *y_dealii;
972 z_dealii->scale(*x_dealii);
973 }
974 }
975
976
977
978 template <typename VectorType>
979 SUNDIALS::realtype
980 weighted_rms_norm(N_Vector x, N_Vector w)
981 {
982 // TODO copy can be avoided by a custom kernel
983 VectorType tmp = *unwrap_nvector_const<VectorType>(x);
984 auto *w_dealii = unwrap_nvector_const<VectorType>(w);
985 const auto n = tmp.size();
986 tmp.scale(*w_dealii);
987 return tmp.l2_norm() / std::sqrt(n);
988 }
989
990
991
992 template <typename VectorType>
993 SUNDIALS::realtype
994 weighted_rms_norm_mask(N_Vector x, N_Vector w, N_Vector mask)
995 {
996 // TODO copy can be avoided by a custom kernel
997 VectorType tmp = *unwrap_nvector_const<VectorType>(x);
998 auto *w_dealii = unwrap_nvector_const<VectorType>(w);
999 auto *mask_dealii = unwrap_nvector_const<VectorType>(mask);
1000 const auto n = tmp.size();
1001 tmp.scale(*w_dealii);
1002 tmp.scale(*mask_dealii);
1003 return tmp.l2_norm() / std::sqrt(n);
1004 }
1005
1006
1007
1008 template <typename VectorType>
1009 SUNDIALS::realtype
1010 max_norm(N_Vector x)
1011 {
1012 return unwrap_nvector_const<VectorType>(x)->linfty_norm();
1013 }
1014
1015
1016
1017 template <typename VectorType,
1018 std::enable_if_t<is_serial_vector<VectorType>::value, int>>
1019 SUNDIALS::realtype
1020 min_element(N_Vector x)
1021 {
1022 auto *vector = unwrap_nvector_const<VectorType>(x);
1023 return *std::min_element(vector->begin(), vector->end());
1024 }
1025
1026
1027
1028 template <typename VectorType,
1029 std::enable_if_t<!is_serial_vector<VectorType>::value &&
1030 !IsBlockVector<VectorType>::value,
1031 int>>
1032 SUNDIALS::realtype
1033 min_element(N_Vector x)
1034 {
1035 auto *vector = unwrap_nvector_const<VectorType>(x);
1036
1037
1038 const auto indexed_less_than = [&](const IndexSet::size_type idxa,
1039 const IndexSet::size_type idxb) {
1040 return (*vector)[idxa] < (*vector)[idxb];
1041 };
1042
1043 auto local_elements = vector->locally_owned_elements();
1044
1045 const auto local_min = *std::min_element(local_elements.begin(),
1046 local_elements.end(),
1047 indexed_less_than);
1048 return Utilities::MPI::min((*vector)[local_min],
1049 get_mpi_communicator<VectorType>(x));
1050 }
1051
1052
1053
1054 template <typename VectorType,
1055 std::enable_if_t<!is_serial_vector<VectorType>::value &&
1056 IsBlockVector<VectorType>::value,
1057 int>>
1058 SUNDIALS::realtype
1059 min_element(N_Vector x)
1060 {
1061 auto *vector = unwrap_nvector_const<VectorType>(x);
1062
1063 // initialize local minimum to the largest possible value
1064 auto proc_local_min =
1065 std::numeric_limits<typename VectorType::value_type>::max();
1066
1067 for (unsigned i = 0; i < vector->n_blocks(); ++i)
1068 {
1069 const auto indexed_less_than = [&](const IndexSet::size_type idxa,
1070 const IndexSet::size_type idxb) {
1071 return vector->block(i)[idxa] < vector->block(i)[idxb];
1072 };
1073
1074 auto local_elements = vector->block(i).locally_owned_elements();
1075
1076 const auto block_local_min_element =
1077 std::min_element(local_elements.begin(),
1078 local_elements.end(),
1079 indexed_less_than);
1080
1081 // guard against empty blocks on this processor
1082 if (block_local_min_element != local_elements.end())
1083 proc_local_min =
1084 std::min(proc_local_min,
1085 vector->block(i)[*block_local_min_element]);
1086 }
1087
1088 return Utilities::MPI::min(proc_local_min,
1089 get_mpi_communicator<VectorType>(x));
1090 }
1091
1092
1093
1094 template <typename VectorType>
1095 void
1096 scale(SUNDIALS::realtype c, N_Vector x, N_Vector z)
1097 {
1098 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1099 auto *z_dealii = unwrap_nvector<VectorType>(z);
1100
1101 if (x_dealii == z_dealii)
1102 (*z_dealii) *= c;
1103 else
1104 z_dealii->sadd(0.0, c, *x_dealii);
1105 }
1106
1107
1108
1109 template <typename VectorType,
1110 std::enable_if_t<!IsBlockVector<VectorType>::value, int>>
1111 void
1112 elementwise_div(N_Vector x, N_Vector y, N_Vector z)
1113 {
1114 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1115 auto *y_dealii = unwrap_nvector_const<VectorType>(y);
1116 auto *z_dealii = unwrap_nvector<VectorType>(z);
1117
1118 AssertDimension(x_dealii->size(), z_dealii->size());
1119 AssertDimension(x_dealii->size(), y_dealii->size());
1120
1121 auto x_ele = x_dealii->locally_owned_elements();
1122 for (const auto idx : x_ele)
1123 {
1124 (*z_dealii)[idx] = (*x_dealii)[idx] / (*y_dealii)[idx];
1125 }
1126 z_dealii->compress(VectorOperation::insert);
1127 }
1128
1129
1130
1131 template <typename VectorType,
1132 std::enable_if_t<IsBlockVector<VectorType>::value, int>>
1133 void
1134 elementwise_div(N_Vector x, N_Vector y, N_Vector z)
1135 {
1136 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1137 auto *y_dealii = unwrap_nvector_const<VectorType>(y);
1138 auto *z_dealii = unwrap_nvector<VectorType>(z);
1139
1140 AssertDimension(x_dealii->size(), z_dealii->size());
1141 AssertDimension(x_dealii->size(), y_dealii->size());
1142 AssertDimension(x_dealii->n_blocks(), z_dealii->n_blocks());
1143 AssertDimension(x_dealii->n_blocks(), y_dealii->n_blocks());
1144
1145 for (unsigned i = 0; i < x_dealii->n_blocks(); ++i)
1146 {
1147 auto x_ele = x_dealii->block(i).locally_owned_elements();
1148 for (const auto idx : x_ele)
1149 {
1150 z_dealii->block(i)[idx] =
1151 x_dealii->block(i)[idx] / y_dealii->block(i)[idx];
1152 }
1153 }
1154 z_dealii->compress(VectorOperation::insert);
1155 }
1156
1157
1158
1159 template <typename VectorType,
1160 std::enable_if_t<!IsBlockVector<VectorType>::value, int>>
1161 void
1162 elementwise_inv(N_Vector x, N_Vector z)
1163 {
1164 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1165 auto *z_dealii = unwrap_nvector<VectorType>(z);
1166
1167 AssertDimension(x_dealii->size(), z_dealii->size());
1168
1169 auto x_ele = x_dealii->locally_owned_elements();
1170 for (const auto idx : x_ele)
1171 {
1172 (*z_dealii)[idx] = 1.0 / (*x_dealii)[idx];
1173 }
1174 z_dealii->compress(VectorOperation::insert);
1175 }
1176
1177
1178
1179 template <typename VectorType,
1180 std::enable_if_t<IsBlockVector<VectorType>::value, int>>
1181 void
1182 elementwise_inv(N_Vector x, N_Vector z)
1183 {
1184 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1185 auto *z_dealii = unwrap_nvector<VectorType>(z);
1186
1187 AssertDimension(x_dealii->size(), z_dealii->size());
1188 AssertDimension(x_dealii->n_blocks(), z_dealii->n_blocks());
1189
1190 for (unsigned i = 0; i < x_dealii->n_blocks(); ++i)
1191 {
1192 auto x_ele = x_dealii->block(i).locally_owned_elements();
1193 for (const auto idx : x_ele)
1194 {
1195 z_dealii->block(i)[idx] = 1.0 / x_dealii->block(i)[idx];
1196 }
1197 }
1198
1199 z_dealii->compress(VectorOperation::insert);
1200 }
1201
1202
1203
1204 template <typename VectorType,
1205 std::enable_if_t<!IsBlockVector<VectorType>::value, int>>
1206 void
1207 elementwise_abs(N_Vector x, N_Vector z)
1208 {
1209 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1210 auto *z_dealii = unwrap_nvector<VectorType>(z);
1211
1212 AssertDimension(x_dealii->size(), z_dealii->size());
1213
1214 auto x_ele = x_dealii->locally_owned_elements();
1215 for (const auto idx : x_ele)
1216 {
1217 (*z_dealii)[idx] = std::fabs((*x_dealii)[idx]);
1218 }
1219
1220 z_dealii->compress(VectorOperation::insert);
1221 }
1222
1223
1224
1225 template <typename VectorType,
1226 std::enable_if_t<IsBlockVector<VectorType>::value, int>>
1227 void
1228 elementwise_abs(N_Vector x, N_Vector z)
1229 {
1230 auto *x_dealii = unwrap_nvector_const<VectorType>(x);
1231 auto *z_dealii = unwrap_nvector<VectorType>(z);
1232
1233 AssertDimension(x_dealii->size(), z_dealii->size());
1234 AssertDimension(x_dealii->n_blocks(), z_dealii->n_blocks());
1235
1236 for (unsigned i = 0; i < x_dealii->n_blocks(); ++i)
1237 {
1238 auto x_ele = x_dealii->block(i).locally_owned_elements();
1239 for (const auto idx : x_ele)
1240 {
1241 z_dealii->block(i)[idx] = std::fabs(x_dealii->block(i)[idx]);
1242 }
1243 }
1244
1245 z_dealii->compress(VectorOperation::insert);
1246 }
1247
1248 } // namespace NVectorOperations
1249
1250
1251 template <typename VectorType>
1252 N_Vector
1253 create_empty_nvector(
1254 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
1255 SUNContext nvector_context
1256 # endif
1257 )
1258 {
1259 # if DEAL_II_SUNDIALS_VERSION_LT(6, 0, 0)
1260 N_Vector v = N_VNewEmpty();
1261 # else
1262 N_Vector v = N_VNewEmpty(nvector_context);
1263 # endif
1264 Assert(v != nullptr, ExcInternalError());
1265
1266 /* constructors, destructors, and utility operations */
1267 v->ops->nvgetvectorid = &NVectorOperations::get_vector_id;
1268 v->ops->nvclone = &NVectorOperations::clone<VectorType>;
1269 v->ops->nvcloneempty = &NVectorOperations::clone_empty;
1270 v->ops->nvdestroy = &NVectorOperations::destroy<VectorType>;
1271 // v->ops->nvspace = undef;
1272 # if DEAL_II_SUNDIALS_VERSION_GTE(7, 0, 0)
1273 v->ops->nvgetcommunicator =
1274 &NVectorOperations::get_mpi_communicator_by_value<VectorType>;
1275 # else
1276 v->ops->nvgetcommunicator =
1277 &NVectorOperations::get_mpi_communicator_as_void_ptr<VectorType>;
1278 # endif
1279 v->ops->nvgetlength = &NVectorOperations::get_global_length<VectorType>;
1280
1281 /* standard vector operations */
1282 v->ops->nvlinearsum = &NVectorOperations::linear_sum<VectorType>;
1283 v->ops->nvconst = &NVectorOperations::set_constant<VectorType>;
1284 v->ops->nvprod = &NVectorOperations::elementwise_product<VectorType>;
1285 v->ops->nvdiv = &NVectorOperations::elementwise_div<VectorType>;
1286 v->ops->nvscale = &NVectorOperations::scale<VectorType>;
1287 v->ops->nvabs = &NVectorOperations::elementwise_abs<VectorType>;
1288 v->ops->nvinv = &NVectorOperations::elementwise_inv<VectorType>;
1289 v->ops->nvaddconst = &NVectorOperations::add_constant<VectorType>;
1290 v->ops->nvdotprod = &NVectorOperations::dot_product<VectorType>;
1291 v->ops->nvmaxnorm = &NVectorOperations::max_norm<VectorType>;
1292 v->ops->nvwrmsnorm = &NVectorOperations::weighted_rms_norm<VectorType>;
1293 v->ops->nvmin = &NVectorOperations::min_element<VectorType>;
1294 v->ops->nvwl2norm = &NVectorOperations::weighted_l2_norm<VectorType>;
1295 v->ops->nvl1norm = &NVectorOperations::l1_norm<VectorType>;
1296 v->ops->nvwrmsnormmask =
1297 &NVectorOperations::weighted_rms_norm_mask<VectorType>;
1298
1299 /* The following are declared as standard by SUNDIALS but were not
1300 * necessary so far.
1301 */
1302 v->ops->nvcompare = nullptr;
1303 v->ops->nvinvtest = nullptr;
1304 v->ops->nvconstrmask = nullptr;
1305 v->ops->nvminquotient = nullptr;
1306
1307 /* fused and vector array operations are disabled by default */
1308
1309 /* OPTIONAL fused vector operations */
1310
1311 // These operations are only implemented for deal.II vectors. SUNDIALS
1312 // will automatically fall back to a less optimized version implemented
1313 // through the standard functions above for other VectorTypes.
1314 if constexpr (is_dealii_compatible_distributed_vector<VectorType>)
1315 {
1316 v->ops->nvlinearcombination =
1317 &NVectorOperations::linear_combination<VectorType>;
1318 v->ops->nvdotprodmulti =
1319 &NVectorOperations::dot_product_multi<VectorType>;
1320 }
1321 else
1322 {
1323 v->ops->nvlinearcombination = nullptr;
1324 v->ops->nvdotprodmulti = nullptr;
1325 }
1326
1327 v->ops->nvscaleaddmulti = nullptr;
1328
1329 /* OPTIONAL vector array operations */
1330 v->ops->nvlinearsumvectorarray = nullptr;
1331 v->ops->nvscalevectorarray = nullptr;
1332 v->ops->nvconstvectorarray = nullptr;
1333 v->ops->nvwrmsnormvectorarray = nullptr;
1334 v->ops->nvwrmsnormmaskvectorarray = nullptr;
1335 v->ops->nvscaleaddmultivectorarray = nullptr;
1336 v->ops->nvlinearcombinationvectorarray = nullptr;
1337
1338 /* Local reduction kernels (no parallel communication) */
1339 v->ops->nvdotprodlocal = nullptr;
1340 v->ops->nvmaxnormlocal = nullptr;
1341 v->ops->nvminlocal = nullptr;
1342 v->ops->nvl1normlocal = nullptr;
1343 v->ops->nvinvtestlocal = nullptr;
1344 v->ops->nvconstrmasklocal = nullptr;
1345 v->ops->nvminquotientlocal = nullptr;
1346 v->ops->nvwsqrsumlocal = nullptr;
1347 v->ops->nvwsqrsummasklocal = nullptr;
1348
1349 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
1350 /* Single buffer reduction operations */
1351
1352 // These operations are only implemented for deal.II vectors. SUNDIALS
1353 // will automatically fall back to a less optimized version implemented
1354 // through the standard functions above for other VectorTypes.
1355 if constexpr (is_dealii_compatible_distributed_vector<VectorType>)
1356 {
1357 v->ops->nvdotprodmultilocal =
1358 &NVectorOperations::dot_product_multi_local<VectorType>;
1359 v->ops->nvdotprodmultiallreduce =
1360 &NVectorOperations::dot_product_multi_all_reduce<VectorType>;
1361 }
1362 else
1363 {
1364 v->ops->nvdotprodmultilocal = nullptr;
1365 v->ops->nvdotprodmultiallreduce = nullptr;
1366 }
1367 # endif
1368
1369 /* XBraid interface operations */
1370 v->ops->nvbufsize = nullptr;
1371 v->ops->nvbufpack = nullptr;
1372 v->ops->nvbufunpack = nullptr;
1373
1374 /* Debugging functions (called when SUNDIALS_DEBUG_PRINTVEC is defined).
1375 */
1376 v->ops->nvprint = nullptr;
1377 v->ops->nvprintfile = nullptr;
1378
1379 return v;
1380 }
1381
1382 } // namespace internal
1383 } // namespace SUNDIALS
1384
1385 DEAL_II_NAMESPACE_CLOSE
1386
1387 #else
1388
1389 // Make sure the scripts that create the C++20 module input files have
1390 // something to latch on if the preprocessor #ifdef above would
1391 // otherwise lead to an empty content of the file.
1392 DEAL_II_NAMESPACE_OPEN
1393 DEAL_II_NAMESPACE_CLOSE
1394
1395 #endif
1396 #endif