// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 1998 - 2025 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_point_h #define dealii_point_h #include #include #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN /** * A class that represents a point in a Cartesian space of dimension * @p dim . * * Objects of this class are used to represent points (i.e., vectors * anchored at the origin) of a vector space equipped with a Cartesian * coordinate system. They are, among other uses, passed to * functions that operate on points in spaces of a priori fixed * dimension: rather than using functions like double f(const * double x) and double f(const double x, const double * y), you can use double f(const Point &p) * instead as it allows writing dimension independent code. * * deal.II specifically uses Point objects as indicating points that * are represented by Cartesian coordinates, i.e., where a point in @p * dim space dimensions is characterized by signed distances along the * axes of a coordinate system spanned by @p dim mutually orthogonal * unit vectors (called the "coordinate axes"). This choice of * representing a vector makes addition and scaling of vectors * particularly simple: one only has to add or multiply each * coordinate value. On the other hand, adding or scaling vectors is * not nearly as simple when a vector is represented in other kinds of * coordinate systems (e.g., spherical * coordinate systems). * * *

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

* * 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::array class. Alternatively, as in the case of * vector-valued functions, you can use objects of type Vector or * std::vector. * * * @tparam dim An integer that denotes the dimension of the space in which a * point lies. This of course equals the number of coordinates that identify a * point. * @tparam Number The data type in which the coordinates values are to be * stored. This will, in almost all cases, simply be the default @p double, * but there are cases where one may want to store coordinates in a different * (and always scalar) type. An example would be an interval type that can * store the value of a coordinate as well as its uncertainty. Another example * would be a type that allows for Automatic Differentiation (see, for * example, the Sacado type used in step-33) and thereby can generate analytic * (spatial) derivatives of a function when passed a Point object whose * coordinates are stored in such a type. * * * @ingroup geomprimitives * * @dealiiConceptRequires{dim >= 0} */ template DEAL_II_CXX20_REQUIRES(dim >= 0) class Point : public Tensor<1, dim, Number> { public: /** * Standard constructor. Creates an object that corresponds to the origin, * i.e., all coordinates are set to zero. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Point(); /** * Convert a tensor to a point. */ constexpr explicit DEAL_II_HOST_DEVICE Point(const Tensor<1, dim, Number> &); /** * Constructor for one dimensional points. This function is only implemented * for dim==1 since the usage is considered unsafe for points with * dim!=1 as it would leave some components of the point * coordinates uninitialized. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr explicit DEAL_II_HOST_DEVICE Point(const Number x); /** * Constructor for two dimensional points. This function is only implemented * for dim==2 since the usage is considered unsafe for points with * dim!=2 as it would leave some components of the point * coordinates uninitialized (if dim>2) or would not use some arguments (if * dim<2). * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Point(const Number x, const Number y); /** * Constructor for three dimensional points. This function is only * implemented for dim==3 since the usage is considered unsafe for * points with dim!=3 as it would leave some components of the * point coordinates uninitialized (if dim>3) or would not use some * arguments (if dim<3). * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Point(const Number x, const Number y, const Number z); /** * Convert a boost::geometry::point to a dealii::Point. */ template = 0> constexpr Point( const boost::geometry::model:: point &boost_pt); /** * Return a unit vector in coordinate direction i, i.e., a vector * that is zero in all coordinates except for a single 1 in the ith * coordinate. * * @note This function can also be used in @ref GlossDevice "device" code. */ static constexpr DEAL_II_HOST_DEVICE Point unit_vector(const unsigned int i); /** * Read access to the indexth coordinate. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Number operator()(const unsigned int index) const; /** * Read and write access to the indexth coordinate. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Number & operator()(const unsigned int index); /** * Assignment operator from Tensor<1, dim, Number> with different underlying * scalar type. This obviously requires that the @p OtherNumber type is * convertible to @p Number. */ template constexpr Point & operator=(const Tensor<1, dim, OtherNumber> &p); /** * @name Addition and subtraction of points. * @{ */ /** * Add an offset given as Tensor<1,dim,Number> to a point. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Point operator+(const Tensor<1, dim, Number> &) const; /** * 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@. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE 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@>. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Point operator-(const Tensor<1, dim, Number> &) const; /** * The opposite vector. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Point operator-() const; /** * @} */ /** * @name Multiplication and scaling of points. Dot products. Norms. * @{ */ /** * Multiply the current point by a factor. * * @note This function can also be used in @ref GlossDevice "device" code. * * @relatesalso EnableIfScalar */ template constexpr DEAL_II_HOST_DEVICE Point< dim, typename ProductType::type>::type> operator*(const OtherNumber) const; /** * Divide the current point by a factor. * * @note This function can also be used in @ref GlossDevice "device" code. */ template constexpr DEAL_II_HOST_DEVICE Point< dim, typename ProductType::type>::type> operator/(const OtherNumber) const; /** * Return the scalar product of the vectors representing two points. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE Number operator*(const Tensor<1, dim, Number> &p) const; /** * Return the scalar product of this point vector with itself, i.e. the * square, or the square of the norm. In case of a complex number type it is * equivalent to the contraction of this point vector with a complex * conjugate of itself. * * @note This function is equivalent to * Tensor::norm_square() which returns the square of the * Frobenius norm. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE typename numbers::NumberTraits::real_type square() const; /** * Return the Euclidean distance of this point to the point * p, i.e. the $l_2$ norm of the difference between the * vectors representing the two points. * * @note This function can also be used in @ref GlossDevice "device" code. */ DEAL_II_HOST_DEVICE typename numbers::NumberTraits::real_type distance(const Point &p) const; /** * Return the squared Euclidean distance of this point to the point * p. * * @note This function can also be used in @ref GlossDevice "device" code. */ constexpr DEAL_II_HOST_DEVICE typename numbers::NumberTraits::real_type distance_square(const Point &p) const; /** * @} */ /** * Read or write the data of this object to or from a stream for the purpose * of serialization using the [BOOST serialization * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). */ template void serialize(Archive &ar, const unsigned int version); }; /*--------------------------- Inline functions: Point -----------------------*/ #ifndef DOXYGEN // At least clang-3.7 requires us to have a user-defined constructor // and we can't use 'Point::Point () = default' here. template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point::Point() // NOLINT {} template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point::Point( const Tensor<1, dim, Number> &t) : Tensor<1, dim, Number>(t) {} template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point::Point(const Number x) { Assert(dim == 1, ExcMessage( "You can only initialize Point<1> objects using the constructor " "that takes only one argument. Point objects with dim!=1 " "require initialization with the constructor that takes 'dim' " "arguments.")); // we can only get here if we pass the assertion. use the switch anyway so // as to avoid compiler warnings about uninitialized elements or writing // beyond the end of the 'values' array switch (dim) { case 1: this->values[0] = x; break; default:; } } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point::Point(const Number x, const Number y) { Assert(dim == 2, ExcMessage( "You can only initialize Point<2> objects using the constructor " "that takes two arguments. Point objects with dim!=2 " "require initialization with the constructor that takes 'dim' " "arguments.")); // we can only get here if we pass the assertion. use the indirection anyway // so as to avoid compiler warnings about uninitialized elements or writing // beyond the end of the 'values' array constexpr unsigned int y_index = (dim < 2) ? 0 : 1; this->values[0] = x; this->values[y_index] = y; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point::Point(const Number x, const Number y, const Number z) { Assert(dim == 3, ExcMessage( "You can only initialize Point<3> objects using the constructor " "that takes three arguments. Point objects with dim!=3 " "require initialization with the constructor that takes 'dim' " "arguments.")); // we can only get here if we pass the assertion. use the indirection anyway // so as to avoid compiler warnings about uninitialized elements or writing // beyond the end of the 'values' array constexpr unsigned int y_index = (dim < 2) ? 0 : 1; constexpr unsigned int z_index = (dim < 3) ? 0 : 2; this->values[0] = x; this->values[y_index] = y; this->values[z_index] = z; } template DEAL_II_CXX20_REQUIRES(dim >= 0) template > constexpr Point::Point( const boost::geometry::model:: point &boost_pt) { Assert(dim <= 3, ExcNotImplemented()); this->values[0] = boost::geometry::get<0>(boost_pt); constexpr unsigned int y_index = (dim < 2) ? 0 : 1; constexpr unsigned int z_index = (dim < 3) ? 0 : 2; if (dim >= 2) this->values[y_index] = boost::geometry::get(boost_pt); if (dim >= 3) this->values[z_index] = boost::geometry::get(boost_pt); } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point Point::unit_vector(unsigned int i) { Point p; p[i] = 1.; return p; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Number Point::operator()( const unsigned int index) const { AssertIndexRange(static_cast(index), dim); return this->values[index]; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Number &Point::operator()( const unsigned int index) { AssertIndexRange(static_cast(index), dim); return this->values[index]; } template DEAL_II_CXX20_REQUIRES(dim >= 0) template constexpr DEAL_II_ALWAYS_INLINE Point &Point::operator=(const Tensor<1, dim, OtherNumber> &p) { Tensor<1, dim, Number>::operator=(p); return *this; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point Point::operator+( const Tensor<1, dim, Number> &p) const { Point tmp = *this; tmp += p; return tmp; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Tensor<1, dim, Number> Point::operator-( const Point &p) const { return (Tensor<1, dim, Number>(*this) -= p); } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point Point::operator-( const Tensor<1, dim, Number> &p) const { Point tmp = *this; tmp -= p; return tmp; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Point Point::operator-() const { Point result; for (unsigned int i = 0; i < dim; ++i) result.values[i] = -this->values[i]; return result; } template DEAL_II_CXX20_REQUIRES(dim >= 0) template constexpr DEAL_II_HOST_DEVICE Point< dim, typename ProductType::type>:: type> Point::operator*(const OtherNumber factor) const { Point::type> tmp; for (unsigned int i = 0; i < dim; ++i) tmp[i] = this->operator[](i) * factor; return tmp; } template DEAL_II_CXX20_REQUIRES(dim >= 0) template constexpr DEAL_II_HOST_DEVICE Point< dim, typename ProductType::type>:: type> Point::operator/(const OtherNumber factor) const { const Tensor<1, dim, Number> &base_object = *this; return Point< dim, typename ProductType::type>::type>( dealii::operator/(base_object, factor)); } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE Number Point::operator*( const Tensor<1, dim, Number> &p) const { Number res = Number(); for (unsigned int i = 0; i < dim; ++i) res += this->operator[](i) * p[i]; return res; } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE typename numbers::NumberTraits::real_type Point::square() const { return this->norm_square(); } template DEAL_II_CXX20_REQUIRES(dim >= 0) inline DEAL_II_HOST_DEVICE typename numbers::NumberTraits::real_type Point::distance(const Point &p) const { return std::sqrt(distance_square(p)); } template DEAL_II_CXX20_REQUIRES(dim >= 0) constexpr DEAL_II_HOST_DEVICE typename numbers::NumberTraits::real_type Point::distance_square(const Point &p) const { Number sum = internal::NumberType::value(0.0); for (unsigned int i = 0; i < dim; ++i) { const Number diff = static_cast(this->values[i]) - p[i]; sum += numbers::NumberTraits::abs_square(diff); } return sum; } template DEAL_II_CXX20_REQUIRES(dim >= 0) template inline void Point::serialize(Archive &ar, const unsigned int) { // forward to serialization // function in the base class ar &static_cast &>(*this); } #endif // DOXYGEN /*--------------------------- Global functions: Point -----------------------*/ /** * Global operator scaling a point vector by a scalar. * * @note This function can also be used in @ref GlossDevice "device" code. * * @relates Point */ template constexpr DEAL_II_HOST_DEVICE Point::type>::type> operator*(const OtherNumber factor, const Point &p) { return p * factor; } /** * Output operator for points. Print the elements consecutively, with a space * in between. * @relatesalso Point * * @dealiiConceptRequires{dim >= 0} */ template DEAL_II_CXX20_REQUIRES(dim >= 0) inline std::ostream & operator<<(std::ostream &out, const Point &p) { for (unsigned int i = 0; i < dim - 1; ++i) out << p[i] << ' '; out << p[dim - 1]; return out; } /** * Input operator for points. Inputs the elements consecutively. * @relatesalso Point * * @dealiiConceptRequires{dim >= 0} */ template DEAL_II_CXX20_REQUIRES(dim >= 0) inline std::istream & operator>>(std::istream &in, Point &p) { for (unsigned int i = 0; i < dim; ++i) in >> p[i]; return in; } #ifndef DOXYGEN /** * Output operator for points of dimension 1. This is implemented specialized * from the general template in order to avoid a compiler warning that the * loop is empty. */ template inline std::ostream & operator<<(std::ostream &out, const Point<1, Number> &p) { out << p[0]; return out; } #endif // DOXYGEN DEAL_II_NAMESPACE_CLOSE #endif