From a7c2bfecd8b75f338972da7526f65562c4b116a8 Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Sun, 10 May 2015 14:19:27 +0200 Subject: [PATCH] update documentation --- doc/doxygen/headers/laoperators.h | 73 +++++++++++++++++++++++++++ include/deal.II/lac/linear_operator.h | 13 +++-- 2 files changed, 82 insertions(+), 4 deletions(-) diff --git a/doc/doxygen/headers/laoperators.h b/doc/doxygen/headers/laoperators.h index 1616826357..f52ed2c168 100644 --- a/doc/doxygen/headers/laoperators.h +++ b/doc/doxygen/headers/laoperators.h @@ -96,6 +96,79 @@ * InverseMatrixRichardson, SchurMatrix, ShiftedMatrix, * ShiftedMatrixGeneralized, TransposeMatrix * + * + *

Packaged Operation

+ * + * An application of a LinearOperator object to a vector via + * operator* yields a PackagedOperation object that stores + * this computation. + * + * The PackagedOperation class allows lazy evaluation of expressions + * involving vectors and linear operators. This is done by storing the + * computational expression and only performing the computation when either + * the object is implicitly converted to a vector object, or + * apply (or apply_add) is invoked by hand. This + * avoids unnecessary temporary storage of intermediate results. + * + * As an example consider the addition of multiple vectors: + * @code + * dealii::Vector a, b, c, d; + * // .. + * dealii::Vector result = a + b - c + d; + * @endcode + * Converting the PackagedOperation a + b - c + d to a vector + * results in code equivalent to the following code + * @code + * dealii::Vector a, b, c, d; + * // .. + * dealii::Vector result = a; + * result += b; + * result -= c; + * result += d; + * @endcode + * that avoids any intermediate storage. As a second example (involving a + * LinearOperator object) consider the computation of a residual $b-Ax$: + * + * @code + * dealii::SparseMatrix A; + * dealii::Vector b, x; + * // .. + * const auto op_a = linear_operator(A); + * + * dealii::Vector residual = b - op_a * x; + * @endcode + * + * @note + * Lazy evaluation of a computational expression necessarily involves + * references to the underlying vector and matrix objects. For example, the + * creation of a residual_expr object + * @code + * auto residual_expr = b - op_a * x; + * @endcode + * stores the computational expression of the residual with references to + * the vector b and matrix A. It does not perform + * any computation at this point. In particular, if b or + * A are changed after the creation of + * residual_expr every subsequent evaluation of the expression + * is performed with the new values + * @code + * auto residual_expr = b - op_a * x; + * residual_expr.apply(tmp); // tmp is a Vector + * + * // modify b, or A + * + * residual_expr.apply(tmp2); // tmp2 is a Vector + * + * // tmp and tmp2 are different + * @endcode + * Thus, as a safeguard, if you want to compute the result of an expression + * right away, always explicitly use a vector type on the left side (and + * not auto): + * @code + * Vector residual = b - op_a * x; // computes the residual at this point + * @endcode + * + * * @ingroup LAC * @ingroup MATRICES */ diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h index f3b1c69662..324df3df3b 100644 --- a/include/deal.II/lac/linear_operator.h +++ b/include/deal.II/lac/linear_operator.h @@ -1314,6 +1314,13 @@ block_diagonal_operator(const LinearOperatorapply (or apply_add) is invoked by hand. This + * avoids unnecessary temporary storage of intermediate results. + * * The class essentially consists of std::function objects * that store the knowledge of how to generate the result of a computation * and store it in a vector: @@ -1328,9 +1335,7 @@ block_diagonal_operator(const LinearOperator reinit_vector; * @endcode * - * The primary purpose of this class is to allow lazy evaluation of - * expressions involving vectors and linear operators. As an example - * consider the addition of multiple vectors + * As an example consider the addition of multiple vectors * @code * dealii::Vector a, b, c, d; * // .. @@ -1343,7 +1348,7 @@ block_diagonal_operator(const LinearOperator residual = b - op_a * x; * @endcode * The expression residual is of type * PackagedOperation>. It stores -- 2.39.5