From acd48500b1075fa18ecc8c20de52b57ffa4eba7c Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Sat, 25 Jun 2016 00:11:25 -0500
Subject: [PATCH] Deprecate constructor and replace it by another one.

Also update the documentation in a number of places.
---
 doc/news/changes.h                       |  7 +++++
 include/deal.II/fe/mapping_q1_eulerian.h | 34 ++++++++++++++++--------
 source/fe/mapping_q1_eulerian.cc         | 11 ++++++++
 3 files changed, 41 insertions(+), 11 deletions(-)

diff --git a/doc/news/changes.h b/doc/news/changes.h
index cef4132d1a..f13477b36d 100644
--- a/doc/news/changes.h
+++ b/doc/news/changes.h
@@ -139,6 +139,13 @@ inconvenience this causes.
 <h3>General</h3>
 
 <ol>
+ <li> Changed: As MappingQEulerian before, MappingQ1Eulerian has gained
+ a second constructor that reverts the order of the arguments to indicate
+ which DoFHandler a vector is based on. The old constructor is now
+ deprecated and will be removed in a future version.
+ <br>
+ (Wolfgang Bangerth, 2016/06/25)
+ </li>
 
  <li> New: Add new classes to expand a scalar finite element solution into
  the orthogonal bases FESeries::Fourier and FESeries::Legendre. Also
diff --git a/include/deal.II/fe/mapping_q1_eulerian.h b/include/deal.II/fe/mapping_q1_eulerian.h
index efc3f6a654..69f7302f82 100644
--- a/include/deal.II/fe/mapping_q1_eulerian.h
+++ b/include/deal.II/fe/mapping_q1_eulerian.h
@@ -31,7 +31,9 @@ template <typename> class Vector;
 /*@{*/
 
 /**
- * Eulerian mapping of general unit cells by $d$-linear shape functions. Each
+ * This class provides a mapping that adds to the location of each cell
+ * a $d$-linear displacement field. (The generalization to higher order
+ * polynomials is provided in the MappingQEulerian class.) Each
  * cell is thus shifted in space by values given to the mapping through a
  * finite element field.
  *
@@ -90,19 +92,29 @@ template <int dim, typename VectorType = Vector<double>, int spacedim=dim >
 class MappingQ1Eulerian : public MappingQGeneric<dim,spacedim>
 {
 public:
+  /**
+   * Constructor.
+   *
+   * @param[in] euler_dof_handler A DoFHandler object that defines a finite
+   * element space. This space needs to have exactly dim components
+   * and these will be considered displacements
+   * relative to the original positions of the cells of the triangulation.
+   * This DoFHandler must be based on a <code>FESystem(FE_Q(1),dim)</code>
+   * finite element.
+   * @param[in] euler_vector A finite element function in the space defined by
+   * the first argument. The dim components of this function will be
+   * interpreted as the displacement we use in defining the mapping, relative
+   * to the location of cells of the underlying triangulation.
+   */
+  MappingQ1Eulerian (const DoFHandler<dim,spacedim> &euler_dof_handler,
+                     const VectorType               &euler_vector);
 
   /**
-   * Constructor. It takes a <tt>Vector<double> &</tt> as its first argument
-   * to specify the transformation of the whole problem from the reference to
-   * the current configuration. The organization of the elements in the @p
-   * Vector must follow the concept how deal.II stores solutions that are
-   * associated to a triangulation.  This is automatically the case if the @p
-   * Vector represents the solution of the previous step of a nonlinear
-   * problem. Alternatively, the @p Vector can be initialized by
-   * <tt>DoFAccessor::set_dof_values()</tt>.
+   * @deprecated Use the constructor with the reverse order of first and
+   * second argument.
    */
-  MappingQ1Eulerian (const VectorType  &euler_transform_vectors,
-                     const DoFHandler<dim,spacedim> &shiftmap_dof_handler);
+  MappingQ1Eulerian (const VectorType               &euler_vector,
+                     const DoFHandler<dim,spacedim> &euler_dof_handler) DEAL_II_DEPRECATED;
 
   /**
    * Return the mapped vertices of the cell. For the current class, this
diff --git a/source/fe/mapping_q1_eulerian.cc b/source/fe/mapping_q1_eulerian.cc
index 35919e3493..0b132b8baf 100644
--- a/source/fe/mapping_q1_eulerian.cc
+++ b/source/fe/mapping_q1_eulerian.cc
@@ -28,6 +28,17 @@
 DEAL_II_NAMESPACE_OPEN
 
 
+template <int dim, class EulerVectorType, int spacedim>
+MappingQ1Eulerian<dim, EulerVectorType, spacedim>::
+MappingQ1Eulerian (const DoFHandler<dim,spacedim> &shiftmap_dof_handler,
+                   const EulerVectorType  &euler_transform_vectors)
+  :
+  MappingQGeneric<dim,spacedim>(1),
+  euler_transform_vectors(&euler_transform_vectors),
+  shiftmap_dof_handler(&shiftmap_dof_handler)
+{}
+
+
 template <int dim, class EulerVectorType, int spacedim>
 MappingQ1Eulerian<dim, EulerVectorType, spacedim>::
 MappingQ1Eulerian (const EulerVectorType  &euler_transform_vectors,
-- 
2.39.5