Make the difference between two points a tensor, rather than a

point. Clarify the use of these two classes in the documentation.

diff --git a/doc/news/changes.h b/doc/news/changes.h
index 83b1cb33af7b8366063bf56a33c9a94cddea67b0..c0b4a4cb060591ff57830d0e734ad9a03772ba27 100644 (file)
--- a/doc/news/changes.h
+++ b/doc/news/changes.h
@@ -292,6 +292,19 @@ inconvenience this causes.
 
 
 <ol>
+  <li> Changed: We have traditionally used Point@<dim@> to represent points
+  in physical space, i.e., vectors that are anchored at the origin, whereas
+  for vectors anchored elsewhere (e.g., differences between points, normal
+  vectors, gradients, etc) we have used Tensor@<1,dim@>. This has now be
+  made more formal in the documentation but also in the return types of
+  <code>operator-()</code> for Point objects: The difference between two
+  points, <code>p1-p2</code> now returns a Tensor@<1,dim@>. On the other
+  hand, subtracting a Tensor@<1,dim@> object from a Point, <code>p-t</code>,
+  results in a Point@<dim@>.
+  <br>
+  (Wolfgang Bangerth, 2015/02/05)
+  </li>
+
   <li> New: Examples from 1 to 16 now use the Manifold interface
   instead of the old Boundary interface to describe curved boundaries
   and domains.

diff --git a/include/deal.II/base/point.h b/include/deal.II/base/point.h
index 115fad0de8bcf3ac541f0f27d428cced3aa04731..75a10626739faf28bb11d499defccda6a885cb52 100644 (file)
--- a/include/deal.II/base/point.h
+++ b/include/deal.II/base/point.h
@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------
 //
-// Copyright (C) 1998 - 2014 by the deal.II authors
+// Copyright (C) 1998 - 2015 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -25,28 +25,47 @@
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * The <tt>Point</tt> class provides for a point or vector in a space with
+ * The <tt>Point</tt> class represents a point in a space with
  * arbitrary dimension <tt>dim</tt>.
  *
  * It is the preferred object to be passed to functions which operate on
- * points in spaces of a priori unknown dimension: rather than using functions
+ * points in spaces of a priori fixed dimension: rather than using functions
  * like <tt>double f(double x)</tt> and <tt>double f(double x, double y)</tt>,
- * you use <tt>double f(Point<dim> &p)</tt>.
+ * you should use <tt>double f(Point<dim> &p)</tt> instead as it allows writing
+ * dimension independent code.
  *
- * <tt>Point</tt> also serves as a starting point for the implementation of
- * the geometrical primitives like cells, edges, or faces.
  *
- * Within deal.II, we use the <tt>Point</tt> class mainly to denote the points
- * that make up geometric objects. As such, they have a small number of
- * additional operations over general tensors of rank 1 for which we use the
- * <tt>Tensor<1,dim></tt> class. In particular, there is a distance() function
- * to compute the Euclidean distance between two points in space.
+ * <h3>What's a <code>Point@<dim@></code> and what is a <code>Tensor@<1,dim@></code>?</h3>
  *
- * The <tt>Point</tt> class is really only used where the coordinates of an
- * object can be thought to possess the dimension of a length. For all other
- * uses, such as the gradient of a scalar function (which is a tensor of rank
- * 1, or vector, with as many elements as a point object, but with different
- * physical units), we use the <tt>Tensor<1,dim></tt> class.
+ * The Point class is derived from Tensor@<1,dim@> and consequently
+ * shares the latter's member functions and other attributes. In fact,
+ * it has relatively few additional functions itself (the most notable
+ * exception being the distance() function to compute the Euclidean
+ * distance between two points in space), and these two classes can
+ * therefore often be used interchangeably.
+ *
+ * Nonetheless, there are semantic differences that make us use these
+ * classes in different and well-defined contexts. Within deal.II, we
+ * use the <tt>Point</tt> class to denote points in space, i.e., for
+ * vectors (rank-1 tensors) that are <em>anchored at the
+ * origin</em>. On the other hand, vectors that are anchored elsewhere
+ * (and consequently do not represent <em>points</em> in the common
+ * usage of the word) are represented by objects of type
+ * Tensor@<1,dim@>. In particular, this is the case for direction
+ * vectors, normal vectors, gradients, and the differences between two
+ * points (i.e., what you get when you subtract one point from
+ * another): all of these are represented by Tensor@<1,dim@> objects
+ * rather than Point@<dim@>.
+ *
+ * Furthermore, the Point class is only used where the coordinates of
+ * an object can be thought to possess the dimension of a length. An
+ * object that represents the weight, height, and cost of an object is
+ * neither a point nor a tensor (because it lacks the transformation
+ * properties under rotation of the coordinate system) and should
+ * consequently not be represented by either of these classes. Use an
+ * array of size 3 in this case, or the <code>std_cxx11::array</code>
+ * class. Alternatively, as in the case of vector-valued functions,
+ * you can use objects of type Vector or <code>std::vector<code>.
  *
  * @ingroup geomprimitives
  * @author Wolfgang Bangerth, 1997
@@ -129,8 +148,20 @@ public:
   Point<dim,Number>   operator + (const Tensor<1,dim,Number> &) const;
 
   /**
-   * Subtract two point vectors. If possible, use <tt>operator +=</tt> instead
-   * since this does not need to copy a point at least once.
+   * Subtract two points, i.e., obtain the vector that connects the
+   * two. As discussed in the documentation of this class, subtracting
+   * two points results in a vector anchored at one of the two points
+   * (rather than at the origin) and, consequently, the result is
+   * returned as a Tensor@<1,dim@> rather than as a Point@<dim@>.
+   */
+  Tensor<1,dim,Number>   operator - (const Point<dim,Number> &) const;
+
+  /**
+   * Subtract a difference vector (represented by a Tensor@<1,dim@>)
+   * from the current point. This results in another point and, as
+   * discussed in the documentation of this class, the result is then
+   * naturally returned as a Point@<dim@> object rather than as a
+   * Tensor@<1,dim@>.
    */
   Point<dim,Number>   operator - (const Tensor<1,dim,Number> &) const;
 
@@ -298,6 +329,16 @@ Point<dim,Number>::operator + (const Tensor<1,dim,Number> &p) const
 
 
 
+template <int dim, typename Number>
+inline
+Tensor<1,dim,Number>
+Point<dim,Number>::operator - (const Point<dim,Number> &p) const
+{
+  return (Tensor<1,dim,Number>(*this) -= p);
+}
+
+
+
 template <int dim, typename Number>
 inline
 Point<dim,Number>