From: Peter Munch <peterrmuench@gmail.com>
Date: Sat, 18 May 2024 10:55:25 +0000 (+0200)
Subject: Extend documentation of PreconditionRelaxation
X-Git-Tag: v9.6.0-rc1~260^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2cc6e4dea832569d9bfac922f284b3b409ab4137;p=dealii.git

Extend documentation of PreconditionRelaxation
---

diff --git a/doc/doxygen/references.bib b/doc/doxygen/references.bib
index 85c081c077..3194268c9d 100644
--- a/doc/doxygen/references.bib
+++ b/doc/doxygen/references.bib
@@ -2470,3 +2470,12 @@
   pages = {102940}
 }
 
+@book{Varga2009,
+   title     = {Matrix iterative analysis},
+   author    = {Varga, R. S.},
+   publisher = {Springer},
+   address   = {Berlin},
+   edition   = {2nd},
+   year      = {2009},
+}
+
diff --git a/include/deal.II/lac/precondition.h b/include/deal.II/lac/precondition.h
index aba0884a7a..7c6ae362ac 100644
--- a/include/deal.II/lac/precondition.h
+++ b/include/deal.II/lac/precondition.h
@@ -537,16 +537,29 @@ private:
  * Jacobi, SOR and SSOR preconditioners are implemented. For preconditioning,
  * refer to derived classes.
  *
- * The relaxation parameter can be set manually or can be automatically
- * determined by:
+ * One iteration is given as:
+ * @f[
+ *  x^{n+1} = x^{n} + \alpha P^{-1} (b-Ax^n).
+ * @f]
+ *
+ * The relaxation parameter $\alpha$ has to be in the range:
+ * @f[
+ *  0 < \alpha < \frac{2}{\lambda_{\max}(P^{-1}A)}.
+ * @f]
+ * Its theoretically optimal value is given by:
  * @f[
- *    \alpha^n_1 := \frac{2}{\lambda_{\max}+\lambda_{\min}}.
+ *    \alpha := \frac{2}{\lambda_{\min}(P^{-1}A)+\lambda_{\max}(P^{-1}A)}.
  * @f]
- * For this purpose, the user needs to set the relaxation parameter to zero.
- * Internally, the minimum and maximum eigenvalues of the preconditioned
- * system are estimated by an eigenvalue algorithm, and the resulting estimate
- * is multiplied by the 1.2 for safety reasons. For more details on the
- * underlying algorithms, see PreconditionChebyshev.
+ *
+ * For details on the algorithm, see @cite Varga2009.
+ *
+ * The relaxation parameter can be set manually or can be automatically
+ * determined, for which we use the theoretically optimal value.
+ * For this purpose, the user needs to set the relaxation parameter
+ * to zero. Internally, the minimum and maximum eigenvalues of the
+ * preconditioned system are estimated by an eigenvalue algorithm, and the
+ * resulting estimate is multiplied by the 1.2 for safety reasons. For more
+ * details on the underlying algorithms, see PreconditionChebyshev.
  */
 template <typename MatrixType         = SparseMatrix<double>,
           typename PreconditionerType = IdentityMatrix>
@@ -1998,7 +2011,7 @@ public:
  * 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).
+ * can be used to determine the number of iteration, see @cite Varga2009.
  *
  * In order to use Chebyshev as a solver, set the degree to
  * numbers::invalid_unsigned_int to force the automatic computation of the
@@ -2009,17 +2022,7 @@ public:
  * 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
- * @code{.bib}
- * @book{Varga2009,
- *   Title     = {Matrix iterative analysis},
- *   Author    = {Varga, R. S.},
- *   Publisher = {Springer},
- *   Address   = {Berlin},
- *   Edition   = {2nd},
- *   Year      = {2009},
- * }
- * @endcode
+ * For details on the algorithm, see section 5.1 of @cite Varga2009.
  *
  * <h4>Requirements on the templated classes</h4>
  *