// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2015 - 2023 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_packaged_operation_h #define dealii_packaged_operation_h #include #include #include #include DEAL_II_NAMESPACE_OPEN // Forward declarations: #ifndef DOXYGEN template class Vector; template class LinearOperator; template > class PackagedOperation; #endif /** * A class to store a 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. * * 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: * @code * std::function apply; * std::function apply_add; * @endcode * * Similar to the LinearOperator class it also has knowledge about how to * initialize a vector of the @p Range space: * @code * std::function reinit_vector; * @endcode * * As an example consider the addition of multiple vectors * @code * Vector a, b, c, d; * // .. * Vector result = a + b - c + d; * @endcode * or the computation of a residual $b-Ax$: * @code * SparseMatrix A; * Vector b, x; * // .. * const auto op_a = linear_operator(A); * * auto residual = b - op_a * x; * @endcode * The expression residual is of type * PackagedOperation>. It stores * references to A, b and x and defers * the actual computation until apply, or apply_add * are explicitly invoked, * @code * Vector y; * residual.reinit_vector(y); * residual.apply(y); * residual.apply_add(y); * @endcode * or until the @p PackagedOperation object is implicitly converted: * @code * Vector y; * y = residual; * y += residual; * y -= residual; * @endcode * * @note The step-20 tutorial program has a detailed usage example of the * LinearOperator class. * * * @ingroup LAOperators */ template class PackagedOperation { public: /** * Create an empty PackagedOperation object. All std::function * member objects are initialized with default variants that throw an * exception upon invocation. */ PackagedOperation() { apply = [](Range &) { Assert(false, ExcMessage( "Uninitialized PackagedOperation::apply called")); }; apply_add = [](Range &) { Assert(false, ExcMessage( "Uninitialized PackagedOperation::apply_add called")); }; reinit_vector = [](Range &, bool) { Assert(false, ExcMessage("Uninitialized PackagedOperation::reinit_vector " "method called")); }; } /** * Default copy constructor. */ PackagedOperation(const PackagedOperation &) = default; /** * Constructor that creates a PackagedOperation object from a reference * vector @p u. The PackagedOperation returns @p u. * * The PackagedOperation object that is created stores a reference to @p u. * Thus, the vector must remain a valid reference for the whole lifetime of * the PackagedOperation object. All changes made on @p u after the creation * of the PackagedOperation object are reflected by the operator object. */ PackagedOperation(const Range &u) { *this = u; } /** * Default copy assignment operator. */ PackagedOperation & operator=(const PackagedOperation &) = default; /** * Copy assignment operator that creates a PackagedOperation object from a * reference vector @p u. The PackagedOperation returns @p u. * * The PackagedOperation object that is created stores a reference to @p u. * Thus, the vector must remain a valid reference for the whole lifetime of * the PackagedOperation object. All changes made on @p u after the creation * of the PackagedOperation object are reflected by the operator object. */ PackagedOperation & operator=(const Range &u) { apply = [&u](Range &v) { v = u; }; apply_add = [&u](Range &v) { v += u; }; reinit_vector = [&u](Range &v, bool omit_zeroing_entries) { v.reinit(u, omit_zeroing_entries); }; return *this; } /** * Convert a PackagedOperation to its result. * * This conversion operator creates a vector of the Range space and calls * apply() on it. */ operator Range() const { Range result_vector; reinit_vector(result_vector, /*bool omit_zeroing_entries=*/true); apply(result_vector); return result_vector; } /** * @name In-place vector space operations */ /** @{ */ /** * Addition with a PackagedOperation @p second_comp with the same @p Range. */ PackagedOperation & operator+=(const PackagedOperation &second_comp) { *this = *this + second_comp; return *this; } /** * Subtraction with a PackagedOperation @p second_comp with the same @p * Range. */ PackagedOperation & operator-=(const PackagedOperation &second_comp) { *this = *this - second_comp; return *this; } /** * Add a constant @p offset (of the @p Range space) to the result of a * PackagedOperation. */ PackagedOperation & operator+=(const Range &offset) { *this = *this + PackagedOperation(offset); return *this; } /** * Subtract a constant @p offset (of the @p Range space) from the result of * a PackagedOperation. */ PackagedOperation & operator-=(const Range &offset) { *this = *this - PackagedOperation(offset); return *this; } /** * Scalar multiplication of the PackagedOperation with a @p number. */ PackagedOperation & operator*=(typename Range::value_type number) { *this = *this * number; return *this; } /** @} */ /** * Store the result of the PackagedOperation in a vector v of the @p Range * space. */ std::function apply; /** * Add the result of the PackagedOperation to a vector v of the @p Range * space. */ std::function apply_add; /** * Initializes a vector v of the Range space to be directly usable as the * destination parameter in an application of apply, or apply_add. Similar * to the reinit functions of the vector classes, the boolean determines * whether a fast initialization is done, i.e., if it is set to false the * content of the vector is set to 0. */ std::function reinit_vector; }; /** * @name Vector space operations */ /** @{ */ /** * @relatesalso PackagedOperation * * Addition of two PackagedOperation objects @p first_comp and @p second_comp * given by vector space addition of the corresponding results. * * @ingroup LAOperators */ template PackagedOperation operator+(const PackagedOperation &first_comp, const PackagedOperation &second_comp) { PackagedOperation return_comp; return_comp.reinit_vector = first_comp.reinit_vector; // ensure to have valid PackagedOperation objects by catching first_comp and // second_comp by value return_comp.apply = [first_comp, second_comp](Range &v) { first_comp.apply(v); second_comp.apply_add(v); }; return_comp.apply_add = [first_comp, second_comp](Range &v) { first_comp.apply_add(v); second_comp.apply_add(v); }; return return_comp; } /** * @relatesalso PackagedOperation * * Subtraction of two PackagedOperation objects @p first_comp and @p * second_comp given by vector space addition of the corresponding results. * * @ingroup LAOperators */ template PackagedOperation operator-(const PackagedOperation &first_comp, const PackagedOperation &second_comp) { PackagedOperation return_comp; return_comp.reinit_vector = first_comp.reinit_vector; // ensure to have valid PackagedOperation objects by catching first_comp and // second_comp by value return_comp.apply = [first_comp, second_comp](Range &v) { second_comp.apply(v); v *= -1.; first_comp.apply_add(v); }; return_comp.apply_add = [first_comp, second_comp](Range &v) { first_comp.apply_add(v); v *= -1.; second_comp.apply_add(v); v *= -1.; }; return return_comp; } /** * @relatesalso PackagedOperation * * Scalar multiplication of a PackagedOperation objects @p comp with a scalar * @p number given by a scaling PackagedOperation result with @p number. * * @ingroup LAOperators */ template PackagedOperation operator*(const PackagedOperation &comp, typename Range::value_type number) { PackagedOperation return_comp; return_comp.reinit_vector = comp.reinit_vector; // the trivial case: number is zero if (number == 0.) { return_comp.apply = [](Range &v) { v = 0.; }; return_comp.apply_add = [](Range &) {}; } else { return_comp.apply = [comp, number](Range &v) { comp.apply(v); v *= number; }; return_comp.apply_add = [comp, number](Range &v) { v /= number; comp.apply_add(v); v *= number; }; } return return_comp; } /** * @relatesalso PackagedOperation * * Scalar multiplication of a PackagedOperation objects @p comp with a scalar * @p number given by a scaling PackagedOperation result with @p number. * * @ingroup LAOperators */ template PackagedOperation operator*(typename Range::value_type number, const PackagedOperation &comp) { return comp * number; } /** * @relatesalso PackagedOperation * * Add a constant @p offset (of the @p Range space) to the result of a * PackagedOperation. * * @ingroup LAOperators */ template PackagedOperation operator+(const PackagedOperation &comp, const Range &offset) { return comp + PackagedOperation(offset); } /** * @relatesalso PackagedOperation * * Add a constant @p offset (of the @p Range space) to the result of a * PackagedOperation. * * @ingroup LAOperators */ template PackagedOperation operator+(const Range &offset, const PackagedOperation &comp) { return PackagedOperation(offset) + comp; } /** * @relatesalso PackagedOperation * * Subtract a constant @p offset (of the @p Range space) from the result of a * PackagedOperation. * * @ingroup LAOperators */ template PackagedOperation operator-(const PackagedOperation &comp, const Range &offset) { return comp - PackagedOperation(offset); } /** * @relatesalso PackagedOperation * * Subtract a computational result from a constant @p offset (of the @p Range * space). The result is a PackagedOperation object that applies this * computation. * * @ingroup LAOperators */ template PackagedOperation operator-(const Range &offset, const PackagedOperation &comp) { return PackagedOperation(offset) - comp; } /** @} */ /** * @name Creation of a PackagedOperation object */ /** @{ */ namespace internal { namespace PackagedOperationImplementation { // Poor man's trait class that determines whether type T is a vector: // FIXME: Implement this as a proper type trait - similar to // isBlockVector template class has_vector_interface { template static std::false_type test(...); template static std::true_type test(decltype(&C::operator+=), decltype(&C::operator-=), decltype(&C::l2_norm)); public: // type is std::true_type if Matrix provides vmult_add and Tvmult_add, // otherwise it is std::false_type using type = decltype(test(nullptr, nullptr, nullptr)); }; // namespace } // namespace PackagedOperationImplementation } // namespace internal /** * @relatesalso PackagedOperation * * Create a PackagedOperation object that stores the addition of two vectors. * * The PackagedOperation object that is created stores a reference to @p u and * @p v. Thus, the vectors must remain valid references for the whole lifetime * of the PackagedOperation object. All changes made on @p u or @p v after the * creation of the PackagedOperation object are reflected by the operator * object. * * @ingroup LAOperators */ template < typename Range, typename = std::enable_if_t::type::value>> PackagedOperation operator+(const Range &u, const Range &v) { PackagedOperation return_comp; // ensure to have valid PackagedOperation objects by catching op by value // u is caught by reference return_comp.reinit_vector = [&u](Range &x, bool omit_zeroing_entries) { x.reinit(u, omit_zeroing_entries); }; return_comp.apply = [&u, &v](Range &x) { x = u; x += v; }; return_comp.apply_add = [&u, &v](Range &x) { x += u; x += v; }; return return_comp; } /** * @relatesalso PackagedOperation * * Create a PackagedOperation object that stores the subtraction of two * vectors. * * The PackagedOperation object that is created stores a reference to @p u and * @p v. Thus, the vectors must remain valid references for the whole lifetime * of the PackagedOperation object. All changes made on @p u or @p v after the * creation of the PackagedOperation object are reflected by the operator * object. * * @ingroup LAOperators */ template < typename Range, typename = std::enable_if_t::type::value>> PackagedOperation operator-(const Range &u, const Range &v) { PackagedOperation return_comp; // ensure to have valid PackagedOperation objects by catching op by value // u is caught by reference return_comp.reinit_vector = [&u](Range &x, bool omit_zeroing_entries) { x.reinit(u, omit_zeroing_entries); }; return_comp.apply = [&u, &v](Range &x) { x = u; x -= v; }; return_comp.apply_add = [&u, &v](Range &x) { x += u; x -= v; }; return return_comp; } /** * @relatesalso PackagedOperation * * Create a PackagedOperation object that stores the scaling of a vector with * a @p number. * * The PackagedOperation object that is created stores a reference to @p u. * Thus, the vectors must remain valid references for the whole lifetime of * the PackagedOperation object. All changes made on @p u or @p v after the * creation of the PackagedOperation object are reflected by the operator * object. * * @ingroup LAOperators */ template < typename Range, typename = std::enable_if_t::type::value>> PackagedOperation operator*(const Range &u, typename Range::value_type number) { return PackagedOperation(u) * number; } /** * @relatesalso PackagedOperation * * Create a PackagedOperation object that stores the scaling of a vector with * a @p number. * * The PackagedOperation object that is created stores a reference to @p u. * Thus, the vectors must remain valid references for the whole lifetime of * the PackagedOperation object. All changes made on @p u or @p v after the * creation of the PackagedOperation object are reflected by the operator * object. * * @ingroup LAOperators */ template < typename Range, typename = std::enable_if_t::type::value>> PackagedOperation operator*(typename Range::value_type number, const Range &u) { return number * PackagedOperation(u); } /** * @relatesalso PackagedOperation * * Create a PackagedOperation object from a LinearOperator and a reference to * a vector @p u of the Domain space. The object stores the PackagedOperation * $\text{op} \,u$ (in matrix notation). return * (return_add) are implemented with vmult(__1,u) * (vmult_add(__1,u)). * * The PackagedOperation object that is created stores a reference to @p u. * Thus, the vector must remain a valid reference for the whole lifetime of * the PackagedOperation object. All changes made on @p u after the creation * of the PackagedOperation object are reflected by the operator object. * * @ingroup LAOperators */ template PackagedOperation operator*(const LinearOperator &op, const Domain &u) { PackagedOperation return_comp; return_comp.reinit_vector = op.reinit_range_vector; // ensure to have valid PackagedOperation objects by catching op by value // u is caught by reference return_comp.apply = [op, &u](Range &v) { op.vmult(v, u); }; return_comp.apply_add = [op, &u](Range &v) { op.vmult_add(v, u); }; return return_comp; } /** * @relatesalso PackagedOperation * * Create a PackagedOperation object from a LinearOperator and a reference to * a vector @p u of the Range space. The object stores the PackagedOperation * $\text{op}^T \,u$ (in matrix notation). return * (return_add) are implemented with Tvmult(__1,u) * (Tvmult_add(__1,u)). * * The PackagedOperation object that is created stores a reference to @p u. * Thus, the vector must remain a valid reference for the whole lifetime of * the PackagedOperation object. All changes made on @p u after the creation * of the PackagedOperation object are reflected by the operator object. * * @ingroup LAOperators */ template PackagedOperation operator*(const Range &u, const LinearOperator &op) { PackagedOperation return_comp; return_comp.reinit_vector = op.reinit_domain_vector; // ensure to have valid PackagedOperation objects by catching op by value // u is caught by reference return_comp.apply = [op, &u](Domain &v) { op.Tvmult(v, u); }; return_comp.apply_add = [op, &u](Domain &v) { op.Tvmult_add(v, u); }; return return_comp; } /** * @relatesalso PackagedOperation * * Composition of a PackagedOperation object with a LinearOperator. The object * stores the computation $\text{op} \,comp$ (in matrix notation). * * @ingroup LAOperators */ template PackagedOperation operator*(const LinearOperator &op, const PackagedOperation &comp) { PackagedOperation return_comp; return_comp.reinit_vector = op.reinit_range_vector; // ensure to have valid PackagedOperation objects by catching op by value // u is caught by reference return_comp.apply = [op, comp](Domain &v) { GrowingVectorMemory vector_memory; typename VectorMemory::Pointer i(vector_memory); op.reinit_domain_vector(*i, /*bool omit_zeroing_entries =*/true); comp.apply(*i); op.vmult(v, *i); }; return_comp.apply_add = [op, comp](Domain &v) { GrowingVectorMemory vector_memory; typename VectorMemory::Pointer i(vector_memory); op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true); comp.apply(*i); op.vmult_add(v, *i); }; return return_comp; } /** * @relatesalso PackagedOperation * * Composition of a PackagedOperation object with a LinearOperator. The object * stores the computation $\text{op}^T \,comp$ (in matrix notation). * * @ingroup LAOperators */ template PackagedOperation operator*(const PackagedOperation &comp, const LinearOperator &op) { PackagedOperation return_comp; return_comp.reinit_vector = op.reinit_domain_vector; // ensure to have valid PackagedOperation objects by catching op by value // u is caught by reference return_comp.apply = [op, comp](Domain &v) { GrowingVectorMemory vector_memory; typename VectorMemory::Pointer i(vector_memory); op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true); comp.apply(*i); op.Tvmult(v, *i); }; return_comp.apply_add = [op, comp](Domain &v) { GrowingVectorMemory vector_memory; typename VectorMemory::Pointer i(vector_memory); op.reinit_range_vector(*i, /*bool omit_zeroing_entries =*/true); comp.apply(*i); op.Tvmult_add(v, *i); }; return return_comp; } /** @} */ DEAL_II_NAMESPACE_CLOSE #endif