From 1e8566982acab9d48d7585833f4e70d63e11e001 Mon Sep 17 00:00:00 2001 From: Guido Kanschat Date: Wed, 5 Aug 2009 21:21:49 +0000 Subject: [PATCH] more on relaxation methods git-svn-id: https://svn.dealii.org/trunk@19185 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/doxygen/headers/preconditioners.h | 54 +++++++++++++++++-- deal.II/lac/include/lac/precondition.h | 22 +++++++- 2 files changed, 72 insertions(+), 4 deletions(-) diff --git a/deal.II/doc/doxygen/headers/preconditioners.h b/deal.II/doc/doxygen/headers/preconditioners.h index 78f2617fe0..e9fd29d0ff 100644 --- a/deal.II/doc/doxygen/headers/preconditioners.h +++ b/deal.II/doc/doxygen/headers/preconditioners.h @@ -20,12 +20,60 @@ * library also supports more complex ones such as Vanka or incomplete LU * decompositions (ILU). In addition, sparse direct solvers can be used as * preconditioners when available. - * - * In order to be used by deal.II solvers, preconditioners must - * conform to the standard matrix interface. Solvers use the function + * + * When talking of preconditioners, we usually expect them to be used + * in Krylov-space methods. Nevertheless, the concept becomes clearer + * in the standard linear defect correction + * @f[ + * x^{k+1} = x^k - P^{-1} \bigl(A x^k - b\bigr), + * @f] + * where P-1 is the preconditioner. Thus, + * preconditioning amounts to applying a linear operator to the + * residual. For this reason, the interface of preconditioners equals + * the one for matrices. + * + *

The interface

+ * + * In this section, we discuss the interface preconditioners usually + * have to provide to work inside the deal.II library. + * + *

Initialization

+ * + * In order to be able to be stored in containers, all preconditioners + * have a constructor with no arguments. Since this will typically + * produce a useless object, all preconditioners have a function + * @code + * void initialize (...) + * @endcode + * + * This function receives the matrix to be preconditioned as well as + * additional required parameters and sets up the internal structures + * of the preconditioner. + * + *

Application of the preconditioner

+ * + * Preconditioners in deal.II are just considered linear operators. + * Therefore, in order to be used by deal.II solvers, preconditioners must + * conform to the standard matrix interface, namely the functions + * @code + * void vmult (VECTOR& dst, const VECTOR& src) const; + * void Tvmult (VECTOR& dst, const VECTOR& src) const; + * @endcode + * Solvers use the function * vmult() of the preconditioner. Some solvers may also use * Tvmult(). * + *

Relaxation methods

+ * + * Additional to the interface described below, some preconditioners + * like SOR and Jacobi have benn known as iterative methods + * themselves. For them, an additional interface exists, consisting of + * the functions + * @code + * void step (VECTOR& dst, const VECTOR& src) const; + * void Tstep (VECTOR& dst, const VECTOR& src) const; + * @endcode + * * @ingroup LAC * @ingroup Matrices */ diff --git a/deal.II/lac/include/lac/precondition.h b/deal.II/lac/include/lac/precondition.h index c0f0f371ae..bcab1dc28b 100644 --- a/deal.II/lac/include/lac/precondition.h +++ b/deal.II/lac/include/lac/precondition.h @@ -402,7 +402,27 @@ class PreconditionJacobi : public PreconditionRelaxation /** - * SOR preconditioner using matrix built-in function. The MATRIX + * SOR preconditioner using matrix built-in function. + * + * Assuming the matrix A = D + L + U is split into its diagonal + * D as well as the strict lower and upper triangles L + * and U, then the SOR preconditioner with relaxation parameter + * r is + * @f[ + * P^{-1} = r (D+rL)^{-1}. + * @f] + * It is this operator P-1, which is implemented by + * vmult() through forward substitution. Analogously, Tvmult() + * implements the operation of r(D+rU)-1. + * + * The SOR iteration itself can be directly written as + * @f[ + * x^{k+1} = x^k - r D^{-1} \bigl(L x^{k+1} + U x^k - b\bigr). + * @f] + * Using the right hand side b and the previous iterate + * x, this is the operation implemented by step(). + * + * The MATRIX * class used is required to have functions * precondition_SOR(VECTOR&, const VECTOR&, double) and * precondition_TSOR(VECTOR&, const VECTOR&, double). -- 2.39.5