Added a subsection about mapping higher-order derivatives in Mapping documentation

diff --git a/doc/news/changes.h b/doc/news/changes.h
index c57b6101cbd5b5e2a549488bfa1a15c2e45dc13a..64c86b4ec821e7815a2330c4cb7c506d11d94863 100644 (file)
--- a/doc/news/changes.h
+++ b/doc/news/changes.h
@@ -278,6 +278,12 @@ inconvenience this causes.
   (Timo Heister, Lei Qiao, 2015/09/09)
   </li>
 
+  <li>New: Introduced third-order derivatives of the shape functions, which
+  can now be accessed through FEValues and FEValuesViews using similar interfaces
+  as shape_values, shape_derivatives and shape_hessians.
+  (Maien Hamed, 2015/09/08)
+  </li>
+
   <li>Cleanup: TableIndices<N> can now be used (constructed and accessed)
   with N > 7.
   <br>

diff --git a/include/deal.II/fe/fe_poly.h b/include/deal.II/fe/fe_poly.h
index 0b03e783df6d4d5ca22e2b8ed056460808eebbf6..79331d4e851b89e134d88309f456a75303a84619 100644 (file)
--- a/include/deal.II/fe/fe_poly.h
+++ b/include/deal.II/fe/fe_poly.h
@@ -445,12 +445,18 @@ protected:
    * to the Jacobian pushed forward gradient and second derivative.
    *
    * Before the correction, the third derivatives would be given by
+   * @f[
    * D_{ijkl} = \frac{d^3\phi_i}{d \hat x_J d \hat x_K d \hat x_L} (J_{jJ})^{-1} (J_{kK})^{-1} (J_{lL})^{-1},
-   * where J_{iI}=\frac{d x_i}{d \hat x_I}. After the correction, the correct
+   * @f]
+   * where $J_{iI}=\frac{d x_i}{d \hat x_I}$. After the correction, the correct
    * third derivative would be given by
-   * \frac{d^3\phi_i}{d x_j d x_k d x_l} = D_{ijkl} - H_{mjl} \frac{d^2 \phi_i}{d x_k d x_m}  - H_{mkl} \frac{d^2 \phi_i}{d x_j d x_m} - H_{mjk} \frac{d^2 \phi_i}{d x_l d x_m} - K_{mjkl} \frac{d \phi_i}{d x_m},
-   * where H_{ijk} = \frac{d^2 x_i}{d \hat x_J d \hat x_K} (J_{jJ})^{-1} (J_{kK})^{-1},
-   * and K_{ijkl} = \frac{d^3 x_i}{d \hat x_J d \hat x_K d \hat x_L} (J_{jJ})^{-1} (J_{kK})^{-1} (J_{lL})^{-1}
+   * @f[
+   * \frac{d^3\phi_i}{d x_j d x_k d x_l} = D_{ijkl} - H_{mjl} \frac{d^2 \phi_i}{d x_k d x_m}
+   * - H_{mkl} \frac{d^2 \phi_i}{d x_j d x_m} - H_{mjk} \frac{d^2 \phi_i}{d x_l d x_m}
+   * - K_{mjkl} \frac{d \phi_i}{d x_m},
+   * @f]
+   * where $H_{ijk}$ is the Jacobian pushed-forward derivative and $K_{ijkl}$ is
+   * the Jacobian pushed-forward second derivative.
    */
   void
   correct_third_derivatives (internal::FEValues::FiniteElementRelatedData<dim,spacedim>       &output_data,

diff --git a/include/deal.II/fe/mapping.h b/include/deal.II/fe/mapping.h
index 18b33925cc1f6d3950bda4313421447c46871dcc..1d178f9bf66ff13960678cba656116ef19939cd1 100644 (file)
--- a/include/deal.II/fe/mapping.h
+++ b/include/deal.II/fe/mapping.h
@@ -215,6 +215,48 @@ enum MappingType
  * transformed is specified by their MappingType argument. See the documentation there
  * for possible choices.
  *
+ * <h4>Derivatives of the mapping</h4>
+ *
+ * Some applications require the derivatives of the mapping, of which the first order
+ * derivative is the mapping Jacobian, $J_{iJ}(\hat{\mathbf  x})=\frac{\partial x_i}{\partial \hat x_J}$,
+ * described above. Higher order derivatives of the mapping are similarly
+ * defined, for example the Jacobian derivative,
+ * $\hat H_{iJK}(\hat{\mathbf  x}) = \frac{\partial^2 x_i}{\partial \hat x_J \partial \hat x_K}$,
+ * and the Jacobian second derivative,
+ * $\hat K_{iJKL}(\hat{\mathbf  x}) = \frac{\partial^3 x_i}{\partial \hat x_J \partial
+ * \hat x_K \partial \hat x_L}$.
+ * It is also useful to define the "pushed-forward" versions of the higher order derivatives:
+ * the Jacobian pushed-forward
+ * derivative, $H_{ijk}(\hat{\mathbf  x}) = \frac{\partial^2 x_i}{\partial \hat x_J \partial
+ * \hat x_K}(J_{jJ})^{-1}(J_{kK})^{-1}$,
+ * and the Jacobian pushed-forward second derivative,
+ * $K_{ijkl}(\hat{\mathbf  x}) = \frac{\partial^3 x_i}{\partial \hat x_J \partial \hat x_K \partial
+ * \hat x_L}(J_{jJ})^{-1}(J_{kK})^{-1}(J_{lL})^{-1}$.
+ * These pushed-forward versions can be used to compute the higher order derivatives of functions
+ * defined on the reference cell with respect to the
+ * real cell coordinates. for instance, the Jacobian derivative with respect to the real cell coordinates is
+ * given by:
+ *
+ * @f[
+ * \frac{\partial}{\partial x_j}\left[J_{iJ}(\hat{\mathbf  x})\right] =
+ * H_{ikn}(\hat{\mathbf  x})J_{nJ}(\hat{\mathbf  x}),
+ * @f]
+ * and the derivative of the Jacobian inverse with respect to the real cell coordinates is similarly given by:
+ * @f[
+ * \frac{\partial}{\partial x_j}\left[\left(J_{iJ}(\hat{\mathbf  x})\right)^{-1}\right]
+ * = -H_{nik}(\hat{\mathbf  x})\left(J_{nJ}(\hat{\mathbf  x})\right)^{-1}.
+ * @f]
+ *
+ * In a similar fashion, higher order derivatives, with respect to the real cell coordinates, of functions
+ *  defined on the reference cell can
+ * be defined using the Jacobian pushed-forward higher-order derivatives.
+ * For example, the derivative, with respect to the real cell coordinates, of the Jacobian pushed-forward
+ * derivative is given by:
+ *
+ * @f[
+ * \frac{\partial}{\partial x_l}\left[H_{ijk}(\hat{\mathbf  x})\right] = K_{ijkl}(\hat{\mathbf  x})
+ * -H_{mjl}(\hat{\mathbf  x})H_{imk}(\hat{\mathbf  x})-H_{mkl}(\hat{\mathbf  x})H_{imk}(\hat{\mathbf  x}).
+ * @f]
  *
  * <h3>References</h3>
  *