#include <deal.II/lac/precondition.h>

Inheritance diagram for PreconditionChebyshev< MatrixType, VectorType, PreconditionerType >:

Classes
struct	AdditionalData

Public Types
using	size_type = types::global_dof_index

Public Member Functions
void	initialize (const MatrixType &matrix, const AdditionalData &additional_data=AdditionalData())

void	vmult (VectorType &dst, const VectorType &src) const

void	Tvmult (VectorType &dst, const VectorType &src) const

void	step (VectorType &dst, const VectorType &src) const

void	Tstep (VectorType &dst, const VectorType &src) const

void	clear ()

size_type	m () const

size_type	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	subscribe (const char *identifier=nullptr) const

void	unsubscribe (const char *identifier=nullptr) const

unsigned int	n_subscriptions () const

template<typename StreamType >
void	list_subscribers (StreamType &stream) const

void	list_subscribers () const

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)

Private Member Functions
void	do_chebyshev_loop (VectorType &dst, const VectorType &src) const

void	do_transpose_chebyshev_loop (VectorType &dst, const VectorType &src) const

void	estimate_eigenvalues (const VectorType &src) const

Private Attributes
SmartPointer< const MatrixType, PreconditionChebyshev< MatrixType, VectorType, PreconditionerType > >	matrix_ptr

VectorType	update1

VectorType	update2

VectorType	update3

AdditionalData	data

double	theta

double	delta

bool	eigenvalues_are_initialized

Threads::Mutex	mutex

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 MatrixType = SparseMatrix<double>, typename VectorType = Vector<double>, typename PreconditionerType = DiagonalMatrix<VectorType>>
class PreconditionChebyshev< MatrixType, VectorType, PreconditionerType >

Preconditioning with a Chebyshev polynomial for symmetric positive definite matrices. This preconditioner is based on an iteration of an inner preconditioner of type PreconditionerType with coefficients that are adapted to optimally cover an eigenvalue range between the largest eigenvalue down to a given lower eigenvalue specified by the optional parameter smoothing_range. The typical use case for the preconditioner is a Jacobi preconditioner specified through DiagonalMatrix, which is also the default value for the preconditioner. Note that if the degree variable is set to zero, the Chebyshev iteration corresponds to a Jacobi preconditioner (or the underlying preconditioner type) with relaxation parameter according to the specified smoothing range.

Besides the default choice of a pointwise Jacobi preconditioner, this class also allows for more advanced types of preconditioners, for example iterating block-Jacobi preconditioners in DG methods.

Apart from the inner preconditioner object, this iteration does not need access to matrix entries, which makes it an ideal ingredient for matrix-free computations. In that context, this class can be used as a multigrid smoother that is trivially parallel (assuming that matrix-vector products are parallel and the inner preconditioner is parallel). Its use is demonstrated in the step-37 tutorial program.

Algorithm execution

The Chebyshev method relies on an estimate of the eigenvalues of the matrix which are computed during the first invocation of vmult(). The algorithm invokes a conjugate gradient solver so symmetry and positive definiteness of the (preconditioned) matrix system are strong requirements. The computation of eigenvalues needs to be deferred until the first vmult() invocation because temporary vectors of the same layout as the source and destination vectors are necessary for these computations and this information gets only available through vmult().

The estimation of eigenvalues can also be bypassed by setting PreconditionChebyshev::AdditionalData::eig_cg_n_iterations to zero and providing sensible values for the largest eigenvalues in the field PreconditionChebyshev::AdditionalData::max_eigenvalue. If the range [max_eigenvalue/smoothing_range, max_eigenvalue] contains all eigenvalues of the preconditioned matrix system and the degree (i.e., number of iterations) is high enough, this class can also be used as a direct solver. For an error estimation of the Chebyshev iteration that can be used to determine the number of iteration, see Varga (2009).

In order to use Chebyshev as a solver, set the degree to numbers::invalid_unsigned_int to force the automatic computation of the number of iterations needed to reach a given target tolerance. In this case, the target tolerance is read from the variable PreconditionChebyshev::AdditionalData::smoothing_range (it needs to be a number less than one to force any iterations obviously).

For details on the algorithm, see section 5.1 of

 @book{Varga2009,
   Title     = {Matrix iterative analysis},
   Author    = {Varga, R. S.},
   Publisher = {Springer},
   Address   = {Berlin},
   Edition   = {2nd},
   Year      = {2009},
 }

Requirements on the templated classes

The class MatrixType must be derived from Subscriptor because a SmartPointer to MatrixType is held in the class. In particular, this means that the matrix object needs to persist during the lifetime of PreconditionChebyshev. The preconditioner is held in a shared_ptr that is copied into the AdditionalData member variable of the class, so the variable used for initialization can safely be discarded after calling initialize(). Both the matrix and the preconditioner need to provide vmult functions for the matrix-vector product and m functions for accessing the number of rows in the (square) matrix. Furthermore, the matrix must provide el(i,i) methods for accessing the matrix diagonal in case the preconditioner type is a diagonal matrix. Even though it is highly recommended to pass the inverse diagonal entries inside a separate preconditioner object for implementing the Jacobi method (which is the only possible way to operate this class when computing in parallel with MPI because there is no knowledge about the locally stored range of entries that would be needed from the matrix alone), there is a backward compatibility function that can extract the diagonal in case of a serial computation.

Author: Martin Kronbichler, 2009, 2016; extension for full compatibility with LinearOperator class: Jean-Paul Pelteret, 2015

Definition at line 959 of file precondition.h.