]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Document instrumenting functions. 16294/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Fri, 24 Nov 2023 23:54:46 +0000 (16:54 -0700)
committerWolfgang Bangerth <bangerth@colostate.edu>
Fri, 24 Nov 2023 23:54:46 +0000 (16:54 -0700)
include/deal.II/lac/linear_operator.h

index 0693e98fb9fe2daf56eb712610cdbca8629c0353..3fba7c475f19c69a5e9ae3e27fe9ae79545b6e07 100644 (file)
@@ -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
  */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.