From: Wolfgang Bangerth Date: Sun, 15 Feb 2015 21:13:53 +0000 (-0600) Subject: Update documentation in Point and Tensor. X-Git-Tag: v8.3.0-rc1~456^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F552%2Fhead;p=dealii.git Update documentation in Point and Tensor. In particular, document the intent of the various template arguments. --- diff --git a/include/deal.II/base/point.h b/include/deal.II/base/point.h index ebb244e819..d2e3925c7f 100644 --- a/include/deal.II/base/point.h +++ b/include/deal.II/base/point.h @@ -25,14 +25,16 @@ DEAL_II_NAMESPACE_OPEN /** - * The Point class represents a point in a space with - * arbitrary dimension dim. + * A class that 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 fixed dimension: rather than using functions - * like double f(double x) and double f(double x, double y), - * you should use double f(Point &p) instead as it allows writing - * dimension independent code. + * Objects of this class are used to represent points, i.e., vectors + * anchored at the origin of a Cartesian vector space. 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(double x) and double f(double x, double + * y), you should use double f(Point &p) instead as + * it allows writing dimension independent code. * * *

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

@@ -67,10 +69,25 @@ DEAL_II_NAMESPACE_OPEN * 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 * @author Wolfgang Bangerth, 1997 */ -template +template class Point : public Tensor<1,dim,Number> { public: @@ -122,7 +139,9 @@ public: const Number z); /** - * Return a unit vector in coordinate direction i. + * 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. */ static Point unit_vector(const unsigned int i); @@ -137,13 +156,12 @@ public: Number &operator () (const unsigned int index); /* - * Plus and minus operators are re-implemented from Tensor<1,dim> - * to avoid additional casting. + * @name Addition and subtraction of points. + * @{ */ /** - * Add two point vectors. If possible, use operator += instead - * since this does not need to copy a point at least once. + * Add two point vectors. */ Point operator + (const Tensor<1,dim,Number> &) const; @@ -171,37 +189,46 @@ public: Point operator - () const; /** - * Multiply by a factor. If possible, use operator *= instead since - * this does not need to copy a point at least once. - * - * There is a commutative complement to this function also + * @} + */ + + /* + * @name Multiplication and scaling of points. Dot products. Norms. + * @{ */ - Point operator * (const Number) const; /** - * Returns the scalar product of two vectors. + * Multiply the current point by a factor. */ - Number operator * (const Tensor<1,dim,Number> &) const; + Point operator * (const Number) const; /** - * Divide by a factor. If possible, use operator /= instead since - * this does not need to copy a point at least once. + * Divide the current point by a factor. */ Point operator / (const Number) const; /** - * Returns the scalar product of this point vector with itself, i.e. the + * Return the scalar product of the vectors representing two points. + */ + 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. */ Number square () const; /** - * Returns the Euclidean distance of this point to the point + * 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. */ Number distance (const Point &p) const; + /** + * @} + */ + /** * Read or write the data of this object to or from a stream for the purpose * of serialization diff --git a/include/deal.II/base/tensor.h b/include/deal.II/base/tensor.h index df573e876e..87e578240a 100644 --- a/include/deal.II/base/tensor.h +++ b/include/deal.II/base/tensor.h @@ -26,21 +26,42 @@ template class Tensor; template class Tensor<1,dim,Number>; /** - * Provide a general tensor class with an arbitrary rank, i.e. with an + * A general tensor class with an arbitrary rank, i.e. with an * arbitrary number of indices. The Tensor class provides an indexing operator * and a bit of infrastructure, but most functionality is recursively handed * down to tensors of rank 1 or put into external templated functions, e.g. * the contract family. * - * Using this tensor class for objects of rank 2 has advantages over matrices - * in many cases since the dimension is known to the compiler as well as the - * location of the data. It is therefore possible to produce far more - * efficient code than for matrices with runtime-dependent dimension. - * - * This class provides an optional template argument for the type of the - * underlying data. It defaults to @p double values. It can be used to base - * tensors on @p float or @p complex numbers or any other data type that - * implements basic arithmetic operations. + * Using this tensor class for objects of rank 2 has advantages over + * matrices in many cases since the dimension is known to the compiler + * as well as the location of the data. It is therefore possible to + * produce far more efficient code than for matrices with + * runtime-dependent dimension. It also makes the code easier to read + * because of the semantic difference between a tensor (an object that + * relates to a coordinate system and has transformation properties + * with regard to coordinate rotations and transforms) and matrices + * (which we consider as operators on arbitrary vector spaces related + * to linear algebra things). + * + * @tparam rank_ An integer that denotes the rank of this tensor. A + * rank-0 tensor is a scalar, a rank-1 tensor is a vector with @p dim + * components, a rank-2 tensor is a matrix with dim-by-dim components, + * etc. There are specializations of this class for rank-0 and rank-1 + * tensors. There is also a related class SymmetricTensor for + * tensors of even rank whose elements are symmetric. + * @tparam dim An integer that denotes the dimension of the space in which + * this tensor operates. This of course equals the number of coordinates that + * identify a point and rank-1 tensor. + * @tparam Number The data type in which the tensor elements 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 elements + * in a different (and always scalar) type. It can be used to base + * tensors on @p float or @p complex numbers or any other data type that + * implements basic arithmetic operations. + * 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 that takes a + * tensor as argument. * * @ingroup geomprimitives * @author Wolfgang Bangerth, 1998-2005 diff --git a/include/deal.II/base/tensor_base.h b/include/deal.II/base/tensor_base.h index 30cc1f1f49..5b52ecf3fe 100644 --- a/include/deal.II/base/tensor_base.h +++ b/include/deal.II/base/tensor_base.h @@ -41,7 +41,7 @@ template class Vector; // this file must be included when using something like Tensor<1,dim>, and // Point and Tensor must not be forward declared without the number type // specified) -template class Point; +template class Point; // general template; specialized for rank==1; the general template is in // tensor.h @@ -63,6 +63,21 @@ template class Tensor<1,dim,Number>; * (i.e. @p Number) for all purposes but is part of the Tensor template * family. * + * @tparam dim An integer that denotes the dimension of the space in which + * this tensor operates. This of course equals the number of coordinates that + * identify a point and rank-1 tensor. Since the current object is a rank-0 + * tensor (a scalar), this template argument has no meaning for this class. + * @tparam Number The data type in which the tensor elements 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 elements + * in a different (and always scalar) type. It can be used to base + * tensors on @p float or @p complex numbers or any other data type that + * implements basic arithmetic operations. + * 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 that takes a + * tensor as argument. + * * @ingroup geomprimitives * @author Wolfgang Bangerth, 2009 */ @@ -179,7 +194,7 @@ public: Tensor<0,dim,Number> &operator -= (const Tensor<0,dim,Number> &rhs); /** - * Scale the vector by factor, i.e. multiply all coordinates by + * Scale the vector by factor, i.e. multiply all elements by * factor. */ Tensor<0,dim,Number> &operator *= (const Number factor); @@ -287,6 +302,20 @@ private: * rank 1, or vector, with as many elements as a point object, but with * different physical units), we use the Tensor<1,dim,Number> class. * + * @tparam dim An integer that denotes the dimension of the space in which + * this tensor operates. This of course equals the number of coordinates that + * identify a point and rank-1 tensor. + * @tparam Number The data type in which the tensor elements 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 elements + * in a different (and always scalar) type. It can be used to base + * tensors on @p float or @p complex numbers or any other data type that + * implements basic arithmetic operations. + * 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 that takes + * a tensor as argument. + * * @ingroup geomprimitives * @author Wolfgang Bangerth, 1998-2005 */ diff --git a/include/deal.II/numerics/data_postprocessor.h b/include/deal.II/numerics/data_postprocessor.h index 5f73960ff2..7a52721750 100644 --- a/include/deal.II/numerics/data_postprocessor.h +++ b/include/deal.II/numerics/data_postprocessor.h @@ -20,6 +20,7 @@ #include #include +#include #include #include #include