From: Wolfgang Bangerth Date: Thu, 5 Feb 2015 13:13:48 +0000 (-0600) Subject: Make the difference between two points a tensor, rather than a X-Git-Tag: v8.3.0-rc1~493^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3535723485889551b764887e13ec9d723b0396ab;p=dealii.git 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 83b1cb33af..c0b4a4cb06 100644 --- a/doc/news/changes.h +++ b/doc/news/changes.h @@ -292,6 +292,19 @@ inconvenience this causes.
    +
  1. Changed: We have traditionally used Point@ 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 + operator-() for Point objects: The difference between two + points, p1-p2 now returns a Tensor@<1,dim@>. On the other + hand, subtracting a Tensor@<1,dim@> object from a Point, p-t, + results in a Point@. +
    + (Wolfgang Bangerth, 2015/02/05) +
  2. +
  3. 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 115fad0de8..75a1062673 100644 --- 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 Point class provides for a point or vector in a space with + * The Point class represents a point in a space with * arbitrary dimension dim. * * 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 double f(double x) and double f(double x, double y), - * you use double f(Point &p). + * you should use double f(Point &p) instead as it allows writing + * dimension independent code. * - * Point also serves as a starting point for the implementation of - * the geometrical primitives like cells, edges, or faces. * - * Within deal.II, we use the Point 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 - * Tensor<1,dim> class. In particular, there is a distance() function - * to compute the Euclidean distance between two points in space. + *

    What's a Point@ and what is a Tensor@<1,dim@>?

    * - * The Point 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 Tensor<1,dim> 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 Point class to denote points in space, i.e., for + * vectors (rank-1 tensors) that are anchored at the + * origin. On the other hand, vectors that are anchored elsewhere + * (and consequently do not represent points 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@. + * + * 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 std_cxx11::array + * class. Alternatively, as in the case of vector-valued functions, + * you can use objects of type Vector or std::vector. * * @ingroup geomprimitives * @author Wolfgang Bangerth, 1997 @@ -129,8 +148,20 @@ public: Point operator + (const Tensor<1,dim,Number> &) const; /** - * Subtract two point vectors. If possible, use operator += 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@. + */ + Tensor<1,dim,Number> operator - (const Point &) 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@ object rather than as a + * Tensor@<1,dim@>. */ Point operator - (const Tensor<1,dim,Number> &) const; @@ -298,6 +329,16 @@ Point::operator + (const Tensor<1,dim,Number> &p) const +template +inline +Tensor<1,dim,Number> +Point::operator - (const Point &p) const +{ + return (Tensor<1,dim,Number>(*this) -= p); +} + + + template inline Point