From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 24 Nov 2023 23:54:46 +0000 (-0700)
Subject: Document instrumenting functions.
X-Git-Tag: relicensing~280^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16294%2Fhead;p=dealii.git

Document instrumenting functions.
---

diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h
index 0693e98fb9..3fba7c475f 100644
--- a/include/deal.II/lac/linear_operator.h
+++ b/include/deal.II/lac/linear_operator.h
@@ -94,7 +94,7 @@ identity_operator(const LinearOperator<Range, Domain, Payload> &);
  *
  * But, in contrast to a usual matrix object, the domain and range of the
  * linear operator are also bound to the LinearOperator class on the type
- * level. Because of this, <code>LinearOperator <Range, Domain></code> has two
+ * level. Because of this, `LinearOperator<Range, Domain>` has two
  * additional function objects
  * @code
  *   std::function<void(Range &, bool)> reinit_range_vector;
@@ -169,9 +169,31 @@ identity_operator(const LinearOperator<Range, Domain, Payload> &);
  * for linear operators have been provided within the respective
  * TrilinosWrappers (and, in the future, PETScWrappers) namespaces.
  *
- * @note The step-20 tutorial program has a detailed usage example of the
+ * <h3> Examples of use </h3>
+ * The step-20 tutorial program has a detailed usage example of the
  * LinearOperator class.
  *
+ * <h3> Instrumenting operations </h3>
+ * It is sometimes useful to know when functions are called, or to inject
+ * additional operations. In such cases, what one wants is to replace, for
+ * example, the `vmult` object of this class with one that does the additional
+ * operations and then calls what was originally supposed to happen. This
+ * can be done with commands such as the following:
+ * @code
+ *    auto A_inv  = inverse_operator(A, solver_A, preconditioner_A);
+ *    A_inv.vmult = [base_vmult = A_inv.vmult](Vector<double>       &dst,
+ *                                             const Vector<double> &src) {
+ *      std::cout << "Calling A_inv.vmult()" << std::endl;
+ *      base_vmult(dst, src);
+ *    };
+ * @endcode
+ * Here, we replace `A_inv.vmult` with a lambda function that first captures
+ * the previous value of `A_inv.vmult` and stores it in the `base_vmult`
+ * object. The newly installed `A_inv.vmult` function then first outputs some
+ * status information, and then calls the original functionality.
+ *
+ * This approach works for all of the other function objects mentioned above
+ * as well.
  *
  * @ingroup LAOperators
  */