Reference documentation for deal.II version Git bd58e18 2017-08-22 18:42:24 +0200
Public Member Functions | Private Attributes | List of all members
ChartManifold< dim, spacedim, chartdim > Class Template Referenceabstract

#include <deal.II/grid/manifold.h>

Inheritance diagram for ChartManifold< dim, spacedim, chartdim >:
[legend]

Public Member Functions

 ChartManifold (const Tensor< 1, chartdim > &periodicity=Tensor< 1, chartdim >())
 
virtual ~ChartManifold ()
 
virtual Point< spacedim > get_new_point (const std::vector< Point< spacedim > > &surrounding_points, const std::vector< double > &weights) const
 
virtual void add_new_points (const std::vector< Point< spacedim > > &surrounding_points, const Table< 2, double > &weights, std::vector< Point< spacedim > > &new_points) const
 
virtual Point< chartdim > pull_back (const Point< spacedim > &space_point) const =0
 
virtual Point< spacedim > push_forward (const Point< chartdim > &chart_point) const =0
 
virtual DerivativeForm< 1, chartdim, spacedim > push_forward_gradient (const Point< chartdim > &chart_point) const
 
virtual Tensor< 1, spacedim > get_tangent_vector (const Point< spacedim > &x1, const Point< spacedim > &x2) const
 
const Tensor< 1, chartdim > & get_periodicity () const
 
- Public Member Functions inherited from Manifold< dim, spacedim >
virtual ~Manifold ()
 
virtual Point< spacedim > get_intermediate_point (const Point< spacedim > &p1, const Point< spacedim > &p2, const double w) const
 
virtual Point< spacedim > project_to_manifold (const std::vector< Point< spacedim > > &surrounding_points, const Point< spacedim > &candidate) const
 
virtual Point< spacedim > get_new_point_on_line (const typename Triangulation< dim, spacedim >::line_iterator &line) const
 
virtual Point< spacedim > get_new_point_on_quad (const typename Triangulation< dim, spacedim >::quad_iterator &quad) const
 
virtual Point< spacedim > get_new_point_on_hex (const typename Triangulation< dim, spacedim >::hex_iterator &hex) const
 
Point< spacedim > get_new_point_on_face (const typename Triangulation< dim, spacedim >::face_iterator &face) const
 
Point< spacedim > get_new_point_on_cell (const typename Triangulation< dim, spacedim >::cell_iterator &cell) const
 
virtual Tensor< 1, spacedim > normal_vector (const typename Triangulation< dim, spacedim >::face_iterator &face, const Point< spacedim > &p) const
 
virtual void get_normals_at_vertices (const typename Triangulation< dim, spacedim >::face_iterator &face, FaceVertexNormals &face_vertex_normals) const
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
 Subscriptor (Subscriptor &&)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
Subscriptoroperator= (Subscriptor &&)
 
void subscribe (const char *identifier=nullptr) const
 
void unsubscribe (const char *identifier=nullptr) const
 
unsigned int n_subscriptions () const
 
void list_subscribers () const
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Private Attributes

const FlatManifold< chartdim, chartdim > sub_manifold
 

Additional Inherited Members

- Public Types inherited from Manifold< dim, spacedim >
typedef Tensor< 1, spacedim > FaceVertexNormals[GeometryInfo< dim >::vertices_per_face]
 
- Static Public Member Functions inherited from Subscriptor
static::ExceptionBase & ExcInUse (int arg1, char *arg2, std::string &arg3)
 
static::ExceptionBase & ExcNoSubscriber (char *arg1, char *arg2)
 

Detailed Description

template<int dim, int spacedim = dim, int chartdim = dim>
class ChartManifold< dim, spacedim, chartdim >

This class describes mappings that can be expressed in terms of charts. Specifically, this class with its template arguments describes a chart of dimension chartdim, which is part of a Manifold<dim,spacedim> and is used in an object of type Triangulation<dim,spacedim>: It specializes a Manifold of dimension chartdim embedded in a manifold of dimension spacedim, for which you have explicit pull_back() and push_forward() transformations. Its use is explained in great detail in step-53.

This is a helper class which is useful when you have an explicit map from an Euclidean space of dimension chartdim to an Euclidean space of dimension spacedim which represents your manifold, i.e., when your manifold \(\mathcal{M}\) can be represented by a map

\[ F: \mathcal{B} \subset R^{\text{chartdim}} \mapsto \mathcal{M} \subset R^{\text{spacedim}} \]

(the push_forward() function) and that admits the inverse transformation

\[ F^{-1}: \mathcal{M} \subset R^{\text{spacedim}} \mapsto \mathcal{B} \subset R^{\text{chartdim}} \]

(the pull_back() function).

The get_new_point() function of the ChartManifold class is implemented by calling the pull_back() method for all surrounding_points, computing their weighted average in the chartdim Euclidean space, and calling the push_forward() method with the resulting point, i.e.,

\[ \mathbf x^{\text{new}} = F(\sum_i w_i F^{-1}(\mathbf x_i)). \]

Derived classes are required to implement the push_forward() and the pull_back() methods. All other functions (with the exception of the push_forward_gradient() function, see below) that are required by mappings will then be provided by this class.

Providing function gradients

In order to compute vectors that are tangent to the manifold (for example, tangent to a surface embedded in higher dimensional space, or simply the three unit vectors of \({\mathbb R}^3\)), one needs to also have access to the gradient of the push-forward function \(F\). The gradient is the matrix \((\nabla F)_{ij}=\partial_j F_i\), where we take the derivative with regard to the chartdim reference coordinates on the flat Euclidean space in which \(\mathcal B\) is located. In other words, at a point \(\mathbf x\), \(\nabla F(\mathbf x)\) is a matrix of size spacedim times chartdim.

Only the ChartManifold::get_tangent_vector() function uses the gradient of the push-forward, but only a subset of all finite element codes actually require the computation of tangent vectors. Consequently, while derived classes need to implement the abstract virtual push_forward() and pull_back() functions of this class, they do not need to implement the virtual push_forward_gradient() function. Rather, that function has a default implementation (and consequently is not abstract, therefore not forcing derived classes to overload it), but the default implementation clearly can not compute anything useful and therefore simply triggers and exception.

A note on the template arguments

The dimension arguments chartdim, dim and spacedim must satisfy the following relationships:

dim <= spacedim
chartdim <= spacedim

However, there is no a priori relationship between dim and chartdim. For example, if you want to describe a mapping for an edge (a 1d object) in a 2d triangulation embedded in 3d space, you could do so by parameterizing it via a line

\[ F: [0,1] \rightarrow {\mathbb R}^3 \]

in which case chartdim is 1. On the other hand, there is no reason why one can't describe this as a mapping

\[ F: {\mathbb R}^3 \rightarrow {\mathbb R}^3 \]

in such a way that the line \([0,1]\times \{0\}\times \{0\}\) happens to be mapped onto the edge in question. Here, chartdim is 3. This may seem cumbersome but satisfies the requirements of an invertible function \(F\) just fine as long as it is possible to get from the edge to the pull-back space and then back again. Finally, given that we are dealing with a 2d triangulation in 3d, one will often have a mapping from, say, the 2d unit square or unit disk to the domain in 3d space, and the edge in question may simply be the mapped edge of the unit domain in 2d space. In this case, chartdim is 2.

Author
Luca Heltai, 2013, 2014

Definition at line 889 of file manifold.h.

Constructor & Destructor Documentation

template<int dim, int spacedim, int chartdim>
ChartManifold< dim, spacedim, chartdim >::ChartManifold ( const Tensor< 1, chartdim > &  periodicity = Tensor<1,chartdim>())

Constructor. The optional argument can be used to specify the periodicity of the chartdim-dimensional manifold (one period per direction). A periodicity value of zero means that along that direction there is no periodicity. By default no periodicity is assumed.

Periodicity affects the way a middle point is computed. It is assumed that if two points are more than half period distant, then the distance should be computed by crossing the periodicity boundary, i.e., then the average is computed by adding a full period to the sum of the two. For example, if along direction 0 we have 2*pi periodicity, then the average of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on the manifold, these two points are at distance 2*eps and not (2*pi-eps)

Definition at line 721 of file manifold.cc.

template<int dim, int spacedim, int chartdim>
ChartManifold< dim, spacedim, chartdim >::~ChartManifold ( )
virtual

Destructor. Does nothing here, but needs to be declared to make it virtual.

Definition at line 715 of file manifold.cc.

Member Function Documentation

template<int dim, int spacedim, int chartdim>
Point< spacedim > ChartManifold< dim, spacedim, chartdim >::get_new_point ( const std::vector< Point< spacedim > > &  surrounding_points,
const std::vector< double > &  weights 
) const
virtual

Refer to the general documentation of this class and the documentation of the base class for more information.

Reimplemented from Manifold< dim, spacedim >.

Reimplemented in CylindricalManifold< dim, spacedim >.

Definition at line 731 of file manifold.cc.

template<int dim, int spacedim, int chartdim>
void ChartManifold< dim, spacedim, chartdim >::add_new_points ( const std::vector< Point< spacedim > > &  surrounding_points,
const Table< 2, double > &  weights,
std::vector< Point< spacedim > > &  new_points 
) const
virtual

Compute a new set of points that interpolate between the given points surrounding_points. weights is a table with as many columns as surrounding_points.size(). The number of rows in weights determines how many new points will be computed and appended to the last input argument new_points. After exit of this function, the size of new_points equals the size at entry plus the number of rows in weights.

The implementation of this function first transforms the surrounding_points to the chart space by calling pull_back(). Then, new points are computed on the chart by usual interpolation according to the given weights, which are finally transformed to the image space by push_forward().

This implementation can be much more efficient for computing multiple new points from the same surrounding points than separate calls to get_new_point() in case the pull_back() operation is expensive. This is because pull_back() is only called once for the surrounding points and the interpolation is done for all given weights using this set of points. Often, pull_back() is also more expensive than push_forward() because the former might involve some kind of Newton iteration in non-trivial manifolds.

Reimplemented from Manifold< dim, spacedim >.

Definition at line 749 of file manifold.cc.

template<int dim, int spacedim = dim, int chartdim = dim>
virtual Point<chartdim> ChartManifold< dim, spacedim, chartdim >::pull_back ( const Point< spacedim > &  space_point) const
pure virtual
template<int dim, int spacedim = dim, int chartdim = dim>
virtual Point<spacedim> ChartManifold< dim, spacedim, chartdim >::push_forward ( const Point< chartdim > &  chart_point) const
pure virtual

Given a point in the chartdim dimensional Euclidean space, this method returns a point on the manifold embedded in the spacedim Euclidean space.

Refer to the general documentation of this class for more information.

Implemented in FunctionManifold< dim, spacedim, chartdim >, TensorProductManifold< dim, dim_A, spacedim_A, chartdim_A, dim_B, spacedim_B, chartdim_B >, and CompositionManifold< dim, spacedim, chartdim, intermediate_dim, dim1, dim2 >.

template<int dim, int spacedim, int chartdim>
DerivativeForm< 1, chartdim, spacedim > ChartManifold< dim, spacedim, chartdim >::push_forward_gradient ( const Point< chartdim > &  chart_point) const
virtual

Given a point in the chartdim dimensional Euclidean space, this method returns the derivatives of the function \(F\) that maps from the chartdim-dimensional to the spacedim-dimensional space. In other words, it is a matrix of size \(\text{spacedim}\times\text{chartdim}\).

This function is used in the computations required by the get_tangent_vector() function. Since not all users of the Manifold class interface will require calling that function, the current function is implemented but will trigger an exception whenever called. This allows derived classes to avoid implementing the push_forward_gradient function if this functionality is not needed in the user program.

Refer to the general documentation of this class for more information.

Reimplemented in FunctionManifold< dim, spacedim, chartdim >, TensorProductManifold< dim, dim_A, spacedim_A, chartdim_A, dim_B, spacedim_B, chartdim_B >, and CompositionManifold< dim, spacedim, chartdim, intermediate_dim, dim1, dim2 >.

Definition at line 775 of file manifold.cc.

template<int dim, int spacedim, int chartdim>
Tensor< 1, spacedim > ChartManifold< dim, spacedim, chartdim >::get_tangent_vector ( const Point< spacedim > &  x1,
const Point< spacedim > &  x2 
) const
virtual

Return a vector that, at \(\mathbf x_1\), is tangential to the geodesic that connects two points \(\mathbf x_1,\mathbf x_2\). See the documentation of the Manifold class and of Manifold::get_tangent_vector() for a more detailed description.

For the current class, we assume that this geodesic is the image under the push_forward() operation of a straight line of the pre-images of x1 and x2 (where pre-images are computed by pulling back the locations x1 and x2). In other words, if these preimages are \(\xi_1=F^{-1}(\mathbf x_1), \xi_2=F^{-1}(\mathbf x_2)\), then the geodesic in preimage (the chartdim-dimensional Euclidean) space is

\begin{align*} \zeta(t) &= \xi_1 + t (\xi_2-\xi_1) \\ &= F^{-1}(\mathbf x_1) + t\left[F^{-1}(\mathbf x_2) -F^{-1}(\mathbf x_1)\right] \end{align*}

In image space, i.e., in the space in which we operate, this leads to the curve

\begin{align*} \mathbf s(t) &= F(\zeta(t)) \\ &= F(\xi_1 + t (\xi_2-\xi_1)) \\ &= F\left(F^{-1}(\mathbf x_1) + t\left[F^{-1}(\mathbf x_2) -F^{-1}(\mathbf x_1)\right]\right). \end{align*}

What the current function is supposed to return is \(\mathbf s'(0)\). By the chain rule, this is equal to

\begin{align*} \mathbf s'(0) &= \frac{d}{dt}\left. F\left(F^{-1}(\mathbf x_1) + t\left[F^{-1}(\mathbf x_2) -F^{-1}(\mathbf x_1)\right]\right) \right|_{t=0} \\ &= \nabla_\xi F\left(F^{-1}(\mathbf x_1)\right) \left[F^{-1}(\mathbf x_2) -F^{-1}(\mathbf x_1)\right]. \end{align*}

This formula may then have to be slightly modified by considering any periodicity that was assumed in the call to the constructor.

Thus, the computation of tangent vectors also requires the implementation of derivatives \(\nabla_\xi F(\xi)\) of the push-forward mapping. Here, \(F^{-1}(\mathbf x_2)-F^{-1}(\mathbf x_1)\) is a chartdim-dimensional vector, and \(\nabla_\xi F\left(F^{-1}(\mathbf x_1)\right) = \nabla_\xi F\left(\xi_1\right)\) is a spacedim-times-chartdim-dimensional matrix. Consequently, and as desired, the operation results in a spacedim-dimensional vector.

Parameters
x1The first point that describes the geodesic, and the one at which the "direction" is to be evaluated.
x2The second point that describes the geodesic.
Returns
A "direction" vector tangential to the geodesic.

Reimplemented from Manifold< dim, spacedim >.

Definition at line 788 of file manifold.cc.

template<int dim, int spacedim, int chartdim>
const Tensor< 1, chartdim > & ChartManifold< dim, spacedim, chartdim >::get_periodicity ( ) const

Return the periodicity associated with the submanifold.

Definition at line 816 of file manifold.cc.

Member Data Documentation

template<int dim, int spacedim = dim, int chartdim = dim>
const FlatManifold<chartdim,chartdim> ChartManifold< dim, spacedim, chartdim >::sub_manifold
private

The sub_manifold object is used to compute the average of the points in the chart coordinates system.

In an ideal world, it would have type FlatManifold<dim,chartdim>. However, this would instantiate cases where dim>spacedim, which leads to invalid situations. We instead use <chartdim,chartdim>, which is (i) always valid, and (ii) does not matter at all since the first (dim) argument of manifolds is, in fact, ignored as far as manifold functionality is concerned.

Definition at line 1075 of file manifold.h.


The documentation for this class was generated from the following files: