Debian Codegraph @

include/deal.II/lac/linear_operator.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_linear_operator_h
16 #define dealii_linear_operator_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 <array>
25 #include <functional>
26 #include <type_traits>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 // Forward declarations:
31 #ifndef DOXYGEN
32 namespace internal
33 {
34 namespace LinearOperatorImplementation
35 {
36 class EmptyPayload;
37 }
38 } // namespace internal
39
40 template <typename Number>
41 class Vector;
42
43 class PreconditionIdentity;
44
45 template <typename Range = Vector<double>,
46 typename Domain = Range,
47 typename Payload =
48 internal::LinearOperatorImplementation::EmptyPayload>
49 class LinearOperator;
50 #endif
51
52 template <
53 typename Range = Vector<double>,
54 typename Domain = Range,
55 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
56 typename OperatorExemplar,
57 typename Matrix>
58 LinearOperator<Range, Domain, Payload>
59 linear_operator(const OperatorExemplar &, const Matrix &);
60
61 template <
62 typename Range = Vector<double>,
63 typename Domain = Range,
64 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
65 typename Matrix>
66 LinearOperator<Range, Domain, Payload>
67 linear_operator(const Matrix &);
68
69 template <
70 typename Range = Vector<double>,
71 typename Domain = Range,
72 typename Payload = internal::LinearOperatorImplementation::EmptyPayload>
73 LinearOperator<Range, Domain, Payload>
74 null_operator(const LinearOperator<Range, Domain, Payload> &);
75
76 template <typename Range, typename Domain, typename Payload>
77 LinearOperator<Range, Domain, Payload>
78 identity_operator(const LinearOperator<Range, Domain, Payload> &);
79
80
81 /**
82 * A class to store the abstract concept of a linear operator.
83 *
84 * The class essentially consists of <code>std::function</code> objects that
85 * store the knowledge of how to apply the linear operator by implementing the
86 * abstract @p Matrix interface:
87 * @code
88 * std::function<void(Range &, const Domain &)> vmult;
89 * std::function<void(Range &, const Domain &)> vmult_add;
90 * std::function<void(Domain &, const Range &)> Tvmult;
91 * std::function<void(Domain &, const Range &)> Tvmult_add;
92 * @endcode
93 *
94 * But, in contrast to a usual matrix object, the domain and range of the
95 * linear operator are also bound to the LinearOperator class on the type
96 * level. Because of this, `LinearOperator<Range, Domain>` has two
97 * additional function objects
98 * @code
99 * std::function<void(Range &, bool)> reinit_range_vector;
100 * std::function<void(Domain &, bool)> reinit_domain_vector;
101 * @endcode
102 * that store the knowledge how to initialize (resize + internal data
103 * structures) an arbitrary vector of the @p Range and @p Domain space.
104 *
105 * The primary purpose of this class is to provide syntactic sugar for complex
106 * matrix-vector operations and free the user from having to create, set up
107 * and handle intermediate storage locations by hand.
108 *
109 * As an example consider the operation $(A+k\,B)\,C$, where $A$, $B$ and $C$
110 * denote (possible different) matrices. In order to construct a
111 * LinearOperator <code>op</code> that stores the knowledge of this operation,
112 * one can write:
113 *
114 * @code
115 * #include <deal.II/lac/linear_operator_tools.h>
116 *
117 * dealii::SparseMatrix<double> A, B, C;
118 * const double k = ...;
119 *
120 * // Setup and assembly of matrices
121 *
122 * const auto op_a = linear_operator(A);
123 * const auto op_b = linear_operator(B);
124 * const auto op_c = linear_operator(C);
125 *
126 * const auto op = (op_a + k * op_b) * op_c;
127 * @endcode
128 *
129 * @note This class makes heavy use of <code>std::function</code> objects and
130 * lambda functions. This flexibility comes with a run-time penalty. Only use
131 * this object to encapsulate matrix object of medium to large size (as a rule
132 * of thumb, sparse matrices with a size $1000\times1000$, or larger).
133 *
134 * @note In order to use Trilinos or PETSc sparse matrices and preconditioners
135 * in conjunction with the LinearOperator class, it is necessary to extend the
136 * functionality of the LinearOperator class by means of an additional Payload.
137 *
138 * For example: LinearOperator instances representing matrix inverses usually
139 * require calling some linear solver. These solvers may not have interfaces
140 * to the LinearOperator (which, for example, may represent a composite
141 * operation). The
142 * TrilinosWrappers::internal::LinearOperatorImplementation::TrilinosPayload
143 * therefore provides an interface extension to the LinearOperator so that it
144 * can be passed to the solver and used by the solver as if it were a Trilinos
145 * operator. This implies that all of the necessary functionality of the
146 * specific Trilinos operator has been overloaded within the Payload class.
147 * This includes operator-vector multiplication and inverse operator-vector
148 * multiplication, where the operator can be either a
149 * TrilinosWrappers::SparseMatrix or a TrilinosWrappers::PreconditionBase
150 * and the vector is a native Trilinos vector.
151 *
152 * Another case where payloads provide a crucial supplement to the
153 * LinearOperator class are when composite operations are constructed (via
154 * operator overloading). In this instance, it is again necessary to provide
155 * an interface that produces the result of this composite operation that is
156 * compatible with Trilinos operator used by Trilinos solvers.
157 *
158 * @note Many use cases of LinearOperator lead to intermediate expressions
159 * requiring a PackagedOperation. In order to include all necessary header
160 * files in one go consider using
161 * @code
162 * #include <deal.II/lac/linear_operator_tools.h>
163 * @endcode
164 *
165 * In order to use the full LinearOperator and PackagedOperation
166 *
167 * @note To ensure that the correct payload is provided, wrapper functions
168 * for linear operators have been provided within the respective
169 * TrilinosWrappers (and, in the future, PETScWrappers) namespaces.
170 *
171 * <h3> Examples of use </h3>
172 * The step-20 tutorial program has a detailed usage example of the
173 * LinearOperator class.
174 *
175 * <h3> Instrumenting operations </h3>
176 * It is sometimes useful to know when functions are called, or to inject
177 * additional operations. In such cases, what one wants is to replace, for
178 * example, the `vmult` object of this class with one that does the additional
179 * operations and then calls what was originally supposed to happen. This
180 * can be done with commands such as the following:
181 * @code
182 * auto A_inv = inverse_operator(A, solver_A, preconditioner_A);
183 * A_inv.vmult = [base_vmult = A_inv.vmult](Vector<double> &dst,
184 * const Vector<double> &src) {
185 * std::cout << "Calling A_inv.vmult()" << std::endl;
186 * base_vmult(dst, src);
187 * };
188 * @endcode
189 * Here, we replace `A_inv.vmult` with a lambda function that first captures
190 * the previous value of `A_inv.vmult` and stores it in the `base_vmult`
191 * object. The newly installed `A_inv.vmult` function then first outputs some
192 * status information, and then calls the original functionality.
193 *
194 * This approach works for all of the other function objects mentioned above
195 * as well.
196 *
197 * @ingroup LAOperators
198 */
199 template <typename Range, typename Domain, typename Payload>
200 class LinearOperator : public Payload
201 {
202 public:
203 /**
204 * Create an empty LinearOperator object.
205 * When a payload is passed to this constructor, the resulting operator is
206 * constructed with a functional payload.
207 * In either case, this constructor yields an object that can not actually
208 * be used for any linear operator operations, and will throw an exception
209 * upon invocation.
210 */
211 LinearOperator(const Payload &payload = Payload())
212 : Payload(payload)
213 , is_null_operator(false)
214 {
215 vmult = [](Range &, const Domain &) {
216 Assert(false,
217 ExcMessage("Uninitialized LinearOperator<Range, "
218 "Domain>::vmult called"));
219 };
220
221 vmult_add = [](Range &, const Domain &) {
222 Assert(false,
223 ExcMessage("Uninitialized LinearOperator<Range, "
224 "Domain>::vmult_add called"));
225 };
226
227 Tvmult = [](Domain &, const Range &) {
228 Assert(false,
229 ExcMessage("Uninitialized LinearOperator<Range, "
230 "Domain>::Tvmult called"));
231 };
232
233 Tvmult_add = [](Domain &, const Range &) {
234 Assert(false,
235 ExcMessage("Uninitialized LinearOperator<Range, "
236 "Domain>::Tvmult_add called"));
237 };
238
239 reinit_range_vector = [](Range &, bool) {
240 Assert(false,
241 ExcMessage("Uninitialized LinearOperator<Range, "
242 "Domain>::reinit_range_vector method called"));
243 };
244
245 reinit_domain_vector = [](Domain &, bool) {
246 Assert(false,
247 ExcMessage("Uninitialized LinearOperator<Range, "
248 "Domain>::reinit_domain_vector method called"));
249 };
250 }
251
252 /**
253 * Default copy constructor.
254 */
255 LinearOperator(const LinearOperator<Range, Domain, Payload> &) = default;
256
257 /**
258 * Templated copy constructor that creates a LinearOperator object from an
259 * object @p op for which the conversion function
260 * <code>linear_operator</code> is defined.
261 */
262 template <typename Op,
263 typename = std::enable_if_t<
264 !std::is_base_of_v<LinearOperator<Range, Domain, Payload>, Op>>>
265 LinearOperator(const Op &op)
266 {
267 *this = linear_operator<Range, Domain, Payload, Op>(op);
268 }
269
270 /**
271 * Default copy assignment operator.
272 */
273 LinearOperator<Range, Domain, Payload> &
274 operator=(const LinearOperator<Range, Domain, Payload> &) = default;
275
276 /**
277 * Templated copy assignment operator for an object @p op for which the
278 * conversion function <code>linear_operator</code> is defined.
279 */
280 template <typename Op,
281 typename = std::enable_if_t<
282 !std::is_base_of_v<LinearOperator<Range, Domain, Payload>, Op>>>
283 LinearOperator<Range, Domain, Payload> &
284 operator=(const Op &op)
285 {
286 *this = linear_operator<Range, Domain, Payload, Op>(op);
287 return *this;
288 }
289
290 /**
291 * Application of the LinearOperator object to a vector u of the @p Domain
292 * space giving a vector v of the @p Range space.
293 */
294 std::function<void(Range &v, const Domain &u)> vmult;
295
296 /**
297 * Application of the LinearOperator object to a vector u of the @p Domain
298 * space. The result is added to the vector v.
299 */
300 std::function<void(Range &v, const Domain &u)> vmult_add;
301
302 /**
303 * Application of the transpose LinearOperator object to a vector u of the
304 * @p Range space giving a vector v of the @p Domain space.
305 */
306 std::function<void(Domain &v, const Range &u)> Tvmult;
307
308 /**
309 * Application of the transpose LinearOperator object to a vector @p u of
310 * the @p Range space.The result is added to the vector @p v.
311 */
312 std::function<void(Domain &v, const Range &u)> Tvmult_add;
313
314 /**
315 * Initializes a vector v of the Range space to be directly usable as the
316 * destination parameter in an application of vmult. Similar to the reinit
317 * functions of the vector classes, the boolean determines whether a fast
318 * initialization is done, i.e., if it is set to false the content of the
319 * vector is set to 0.
320 */
321 std::function<void(Range &v, bool omit_zeroing_entries)> reinit_range_vector;
322
323 /**
324 * Initializes a vector of the Domain space to be directly usable as the
325 * source parameter in an application of vmult. Similar to the reinit
326 * functions of the vector classes, the boolean determines whether a fast
327 * initialization is done, i.e., if it is set to false the content of the
328 * vector is set to 0.
329 */
330 std::function<void(Domain &v, bool omit_zeroing_entries)>
331 reinit_domain_vector;
332
333 /**
334 * @name In-place vector space operations
335 */
336 /** @{ */
337
338 /**
339 * Addition with a LinearOperator @p second_op with the same @p Domain and
340 * @p Range.
341 */
342 LinearOperator<Range, Domain, Payload> &
343 operator+=(const LinearOperator<Range, Domain, Payload> &second_op)
344 {
345 *this = *this + second_op;
346 return *this;
347 }
348
349 /**
350 * Subtraction with a LinearOperator @p second_op with the same @p Domain
351 * and @p Range.
352 */
353 LinearOperator<Range, Domain, Payload> &
354 operator-=(const LinearOperator<Range, Domain, Payload> &second_op)
355 {
356 *this = *this - second_op;
357 return *this;
358 }
359
360 /**
361 * Composition of the LinearOperator with an endomorphism @p second_op of
362 * the @p Domain space.
363 */
364 LinearOperator<Range, Domain, Payload> &
365 operator*=(const LinearOperator<Domain, Domain, Payload> &second_op)
366 {
367 *this = *this * second_op;
368 return *this;
369 }
370
371 /**
372 * Scalar multiplication of the LinearOperator with @p number from the
373 * right.
374 */
375 LinearOperator<Range, Domain, Payload>
376 operator*=(typename Domain::value_type number)
377 {
378 *this = *this * number;
379 return *this;
380 }
381
382 /**
383 * This bool is used to determine whether a linear operator is a null
384 * operator. In this case the class is able to optimize some operations like
385 * multiplication or addition.
386 */
387 bool is_null_operator;
388
389 /** @} */
390 };
391
392
393 /**
394 * @name Vector space operations
395 */
396 /** @{ */
397
398 /**
399 * @relatesalso LinearOperator
400 *
401 * Addition of two linear operators @p first_op and @p second_op given by
402 * $(\mathrm{first\_op}+\mathrm{second\_op})x \dealcoloneq \mathrm{first\_op}(x)
403 * + \mathrm{second\_op}(x)$
404 *
405 * @ingroup LAOperators
406 */
407 template <typename Range, typename Domain, typename Payload>
408 LinearOperator<Range, Domain, Payload>
409 operator+(const LinearOperator<Range, Domain, Payload> &first_op,
410 const LinearOperator<Range, Domain, Payload> &second_op)
411 {
412 if (first_op.is_null_operator)
413 {
414 return second_op;
415 }
416 else if (second_op.is_null_operator)
417 {
418 return first_op;
419 }
420 else
421 {
422 LinearOperator<Range, Domain, Payload> return_op{
423 static_cast<const Payload &>(first_op) +
424 static_cast<const Payload &>(second_op)};
425
426 return_op.reinit_range_vector = first_op.reinit_range_vector;
427 return_op.reinit_domain_vector = first_op.reinit_domain_vector;
428
429 // ensure to have valid computation objects by catching first_op and
430 // second_op by value
431
432 return_op.vmult = [first_op, second_op](Range &v, const Domain &u) {
433 first_op.vmult(v, u);
434 second_op.vmult_add(v, u);
435 };
436
437 return_op.vmult_add = [first_op, second_op](Range &v, const Domain &u) {
438 first_op.vmult_add(v, u);
439 second_op.vmult_add(v, u);
440 };
441
442 return_op.Tvmult = [first_op, second_op](Domain &v, const Range &u) {
443 second_op.Tvmult(v, u);
444 first_op.Tvmult_add(v, u);
445 };
446
447 return_op.Tvmult_add = [first_op, second_op](Domain &v, const Range &u) {
448 second_op.Tvmult_add(v, u);
449 first_op.Tvmult_add(v, u);
450 };
451
452 return return_op;
453 }
454 }
455
456
457 /**
458 * @relatesalso LinearOperator
459 *
460 * Subtraction of two linear operators @p first_op and @p second_op given by
461 * $(\mathrm{first\_op}-\mathrm{second\_op})x \dealcoloneq \mathrm{first\_op}(x)
462 * - \mathrm{second\_op}(x)$
463 *
464 * @ingroup LAOperators
465 */
466 template <typename Range, typename Domain, typename Payload>
467 LinearOperator<Range, Domain, Payload>
468 operator-(const LinearOperator<Range, Domain, Payload> &first_op,
469 const LinearOperator<Range, Domain, Payload> &second_op)
470 {
471 if (first_op.is_null_operator)
472 {
473 return -1. * second_op;
474 }
475 else if (second_op.is_null_operator)
476 {
477 return first_op;
478 }
479 else
480 {
481 // implement with addition and scalar multiplication
482 return first_op + (-1. * second_op);
483 }
484 }
485
486
487 /**
488 * @relatesalso LinearOperator
489 *
490 * Scalar multiplication of a ScalarOperator object @p op with @p number from
491 * the left.
492 *
493 * The @p Domain and @p Range types must implement the following
494 * <code>operator*=</code> member functions accepting the appropriate scalar
495 * Number type for rescaling:
496 *
497 * @code
498 * Domain & operator *=(Domain::value_type);
499 * Range & operator *=(Range::value_type);
500 * @endcode
501 *
502 * @ingroup LAOperators
503 */
504 template <typename Range, typename Domain, typename Payload>
505 LinearOperator<Range, Domain, Payload>
506 operator*(typename Range::value_type number,
507 const LinearOperator<Range, Domain, Payload> &op)
508 {
509 static_assert(
510 std::is_convertible_v<typename Range::value_type,
511 typename Domain::value_type>,
512 "Range and Domain must have implicitly convertible 'value_type's");
513
514 if (op.is_null_operator)
515 {
516 return op;
517 }
518 else if (number == 0.)
519 {
520 return null_operator(op);
521 }
522 else
523 {
524 LinearOperator<Range, Domain, Payload> return_op = op;
525
526 // ensure to have valid computation objects by catching number and op by
527 // value
528
529 return_op.vmult = [number, op](Range &v, const Domain &u) {
530 op.vmult(v, u);
531 v *= number;
532 };
533
534 return_op.vmult_add = [number, op](Range &v, const Domain &u) {
535 v /= number;
536 op.vmult_add(v, u);
537 v *= number;
538 };
539
540 return_op.Tvmult = [number, op](Domain &v, const Range &u) {
541 op.Tvmult(v, u);
542 v *= number;
543 };
544
545 return_op.Tvmult_add = [number, op](Domain &v, const Range &u) {
546 v /= number;
547 op.Tvmult_add(v, u);
548 v *= number;
549 };
550
551 return return_op;
552 }
553 }
554
555
556 /**
557 * @relatesalso LinearOperator
558 *
559 * Scalar multiplication of a ScalarOperator object from the right.
560 *
561 * The @p Domain and @p Range types must implement the following
562 * <code>operator*=</code> member functions for rescaling:
563 *
564 * @code
565 * Domain & operator *=(Domain::value_type);
566 * Range & operator *=(Range::value_type);
567 * @endcode
568 *
569 * @ingroup LAOperators
570 */
571 template <typename Range, typename Domain, typename Payload>
572 LinearOperator<Range, Domain, Payload>
573 operator*(const LinearOperator<Range, Domain, Payload> &op,
574 typename Domain::value_type number)
575 {
576 static_assert(
577 std::is_convertible_v<typename Range::value_type,
578 typename Domain::value_type>,
579 "Range and Domain must have implicitly convertible 'value_type's");
580
581 return number * op;
582 }
583
584 /** @} */
585
586
587 /**
588 * @name Composition and manipulation of a LinearOperator
589 */
590 /** @{ */
591
592 /**
593 * @relatesalso LinearOperator
594 *
595 * Composition of two linear operators @p first_op and @p second_op given by
596 * $(\mathrm{first\_op}*\mathrm{second\_op})x \dealcoloneq
597 * \mathrm{first\_op}(\mathrm{second\_op}(x))$
598 *
599 * @ingroup LAOperators
600 */
601 template <typename Range,
602 typename Intermediate,
603 typename Domain,
604 typename Payload>
605 LinearOperator<Range, Domain, Payload>
606 operator*(const LinearOperator<Range, Intermediate, Payload> &first_op,
607 const LinearOperator<Intermediate, Domain, Payload> &second_op)
608 {
609 if (first_op.is_null_operator || second_op.is_null_operator)
610 {
611 LinearOperator<Range, Domain, Payload> return_op;
612 return_op.reinit_domain_vector = second_op.reinit_domain_vector;
613 return_op.reinit_range_vector = first_op.reinit_range_vector;
614 return null_operator(return_op);
615 }
616 else
617 {
618 LinearOperator<Range, Domain, Payload> return_op{
619 static_cast<const Payload &>(first_op) *
620 static_cast<const Payload &>(second_op)};
621
622 return_op.reinit_domain_vector = second_op.reinit_domain_vector;
623 return_op.reinit_range_vector = first_op.reinit_range_vector;
624
625 // ensure to have valid computation objects by catching first_op and
626 // second_op by value
627
628 return_op.vmult = [first_op, second_op](Range &v, const Domain &u) {
629 GrowingVectorMemory<Intermediate> vector_memory;
630
631 typename VectorMemory<Intermediate>::Pointer i(vector_memory);
632 second_op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true);
633 second_op.vmult(*i, u);
634 first_op.vmult(v, *i);
635 };
636
637 return_op.vmult_add = [first_op, second_op](Range &v, const Domain &u) {
638 GrowingVectorMemory<Intermediate> vector_memory;
639
640 typename VectorMemory<Intermediate>::Pointer i(vector_memory);
641 second_op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true);
642 second_op.vmult(*i, u);
643 first_op.vmult_add(v, *i);
644 };
645
646 return_op.Tvmult = [first_op, second_op](Domain &v, const Range &u) {
647 GrowingVectorMemory<Intermediate> vector_memory;
648
649 typename VectorMemory<Intermediate>::Pointer i(vector_memory);
650 first_op.reinit_domain_vector(*i, /*bool omit_zeroing_entries =*/true);
651 first_op.Tvmult(*i, u);
652 second_op.Tvmult(v, *i);
653 };
654
655 return_op.Tvmult_add = [first_op, second_op](Domain &v, const Range &u) {
656 GrowingVectorMemory<Intermediate> vector_memory;
657
658 typename VectorMemory<Intermediate>::Pointer i(vector_memory);
659 first_op.reinit_domain_vector(*i, /*bool omit_zeroing_entries =*/true);
660 first_op.Tvmult(*i, u);
661 second_op.Tvmult_add(v, *i);
662 };
663
664 return return_op;
665 }
666 }
667
668
669 /**
670 * @relatesalso LinearOperator
671 *
672 * Return the transpose linear operations of @p op.
673 *
674 *
675 * @ingroup LAOperators
676 */
677 template <typename Range, typename Domain, typename Payload>
678 LinearOperator<Domain, Range, Payload>
679 transpose_operator(const LinearOperator<Range, Domain, Payload> &op)
680 {
681 LinearOperator<Domain, Range, Payload> return_op{op.transpose_payload()};
682
683 return_op.reinit_range_vector = op.reinit_domain_vector;
684 return_op.reinit_domain_vector = op.reinit_range_vector;
685
686 return_op.vmult = op.Tvmult;
687 return_op.vmult_add = op.Tvmult_add;
688 return_op.Tvmult = op.vmult;
689 return_op.Tvmult_add = op.vmult_add;
690
691 return return_op;
692 }
693
694
695 /**
696 * @relatesalso LinearOperator
697 *
698 * Return an object representing the inverse of the LinearOperator @p op.
699 *
700 * The function takes references @p solver and @p preconditioner to an
701 * iterative solver and a preconditioner that are used in the
702 * <code>vmult</code> and <code>Tvmult</code> implementations of the
703 * LinearOperator object.
704 *
705 * The LinearOperator object that is created stores a reference to @p solver
706 * and @p preconditioner. Thus, both objects must remain a valid reference for
707 * the whole lifetime of the LinearOperator object. Internal data structures
708 * of the @p solver object will be modified upon invocation of
709 * <code>vmult</code> or <code>Tvmult</code>.
710 *
711 *
712 * @ingroup LAOperators
713 */
714 template <typename Payload,
715 typename Solver,
716 typename Preconditioner,
717 typename Range = typename Solver::vector_type,
718 typename Domain = Range>
719 LinearOperator<Domain, Range, Payload>
720 inverse_operator(const LinearOperator<Range, Domain, Payload> &op,
721 Solver &solver,
722 const Preconditioner &preconditioner)
723 {
724 LinearOperator<Domain, Range, Payload> return_op{
725 op.inverse_payload(solver, preconditioner)};
726
727 return_op.reinit_range_vector = op.reinit_domain_vector;
728 return_op.reinit_domain_vector = op.reinit_range_vector;
729
730 return_op.vmult = [op, &solver, &preconditioner](Range &v, const Domain &u) {
731 op.reinit_range_vector(v, /*bool omit_zeroing_entries =*/false);
732 solver.solve(op, v, u, preconditioner);
733 };
734
735 return_op.vmult_add = [op, &solver, &preconditioner](Range &v,
736 const Domain &u) {
737 GrowingVectorMemory<Range> vector_memory;
738
739 typename VectorMemory<Range>::Pointer v2(vector_memory);
740 op.reinit_range_vector(*v2, /*bool omit_zeroing_entries =*/false);
741 solver.solve(op, *v2, u, preconditioner);
742 v += *v2;
743 };
744
745 return_op.Tvmult = [op, &solver, &preconditioner](Range &v, const Domain &u) {
746 op.reinit_range_vector(v, /*bool omit_zeroing_entries =*/false);
747 solver.solve(transpose_operator(op), v, u, preconditioner);
748 };
749
750 return_op.Tvmult_add = [op, &solver, &preconditioner](Range &v,
751 const Domain &u) {
752 GrowingVectorMemory<Range> vector_memory;
753
754 typename VectorMemory<Range>::Pointer v2(vector_memory);
755 op.reinit_range_vector(*v2, /*bool omit_zeroing_entries =*/false);
756 solver.solve(transpose_operator(op), *v2, u, preconditioner);
757 v += *v2;
758 };
759
760 return return_op;
761 }
762
763
764 /**
765 * @relatesalso LinearOperator
766 *
767 * Variant of above function that takes a LinearOperator @p preconditioner
768 * as preconditioner argument.
769 *
770 * @ingroup LAOperators
771 */
772 template <typename Payload,
773 typename Solver,
774 typename Range = typename Solver::vector_type,
775 typename Domain = Range>
776 LinearOperator<Domain, Range, Payload>
777 inverse_operator(const LinearOperator<Range, Domain, Payload> &op,
778 Solver &solver,
779 const LinearOperator<Range, Domain, Payload> &preconditioner)
780 {
781 LinearOperator<Domain, Range, Payload> return_op{
782 op.inverse_payload(solver, preconditioner)};
783
784 return_op.reinit_range_vector = op.reinit_domain_vector;
785 return_op.reinit_domain_vector = op.reinit_range_vector;
786
787 return_op.vmult = [op, &solver, preconditioner](Range &v, const Domain &u) {
788 op.reinit_range_vector(v, /*bool omit_zeroing_entries =*/false);
789 solver.solve(op, v, u, preconditioner);
790 };
791
792 return_op.vmult_add = [op, &solver, preconditioner](Range &v,
793 const Domain &u) {
794 GrowingVectorMemory<Range> vector_memory;
795
796 typename VectorMemory<Range>::Pointer v2(vector_memory);
797 op.reinit_range_vector(*v2, /*bool omit_zeroing_entries =*/false);
798 solver.solve(op, *v2, u, preconditioner);
799 v += *v2;
800 };
801
802 return_op.Tvmult = [op, &solver, preconditioner](Range &v, const Domain &u) {
803 op.reinit_range_vector(v, /*bool omit_zeroing_entries =*/false);
804 solver.solve(transpose_operator(op), v, u, preconditioner);
805 };
806
807 return_op.Tvmult_add = [op, &solver, preconditioner](Range &v,
808 const Domain &u) {
809 GrowingVectorMemory<Range> vector_memory;
810
811 typename VectorMemory<Range>::Pointer v2(vector_memory);
812 op.reinit_range_vector(*v2, /*bool omit_zeroing_entries =*/false);
813 solver.solve(transpose_operator(op), *v2, u, preconditioner);
814 v += *v2;
815 };
816
817 return return_op;
818 }
819
820
821 /**
822 * @relatesalso LinearOperator
823 *
824 * Variant of above function without a preconditioner argument. In this
825 * case the identity_operator() of the @p op argument is used as a
826 * preconditioner. This is equivalent to using PreconditionIdentity.
827 *
828 * @ingroup LAOperators
829 */
830 template <typename Payload,
831 typename Solver,
832 typename Range = typename Solver::vector_type,
833 typename Domain = Range>
834 LinearOperator<Domain, Range, Payload>
835 inverse_operator(const LinearOperator<Range, Domain, Payload> &op,
836 Solver &solver)
837 {
838 return inverse_operator(op, solver, identity_operator(op));
839 }
840
841
842 /**
843 * @relatesalso LinearOperator
844 *
845 * Special overload of above function that takes a PreconditionIdentity
846 * argument.
847 *
848 * @ingroup LAOperators
849 */
850 template <typename Payload,
851 typename Solver,
852 typename Range = typename Solver::vector_type,
853 typename Domain = Range>
854 LinearOperator<Domain, Range, Payload>
855 inverse_operator(const LinearOperator<Range, Domain, Payload> &op,
856 Solver &solver,
857 const PreconditionIdentity &)
858 {
859 return inverse_operator(op, solver);
860 }
861
862 /** @} */
863
864
865 /**
866 * @name Creation of a LinearOperator
867 */
868 /** @{ */
869
870 /**
871 * @relatesalso LinearOperator
872 *
873 * Return a LinearOperator that is the identity of the vector space @p Range.
874 *
875 * The function takes an <code>std::function</code> object @p reinit_vector as
876 * an argument to initialize the <code>reinit_range_vector</code> and
877 * <code>reinit_domain_vector</code> objects of the LinearOperator object.
878 *
879 * @ingroup LAOperators
880 */
881 template <
882 typename Range,
883 typename Payload = internal::LinearOperatorImplementation::EmptyPayload>
884 LinearOperator<Range, Range, Payload>
885 identity_operator(const std::function<void(Range &, bool)> &reinit_vector)
886 {
887 LinearOperator<Range, Range, Payload> return_op{Payload()};
888
889 return_op.reinit_range_vector = reinit_vector;
890 return_op.reinit_domain_vector = reinit_vector;
891
892 return_op.vmult = [](Range &v, const Range &u) { v = u; };
893
894 return_op.vmult_add = [](Range &v, const Range &u) { v += u; };
895
896 return_op.Tvmult = [](Range &v, const Range &u) { v = u; };
897
898 return_op.Tvmult_add = [](Range &v, const Range &u) { v += u; };
899
900 return return_op;
901 }
902
903
904 /**
905 * @relatesalso LinearOperator
906 *
907 * Return a LinearOperator that is the identity of the vector space @p Range.
908 *
909 * The function takes a LinearOperator @p op and uses its range initializer
910 * to create an identity operator. In contrast to the function above, this
911 * function also ensures that the underlying Payload matches that of the
912 * input @p op.
913 *
914 * @ingroup LAOperators
915 */
916 template <typename Range, typename Domain, typename Payload>
917 LinearOperator<Range, Domain, Payload>
918 identity_operator(const LinearOperator<Range, Domain, Payload> &op)
919 {
920 auto return_op = identity_operator<Range, Payload>(op.reinit_range_vector);
921 static_cast<Payload &>(return_op) = op.identity_payload();
922
923 return return_op;
924 }
925
926
927 /**
928 * @relatesalso LinearOperator
929 *
930 * Return a nulled variant of the LinearOperator @p op, i.e. with optimized
931 * LinearOperator::vmult, LinearOperator::vmult_add, etc. functions and with
932 * LinearOperator::is_null_operator set to true.
933 *
934 * @ingroup LAOperators
935 */
936 template <typename Range, typename Domain, typename Payload>
937 LinearOperator<Range, Domain, Payload>
938 null_operator(const LinearOperator<Range, Domain, Payload> &op)
939 {
940 LinearOperator<Range, Domain, Payload> return_op{op.null_payload()};
941
942 return_op.is_null_operator = true;
943
944 return_op.reinit_range_vector = op.reinit_range_vector;
945 return_op.reinit_domain_vector = op.reinit_domain_vector;
946
947 return_op.vmult = [](Range &v, const Domain &) { v = 0.; };
948
949 return_op.vmult_add = [](Range &, const Domain &) {};
950
951 return_op.Tvmult = [](Domain &v, const Range &) { v = 0.; };
952
953 return_op.Tvmult_add = [](Domain &, const Range &) {};
954
955 return return_op;
956 }
957
958
959 /**
960 * @relatesalso LinearOperator
961 *
962 * Return a LinearOperator that acts as a mean value filter. The vmult()
963 * functions of this matrix subtract the mean values of the vector.
964 *
965 * The function takes an <code>std::function</code> object @p reinit_vector as
966 * an argument to initialize the <code>reinit_range_vector</code> and
967 * <code>reinit_domain_vector</code> objects of the LinearOperator object.
968 *
969 * @ingroup LAOperators
970 */
971 template <
972 typename Range,
973 typename Payload = internal::LinearOperatorImplementation::EmptyPayload>
974 LinearOperator<Range, Range, Payload>
975 mean_value_filter(const std::function<void(Range &, bool)> &reinit_vector)
976 {
977 LinearOperator<Range, Range, Payload> return_op{Payload()};
978
979 return_op.reinit_range_vector = reinit_vector;
980 return_op.reinit_domain_vector = reinit_vector;
981
982 return_op.vmult = [](Range &v, const Range &u) {
983 const auto mean = u.mean_value();
984
985 v = u;
986 v.add(-mean);
987 };
988
989 return_op.vmult_add = [](Range &v, const Range &u) {
990 const auto mean = u.mean_value();
991
992 v += u;
993 v.add(-mean);
994 };
995
996 return_op.Tvmult = return_op.vmult_add;
997 return_op.Tvmult_add = return_op.vmult_add;
998
999 return return_op;
1000 }
1001
1002
1003 /**
1004 * @relatesalso LinearOperator
1005 *
1006 * Return a LinearOperator that acts as a mean value filter. The vmult()
1007 * functions of this matrix subtract the mean values of the vector.
1008 *
1009 * The function takes a LinearOperator @p op and uses its range initializer
1010 * to create an mean value filter operator. The function also ensures that
1011 * the underlying Payload matches that of the input @p op.
1012 *
1013 * @ingroup LAOperators
1014 */
1015 template <typename Range, typename Domain, typename Payload>
1016 LinearOperator<Range, Domain, Payload>
1017 mean_value_filter(const LinearOperator<Range, Domain, Payload> &op)
1018 {
1019 auto return_op = mean_value_filter<Range, Payload>(op.reinit_range_vector);
1020 static_cast<Payload &>(return_op) = op.identity_payload();
1021
1022 return return_op;
1023 }
1024
1025
1026 namespace internal
1027 {
1028 namespace LinearOperatorImplementation
1029 {
1030 /**
1031 * A helper class that is responsible for the initialization of a vector
1032 * to be directly usable as the destination parameter, or source parameter
1033 * in an application of vmult of a matrix.
1034 *
1035 * The generic version of this class just calls
1036 * <code>Vector::reinit()</code> with the result of
1037 * <code>Matrix::m()</code> or <code>Matrix::n()</code>, respectively.
1038 * This class is specialized for more complicated data structures, such as
1039 * TrilinosWrappers::MPI::Vector, etc.
1040 */
1041 template <typename Vector>
1042 class ReinitHelper
1043 {
1044 public:
1045 /**
1046 * Initializes a vector v of the Range space to be directly usable as
1047 * the destination parameter in an application of vmult. Similar to the
1048 * reinit functions of the vector classes, the boolean determines
1049 * whether a fast initialization is done, i.e., if it is set to false the
1050 * content of the vector is set to 0.
1051 *
1052 * The generic version of this class just calls
1053 * <code>Vector::reinit()</code> with the result of
1054 * <code>Matrix::m()</code>.
1055 */
1056 template <typename Matrix>
1057 static void
1058 reinit_range_vector(const Matrix &matrix,
1059 Vector &v,
1060 bool omit_zeroing_entries)
1061 {
1062 v.reinit(matrix.m(), omit_zeroing_entries);
1063 }
1064
1065 /**
1066 * Initializes a vector of the Domain space to be directly usable as the
1067 * source parameter in an application of vmult. Similar to the reinit
1068 * functions of the vector classes, the boolean determines whether a
1069 * fast initialization is done, i.e., if it is set to false the content
1070 * of the vector is set to 0.
1071 *
1072 * The generic version of this class just calls
1073 * <code>Vector::reinit()</code> with the result of
1074 * <code>Matrix::n()</code>.
1075 */
1076 template <typename Matrix>
1077 static void
1078 reinit_domain_vector(const Matrix &matrix,
1079 Vector &v,
1080 bool omit_zeroing_entries)
1081 {
1082 v.reinit(matrix.n(), omit_zeroing_entries);
1083 }
1084 };
1085
1086
1087 /**
1088 * A dummy class for LinearOperators that do not require any extensions to
1089 * facilitate the operations of the matrix.
1090 *
1091 * This is the Payload class typically associated with deal.II's native
1092 * SparseMatrix. To use Trilinos and PETSc sparse matrix classes it is
1093 * necessary to initialize a LinearOperator with their associated Payload.
1094 *
1095 *
1096 * @ingroup LAOperators
1097 */
1098 class EmptyPayload
1099 {
1100 public:
1101 /**
1102 * Default constructor
1103 *
1104 * Since this class does not do anything in particular and needs no
1105 * special configuration, we have only one generic constructor that can
1106 * be called under any conditions.
1107 */
1108 template <typename... Args>
1109 EmptyPayload(const Args &...)
1110 {}
1111
1112
1113 /**
1114 * Return a payload configured for identity operations
1115 */
1116 EmptyPayload
1117 identity_payload() const
1118 {
1119 return *this;
1120 }
1121
1122
1123 /**
1124 * Return a payload configured for null operations
1125 */
1126 EmptyPayload
1127 null_payload() const
1128 {
1129 return *this;
1130 }
1131
1132
1133 /**
1134 * Return a payload configured for transpose operations
1135 */
1136 EmptyPayload
1137 transpose_payload() const
1138 {
1139 return *this;
1140 }
1141
1142
1143 /**
1144 * Return a payload configured for inverse operations
1145 */
1146 template <typename Solver, typename Preconditioner>
1147 EmptyPayload
1148 inverse_payload(Solver &, const Preconditioner &) const
1149 {
1150 return *this;
1151 }
1152 };
1153
1154 /**
1155 * Operator that returns a payload configured to support the addition of
1156 * two LinearOperators
1157 */
1158 inline EmptyPayload
1159 operator+(const EmptyPayload &, const EmptyPayload &)
1160 {
1161 return {};
1162 }
1163
1164 /**
1165 * Operator that returns a payload configured to support the
1166 * multiplication of two LinearOperators
1167 */
1168 inline EmptyPayload
1169 operator*(const EmptyPayload &, const EmptyPayload &)
1170 {
1171 return {};
1172 }
1173
1174
1175
1176 // A trait class that determines whether type T provides public
1177 // (templated or non-templated) vmult_add member functions
1178 template <typename Range, typename Domain, typename T>
1179 class has_vmult_add_and_Tvmult_add
1180 {
1181 template <typename C>
1182 static std::false_type
1183 test(...);
1184
1185 template <typename C>
1186 static auto
1187 test(Range *r, Domain *d)
1188 -> decltype(std::declval<C>().vmult_add(*r, *d),
1189 std::declval<C>().Tvmult_add(*d, *r),
1190 std::true_type());
1191
1192 public:
1193 // type is std::true_type if Matrix provides vmult_add and Tvmult_add,
1194 // otherwise it is std::false_type
1195
1196 using type = decltype(test<T>(nullptr, nullptr));
1197 };
1198
1199
1200 // A helper function to apply a given vmult, or Tvmult to a vector with
1201 // intermediate storage
1202 template <typename Function, typename Range, typename Domain>
1203 void
1204 apply_with_intermediate_storage(Function function,
1205 Range &v,
1206 const Domain &u,
1207 bool add)
1208 {
1209 GrowingVectorMemory<Range> vector_memory;
1210
1211 typename VectorMemory<Range>::Pointer i(vector_memory);
1212 i->reinit(v, /*bool omit_zeroing_entries =*/true);
1213
1214 function(*i, u);
1215
1216 if (add)
1217 v += *i;
1218 else
1219 v = *i;
1220 }
1221
1222
1223 // A helper class to add a reduced matrix interface to a LinearOperator
1224 // (typically provided by Preconditioner classes)
1225 template <typename Range, typename Domain, typename Payload>
1226 class MatrixInterfaceWithoutVmultAdd
1227 {
1228 public:
1229 template <typename Matrix>
1230 void
1231 operator()(LinearOperator<Range, Domain, Payload> &op,
1232 const Matrix &matrix)
1233 {
1234 op.vmult = [&matrix](Range &v, const Domain &u) {
1235 if (PointerComparison::equal(&v, &u))
1236 {
1237 // If v and u are the same memory location use intermediate
1238 // storage
1239 apply_with_intermediate_storage(
1240 [&matrix](Range &b, const Domain &a) { matrix.vmult(b, a); },
1241 v,
1242 u,
1243 /*bool add =*/false);
1244 }
1245 else
1246 {
1247 matrix.vmult(v, u);
1248 }
1249 };
1250
1251 op.vmult_add = [&matrix](Range &v, const Domain &u) {
1252 // use intermediate storage to implement vmult_add with vmult
1253 apply_with_intermediate_storage(
1254 [&matrix](Range &b, const Domain &a) { matrix.vmult(b, a); },
1255 v,
1256 u,
1257 /*bool add =*/true);
1258 };
1259
1260 op.Tvmult = [&matrix](Domain &v, const Range &u) {
1261 if (PointerComparison::equal(&v, &u))
1262 {
1263 // If v and u are the same memory location use intermediate
1264 // storage
1265 apply_with_intermediate_storage(
1266 [&matrix](Domain &b, const Range &a) { matrix.Tvmult(b, a); },
1267 v,
1268 u,
1269 /*bool add =*/false);
1270 }
1271 else
1272 {
1273 matrix.Tvmult(v, u);
1274 }
1275 };
1276
1277 op.Tvmult_add = [&matrix](Domain &v, const Range &u) {
1278 // use intermediate storage to implement Tvmult_add with Tvmult
1279 apply_with_intermediate_storage(
1280 [&matrix](Domain &b, const Range &a) { matrix.Tvmult(b, a); },
1281 v,
1282 u,
1283 /*bool add =*/true);
1284 };
1285 }
1286 };
1287
1288
1289 // A helper class to add the full matrix interface to a LinearOperator
1290 template <typename Range, typename Domain, typename Payload>
1291 class MatrixInterfaceWithVmultAdd
1292 {
1293 public:
1294 template <typename Matrix>
1295 void
1296 operator()(LinearOperator<Range, Domain, Payload> &op,
1297 const Matrix &matrix)
1298 {
1299 // As above ...
1300
1301 MatrixInterfaceWithoutVmultAdd<Range, Domain, Payload>().operator()(
1302 op, matrix);
1303
1304 // ... but add native vmult_add and Tvmult_add variants:
1305
1306 op.vmult_add = [&matrix](Range &v, const Domain &u) {
1307 if (PointerComparison::equal(&v, &u))
1308 {
1309 apply_with_intermediate_storage(
1310 [&matrix](Range &b, const Domain &a) { matrix.vmult(b, a); },
1311 v,
1312 u,
1313 /*bool add =*/true);
1314 }
1315 else
1316 {
1317 matrix.vmult_add(v, u);
1318 }
1319 };
1320
1321 op.Tvmult_add = [&matrix](Domain &v, const Range &u) {
1322 if (PointerComparison::equal(&v, &u))
1323 {
1324 apply_with_intermediate_storage(
1325 [&matrix](Domain &b, const Range &a) { matrix.Tvmult(b, a); },
1326 v,
1327 u,
1328 /*bool add =*/true);
1329 }
1330 else
1331 {
1332 matrix.Tvmult_add(v, u);
1333 }
1334 };
1335 }
1336 };
1337 } // namespace LinearOperatorImplementation
1338 } // namespace internal
1339
1340
1341 /**
1342 * @relatesalso LinearOperator
1343 *
1344 * A function that encapsulates generic @p matrix objects that act on a
1345 * compatible Vector type into a LinearOperator. The LinearOperator object
1346 * that is created stores a reference to the matrix object. Thus, @p matrix
1347 * must remain a valid reference for the whole lifetime of the LinearOperator
1348 * object.
1349 *
1350 * All changes made on @p matrix after the creation of the LinearOperator
1351 * object are reflected by the operator object. For example, it is a valid
1352 * procedure to first create a LinearOperator and resize, reassemble the
1353 * matrix later.
1354 *
1355 * The Matrix class in question must provide the following minimal interface:
1356 *
1357 * @code
1358 * class Matrix
1359 * {
1360 * public:
1361 * // (type specific) information how to create a Range and Domain vector
1362 * // with appropriate size and internal layout
1363 *
1364 * // Application of matrix to vector src, writes the result into dst.
1365 * vmult(Range &dst, const Domain &src);
1366 *
1367 * // Application of the transpose of matrix to vector src, writes the
1368 * // result into dst. (Depending on the usage of the linear operator
1369 * // class this can be a dummy implementation throwing an error.)
1370 * Tvmult(Range &dst, const Domain &src);
1371 * };
1372 * @endcode
1373 *
1374 * The following (optional) interface is used if available:
1375 *
1376 * @code
1377 * class Matrix
1378 * {
1379 * public:
1380 * // Application of matrix to vector src, adds the result to dst.
1381 * vmult_add(Range &dst, const Domain &src);
1382 *
1383 * // Application of the transpose of matrix to vector src, adds the
1384 * // result to dst.
1385 * Tvmult_add(Range &dst, const Domain &src);
1386 * };
1387 * @endcode
1388 *
1389 * If the Matrix does not provide <code>vmult_add</code> and
1390 * <code>Tvmult_add</code>, they are implemented in terms of
1391 * <code>vmult</code> and <code>Tvmult</code> (requiring intermediate
1392 * storage).
1393 *
1394 *
1395 * @ingroup LAOperators
1396 */
1397 template <typename Range, typename Domain, typename Payload, typename Matrix>
1398 LinearOperator<Range, Domain, Payload>
1399 linear_operator(const Matrix &matrix)
1400 {
1401 // implement with the more generic variant below...
1402 return linear_operator<Range, Domain, Payload, Matrix, Matrix>(matrix,
1403 matrix);
1404 }
1405
1406
1407 /**
1408 * @relatesalso LinearOperator
1409 *
1410 * Variant of above function that takes an operator object @p
1411 * operator_exemplar as an additional reference. This object is used to
1412 * populate the reinit_domain_vector and reinit_range_vector function objects.
1413 * The reference @p matrix is used to construct vmult, Tvmult, etc.
1414 *
1415 * This variant can, for example, be used to encapsulate preconditioners (that
1416 * typically do not expose any information about the underlying matrix).
1417 *
1418 *
1419 * @ingroup LAOperators
1420 */
1421 template <typename Range,
1422 typename Domain,
1423 typename Payload,
1424 typename OperatorExemplar,
1425 typename Matrix>
1426 LinearOperator<Range, Domain, Payload>
1427 linear_operator(const OperatorExemplar &operator_exemplar, const Matrix &matrix)
1428 {
1429 using namespace internal::LinearOperatorImplementation;
1430 // Initialize the payload based on the input exemplar matrix
1431 LinearOperator<Range, Domain, Payload> return_op{
1432 Payload(operator_exemplar, matrix)};
1433
1434 // Always store a reference to matrix and operator_exemplar in the lambda
1435 // functions. This ensures that a modification of the matrix after the
1436 // creation of a LinearOperator wrapper is respected - further a matrix
1437 // or an operator_exemplar cannot usually be copied...
1438
1439 return_op.reinit_range_vector =
1440 [&operator_exemplar](Range &v, bool omit_zeroing_entries) {
1441 internal::LinearOperatorImplementation::ReinitHelper<
1442 Range>::reinit_range_vector(operator_exemplar, v, omit_zeroing_entries);
1443 };
1444
1445 return_op.reinit_domain_vector = [&operator_exemplar](
1446 Domain &v, bool omit_zeroing_entries) {
1447 internal::LinearOperatorImplementation::ReinitHelper<
1448 Domain>::reinit_domain_vector(operator_exemplar, v, omit_zeroing_entries);
1449 };
1450
1451 std::conditional_t<
1452 has_vmult_add_and_Tvmult_add<Range, Domain, Matrix>::type::value,
1453 MatrixInterfaceWithVmultAdd<Range, Domain, Payload>,
1454 MatrixInterfaceWithoutVmultAdd<Range, Domain, Payload>>()
1455 .
1456 operator()(return_op, matrix);
1457
1458 return return_op;
1459 }
1460
1461
1462
1463 /**
1464 * @relatesalso LinearOperator
1465 *
1466 * Variant of above function that takes a LinearOperator @p
1467 * operator_exemplar as an additional reference.
1468 * The reinit_domain_vector and reinit_range_vector function are copied
1469 * from the @p operator_exemplar object.
1470 *
1471 * The reference @p matrix is used to construct vmult, Tvmult, etc.
1472 *
1473 * This variant can, for example, be used to encapsulate preconditioners (that
1474 * typically do not expose any information about the underlying matrix).
1475 *
1476 *
1477 * @ingroup LAOperators
1478 */
1479 template <typename Range, typename Domain, typename Payload, typename Matrix>
1480 LinearOperator<Range, Domain, Payload>
1481 linear_operator(const LinearOperator<Range, Domain, Payload> &operator_exemplar,
1482 const Matrix &matrix)
1483 {
1484 using namespace internal::LinearOperatorImplementation;
1485 // Initialize the payload based on the LinearOperator exemplar
1486 auto return_op = operator_exemplar;
1487
1488 std::conditional_t<
1489 has_vmult_add_and_Tvmult_add<Range, Domain, Matrix>::type::value,
1490 MatrixInterfaceWithVmultAdd<Range, Domain, Payload>,
1491 MatrixInterfaceWithoutVmultAdd<Range, Domain, Payload>>()
1492 .
1493 operator()(return_op, matrix);
1494
1495 return return_op;
1496 }
1497
1498
1499 /** @} */
1500
1501 #ifndef DOXYGEN
1502
1503 //
1504 // Ensure that we never capture a reference to a temporary by accident.
1505 // to avoid "stack use after free".
1506 //
1507
1508 template <
1509 typename Range = Vector<double>,
1510 typename Domain = Range,
1511 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
1512 typename OperatorExemplar,
1513 typename Matrix,
1514 typename = std::enable_if_t<!std::is_lvalue_reference_v<Matrix>>>
1515 LinearOperator<Range, Domain, Payload>
1516 linear_operator(const OperatorExemplar &, Matrix &&) = delete;
1517
1518 template <
1519 typename Range = Vector<double>,
1520 typename Domain = Range,
1521 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
1522 typename OperatorExemplar,
1523 typename Matrix,
1524 typename = std::enable_if_t<!std::is_lvalue_reference_v<OperatorExemplar>>,
1525 typename = std::enable_if_t<
1526 !std::is_same_v<OperatorExemplar, LinearOperator<Range, Domain, Payload>>>>
1527 LinearOperator<Range, Domain, Payload>
1528 linear_operator(OperatorExemplar &&, const Matrix &) = delete;
1529
1530 template <
1531 typename Range = Vector<double>,
1532 typename Domain = Range,
1533 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
1534 typename OperatorExemplar,
1535 typename Matrix,
1536 typename = std::enable_if_t<!std::is_lvalue_reference_v<Matrix>>,
1537 typename = std::enable_if_t<!std::is_lvalue_reference_v<OperatorExemplar>>,
1538 typename = std::enable_if_t<
1539 !std::is_same_v<OperatorExemplar, LinearOperator<Range, Domain, Payload>>>>
1540 LinearOperator<Range, Domain, Payload>
1541 linear_operator(OperatorExemplar &&, Matrix &&) = delete;
1542
1543 template <
1544 typename Range = Vector<double>,
1545 typename Domain = Range,
1546 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
1547 typename Matrix,
1548 typename = std::enable_if_t<!std::is_lvalue_reference_v<Matrix>>>
1549 LinearOperator<Range, Domain, Payload>
1550 linear_operator(const LinearOperator<Range, Domain, Payload> &,
1551 Matrix &&) = delete;
1552
1553 template <
1554 typename Range = Vector<double>,
1555 typename Domain = Range,
1556 typename Payload = internal::LinearOperatorImplementation::EmptyPayload,
1557 typename Matrix,
1558 typename = std::enable_if_t<!std::is_lvalue_reference_v<Matrix>>>
1559 LinearOperator<Range, Domain, Payload>
1560 linear_operator(Matrix &&) = delete;
1561
1562 template <
1563 typename Payload,
1564 typename Solver,
1565 typename Preconditioner,
1566 typename Range = typename Solver::vector_type,
1567 typename Domain = Range,
1568 typename = std::enable_if_t<!std::is_lvalue_reference_v<Preconditioner>>,
1569 typename =
1570 std::enable_if_t<!std::is_same_v<Preconditioner, PreconditionIdentity>>,
1571 typename = std::enable_if_t<
1572 !std::is_same_v<Preconditioner, LinearOperator<Range, Domain, Payload>>>>
1573 LinearOperator<Domain, Range, Payload>
1574 inverse_operator(const LinearOperator<Range, Domain, Payload> &,
1575 Solver &,
1576 Preconditioner &&) = delete;
1577
1578 #endif // DOXYGEN
1579
1580 DEAL_II_NAMESPACE_CLOSE
1581
1582 #endif