From: Guido Kanschat <dr.guido.kanschat@gmail.com>
Date: Wed, 5 Aug 2009 21:21:49 +0000 (+0000)
Subject: more on relaxation methods
X-Git-Tag: v8.0.0~7382
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1e8566982acab9d48d7585833f4e70d63e11e001;p=dealii.git

more on relaxation methods

git-svn-id: https://svn.dealii.org/trunk@19185 0785d39b-7218-0410-832d-ea1e28bc413d
---

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 <i>P<sup>-1</sup></i> 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.
+ *
+ * <h3>The interface</h3>
+ *
+ * In this section, we discuss the interface preconditioners usually
+ * have to provide to work inside the deal.II library.
+ *
+ * <h4>Initialization</h4>
+ *
+ * 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.
+ *
+ * <h4>Application of the preconditioner</h4>
+ *
+ * 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
  * <tt>vmult()</tt> of the preconditioner. Some solvers may also use
  * <tt>Tvmult()</tt>.
  *
+ * <h4>Relaxation methods</h4>
+ *
+ * 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<MATRIX>
 
 
 /**
- * SOR preconditioner using matrix built-in function.  The MATRIX
+ * SOR preconditioner using matrix built-in function.
+ *
+ * Assuming the matrix <i>A = D + L + U</i> is split into its diagonal
+ * <i>D</i> as well as the strict lower and upper triangles <i>L</i>
+ * and <i>U</i>, then the SOR preconditioner with relaxation parameter
+ * <i>r</i> is
+ * @f[
+ *  P^{-1} = r (D+rL)^{-1}.
+ * @f]
+ * It is this operator <i>P<sup>-1</sup></i>, which is implemented by
+ * vmult() through forward substitution. Analogously, Tvmult()
+ * implements the operation of <i>r(D+rU)<sup>-1</sup></i>.
+ *
+ * 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 <i>b</i> and the previous iterate
+ * <i>x</i>, this is the operation implemented by step().
+ *
+ * The MATRIX
  * class used is required to have functions
  * <tt>precondition_SOR(VECTOR&, const VECTOR&, double)</tt> and
  * <tt>precondition_TSOR(VECTOR&, const VECTOR&, double)</tt>.