From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Sun, 2 Aug 2015 21:18:07 +0000 (-0500)
Subject: Update documentation.
X-Git-Tag: v8.4.0-rc2~692^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F1235%2Fhead;p=dealii.git

Update documentation.
---

diff --git a/include/deal.II/base/derivative_form.h b/include/deal.II/base/derivative_form.h
index b74fa9eb76..bf79b842f0 100644
--- a/include/deal.II/base/derivative_form.h
+++ b/include/deal.II/base/derivative_form.h
@@ -24,13 +24,33 @@ DEAL_II_NAMESPACE_OPEN
  * This class represents the (tangential) derivatives of a function $ f:
  * {\mathbb R}^{\text{dim}} \rightarrow {\mathbb R}^{\text{spacedim}}$. Such
  * functions are always used to map the reference dim-dimensional cell into
- * spacedim-dimensional space. For such objects, the first  derivative of the
- * function is a linear map from ${\mathbb R}^{\text{dim}}$  to ${\mathbb
- * R}^{\text{spacedim}}$, the second derivative a bilinear map from  ${\mathbb
+ * spacedim-dimensional space. For such objects, the first derivative of the
+ * function is a linear map from ${\mathbb R}^{\text{dim}}$ to ${\mathbb
+ * R}^{\text{spacedim}}$, i.e., it can be represented as a matrix
+ * in ${\mathbb R}^{\text{spacedim}\times \text{dim}}. This makes sense
+ * since one would represent the first derivative, $\nabla f(\mathbf x)$
+ * with $\mathbf x\in {\mathbb R}^{\text{dim}}$, in such a way that the
+ * directional derivative in direction $\mathbf d\in {\mathbb R}^{\text{dim}}$
+ * so that
+ * @f{align*}
+ *   \nabla f(\mathbf x) \mathbf d
+ *   = \lim_{\varepsilon\rightarrow 0}
+ *     \frac{f(\mathbf x + \varepsilon \mathbf d) - f(\mathbf x)}{\varepsilon},
+ * @f}
+ * i.e., one needs to be able to multiply the matrix $\nabla f(\mathbf x)$ by
+ * a vector in ${\mathbb R}^{\text{dim}}$, and the result is a difference
+ * of function values, which are in ${\mathbb R}^{\text{spacedim}}. Consequently,
+ * the matrix must be of size $\text{spacedim}\times\text{dim}$.
+ *
+ * Similarly, the second derivative is a bilinear map from  ${\mathbb
  * R}^{\text{dim}} \times  {\mathbb R}^{\text{dim}}$ to ${\mathbb
- * R}^{\text{spacedim}}$ and so on.  In deal.II we represent these derivatives
- * using objects of type DerivativeForm<1,dim,spacedim,Number>,
- * DerivativeForm<2,dim,spacedim,Number> and so on.
+ * R}^{\text{spacedim}}$, which one can think of a rank-3 object of size
+ * $\text{spacedim}\times\text{dim}\times\text{dim}$.
+ *
+ * In deal.II we represent these derivatives
+ * using objects of type DerivativeForm@<1,dim,spacedim,Number@>,
+ * DerivativeForm@<2,dim,spacedim,Number@> and so on.
+ *
  * @author Sebastian Pauletti, 2011, Luca Heltai, 2015
  */
 template <int order, int dim, int spacedim, typename Number=double>