#include <linear_operator_for_mg.h>

Inheritance diagram for LinearOperatorMG< Range, Domain, Payload >:

Public Member Functions
	LinearOperatorMG (const Payload &payload=Payload())

	LinearOperatorMG (const LinearOperatorMG< Range, Domain, Payload > &)=default

template<typename Op , typename = std::enable_if_t< !std::is_base_of_v<LinearOperatorMG<Range, Domain, Payload>, Op>>>
	LinearOperatorMG (const Op &op)

LinearOperatorMG< Range, Domain, Payload > &	operator= (const LinearOperatorMG< Range, Domain, Payload > &)=default

template<typename Op , typename = std::enable_if_t< !std::is_base_of_v<LinearOperatorMG<Range, Domain, Payload>, Op>>>
LinearOperatorMG< Range, Domain, Payload > &	operator= (const Op &op)

types::global_dof_index	m () const

types::global_dof_index	n () const

Public Member Functions inherited from Subscriptor
	Subscriptor ()

	Subscriptor (const Subscriptor &)

	Subscriptor (Subscriptor &&) noexcept

virtual	~Subscriptor ()

Subscriptor &	operator= (const Subscriptor &)

Subscriptor &	operator= (Subscriptor &&) noexcept

void	serialize (Archive &ar, const unsigned int version)

void	subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

void	unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

unsigned int	n_subscriptions () const

void	list_subscribers (StreamType &stream) const

void	list_subscribers () const

void	subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

void	unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

unsigned int	n_subscriptions () const

void	list_subscribers (StreamType &stream) const

void	list_subscribers () const

Public Attributes
std::function< void(Range &v, const Domain &u)>	vmult

std::function< void(Range &v, const Domain &u)>	vmult_add

std::function< void(Domain &v, const Range &u)>	Tvmult

std::function< void(Domain &v, const Range &u)>	Tvmult_add

std::function< void(Range &v, bool omit_zeroing_entries)>	reinit_range_vector

std::function< void(Domain &v, bool omit_zeroing_entries)>	reinit_domain_vector

std::function< typename Domain::value_type(const types::global_dof_index i, const types::global_dof_index j)>	el

Related Symbols
(Note that these are not member symbols.)
Vector space operations
template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	operator+ (const LinearOperatorMG< Range, Domain, Payload > &first_op, const LinearOperatorMG< Range, Domain, Payload > &second_op)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	operator- (const LinearOperatorMG< Range, Domain, Payload > &first_op, const LinearOperatorMG< Range, Domain, Payload > &second_op)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	operator* (typename Range::value_type number, const LinearOperatorMG< Range, Domain, Payload > &op)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	operator* (const LinearOperatorMG< Range, Domain, Payload > &op, typename Domain::value_type number)

Composition and manipulation of a LinearOperatorMG
template<typename Range , typename Intermediate , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	operator* (const LinearOperatorMG< Range, Intermediate, Payload > &first_op, const LinearOperatorMG< Intermediate, Domain, Payload > &second_op)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Domain, Range, Payload >	transpose_operator (const LinearOperatorMG< Range, Domain, Payload > &op)

template<typename Payload , typename Solver , typename Preconditioner , typename Range = typename Solver::vector_type, typename Domain = Range>
LinearOperatorMG< Domain, Range, Payload >	inverse_operator (const LinearOperatorMG< Range, Domain, Payload > &op, Solver &solver, const Preconditioner &preconditioner)

template<typename Payload , typename Solver , typename Range = typename Solver::vector_type, typename Domain = Range>
LinearOperatorMG< Domain, Range, Payload >	inverse_operator (const LinearOperatorMG< Range, Domain, Payload > &op, Solver &solver, const LinearOperatorMG< Range, Domain, Payload > &preconditioner)

template<typename Payload , typename Solver , typename Range = typename Solver::vector_type, typename Domain = Range>
LinearOperatorMG< Domain, Range, Payload >	inverse_operator (const LinearOperatorMG< Range, Domain, Payload > &op, Solver &solver)

template<typename Payload , typename Solver , typename Range = typename Solver::vector_type, typename Domain = Range>
LinearOperatorMG< Domain, Range, Payload >	inverse_operator (const LinearOperatorMG< Range, Domain, Payload > &op, Solver &solver, const PreconditionIdentity &)

Creation of a LinearOperatorMG
template<typename Range , typename Payload = internal::LinearOperatorMGImplementation::EmptyPayload>
LinearOperatorMG< Range, Range, Payload >	identity_operator (const std::function< void(Range &, bool)> &reinit_vector)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	identity_operator (const LinearOperatorMG< Range, Domain, Payload > &op)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	null_operator (const LinearOperatorMG< Range, Domain, Payload > &op)

template<typename Range , typename Payload = internal::LinearOperatorMGImplementation::EmptyPayload>
LinearOperatorMG< Range, Range, Payload >	mean_value_filter (const std::function< void(Range &, bool)> &reinit_vector)

template<typename Range , typename Domain , typename Payload >
LinearOperatorMG< Range, Domain, Payload >	mean_value_filter (const LinearOperatorMG< Range, Domain, Payload > &op)

template<typename Range , typename Domain , typename Payload , typename Matrix >
LinearOperatorMG< Range, Domain, Payload >	linear_operator_mg (const Matrix &matrix)

template<typename Range , typename Domain , typename Payload , typename OperatorExemplar , typename Matrix >
LinearOperatorMG< Range, Domain, Payload >	linear_operator_mg (const OperatorExemplar &operator_exemplar, const Matrix &matrix)

template<typename Range , typename Domain , typename Payload , typename Matrix >
LinearOperatorMG< Range, Domain, Payload >	linear_operator_mg (const LinearOperatorMG< Range, Domain, Payload > &operator_exemplar, const Matrix &matrix)

In-place vector space operations
bool	is_null_operator

types::global_dof_index	n_rows

types::global_dof_index	n_cols

LinearOperatorMG< Range, Domain, Payload > &	operator+= (const LinearOperatorMG< Range, Domain, Payload > &second_op)

LinearOperatorMG< Range, Domain, Payload > &	operator-= (const LinearOperatorMG< Range, Domain, Payload > &second_op)

LinearOperatorMG< Range, Domain, Payload > &	operator*= (const LinearOperatorMG< Domain, Domain, Payload > &second_op)

LinearOperatorMG< Range, Domain, Payload >	operator*= (typename Domain::value_type number)

Additional Inherited Members
Static Public Member Functions inherited from Subscriptor
static ::ExceptionBase &	ExcInUse (int arg1, std::string arg2, std::string arg3)

static ::ExceptionBase &	ExcNoSubscriber (std::string arg1, std::string arg2)

Detailed Description

template<typename Range, typename Domain, typename Payload>
class LinearOperatorMG< Range, Domain, Payload >

A class to store the abstract concept of a linear operator.

The class essentially consists of std::function objects that store the knowledge of how to apply the linear operator by implementing the abstract Matrix interface:

std::function<void(Range &, const Domain &)> vmult;
std::function<void(Range &, const Domain &)> vmult_add;
std::function<void(Domain &, const Range &)> Tvmult;
std::function<void(Domain &, const Range &)> Tvmult_add;

But, in contrast to a usual matrix object, the domain and range of the linear operator are also bound to the LinearOperatorMG class on the type level. Because of this, LinearOperatorMG<Range, Domain> has two additional function objects

std::function<void(Range &, bool)> reinit_range_vector;

std::function<void(Domain &, bool)> reinit_domain_vector;

LinearOperatorMG::reinit_range_vector

std::function< void(Range &v, bool omit_zeroing_entries)> reinit_range_vector

Definition linear_operator_for_mg.h:322

LinearOperatorMG::reinit_domain_vector

std::function< void(Domain &v, bool omit_zeroing_entries)> reinit_domain_vector

Definition linear_operator_for_mg.h:332

that store the knowledge how to initialize (resize + internal data structures) an arbitrary vector of the Range and Domain space.

The primary purpose of this class is to provide syntactic sugar for complex matrix-vector operations and free the user from having to create, set up and handle intermediate storage locations by hand.

As an example consider the operation $(A+k\,B)\,C$, where $A$, $B$ and $C$ denote (possible different) matrices. In order to construct a LinearOperatorMG op that stores the knowledge of this operation, one can write:

#include <deal.II/lac/linear_operator_tools.h>
 
dealii::SparseMatrix<double> A, B, C;
const double k = ...;
 
// Setup and assembly of matrices
 
const auto op_a = linear_operator_mg(A);
const auto op_b = linear_operator_mg(B);
const auto op_c = linear_operator_mg(C);
 
const auto op = (op_a + k * op_b) * op_c;

Note: This class makes heavy use of std::function objects and lambda functions. This flexibility comes with a run-time penalty. Only use this object to encapsulate matrix object of medium to large size (as a rule of thumb, sparse matrices with a size $1000\times1000$, or larger).; In order to use Trilinos or PETSc sparse matrices and preconditioners in conjunction with the LinearOperatorMG class, it is necessary to extend the functionality of the LinearOperatorMG class by means of an additional Payload.

For example: LinearOperatorMG instances representing matrix inverses usually require calling some linear solver. These solvers may not have interfaces to the LinearOperatorMG (which, for example, may represent a composite operation). The TrilinosWrappers::internal::LinearOperatorMGImplementation::TrilinosPayload therefore provides an interface extension to the LinearOperatorMG so that it can be passed to the solver and used by the solver as if it were a Trilinos operator. This implies that all of the necessary functionality of the specific Trilinos operator has been overloaded within the Payload class. This includes operator-vector multiplication and inverse operator-vector multiplication, where the operator can be either a TrilinosWrappers::SparseMatrix or a TrilinosWrappers::PreconditionBase and the vector is a native Trilinos vector.

Another case where payloads provide a crucial supplement to the LinearOperatorMG class are when composite operations are constructed (via operator overloading). In this instance, it is again necessary to provide an interface that produces the result of this composite operation that is compatible with Trilinos operator used by Trilinos solvers.

Note: Many use cases of LinearOperatorMG lead to intermediate expressions requiring a PackagedOperation. In order to include all necessary header files in one go consider using
#include <deal.II/lac/linear_operator_tools.h>

In order to use the full LinearOperatorMG and PackagedOperation

Note: To ensure that the correct payload is provided, wrapper functions for linear operators have been provided within the respective TrilinosWrappers (and, in the future, PETScWrappers) namespaces.

Examples of use

The step-20 tutorial program has a detailed usage example of the LinearOperatorMG class.

Instrumenting operations

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:

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);
};

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.

Definition at line 201 of file linear_operator_for_mg.h.

Constructor & Destructor Documentation

◆ LinearOperatorMG() [1/3]

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG ( const Payload & payload = Payload() )

inline

Create an empty LinearOperatorMG object. When a payload is passed to this constructor, the resulting operator is constructed with a functional payload. In either case, this constructor yields an object that can not actually be used for any linear operator operations, and will throw an exception upon invocation.

Definition at line 212 of file linear_operator_for_mg.h.

References Assert, LinearOperatorMG< Range, Domain, Payload >::reinit_domain_vector, LinearOperatorMG< Range, Domain, Payload >::reinit_range_vector, LinearOperatorMG< Range, Domain, Payload >::Tvmult, LinearOperatorMG< Range, Domain, Payload >::Tvmult_add, LinearOperatorMG< Range, Domain, Payload >::vmult, and LinearOperatorMG< Range, Domain, Payload >::vmult_add.

◆ LinearOperatorMG() [2/3]

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG ( const LinearOperatorMG< Range, Domain, Payload > & )

default

Default copy constructor.

◆ LinearOperatorMG() [3/3]

template<typename Range , typename Domain , typename Payload >

template<typename Op , typename = std::enable_if_t< !std::is_base_of_v<LinearOperatorMG<Range, Domain, Payload>, Op>>>

LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG ( const Op & op )

inline

Templated copy constructor that creates a LinearOperatorMG object from an object op for which the conversion function linear_operator_mg is defined.

Definition at line 266 of file linear_operator_for_mg.h.

Member Function Documentation

◆ m()

template<typename Range , typename Domain , typename Payload >

types::global_dof_index LinearOperatorMG< Range, Domain, Payload >::m ( ) const

inline

Return the number of rows of this LinearOperatorMG.

Definition at line 345 of file linear_operator_for_mg.h.

References LinearOperatorMG< Range, Domain, Payload >::n_rows.

◆ n()

template<typename Range , typename Domain , typename Payload >

types::global_dof_index LinearOperatorMG< Range, Domain, Payload >::n ( ) const

inline

Return the number of columns of this LinearOperatorMG.

Definition at line 354 of file linear_operator_for_mg.h.

References LinearOperatorMG< Range, Domain, Payload >::n_cols.

◆ operator*=() [1/2]

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload > & LinearOperatorMG< Range, Domain, Payload >::operator*= ( const LinearOperatorMG< Domain, Domain, Payload > & second_op )

inline

Composition of the LinearOperatorMG with an endomorphism second_op of the Domain space.

Definition at line 391 of file linear_operator_for_mg.h.

◆ operator*=() [2/2]

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload > LinearOperatorMG< Range, Domain, Payload >::operator*= ( typename Domain::value_type number )

inline

Scalar multiplication of the LinearOperatorMG with number from the right.

Definition at line 402 of file linear_operator_for_mg.h.

◆ operator+=()

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload > & LinearOperatorMG< Range, Domain, Payload >::operator+= ( const LinearOperatorMG< Range, Domain, Payload > & second_op )

inline

Addition with a LinearOperatorMG second_op with the same Domain and Range.

Definition at line 369 of file linear_operator_for_mg.h.

◆ operator-=()

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload > & LinearOperatorMG< Range, Domain, Payload >::operator-= ( const LinearOperatorMG< Range, Domain, Payload > & second_op )

inline

Subtraction with a LinearOperatorMG second_op with the same Domain and Range.

Definition at line 380 of file linear_operator_for_mg.h.

◆ operator=() [1/2]

template<typename Range , typename Domain , typename Payload >

LinearOperatorMG< Range, Domain, Payload > & LinearOperatorMG< Range, Domain, Payload >::operator= ( const LinearOperatorMG< Range, Domain, Payload > & )

default

Default copy assignment operator.

◆ operator=() [2/2]

template<typename Range , typename Domain , typename Payload >

template<typename Op , typename = std::enable_if_t< !std::is_base_of_v<LinearOperatorMG<Range, Domain, Payload>, Op>>>

LinearOperatorMG< Range, Domain, Payload > & LinearOperatorMG< Range, Domain, Payload >::operator= ( const Op & op )

inline

Templated copy assignment operator for an object op for which the conversion function linear_operator_mg is defined.

Definition at line 285 of file linear_operator_for_mg.h.

Member Data Documentation

◆ el

template<typename Range , typename Domain , typename Payload >

std::function<typename Domain::value_type(const types::global_dof_index i, const types::global_dof_index j)> LinearOperatorMG< Range, Domain, Payload >::el

Definition at line 339 of file linear_operator_for_mg.h.

◆ is_null_operator

template<typename Range , typename Domain , typename Payload >

bool LinearOperatorMG< Range, Domain, Payload >::is_null_operator

This bool is used to determine whether a linear operator is a null operator. In this case the class is able to optimize some operations like multiplication or addition.

Definition at line 413 of file linear_operator_for_mg.h.

◆ n_cols

template<typename Range , typename Domain , typename Payload >

types::global_dof_index LinearOperatorMG< Range, Domain, Payload >::n_cols

Definition at line 417 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::n().

◆ n_rows

template<typename Range , typename Domain , typename Payload >

types::global_dof_index LinearOperatorMG< Range, Domain, Payload >::n_rows

Definition at line 415 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::m().

◆ reinit_domain_vector

template<typename Range , typename Domain , typename Payload >

std::function<void(Domain &v, bool omit_zeroing_entries)> LinearOperatorMG< Range, Domain, Payload >::reinit_domain_vector

Initializes a vector of the Domain space to be directly usable as the source parameter in an application of vmult. 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.

Definition at line 332 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG().

◆ reinit_range_vector

template<typename Range , typename Domain , typename Payload >

std::function<void(Range &v, bool omit_zeroing_entries)> LinearOperatorMG< Range, Domain, Payload >::reinit_range_vector

Initializes a vector v of the Range space to be directly usable as the destination parameter in an application of vmult. 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.

Definition at line 322 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG().

◆ Tvmult

template<typename Range , typename Domain , typename Payload >

std::function<void(Domain &v, const Range &u)> LinearOperatorMG< Range, Domain, Payload >::Tvmult

Application of the transpose LinearOperatorMG object to a vector u of the Range space giving a vector v of the Domain space.

Definition at line 307 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG(), and internal::LinearOperatorMGImplementation::MatrixInterfaceWithoutVmultAdd< Range, Domain, Payload >::operator()().

◆ Tvmult_add

template<typename Range , typename Domain , typename Payload >

std::function<void(Domain &v, const Range &u)> LinearOperatorMG< Range, Domain, Payload >::Tvmult_add

Application of the transpose LinearOperatorMG object to a vector u of the Range space.The result is added to the vector v.

Definition at line 313 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG(), internal::LinearOperatorMGImplementation::MatrixInterfaceWithoutVmultAdd< Range, Domain, Payload >::operator()(), and internal::LinearOperatorMGImplementation::MatrixInterfaceWithVmultAdd< Range, Domain, Payload >::operator()().

◆ vmult

template<typename Range , typename Domain , typename Payload >

std::function<void(Range &v, const Domain &u)> LinearOperatorMG< Range, Domain, Payload >::vmult

Application of the LinearOperatorMG object to a vector u of the Domain space giving a vector v of the Range space.

Definition at line 295 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG(), and internal::LinearOperatorMGImplementation::MatrixInterfaceWithoutVmultAdd< Range, Domain, Payload >::operator()().

◆ vmult_add

template<typename Range , typename Domain , typename Payload >

std::function<void(Range &v, const Domain &u)> LinearOperatorMG< Range, Domain, Payload >::vmult_add

Application of the LinearOperatorMG object to a vector u of the Domain space. The result is added to the vector v.

Definition at line 301 of file linear_operator_for_mg.h.

Referenced by LinearOperatorMG< Range, Domain, Payload >::LinearOperatorMG(), internal::LinearOperatorMGImplementation::MatrixInterfaceWithoutVmultAdd< Range, Domain, Payload >::operator()(), and internal::LinearOperatorMGImplementation::MatrixInterfaceWithVmultAdd< Range, Domain, Payload >::operator()().

The documentation for this class was generated from the following file:

/github/workspace/include/linear_operator_for_mg.h

Public Member Functions

Public Attributes

Related Symbols

In-place vector space operations

Additional Inherited Members

Detailed Description

Examples of use

Instrumenting operations

Constructor & Destructor Documentation

◆ LinearOperatorMG() [1/3]

◆ LinearOperatorMG() [2/3]

◆ LinearOperatorMG() [3/3]

Member Function Documentation

◆ m()

◆ n()

◆ operator*=() [1/2]

◆ operator*=() [2/2]

◆ operator+=()

◆ operator-=()

◆ operator=() [1/2]

◆ operator=() [2/2]

Member Data Documentation

◆ el

◆ is_null_operator

◆ n_cols

◆ n_rows

◆ reinit_domain_vector

◆ reinit_range_vector

◆ Tvmult

◆ Tvmult_add

◆ vmult

◆ vmult_add