Regina Calculation Engine
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
regina::Face< dim, subdim > Class Template Reference

Represents a subdim-face in the skeleton of a dim-dimensional triangulation. More...

#include <generic/face.h>

Inheritance diagram for regina::Face< dim, subdim >:
regina::detail::FaceBase< dim, subdim > regina::Output< Face< dim, subdim > > regina::detail::FaceStorage< dim, dim - subdim > regina::detail::FaceValidity< allowsInvalidFaces(dim, subdim), standardDim(dim)> regina::detail::FaceOrientability< allowsNonOrientableLinks(dim, subdim)> regina::FaceNumbering< dim, subdim > regina::NMarkedElement regina::alias::FaceOfSimplex< FaceBase< dim, subdim >, dim, subdim - 1 > regina::detail::FaceNumberingImpl< dim, subdim,((dim+1) >=2 *(subdim+1))> regina::detail::FaceNumberingAPI< dim, subdim >

Public Member Functions

void writeTextShort (std::ostream &out) const
 Writes a short text representation of this face to the given output stream. More...
 
void writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this face to the given output stream. More...
 
size_t index () const
 Returns the index of this face within the underlying triangulation. More...
 
Triangulation< dim > * triangulation () const
 Returns the triangulation to which this face belongs. More...
 
REGINA_DEPRECATED Triangulation< dim > * getTriangulation () const
 Deprecated routine that returns the triangulation to which this face belongs. More...
 
Component< dim > * component () const
 Returns the component of the triangulation to which this face belongs. More...
 
REGINA_DEPRECATED Component< dim > * getComponent () const
 Deprecated routine that returns the component of the triangulation to which this face belongs. More...
 
template<int lowerdim>
Face< dim, lowerdim > * face (int face) const
 Returns the lowerdim-face of the underlying triangulation that appears as the given lowerdim-dimensional subface of this face. More...
 
template<int lowerdim>
NPerm< dim+1 > faceMapping (int face) const
 Examines the given lowerdim-dimensional subface of this face, and returns the mapping between the underlying lowerdim-face of the triangulation and the individual vertices of this face. More...
 
size_t degree () const
 Returns the degree of this face. More...
 
REGINA_DEPRECATED size_t getDegree () const
 Deprecated routine that returns the degree of this face. More...
 
const FaceEmbedding< dim, dim - codim > & embedding (size_t index) const
 Returns one of the ways in which this face appears within a top-dimensional simplex of the underlying triangluation. More...
 
REGINA_DEPRECATED const FaceEmbedding< dim, dim - codim > & getEmbedding (size_t index) const
 Deprecated routine that returns one of the ways in which this face appears within a top-dimensional simplex of the underlying triangulation. More...
 
std::vector< FaceEmbedding< dim, dim - codim > >::const_iterator begin () const
 A begin function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
 
std::vector< FaceEmbedding< dim, dim - codim > >::const_iterator end () const
 An end function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
 
const FaceEmbedding< dim, dim - codim > & front () const
 Returns the first appearance of this face within a top-dimensional simplex of the underlying triangluation. More...
 
const FaceEmbedding< dim, dim - codim > & back () const
 Returns the last appearance of this face within a top-dimensional simplex of the underlying triangluation. More...
 
bool isValid () const
 Determines if this face is valid. More...
 
bool hasBadIdentification () const
 Determines if this face is identified with itself under a non-identity permutation. More...
 
bool hasBadLink () const
 Determines if this face does not have an appropriate link. More...
 
bool isLinkOrientable () const
 Determines if the link of this face is orientable. More...
 
size_t markedIndex () const
 Returns the index at which this object is stored in an NMarkedVector. More...
 
std::string str () const
 Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 
REGINA_DEPRECATED std::string toString () const
 A deprecated alias for str(). More...
 
REGINA_DEPRECATED std::string toStringLong () const
 A deprecated alias for detail(). More...
 

Static Public Member Functions

static NPerm< dim+1 > ordering (unsigned face)
 Given a subdim-face number within a dim-dimensional simplex, returns the corresponding canonical ordering of the simplex vertices. More...
 
static unsigned faceNumber (NPerm< dim+1 > vertices)
 Identifies which subdim-face in a dim-dimensional simplex is represented by the first (subdim + 1) elements of the given permutation. More...
 
static bool containsVertex (unsigned face, unsigned vertex)
 Tests whether the given subdim-face of a dim-dimensional simplex contains the given vertex of the simplex. More...
 

Static Public Attributes

static constexpr int nFaces
 The total number of subdim-dimensional faces in each dim-dimensional simplex. More...
 

Protected Member Functions

 Face (Component< dim > *component)
 Creates a new face. More...
 
void push_back (const FaceEmbedding< dim, dim - codim > &emb)
 Internal routine to help build the skeleton of a triangulation. More...
 
void markBadIdentification ()
 Marks this face as having a non-identity self-identification. More...
 
void markBadLink ()
 Marks this face as having a bad link. More...
 
void markLinkNonorientable ()
 Marks the link of this face as non-orientable. More...
 

Friends

class Triangulation< dim >
 
class detail::TriangulationBase< dim >
 

Detailed Description

template<int dim, int subdim>
class regina::Face< dim, subdim >

Represents a subdim-face in the skeleton of a dim-dimensional triangulation.

A given subdim-face F of the triangulation may appear many times within the various top-dimensional simplices of the underlying triangulation. As an extreme example, in a 1-vertex triangulation of a 3-manifold, the single vertex makes 4n such appearances, where n is the total number of tetrahedra.

Each such appearance is described by a single FaceEmbedding object. You can iterate through these appearances using begin() and end(), or using a C++11 range-based for loop: for (auto& emb : F) { ... }. You can count these appearances by calling degree(), and you can also examine them using routines such as front(), back() and embedding().

Warning
Face objects are highly temporary: whenever a triangulation changes, all its face objects will be deleted and new ones will be created in their place.

If dim is one of Regina's standard dimensions, then this template is specialised to offer additional functionality. In order to use these specialised classes, you will need to include the corresponding headers (e.g., dim2/dim2edge.h for (dim, subdim) = (2, 1), or triangulation/nvertex.h for (dim, subdim) = (3, 0)). For convenience, there are typedefs for these specialised classes (such as Dim2Edge and NVertex respectively).

Python:
Python does not support templates. Instead this class can be used by appending dimensions dim and subdim as suffices (e.g., Face2_1 and Face3_0 for the two examples above). The typedefs mentioned above for standard dimensions (e.g., Dim2Edge and NVertex) are also available.
Template Parameters
dimthe dimension of the underlying triangulation. This must be between 2 and 15 inclusive.
subdimthe dimension of the faces that this class represents. This must be between 0 and dim-1 inclusive.

Constructor & Destructor Documentation

§ Face()

template<int dim, int subdim>
regina::Face< dim, subdim >::Face ( Component< dim > *  component)
inlineprotected

Creates a new face.

Parameters
componentthe component of the underlying triangulation to which the new face belongs.

Member Function Documentation

§ back()

const FaceEmbedding< dim, dim-2 > & regina::detail::FaceStorage< dim >::back ( ) const
inlineinherited

Returns the last appearance of this face within a top-dimensional simplex of the underlying triangluation.

This is equivalent to calling embedding(degree()-1).

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where the appearances of a face are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle). In particular, for a boundary face of codimension 2, both front() and back() will refer to the two appearances of this face on the (dim-1)-dimensional boundary.

Returns
details of the last appearance.

§ begin()

std::deque< FaceEmbedding< dim, dim-2 > >::const_iterator regina::detail::FaceStorage< dim >::begin ( ) const
inlineinherited

A begin function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where these appearances are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle).

An iteration from begin() to end() will run through degree() appearances in total.

Python:
Not present. However, Python users can call the Python-only routine embeddings(), which will return all appearances (from begin() through to end()) in a Python sequence.
Returns
a iterator that points to the first appearance.

§ component()

template<int dim, int subdim>
Component< dim > * regina::detail::FaceBase< dim, subdim >::component ( ) const
inlineinherited

Returns the component of the triangulation to which this face belongs.

Returns
the component containing this face.

§ degree()

size_t regina::detail::FaceStorage< dim >::degree ( ) const
inlineinherited

Returns the degree of this face.

This is the number of different ways in which the face appears within the various top-dimensional simplices of the underlying triangulation.

Note that if this face appears multiple times within the same top-dimensional simplex, then it will be counted multiple times by this routine.

Returns
the degree of this face.

§ detail()

std::string regina::Output< Face< dim, subdim > , false >::detail ( ) const
inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns
a detailed text representation of this object.

§ embedding()

const FaceEmbedding< dim, dim-2 > & regina::detail::FaceStorage< dim >::embedding ( size_t  index) const
inlineinherited

Returns one of the ways in which this face appears within a top-dimensional simplex of the underlying triangluation.

For convenience, you can also use begin() and end() to iterate through all such appearances.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where these appearances are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle).

Parameters
indexthe index of the requested appearance. This must be between 0 and degree()-1 inclusive.
Returns
details of the requested appearance.

§ end()

std::deque< FaceEmbedding< dim, dim-2 > >::const_iterator regina::detail::FaceStorage< dim >::end ( ) const
inlineinherited

An end function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where these appearances are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle).

An iteration from begin() to end() will run through degree() appearances in total.

Python:
Not present. However, Python users can call the Python-only routine embeddings(), which will return all appearances (from begin() through to end()) in a Python sequence.
Returns
a "beyond the end" iterator that comes immediately after the last appearance.

§ face()

template<int dim, int subdim>
template<int lowerdim>
Face< dim, lowerdim > * regina::detail::FaceBase< dim, subdim >::face ( int  face) const
inlineinherited

Returns the lowerdim-face of the underlying triangulation that appears as the given lowerdim-dimensional subface of this face.

The argument face must represent a lowerdim-face number within a subdim-simplex. This lowerdim-face number will be interpreted with respect to the inherent labelling (0, ..., subdim) of the vertices of this subdim-face. See FaceEmbedding<dim, subdim>::vertices() for details on how these map to the vertex numbers of the dim-dimensional simplices that contain this face in the overall triangulation.

See FaceNumbering<subdim, lowerdim> for the conventions of how lowerdim-faces are numbered within a subdim-simplex.

Python:
Python does not support templates. Instead, Python users should call this function in the form face(lowerdim, face); that is, the template parameter lowerdim becomes the first argument of the function.
Parameters
facethe lowerdim-face of this subdim-face to examine. This should be between 0 and (subdim+1 choose lowerdim+1)-1 inclusive.
Returns
the corresponding lowerdim-face of the triangulation.

§ faceMapping()

template<int dim, int subdim>
template<int lowerdim>
NPerm< dim+1 > regina::detail::FaceBase< dim, subdim >::faceMapping ( int  face) const
inherited

Examines the given lowerdim-dimensional subface of this face, and returns the mapping between the underlying lowerdim-face of the triangulation and the individual vertices of this face.

The argument face must represent a lowerdim-face number within a subdim-simplex. This lowerdim-face number will be interpreted with respect to the inherent labelling (0, ..., subdim) of the vertices of this subdim-face. See FaceEmbedding<dim, subdim>::vertices() for details on how these map to the vertex numbers of the dim-dimensional simplices that contain this face in the overall triangulation.

Let F denote this subdim-face of the triangulation, and let L denote the lowerdim-face of the triangulation that corresponds to the given subface of F. Then the permutation returned by this routine maps the vertex numbers (0, ..., lowerdim) of L to the corresponding vertex numbers of F. This is with respect to the inherent labellings (0, ..., lowerdim) and (0, ..., subdim) of the vertices of L and F respectively.

In particular, if this routine returns the permutation p, then the images p[0,...,lowerdim] will be some permutation of the vertices Face<subdim, lowerdim>::ordering(face)[0,...,lowerdim].

This routine differs from Simplex<dim>::faceMapping<lowerdim>() in how it handles the images of (lowerdim+1, ..., dim):

  • This routine will map (lowerdim+1, ..., subdim) to the remaining vertices of this face in an arbitrary order, and will map (subdim+1, ..., dim) to (subdim+1, ..., dim) again in an arbitrary order.
  • In contrast, Simplex<dim>::faceMapping<lowerdim>() chooses the images of (lowerdim+1, ..., dim) to satisfy an additional orientability constraint.

See FaceNumbering<subdim, lowerdim> for the conventions of how lowerdim-faces are numbered within a subdim-simplex.

Python:
Python does not support templates. Instead, Python users should call this function in the form faceMapping(lowerdim, face); that is, the template parameter lowerdim becomes the first argument of the function.
Parameters
facethe lowerdim-face of this subdim-face to examine. This should be between 0 and (subdim+1 choose lowerdim+1)-1 inclusive.
Returns
a mapping from the vertices of the underlying lowerdim-face of the triangulation to the vertices of this subdim-face.

§ front()

const FaceEmbedding< dim, dim-2 > & regina::detail::FaceStorage< dim >::front ( ) const
inlineinherited

Returns the first appearance of this face within a top-dimensional simplex of the underlying triangluation.

This is equivalent to calling *begin(), or embedding(0).

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where the appearances of a face are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle). In particular, for a boundary face of codimension 2, both front() and back() will refer to the two appearances of this face on the (dim-1)-dimensional boundary.

Returns
details of the first appearance.

§ getComponent()

template<int dim, int subdim>
Component< dim > * regina::detail::FaceBase< dim, subdim >::getComponent ( ) const
inlineinherited

Deprecated routine that returns the component of the triangulation to which this face belongs.

Deprecated:
Simply call component() instead.

See component() for further details.

§ getDegree()

size_t regina::detail::FaceStorage< dim >::getDegree ( ) const
inlineinherited

Deprecated routine that returns the degree of this face.

Deprecated:
Simply call degree() instead.

See degree() for further details.

§ getEmbedding()

const FaceEmbedding< dim, dim-2 > & regina::detail::FaceStorage< dim >::getEmbedding ( size_t  index) const
inlineinherited

Deprecated routine that returns one of the ways in which this face appears within a top-dimensional simplex of the underlying triangulation.

Deprecated:
Simply call embedding() instead.

See embedding() for further details.

§ getTriangulation()

template<int dim, int subdim>
Triangulation< dim > * regina::detail::FaceBase< dim, subdim >::getTriangulation ( ) const
inlineinherited

Deprecated routine that returns the triangulation to which this face belongs.

Deprecated:
Simply call triangulation() instead.

See triangulation() for further details.

§ hasBadIdentification()

bool regina::detail::FaceValidity< allowsInvalid, testLinks >::hasBadIdentification ( ) const
inherited

Determines if this face is identified with itself under a non-identity permutation.

For example, if this face is an edge then this routine tests whether the edge is identified with itself in reverse.

Such a face will always be marked as invalid. Note that, for standard dimensions dim, there are other types of invalid faces also. See isValid() for a full discussion of what it means for a face to be valid.

Returns
true if and only if this face is identified with itself under a non-identity permutation.

§ hasBadLink()

bool regina::detail::FaceValidity< allowsInvalid, testLinks >::hasBadLink ( ) const
inherited

Determines if this face does not have an appropriate link.

See condition (2) in the documentation for isValid() for a full description of what "appropriate" means.

This routine is only available where dim is one of Regina's standard dimensions, since testing this condition in arbitrary dimensions is undecidable. For higher dimensions dim, this routine is not present.

A face whose link is not appropriate will always be marked as invalid. Note that there are other types of invalid faces also. See isValid() for a full discussion of what it means for a face to be valid.

Returns
true if and only if the link of this face is not appropriate.

§ index()

template<int dim, int subdim>
size_t regina::detail::FaceBase< dim, subdim >::index ( ) const
inlineinherited

Returns the index of this face within the underlying triangulation.

This is identical to calling the deprecated function triangulation()->vertexIndex(this) for faces of dimension subdim = 1, or triangulation()->edgeIndex(this) for faces of dimension subdim = 2, or so on.

Returns
the index of this face.

§ isLinkOrientable()

bool regina::detail::FaceOrientability< allowsNonorientable >::isLinkOrientable ( ) const
inherited

Determines if the link of this face is orientable.

This routine is fast: it uses pre-computed information, and does not need to build a full triangulation of the link.

Warning
If this face is identified with itself under a non-identity permutation (which makes the face invalid), then the return value of this routine is undefined.
Returns
true if and only if the link is orientable.

§ isValid()

bool regina::detail::FaceValidity< allowsInvalid, testLinks >::isValid ( ) const
inherited

Determines if this face is valid.

There are several conditions that might make a subdim-face of a dim-dimensional triangulation invalid:

  1. if the face is identified with itself under a non-identity permutation (e.g., an edge is identified with itself in reverse, or a triangle is identified with itself under a rotation);
  2. if the face does not have an appropriate link. Here the meaning of "appropriate" depends upon the type of face:
    • for a face that belongs to some boundary facet(s) of the triangulation, its link must be a topological ball;
    • for a vertex that does not belong to any boundary facets, its link must be a closed (dim - 1)-manifold;
    • for a (subdim ≥ 1)-face that does not belong to any boundary facets, its link must be a topological sphere.

Condition (1) is tested for all dimensions subdim and dim. Condition (2) is more difficult, since it relies on undecidable problems. As a result, (2) is only tested when dim is one of Regina's standard dimensions.

If this face is invalid, then it is possible to find out why. In non-standard dimensions, this must mean that the face fails condition (1) above. In standard dimensions, you can call the functions hasBadIdentification() and/or hasBadLink() to determine whether the failure is due to conditions (1) or (2) respectively.

Returns
for standard dimensions dim, returns true if and only if this face is valid according to both conditions (1) and (2) above; for non-standard dimensions dim, returns true if and only if this face is valid according to condition (1).

§ markBadIdentification()

void regina::detail::FaceValidity< allowsInvalid, testLinks >::markBadIdentification ( )
protectedinherited

Marks this face as having a non-identity self-identification.

§ markBadLink()

void regina::detail::FaceValidity< allowsInvalid, testLinks >::markBadLink ( )
protectedinherited

Marks this face as having a bad link.

§ markedIndex()

size_t regina::NMarkedElement::markedIndex ( ) const
inlineinherited

Returns the index at which this object is stored in an NMarkedVector.

If this object does not belong to an NMarkedVector, the return value is undefined.

Returns
the index at which this object is stored.

§ markLinkNonorientable()

void regina::detail::FaceOrientability< allowsNonorientable >::markLinkNonorientable ( )
protectedinherited

Marks the link of this face as non-orientable.

§ push_back()

void regina::detail::FaceStorage< dim >::push_back ( const FaceEmbedding< dim, dim - codim > &  emb)
inlineprotectedinherited

Internal routine to help build the skeleton of a triangulation.

This routine pushes the given object onto the end of the internal list of appearances of this face within top-dimensional simplices.

Parameters
embthe appearance to push onto the end of the internal list.

§ str()

std::string regina::Output< Face< dim, subdim > , false >::str ( ) const
inherited

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
In addition to str(), this is also used as the Python "stringification" function __str__().
Returns
a short text representation of this object.

§ toString()

REGINA_DEPRECATED std::string regina::Output< Face< dim, subdim > , false >::toString ( ) const
inherited

A deprecated alias for str().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type str() instead.
Returns
a short text representation of this object.

§ toStringLong()

REGINA_DEPRECATED std::string regina::Output< Face< dim, subdim > , false >::toStringLong ( ) const
inherited

A deprecated alias for detail().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.
Returns
a long text representation of this object.

§ triangulation()

template<int dim, int subdim>
Triangulation< dim > * regina::detail::FaceBase< dim, subdim >::triangulation ( ) const
inlineinherited

Returns the triangulation to which this face belongs.

Returns
the triangulation containing this face.

§ utf8()

std::string regina::Output< Face< dim, subdim > , false >::utf8 ( ) const
inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
a short text representation of this object.

§ writeTextLong()

template<int dim, int subdim>
void regina::Face< dim, subdim >::writeTextLong ( std::ostream &  out) const
inline

Writes a detailed text representation of this face to the given output stream.

Python:
Not present.
Parameters
outthe output stream to which to write.

§ writeTextShort()

template<int dim, int subdim>
void regina::Face< dim, subdim >::writeTextShort ( std::ostream &  out) const
inline

Writes a short text representation of this face to the given output stream.

Python:
Not present.
Parameters
outthe output stream to which to write.

Member Data Documentation

§ nFaces

constexpr int regina::detail::FaceNumberingImpl< dim, subdim, lex >::nFaces
staticinherited

The total number of subdim-dimensional faces in each dim-dimensional simplex.


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

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).