From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 5 May 2020 21:39:56 +0000 (-0600)
Subject: Clarify what this class actually computes.
X-Git-Tag: v9.2.0-rc1~114^2~1
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1b1625f200e391ace869201103c040754b2855e8;p=dealii.git

Clarify what this class actually computes.
---

diff --git a/include/deal.II/numerics/error_estimator.h b/include/deal.II/numerics/error_estimator.h
index 786be94d54..dfe0c61d0e 100644
--- a/include/deal.II/numerics/error_estimator.h
+++ b/include/deal.II/numerics/error_estimator.h
@@ -87,11 +87,21 @@ namespace hp
  *   \eta_K^2
  *   =
  *   \sum_{F\in\partial K}
- *     c_F \int_{\partial K_F} \left[a \frac{\partial u_h}{\partial n}\right]^2
+ *     c_F \int_{\partial K_F} \jump{a \frac{\partial u_h}{\partial n}}^2
  * @f]
- * be the error estimator for
- * cell $K$. $[\cdot]$ denotes the jump of the argument at the face. In the
- * paper of Ainsworth $ c_F=\frac {h_K}{24} $, but this factor is a bit
+ * be the error estimator for cell $K$. $\jump{\cdot}$ denotes the jump of the
+ * function in square brackets at the face, and $c_F$ is a factor discussed
+ * below. This is the general form of the interface terms of the error
+ * estimator derived by Kelly et al. in the paper referenced above. The overall
+ * error estimate is then computed as
+ * @f[
+ *   \eta^2 = \sum_K \eta_K^2
+ * @f]
+ * so that $\eta \approx \|\nabla (u-u_h)\|$ for the Laplace equation. The
+ * functions of this class compute a vector of values that corresponds to
+ * $\eta_K$ (i.e., the square root of the quantity above).
+ *
+ * In the paper of Ainsworth $ c_F=\frac {h_K}{24} $, but this factor is a bit
  * esoteric, stemming from interpolation estimates and stability constants which
  * may hold for the Poisson problem, but may not hold for more general
  * situations. Alternatively, we consider the case when $c_F=\frac {h_F}{2p_F}$,