Debian Codegraph @

include/deal.II/lac/packaged_operation.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 2023 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_packaged_operation_h
16 #define dealii_packaged_operation_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21
22 #include <deal.II/lac/vector_memory.h>
23
24 #include <functional>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 // Forward declarations:
29 #ifndef DOXYGEN
30 template <typename Number>
31 class Vector;
32 template <typename Range, typename Domain, typename Payload>
33 class LinearOperator;
34 template <typename Range = Vector<double>>
35 class PackagedOperation;
36 #endif
37
38
39 /**
40 * A class to store a computation.
41 *
42 * The PackagedOperation class allows lazy evaluation of expressions involving
43 * vectors and linear operators. This is done by storing the computational
44 * expression and only performing the computation when either the object is
45 * implicitly converted to a vector object, or <code>apply</code> (or
46 * <code>apply_add</code>) is invoked by hand. This avoids unnecessary
47 * temporary storage of intermediate results.
48 *
49 * The class essentially consists of <code>std::function</code> objects that
50 * store the knowledge of how to generate the result of a computation and
51 * store it in a vector:
52 * @code
53 * std::function<void(Range &)> apply;
54 * std::function<void(Range &)> apply_add;
55 * @endcode
56 *
57 * Similar to the LinearOperator class it also has knowledge about how to
58 * initialize a vector of the @p Range space:
59 * @code
60 * std::function<void(Range &, bool)> reinit_vector;
61 * @endcode
62 *
63 * As an example consider the addition of multiple vectors
64 * @code
65 * Vector<double> a, b, c, d;
66 * // ..
67 * Vector<double> result = a + b - c + d;
68 * @endcode
69 * or the computation of a residual $b-Ax$:
70 * @code
71 * SparseMatrix<double> A;
72 * Vector<double> b, x;
73 * // ..
74 * const auto op_a = linear_operator(A);
75 *
76 * auto residual = b - op_a * x;
77 * @endcode
78 * The expression <code>residual</code> is of type
79 * <code>PackagedOperation<Vector<double>></code>. It stores
80 * references to <code>A</code>, <code>b</code> and <code>x</code> and defers
81 * the actual computation until <code>apply</code>, or <code>apply_add</code>
82 * are explicitly invoked,
83 * @code
84 * Vector<double> y;
85 * residual.reinit_vector(y);
86 * residual.apply(y);
87 * residual.apply_add(y);
88 * @endcode
89 * or until the @p PackagedOperation object is implicitly converted:
90 * @code
91 * Vector<double> y;
92 * y = residual;
93 * y += residual;
94 * y -= residual;
95 * @endcode
96 *
97 * @note The step-20 tutorial program has a detailed usage example of the
98 * LinearOperator class.
99 *
100 *
101 * @ingroup LAOperators
102 */
103 template <typename Range>
104 class PackagedOperation
105 {
106 public:
107 /**
108 * Create an empty PackagedOperation object. All <code>std::function</code>
109 * member objects are initialized with default variants that throw an
110 * exception upon invocation.
111 */
112 PackagedOperation()
113 {
114 apply = [](Range &) {
115 Assert(false,
116 ExcMessage(
117 "Uninitialized PackagedOperation<Range>::apply called"));
118 };
119
120 apply_add = [](Range &) {
121 Assert(false,
122 ExcMessage(
123 "Uninitialized PackagedOperation<Range>::apply_add called"));
124 };
125
126 reinit_vector = [](Range &, bool) {
127 Assert(false,
128 ExcMessage("Uninitialized PackagedOperation<Range>::reinit_vector "
129 "method called"));
130 };
131 }
132
133 /**
134 * Default copy constructor.
135 */
136 PackagedOperation(const PackagedOperation<Range> &) = default;
137
138 /**
139 * Constructor that creates a PackagedOperation object from a reference
140 * vector @p u. The PackagedOperation returns @p u.
141 *
142 * The PackagedOperation object that is created stores a reference to @p u.
143 * Thus, the vector must remain a valid reference for the whole lifetime of
144 * the PackagedOperation object. All changes made on @p u after the creation
145 * of the PackagedOperation object are reflected by the operator object.
146 */
147 PackagedOperation(const Range &u)
148 {
149 *this = u;
150 }
151
152 /**
153 * Default copy assignment operator.
154 */
155 PackagedOperation<Range> &
156 operator=(const PackagedOperation<Range> &) = default;
157
158 /**
159 * Copy assignment operator that creates a PackagedOperation object from a
160 * reference vector @p u. The PackagedOperation returns @p u.
161 *
162 * The PackagedOperation object that is created stores a reference to @p u.
163 * Thus, the vector must remain a valid reference for the whole lifetime of
164 * the PackagedOperation object. All changes made on @p u after the creation
165 * of the PackagedOperation object are reflected by the operator object.
166 */
167 PackagedOperation<Range> &
168 operator=(const Range &u)
169 {
170 apply = [&u](Range &v) { v = u; };
171
172 apply_add = [&u](Range &v) { v += u; };
173
174 reinit_vector = [&u](Range &v, bool omit_zeroing_entries) {
175 v.reinit(u, omit_zeroing_entries);
176 };
177
178 return *this;
179 }
180
181 /**
182 * Convert a PackagedOperation to its result.
183 *
184 * This conversion operator creates a vector of the Range space and calls
185 * <code>apply()</code> on it.
186 */
187 operator Range() const
188 {
189 Range result_vector;
190
191 reinit_vector(result_vector, /*bool omit_zeroing_entries=*/true);
192 apply(result_vector);
193
194 return result_vector;
195 }
196
197 /**
198 * @name In-place vector space operations
199 */
200 /** @{ */
201
202 /**
203 * Addition with a PackagedOperation @p second_comp with the same @p Range.
204 */
205 PackagedOperation<Range> &
206 operator+=(const PackagedOperation<Range> &second_comp)
207 {
208 *this = *this + second_comp;
209 return *this;
210 }
211
212 /**
213 * Subtraction with a PackagedOperation @p second_comp with the same @p
214 * Range.
215 */
216 PackagedOperation<Range> &
217 operator-=(const PackagedOperation<Range> &second_comp)
218 {
219 *this = *this - second_comp;
220 return *this;
221 }
222
223 /**
224 * Add a constant @p offset (of the @p Range space) to the result of a
225 * PackagedOperation.
226 */
227 PackagedOperation<Range> &
228 operator+=(const Range &offset)
229 {
230 *this = *this + PackagedOperation<Range>(offset);
231 return *this;
232 }
233
234 /**
235 * Subtract a constant @p offset (of the @p Range space) from the result of
236 * a PackagedOperation.
237 */
238 PackagedOperation<Range> &
239 operator-=(const Range &offset)
240 {
241 *this = *this - PackagedOperation<Range>(offset);
242 return *this;
243 }
244
245 /**
246 * Scalar multiplication of the PackagedOperation with a @p number.
247 */
248 PackagedOperation<Range> &
249 operator*=(typename Range::value_type number)
250 {
251 *this = *this * number;
252 return *this;
253 }
254 /** @} */
255
256 /**
257 * Store the result of the PackagedOperation in a vector v of the @p Range
258 * space.
259 */
260 std::function<void(Range &v)> apply;
261
262 /**
263 * Add the result of the PackagedOperation to a vector v of the @p Range
264 * space.
265 */
266 std::function<void(Range &v)> apply_add;
267
268 /**
269 * Initializes a vector v of the Range space to be directly usable as the
270 * destination parameter in an application of apply, or apply_add. Similar
271 * to the reinit functions of the vector classes, the boolean determines
272 * whether a fast initialization is done, i.e., if it is set to false the
273 * content of the vector is set to 0.
274 */
275 std::function<void(Range &v, bool omit_zeroing_entries)> reinit_vector;
276 };
277
278
279 /**
280 * @name Vector space operations
281 */
282 /** @{ */
283
284 /**
285 * @relatesalso PackagedOperation
286 *
287 * Addition of two PackagedOperation objects @p first_comp and @p second_comp
288 * given by vector space addition of the corresponding results.
289 *
290 * @ingroup LAOperators
291 */
292 template <typename Range>
293 PackagedOperation<Range>
294 operator+(const PackagedOperation<Range> &first_comp,
295 const PackagedOperation<Range> &second_comp)
296 {
297 PackagedOperation<Range> return_comp;
298
299 return_comp.reinit_vector = first_comp.reinit_vector;
300
301 // ensure to have valid PackagedOperation objects by catching first_comp and
302 // second_comp by value
303
304 return_comp.apply = [first_comp, second_comp](Range &v) {
305 first_comp.apply(v);
306 second_comp.apply_add(v);
307 };
308
309 return_comp.apply_add = [first_comp, second_comp](Range &v) {
310 first_comp.apply_add(v);
311 second_comp.apply_add(v);
312 };
313
314 return return_comp;
315 }
316
317 /**
318 * @relatesalso PackagedOperation
319 *
320 * Subtraction of two PackagedOperation objects @p first_comp and @p
321 * second_comp given by vector space addition of the corresponding results.
322 *
323 * @ingroup LAOperators
324 */
325 template <typename Range>
326 PackagedOperation<Range>
327 operator-(const PackagedOperation<Range> &first_comp,
328 const PackagedOperation<Range> &second_comp)
329 {
330 PackagedOperation<Range> return_comp;
331
332 return_comp.reinit_vector = first_comp.reinit_vector;
333
334 // ensure to have valid PackagedOperation objects by catching first_comp and
335 // second_comp by value
336
337 return_comp.apply = [first_comp, second_comp](Range &v) {
338 second_comp.apply(v);
339 v *= -1.;
340 first_comp.apply_add(v);
341 };
342
343 return_comp.apply_add = [first_comp, second_comp](Range &v) {
344 first_comp.apply_add(v);
345 v *= -1.;
346 second_comp.apply_add(v);
347 v *= -1.;
348 };
349
350 return return_comp;
351 }
352
353 /**
354 * @relatesalso PackagedOperation
355 *
356 * Scalar multiplication of a PackagedOperation objects @p comp with a scalar
357 * @p number given by a scaling PackagedOperation result with @p number.
358 *
359 * @ingroup LAOperators
360 */
361 template <typename Range>
362 PackagedOperation<Range>
363 operator*(const PackagedOperation<Range> &comp,
364 typename Range::value_type number)
365 {
366 PackagedOperation<Range> return_comp;
367
368 return_comp.reinit_vector = comp.reinit_vector;
369
370 // the trivial case: number is zero
371 if (number == 0.)
372 {
373 return_comp.apply = [](Range &v) { v = 0.; };
374
375 return_comp.apply_add = [](Range &) {};
376 }
377 else
378 {
379 return_comp.apply = [comp, number](Range &v) {
380 comp.apply(v);
381 v *= number;
382 };
383
384 return_comp.apply_add = [comp, number](Range &v) {
385 v /= number;
386 comp.apply_add(v);
387 v *= number;
388 };
389 }
390
391 return return_comp;
392 }
393
394 /**
395 * @relatesalso PackagedOperation
396 *
397 * Scalar multiplication of a PackagedOperation objects @p comp with a scalar
398 * @p number given by a scaling PackagedOperation result with @p number.
399 *
400 * @ingroup LAOperators
401 */
402 template <typename Range>
403 PackagedOperation<Range>
404 operator*(typename Range::value_type number,
405 const PackagedOperation<Range> &comp)
406 {
407 return comp * number;
408 }
409
410 /**
411 * @relatesalso PackagedOperation
412 *
413 * Add a constant @p offset (of the @p Range space) to the result of a
414 * PackagedOperation.
415 *
416 * @ingroup LAOperators
417 */
418 template <typename Range>
419 PackagedOperation<Range>
420 operator+(const PackagedOperation<Range> &comp, const Range &offset)
421 {
422 return comp + PackagedOperation<Range>(offset);
423 }
424
425 /**
426 * @relatesalso PackagedOperation
427 *
428 * Add a constant @p offset (of the @p Range space) to the result of a
429 * PackagedOperation.
430 *
431 * @ingroup LAOperators
432 */
433 template <typename Range>
434 PackagedOperation<Range>
435 operator+(const Range &offset, const PackagedOperation<Range> &comp)
436 {
437 return PackagedOperation<Range>(offset) + comp;
438 }
439
440 /**
441 * @relatesalso PackagedOperation
442 *
443 * Subtract a constant @p offset (of the @p Range space) from the result of a
444 * PackagedOperation.
445 *
446 * @ingroup LAOperators
447 */
448 template <typename Range>
449 PackagedOperation<Range>
450 operator-(const PackagedOperation<Range> &comp, const Range &offset)
451 {
452 return comp - PackagedOperation<Range>(offset);
453 }
454
455
456 /**
457 * @relatesalso PackagedOperation
458 *
459 * Subtract a computational result from a constant @p offset (of the @p Range
460 * space). The result is a PackagedOperation object that applies this
461 * computation.
462 *
463 * @ingroup LAOperators
464 */
465 template <typename Range>
466 PackagedOperation<Range>
467 operator-(const Range &offset, const PackagedOperation<Range> &comp)
468 {
469 return PackagedOperation<Range>(offset) - comp;
470 }
471
472 /** @} */
473
474
475 /**
476 * @name Creation of a PackagedOperation object
477 */
478 /** @{ */
479
480 namespace internal
481 {
482 namespace PackagedOperationImplementation
483 {
484 // Poor man's trait class that determines whether type T is a vector:
485 // FIXME: Implement this as a proper type trait - similar to
486 // isBlockVector
487
488 template <typename T>
489 class has_vector_interface
490 {
491 template <typename C>
492 static std::false_type
493 test(...);
494
495 template <typename C>
496 static std::true_type
497 test(decltype(&C::operator+=),
498 decltype(&C::operator-=),
499 decltype(&C::l2_norm));
500
501 public:
502 // type is std::true_type if Matrix provides vmult_add and Tvmult_add,
503 // otherwise it is std::false_type
504
505 using type = decltype(test<T>(nullptr, nullptr, nullptr));
506 }; // namespace
507 } // namespace PackagedOperationImplementation
508 } // namespace internal
509
510
511 /**
512 * @relatesalso PackagedOperation
513 *
514 * Create a PackagedOperation object that stores the addition of two vectors.
515 *
516 * The PackagedOperation object that is created stores a reference to @p u and
517 * @p v. Thus, the vectors must remain valid references for the whole lifetime
518 * of the PackagedOperation object. All changes made on @p u or @p v after the
519 * creation of the PackagedOperation object are reflected by the operator
520 * object.
521 *
522 * @ingroup LAOperators
523 */
524
525 template <
526 typename Range,
527 typename = std::enable_if_t<internal::PackagedOperationImplementation::
528 has_vector_interface<Range>::type::value>>
529 PackagedOperation<Range>
530 operator+(const Range &u, const Range &v)
531 {
532 PackagedOperation<Range> return_comp;
533
534 // ensure to have valid PackagedOperation objects by catching op by value
535 // u is caught by reference
536
537 return_comp.reinit_vector = [&u](Range &x, bool omit_zeroing_entries) {
538 x.reinit(u, omit_zeroing_entries);
539 };
540
541 return_comp.apply = [&u, &v](Range &x) {
542 x = u;
543 x += v;
544 };
545
546 return_comp.apply_add = [&u, &v](Range &x) {
547 x += u;
548 x += v;
549 };
550
551 return return_comp;
552 }
553
554
555 /**
556 * @relatesalso PackagedOperation
557 *
558 * Create a PackagedOperation object that stores the subtraction of two
559 * vectors.
560 *
561 * The PackagedOperation object that is created stores a reference to @p u and
562 * @p v. Thus, the vectors must remain valid references for the whole lifetime
563 * of the PackagedOperation object. All changes made on @p u or @p v after the
564 * creation of the PackagedOperation object are reflected by the operator
565 * object.
566 *
567 * @ingroup LAOperators
568 */
569
570 template <
571 typename Range,
572 typename = std::enable_if_t<internal::PackagedOperationImplementation::
573 has_vector_interface<Range>::type::value>>
574 PackagedOperation<Range>
575 operator-(const Range &u, const Range &v)
576 {
577 PackagedOperation<Range> return_comp;
578
579 // ensure to have valid PackagedOperation objects by catching op by value
580 // u is caught by reference
581
582 return_comp.reinit_vector = [&u](Range &x, bool omit_zeroing_entries) {
583 x.reinit(u, omit_zeroing_entries);
584 };
585
586 return_comp.apply = [&u, &v](Range &x) {
587 x = u;
588 x -= v;
589 };
590
591 return_comp.apply_add = [&u, &v](Range &x) {
592 x += u;
593 x -= v;
594 };
595
596 return return_comp;
597 }
598
599
600 /**
601 * @relatesalso PackagedOperation
602 *
603 * Create a PackagedOperation object that stores the scaling of a vector with
604 * a @p number.
605 *
606 * The PackagedOperation object that is created stores a reference to @p u.
607 * Thus, the vectors must remain valid references for the whole lifetime of
608 * the PackagedOperation object. All changes made on @p u or @p v after the
609 * creation of the PackagedOperation object are reflected by the operator
610 * object.
611 *
612 * @ingroup LAOperators
613 */
614 template <
615 typename Range,
616 typename = std::enable_if_t<internal::PackagedOperationImplementation::
617 has_vector_interface<Range>::type::value>>
618 PackagedOperation<Range>
619 operator*(const Range &u, typename Range::value_type number)
620 {
621 return PackagedOperation<Range>(u) * number;
622 }
623
624
625 /**
626 * @relatesalso PackagedOperation
627 *
628 * Create a PackagedOperation object that stores the scaling of a vector with
629 * a @p number.
630 *
631 * The PackagedOperation object that is created stores a reference to @p u.
632 * Thus, the vectors must remain valid references for the whole lifetime of
633 * the PackagedOperation object. All changes made on @p u or @p v after the
634 * creation of the PackagedOperation object are reflected by the operator
635 * object.
636 *
637 * @ingroup LAOperators
638 */
639 template <
640 typename Range,
641 typename = std::enable_if_t<internal::PackagedOperationImplementation::
642 has_vector_interface<Range>::type::value>>
643 PackagedOperation<Range>
644 operator*(typename Range::value_type number, const Range &u)
645 {
646 return number * PackagedOperation<Range>(u);
647 }
648
649
650 /**
651 * @relatesalso PackagedOperation
652 *
653 * Create a PackagedOperation object from a LinearOperator and a reference to
654 * a vector @p u of the Domain space. The object stores the PackagedOperation
655 * $\text{op} \,u$ (in matrix notation). <code>return</code>
656 * (<code>return_add</code>) are implemented with <code>vmult(__1,u)</code>
657 * (<code>vmult_add(__1,u)</code>).
658 *
659 * The PackagedOperation object that is created stores a reference to @p u.
660 * Thus, the vector must remain a valid reference for the whole lifetime of
661 * the PackagedOperation object. All changes made on @p u after the creation
662 * of the PackagedOperation object are reflected by the operator object.
663 *
664 * @ingroup LAOperators
665 */
666 template <typename Range, typename Domain, typename Payload>
667 PackagedOperation<Range>
668 operator*(const LinearOperator<Range, Domain, Payload> &op, const Domain &u)
669 {
670 PackagedOperation<Range> return_comp;
671
672 return_comp.reinit_vector = op.reinit_range_vector;
673
674 // ensure to have valid PackagedOperation objects by catching op by value
675 // u is caught by reference
676
677 return_comp.apply = [op, &u](Range &v) { op.vmult(v, u); };
678
679 return_comp.apply_add = [op, &u](Range &v) { op.vmult_add(v, u); };
680
681 return return_comp;
682 }
683
684
685 /**
686 * @relatesalso PackagedOperation
687 *
688 * Create a PackagedOperation object from a LinearOperator and a reference to
689 * a vector @p u of the Range space. The object stores the PackagedOperation
690 * $\text{op}^T \,u$ (in matrix notation). <code>return</code>
691 * (<code>return_add</code>) are implemented with <code>Tvmult(__1,u)</code>
692 * (<code>Tvmult_add(__1,u)</code>).
693 *
694 * The PackagedOperation object that is created stores a reference to @p u.
695 * Thus, the vector must remain a valid reference for the whole lifetime of
696 * the PackagedOperation object. All changes made on @p u after the creation
697 * of the PackagedOperation object are reflected by the operator object.
698 *
699 * @ingroup LAOperators
700 */
701 template <typename Range, typename Domain, typename Payload>
702 PackagedOperation<Domain>
703 operator*(const Range &u, const LinearOperator<Range, Domain, Payload> &op)
704 {
705 PackagedOperation<Range> return_comp;
706
707 return_comp.reinit_vector = op.reinit_domain_vector;
708
709 // ensure to have valid PackagedOperation objects by catching op by value
710 // u is caught by reference
711
712 return_comp.apply = [op, &u](Domain &v) { op.Tvmult(v, u); };
713
714 return_comp.apply_add = [op, &u](Domain &v) { op.Tvmult_add(v, u); };
715
716 return return_comp;
717 }
718
719
720 /**
721 * @relatesalso PackagedOperation
722 *
723 * Composition of a PackagedOperation object with a LinearOperator. The object
724 * stores the computation $\text{op} \,comp$ (in matrix notation).
725 *
726 * @ingroup LAOperators
727 */
728 template <typename Range, typename Domain, typename Payload>
729 PackagedOperation<Range>
730 operator*(const LinearOperator<Range, Domain, Payload> &op,
731 const PackagedOperation<Domain> &comp)
732 {
733 PackagedOperation<Range> return_comp;
734
735 return_comp.reinit_vector = op.reinit_range_vector;
736
737 // ensure to have valid PackagedOperation objects by catching op by value
738 // u is caught by reference
739
740 return_comp.apply = [op, comp](Domain &v) {
741 GrowingVectorMemory<Range> vector_memory;
742
743 typename VectorMemory<Range>::Pointer i(vector_memory);
744 op.reinit_domain_vector(*i, /*bool omit_zeroing_entries =*/true);
745
746 comp.apply(*i);
747 op.vmult(v, *i);
748 };
749
750 return_comp.apply_add = [op, comp](Domain &v) {
751 GrowingVectorMemory<Range> vector_memory;
752
753 typename VectorMemory<Range>::Pointer i(vector_memory);
754 op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true);
755
756 comp.apply(*i);
757 op.vmult_add(v, *i);
758 };
759
760 return return_comp;
761 }
762
763
764 /**
765 * @relatesalso PackagedOperation
766 *
767 * Composition of a PackagedOperation object with a LinearOperator. The object
768 * stores the computation $\text{op}^T \,comp$ (in matrix notation).
769 *
770 * @ingroup LAOperators
771 */
772 template <typename Range, typename Domain, typename Payload>
773 PackagedOperation<Domain>
774 operator*(const PackagedOperation<Range> &comp,
775 const LinearOperator<Range, Domain, Payload> &op)
776 {
777 PackagedOperation<Range> return_comp;
778
779 return_comp.reinit_vector = op.reinit_domain_vector;
780
781 // ensure to have valid PackagedOperation objects by catching op by value
782 // u is caught by reference
783
784 return_comp.apply = [op, comp](Domain &v) {
785 GrowingVectorMemory<Range> vector_memory;
786
787 typename VectorMemory<Range>::Pointer i(vector_memory);
788 op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true);
789
790 comp.apply(*i);
791 op.Tvmult(v, *i);
792 };
793
794 return_comp.apply_add = [op, comp](Domain &v) {
795 GrowingVectorMemory<Range> vector_memory;
796
797 typename VectorMemory<Range>::Pointer i(vector_memory);
798 op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true);
799
800 comp.apply(*i);
801 op.Tvmult_add(v, *i);
802 };
803
804 return return_comp;
805 }
806
807 /** @} */
808
809 DEAL_II_NAMESPACE_CLOSE
810
811 #endif