Reference documentation for deal.II version GIT 35969cdc9b 20231209 01:10:02+00:00

#include <deal.II/grid/manifold.h>
Public Types  
using  FaceVertexNormals = std::array< Tensor< 1, spacedim >, GeometryInfo< dim >::vertices_per_face > 
Public Member Functions  
ChartManifold (const Tensor< 1, chartdim > &periodicity=Tensor< 1, chartdim >())  
virtual  ~ChartManifold () override=default 
virtual Point< spacedim >  get_intermediate_point (const Point< spacedim > &p1, const Point< spacedim > &p2, const double w) const override 
virtual Point< spacedim >  get_new_point (const ArrayView< const Point< spacedim >> &surrounding_points, const ArrayView< const double > &weights) const override 
virtual void  get_new_points (const ArrayView< const Point< spacedim >> &surrounding_points, const Table< 2, double > &weights, ArrayView< Point< spacedim >> new_points) const override 
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 override 
const Tensor< 1, chartdim > &  get_periodicity () const 
virtual std::unique_ptr< Manifold< dim, spacedim > >  clone () const=0 
template<class Archive >  
void  serialize (Archive &ar, const unsigned int version) 
Computing the location of points.  
virtual Point< spacedim >  project_to_manifold (const ArrayView< const 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 
Computing normal vectors  
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 
Subscriptor functionality  
Classes derived from Subscriptor provide a facility to subscribe to this object. This is mostly used by the SmartPointer class.  
void  subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const 
void  unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const 
unsigned int  n_subscriptions () const 
template<typename StreamType >  
void  list_subscribers (StreamType &stream) const 
void  list_subscribers () const 
Static Public Member Functions  
static ::ExceptionBase &  ExcInUse (int arg1, std::string arg2, std::string arg3) 
static ::ExceptionBase &  ExcNoSubscriber (std::string arg1, std::string arg2) 
Private Types  
using  map_value_type = decltype(counter_map)::value_type 
using  map_iterator = decltype(counter_map)::iterator 
Private Member Functions  
void  check_no_subscribers () const noexcept 
Private Attributes  
const FlatManifold< chartdim, chartdim >  sub_manifold 
std::atomic< unsigned int >  counter 
std::map< std::string, unsigned int >  counter_map 
std::vector< std::atomic< bool > * >  validity_pointers 
const std::type_info *  object_info 
Static Private Attributes  
static std::mutex  mutex 
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 step53.
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.
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 pushforward 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 pushforward, 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.
The dimension arguments chartdim
, dim
and spacedim
must satisfy the following relationships:
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 pullback 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.
Definition at line 902 of file manifold.h.

inherited 
Type keeping information about the normals at the vertices of a face of a cell. Thus, there are GeometryInfo<dim>::vertices_per_face
normal vectors, that define the tangent spaces of the boundary at the vertices. Note that the vectors stored in this object are not required to be normalized, nor to actually point outward, as one often will only want to check for orthogonality to define the tangent plane; if a function requires the normals to be normalized, then it must do so itself.
For obvious reasons, this type is not useful in 1d.
Definition at line 306 of file manifold.h.

privateinherited 
The data type used in counter_map.
Definition at line 230 of file subscriptor.h.

privateinherited 
The iterator type used in counter_map.
Definition at line 235 of file subscriptor.h.
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 chartdimdimensional 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*pieps) 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*pieps)
Definition at line 1015 of file manifold.cc.

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

overridevirtual 
Refer to the general documentation of this class and the documentation of the base class for more information.
Reimplemented from Manifold< dim, dim >.
Definition at line 1024 of file manifold.cc.

overridevirtual 
Refer to the general documentation of this class and the documentation of the base class for more information.
Reimplemented from Manifold< dim, dim >.
Reimplemented in CylindricalManifold< dim, spacedim >.
Definition at line 1039 of file manifold.cc.

overridevirtual 
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
must match the length of new_points
.
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 nontrivial manifolds.
Reimplemented from Manifold< dim, dim >.
Definition at line 1060 of file manifold.cc.

pure virtual 
Pull back the given point in spacedim to the Euclidean chartdim dimensional space.
Refer to the general documentation of this class for more information.
Implemented in OpenCASCADE::NURBSPatchManifold< dim, spacedim >, OpenCASCADE::ArclengthProjectionLineManifold< dim, spacedim >, TensorProductManifold< dim, dim_A, spacedim_A, chartdim_A, dim_B, spacedim_B, chartdim_B >, FunctionManifold< dim, spacedim, chartdim >, EllipticalManifold< dim, spacedim >, CylindricalManifold< dim, spacedim >, PolarManifold< dim, spacedim >, and CompositionManifold< dim, spacedim, chartdim, intermediate_dim, dim1, dim2 >.

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 TensorProductManifold< dim, dim_A, spacedim_A, chartdim_A, dim_B, spacedim_B, chartdim_B >, FunctionManifold< dim, spacedim, chartdim >, and CompositionManifold< dim, spacedim, chartdim, intermediate_dim, dim1, dim2 >.

virtual 
Given a point in the chartdim dimensional Euclidean space, this method returns the derivatives of the function \(F\) that maps from the chartdimdimensional to the spacedimdimensional 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 TensorProductManifold< dim, dim_A, spacedim_A, chartdim_A, dim_B, spacedim_B, chartdim_B >, FunctionManifold< dim, spacedim, chartdim >, and CompositionManifold< dim, spacedim, chartdim, intermediate_dim, dim1, dim2 >.
Definition at line 1089 of file manifold.cc.

overridevirtual 
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 preimages of x1
and x2
(where preimages 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 chartdimdimensional 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 pushforward mapping. Here, \(F^{1}(\mathbf x_2)F^{1}(\mathbf x_1)\) is a chartdimdimensional vector, and \(\nabla_\xi F\left(F^{1}(\mathbf x_1)\right) = \nabla_\xi F\left(\xi_1\right)\) is a spacedimtimeschartdimdimensional matrix. Consequently, and as desired, the operation results in a spacedimdimensional vector.
x1  The first point that describes the geodesic, and the one at which the "direction" is to be evaluated. 
x2  The second point that describes the geodesic. 
Reimplemented from Manifold< dim, dim >.
Definition at line 1102 of file manifold.cc.
const Tensor< 1, chartdim > & ChartManifold< dim, spacedim, chartdim >::get_periodicity 
Return the periodicity associated with the submanifold.
Definition at line 1134 of file manifold.cc.

pure virtualinherited 
Return a copy of this manifold.
Every derived class should implement this operation in a sensible manner.
Implemented in TransfiniteInterpolationManifold< dim, spacedim >, SphericalManifold< dim, spacedim >, and FlatManifold< dim, spacedim >.

virtualinherited 
Given a point which lies close to the given manifold, it modifies it and projects it to manifold itself.
This class is used by the default implementation of the function get_new_point() and should be implemented by derived classes. The default implementation simply throws an exception if called.
If your manifold is simple, you could implement this function only, and the default behavior should work out of the box.
Reimplemented in FlatManifold< dim, spacedim >.

virtualinherited 
Backward compatibility interface. Return the point which shall become the new middle vertex of the two children of a regular line. In 2d, this line is a line at the boundary, while in 3d, it is bounding a face at the boundary (the lines therefore is also on the boundary).
The default implementation of this function passes its argument to the Manifolds::get_default_points_and_weights() function, and then calls the Manifold<dim,spacedim>::get_new_point() function. User derived classes can overload Manifold<dim,spacedim>::get_new_point() or Manifold<dim,spacedim>::project_to_manifold(), which is called by the default implementation of Manifold<dim,spacedim>::get_new_point().

virtualinherited 
Backward compatibility interface. Return the point which shall become the common point of the four children of a quad at the boundary in three or more spatial dimensions. This function therefore is only useful in at least three dimensions and should not be called for lower dimensions.
This function is called after the four lines bounding the given quad
are refined, so you may want to use the information provided by quad>line(i)>child(j)
, i=0...3
, j=0,1
.
The default implementation of this function passes its argument to the Manifolds::get_default_points_and_weights() function, and then calls the Manifold<dim,spacedim>::get_new_point() function. User derived classes can overload Manifold<dim,spacedim>::get_new_point() or Manifold<dim,spacedim>::project_to_manifold(), which is called by the default implementation of Manifold<dim,spacedim>::get_new_point().

virtualinherited 
Backward compatibility interface. Return the point which shall become the common point of the eight children of a hex in three or spatial dimensions. This function therefore is only useful in at least three dimensions and should not be called for lower dimensions.
This function is called after the all the bounding objects of the given hex
are refined, so you may want to use the information provided by hex>quad(i)>line(j)>child(k)
, i=0...5
, j=0...3
, k=0,1
.
The default implementation of this function passes its argument to the Manifolds::get_default_points_and_weights() function, and then calls the Manifold<dim,spacedim>::get_new_point() function. User derived classes can overload Manifold<dim,spacedim>::get_new_point() or Manifold<dim,spacedim>::project_to_manifold(), which is called by the default implementation of Manifold<dim,spacedim>::get_new_point().

inherited 
Backward compatibility interface. Depending on dim=2
or dim=3
this function calls the get_new_point_on_line or the get_new_point_on_quad function. It throws an exception for dim=1
. This wrapper allows dimension independent programming.

inherited 
Backward compatibility interface. Depending on dim=1
, dim=2
or dim=3
this function calls the get_new_point_on_line, get_new_point_on_quad or the get_new_point_on_hex function. This wrapper allows dimension independent programming.

virtualinherited 
Return the normal vector to a face embedded in this manifold, at the point p. It is not required that the normals actually point outward from the domain even if the face iterator given points to a face on the boundary of the domain. If p is not in fact on the surface, but only closeby, try to return something reasonable, for example the normal vector at the surface point closest to p. (The point p will in fact not normally lie on the actual surface, but rather be a quadrature point mapped by some polynomial mapping; the mapped surface, however, will not usually coincide with the actual surface.)
This function only makes sense if dim==spacedim because otherwise there is no unique normal vector but in fact a (spacedimdim+1)dimensional tangent space of vectors that are all both normal to the face and normal to the dimdimensional surface that lives in spacedimdimensional space. For example, think of a twodimensional mesh that covers a twodimensional surface in threedimensional space. In that case, each face (edge) is onedimensional, and there are two linearly independent vectors that are both normal to the edge: one is normal to the edge and tangent to the surface (intuitively, that would be the one that points from the current cell to the neighboring one, if the surface was locally flat), and the other one is rooted in the edge but points perpendicular to the surface (which is also perpendicular to the edge that lives within the surface). Thus, because there are no obviously correct semantics for this function if spacedim is greater than dim, the function will simply throw an error in that situation.
The face iterator gives an indication which face this function is supposed to compute the normal vector for. This is useful if the boundary of the domain is composed of different nondifferential pieces (for example when using the FlatManifold class to approximate a geometry that is completely described by the coarse mesh, with piecewise (bi)linear components between the vertices, but where the boundary may have a kink at the vertices itself).
Reimplemented in SphericalManifold< dim, spacedim >, and FlatManifold< dim, spacedim >.

virtualinherited 
Compute the normal vectors to the boundary at each vertex of the given face embedded in the Manifold. It is not required that the normal vectors be normed somehow. Neither is it required that the normals actually point outward.
This function is needed to compute data for C1 mappings. The default implementation calls normal_vector() on each vertex.
Note that when computing normal vectors at a vertex where the boundary is not differentiable, you have to make sure that you compute the onesided limits, i.e. limit with respect to points inside the given face.

inherited 
Subscribes a user of the object by storing the pointer validity
. The subscriber may be identified by text supplied as identifier
.
Definition at line 136 of file subscriptor.cc.

inherited 
Unsubscribes a user from the object.
identifier
and the validity
pointer must be the same as the one supplied to subscribe(). Definition at line 156 of file subscriptor.cc.

inlineinherited 
Return the present number of subscriptions to this object. This allows to use this class for reference counted lifetime determination where the last one to unsubscribe also deletes the object.
Definition at line 301 of file subscriptor.h.

inlineinherited 
List the subscribers to the input stream
.
Definition at line 318 of file subscriptor.h.

inherited 
List the subscribers to deallog
.
Definition at line 204 of file subscriptor.cc.

inlineinherited 
Read or write the data of this object to or from a stream for the purpose of serialization using the BOOST serialization library.
This function does not actually serialize any of the member variables of this class. The reason is that what this class stores is only who subscribes to this object, but who does so at the time of storing the contents of this object does not necessarily have anything to do with who subscribes to the object when it is restored. Consequently, we do not want to overwrite the subscribers at the time of restoring, and then there is no reason to write the subscribers out in the first place.
Definition at line 310 of file subscriptor.h.

privatenoexceptinherited 
Check that there are no objects subscribing to this object. If this check passes then it is safe to destroy the current object. It this check fails then this function will either abort or print an error message to deallog (by using the AssertNothrow mechanism), but will not throw an exception.
Definition at line 53 of file subscriptor.cc.

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 1088 of file manifold.h.

mutableprivateinherited 
Store the number of objects which subscribed to this object. Initially, this number is zero, and upon destruction it shall be zero again (i.e. all objects which subscribed should have unsubscribed again).
The creator (and owner) of an object is counted in the map below if HE manages to supply identification.
We use the mutable
keyword in order to allow subscription to constant objects also.
This counter may be read from and written to concurrently in multithreaded code: hence we use the std::atomic
class template.
Definition at line 219 of file subscriptor.h.

mutableprivateinherited 
In this map, we count subscriptions for each different identification string supplied to subscribe().
Definition at line 225 of file subscriptor.h.

mutableprivateinherited 
In this vector, we store pointers to the validity bool in the SmartPointer objects that subscribe to this class.
Definition at line 241 of file subscriptor.h.

mutableprivateinherited 
Pointer to the typeinfo object of this object, from which we can later deduce the class name. Since this information on the derived class is neither available in the destructor, nor in the constructor, we obtain it in between and store it here.
Definition at line 249 of file subscriptor.h.

staticprivateinherited 
A mutex used to ensure data consistency when accessing the mutable
members of this class. This lock is used in the subscribe() and unsubscribe() functions, as well as in list_subscribers()
.
Definition at line 272 of file subscriptor.h.