Regina 7.3 Calculation Engine
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Static Protected Attributes | Friends | List of all members
regina::Face< 3, 0 > Class Reference

Represents a vertex in the skeleton of a 3-manifold triangulation. More...

#include <triangulation/dim3.h>

Inheritance diagram for regina::Face< 3, 0 >:
regina::detail::FaceBase< 3, 0 > regina::FaceNumbering< dim, subdim > regina::MarkedElement regina::ShortOutput< Face< dim, subdim > > regina::detail::FaceNumberingImpl< dim, subdim, codim > regina::Output< Face< dim, subdim >, false > regina::detail::FaceNumberingAPI< dim, subdim >

Public Types

enum  LinkType {
  SPHERE = 1 , DISC = 2 , TORUS = 3 , KLEIN_BOTTLE = 4 ,
  NON_STANDARD_CUSP = 5 , INVALID = 6
}
 Categorises the possible links of a vertex into a small number of common types. More...
 

Public Member Functions

 ~Face ()
 Default destructor. More...
 
LinkType linkType () const
 Returns a broad categorisation of the link of the vertex. More...
 
const Triangulation< 2 > & buildLink () const
 Returns a full 2-manifold triangulation describing the link of this vertex. More...
 
Isomorphism< 3 > buildLinkInclusion () const
 Returns details of how the triangles are labelled in the link of this vertex. More...
 
bool isLinkClosed () const
 Determines if the link of this vertex is closed. More...
 
bool isIdeal () const
 Determines if this vertex is an ideal vertex. More...
 
bool isStandard () const
 Determines if this vertex is standard. More...
 
long linkEulerChar () const
 Returns the Euler characteristic of the vertex link. More...
 
NormalSurface linkingSurface () const
 Returns the link of this vertex as a normal surface. 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...
 
Component< dim > * component () const
 Returns the component of the triangulation to which this face belongs. More...
 
BoundaryComponent< dim > * boundaryComponent () const
 Returns the boundary component of the triangulation to which this face belongs. More...
 
bool isBoundary () const
 Determines if this face lies entirely on the boundary of the triangulation. More...
 
size_t degree () const
 Returns the degree of this face. More...
 
const FaceEmbedding< dim, subdim > & 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...
 
auto embeddings () const
 Returns an object that allows iteration through and random access to all of the ways in which this face appears within a top-dimensional simplex of the underlying triangluation. More...
 
auto begin () const
 A C++ begin function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
 
auto end () const
 A C++ end function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
 
auto __iter__ () const
 Provides Python support for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
 
const FaceEmbedding< dim, subdim > & front () const
 Returns the first appearance of this face within a top-dimensional simplex of the underlying triangluation. More...
 
const FaceEmbedding< dim, subdim > & back () const
 Returns the last appearance of this face within a top-dimensional simplex of the underlying triangluation. More...
 
bool inMaximalForest () const
 Determines whether a codimension-1-face represents a dual edge in the maximal forest that has been chosen for the dual 1-skeleton of the triangulation. More...
 
bool isLinkOrientable () const
 Determines if the link of this face is orientable. 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...
 
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...
 
Face< dim, 0 > * vertex (int i) const
 A dimension-specific alias for face<0>(). More...
 
Face< dim, 1 > * edge (int i) const
 A dimension-specific alias for face<1>(). More...
 
Face< dim, 2 > * triangle (int i) const
 A dimension-specific alias for face<2>(). More...
 
Face< dim, 3 > * tetrahedron (int i) const
 A dimension-specific alias for face<3>(). More...
 
Face< dim, 4 > * pentachoron (int i) const
 A dimension-specific alias for face<4>(). More...
 
Perm< 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...
 
Perm< dim+1 > vertexMapping (int face) const
 A dimension-specific alias for faceMapping<0>(). More...
 
Perm< dim+1 > edgeMapping (int face) const
 A dimension-specific alias for faceMapping<1>(). More...
 
Perm< dim+1 > triangleMapping (int face) const
 A dimension-specific alias for faceMapping<2>(). More...
 
Perm< dim+1 > tetrahedronMapping (int face) const
 A dimension-specific alias for faceMapping<3>(). More...
 
Perm< dim+1 > pentachoronMapping (int face) const
 A dimension-specific alias for faceMapping<4>(). More...
 
void writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
size_t markedIndex () const
 Returns the index at which this object is stored in an MarkedVector. More...
 
void writeTextLong (std::ostream &out) const
 A default implementation for detailed output. 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...
 

Static Public Member Functions

static constexpr Perm< dim+1 > ordering (int face)
 Given a subdim-face number within a dim-dimensional simplex, returns the corresponding canonical ordering of the simplex vertices. More...
 
static constexpr int faceNumber (Perm< 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 constexpr bool containsVertex (int face, int 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 dimension
 A compile-time constant that gives the dimension of the triangulation containing this face. More...
 
static constexpr int subdimension
 A compile-time constant that gives the dimension of this face. More...
 
static constexpr bool allowsNonOrientableLinks
 Indicates whether it is possible for a face of this dimension to have a non-orientable link. More...
 
static constexpr bool allowsInvalidFaces
 Indicates whether it is possible for a face of this dimension to be invalid. More...
 
static constexpr int oppositeDim = (dim - 1 - subdim)
 The dimension of the faces opposite these in a top-dimensional simplex of a dim-dimensional triangulation. More...
 
static constexpr bool lexNumbering = (subdim <= oppositeDim)
 true if faces are numbered in lexicographical order according to their vertices, or false if faces are numbered in reverse lexicographical order. More...
 
static constexpr int nFaces = binomSmall(dim + 1, lexDim + 1)
 The total number of subdim-dimensional faces in each dim-dimensional simplex. More...
 

Static Protected Attributes

static constexpr int lexDim = (lexNumbering ? subdim : oppositeDim)
 Whichever of subdim or oppositeDim uses lexicographical face numbering. More...
 

Friends

class Triangulation< 3 >
 
class detail::TriangulationBase< 3 >
 

Detailed Description

Represents a vertex in the skeleton of a 3-manifold triangulation.

This is a specialisation of the generic Face class template; see the documentation for Face for a general overview of how this class works.

These specialisations for Regina's standard dimensions offer significant extra functionality.

Vertices do not support value semantics: they cannot be copied, swapped, or manually constructed. Their location in memory defines them, and they are often passed and compared by pointer. End users are never responsible for their memory management; this is all taken care of by the Triangulation to which they belong.

Member Enumeration Documentation

◆ LinkType

enum regina::Face< 3, 0 >::LinkType

Categorises the possible links of a vertex into a small number of common types.

Here a vertex link is considered only up to its topology (not the combinatorics of its triangulation).

See also
Knots and Links
Enumerator
SPHERE 

Specifies a vertex link that is a sphere.

In other words, the vertex is internal.

DISC 

Specifies a vertex link that is a disc.

In other words, the vertex lies on a real boundary component.

TORUS 

Specifies a vertex link that is a torus.

In other words, this is an ideal vertex representing a torus cusp.

KLEIN_BOTTLE 

Specifies a vertex link that is a Klein bottle.

In other words, this is an ideal vertex representing a Klein bottle cusp.

NON_STANDARD_CUSP 

Specifies a vertex link that is closed and is not a sphere, torus or Klein bottle.

In other words, this is an ideal vertex but not one of the standard ideal vertex types.

INVALID 

Specifies a vertex link that has boundary and is not a disc.

In other words, this vertex makes the triangulation invalid.

Constructor & Destructor Documentation

◆ ~Face()

regina::Face< 3, 0 >::~Face ( )

Default destructor.

Member Function Documentation

◆ __iter__()

auto regina::detail::FaceBase< dim, subdim >::__iter__ ( ) const
inherited

Provides Python support 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).

Iterating over this face will run through degree() appearances in total. This is also equivalent to iterating over embeddings(): iterating directly over a face generates a tiny bit less overhead, but you may also find it to be less readable. In particular, the following three blocks of code are all equivalent:

for emb in face:
...
for emb in face.embeddings():
...
for i in range(face.degree()):
emb = face.embedding(i)
...
C++
Not present. For C++ users, Face provides the usual begin() and end() functions instead. In particular, you can iterate over the appearances of this face in the usual way using a range-based for loop.
Returns
an iterator over all the appearances of this face.

◆ back()

const FaceEmbedding< dim, subdim > & regina::detail::FaceBase< dim, subdim >::back
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()

auto regina::detail::FaceBase< dim, subdim >::begin
inlineinherited

A C++ 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.

The type that is returned will be a lightweight iterator type, guaranteed to satisfy the C++ LegacyRandomAccessIterator requirement. The precise C++ type of the iterator is subject to change, so C++ users should use auto (just like this declaration does).

Iterating from begin() to end() (that is, iterating directly over a face) is equivalent to iterating over embeddings(). Iterating directly over a face generates a tiny bit less overhead, but you may also find it to be less readable. In particular, the following three blocks of code are all equivalent:

Face<dim, subdim>* face = ...;
for (const auto& emb : *face) { ... }
Face< dim, lowerdim > * face(int face) const
Returns the lowerdim-face of the underlying triangulation that appears as the given lowerdim-dimensio...
Definition: face.h:1183
Face<dim, subdim>* face = ...;
for (const auto& emb : face->embeddings()) { ... }
Face<dim, subdim>* face = ...;
for (size_t i = 0; i < face->degree(); ++i) {
const auto& emb = face->embedding(i);
...
}
Python
Not present. For Python users, Face implements the Python iterable interface. You can iterate over this face in the same way that you would iterate over any native Python container.
Returns
a iterator that points to the first appearance.

◆ boundaryComponent()

BoundaryComponent< dim > * regina::detail::FaceBase< dim, subdim >::boundaryComponent
inlineinherited

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

See the note in the BoundaryComponent overview regarding what happens if the link of the face itself has more than one boundary component. Note that such a link makes both the face and the underlying triangulation invalid.

For dimensions in which ideal and/or invalid vertices are both possible and recognised: an ideal vertex will have its own individual boundary component to which it belongs, and so will an invalid vertex boundary component if the invalid vertex does not already belong to some real boundary component.

Returns
the boundary component containing this face, or null if this face does not lie entirely within the boundary of the triangulation.

◆ buildLink()

const Triangulation< 2 > & regina::Face< 3, 0 >::buildLink ( ) const

Returns a full 2-manifold triangulation describing the link of this vertex.

This routine is fast (it uses a pre-computed triangulation if possible). The downside is that the triangulation is read-only (though you can always clone it).

Regarding the labelling of triangles in the vertex link:

  • The triangles of the vertex link are numbered as follows. Let i lie between 0 and degree()-1 inclusive, let tet represent embedding(i).tetrahedron(), and let v represent embedding(i).vertex(). Then buildLink()->triangle(i) is the triangle in the vertex link that "slices off" vertex v from tetrahedron tet. In other words, buildLink()->triangle(i) in the vertex link is parallel to triangle tet->triangle(v) in the surrounding 3-manifold triangulation.
  • The vertices of each triangle in the vertex link are numbered as follows. Following the discussion above, suppose that buildLink()->triangle(i) sits within tet and is parallel to tet->triangle(v). Then vertices 0,1,2 of the triangle in the link will be parallel to vertices 0,1,2 of the corresponding Triangle<3>. The permutation tet->triangleMapping(v) will map vertices 0,1,2 of the triangle in the link to the corresponding vertices of tet (those opposite v), and will map 3 to v itself.
  • If you need this labelling data in a format that is easy to compute with, you can call buildLinkInclusion() to retrieve this information as an isomorphism.
Python
Since Python does not distinguish between const and non-const, this routine will return by value (thus making a deep copy of the vertex link). You are free to modify the triangulation that is returned.
Returns
the read-only triangulated link of the vertex.

◆ buildLinkInclusion()

Isomorphism< 3 > regina::Face< 3, 0 >::buildLinkInclusion ( ) const

Returns details of how the triangles are labelled in the link of this vertex.

This is a companion function to buildLink(), which returns a full 2-manifold triangulation of the vertex link.

The documentation for buildLink() describes in plain English exactly how the vertex link will be triangulated. This function essentially returns the same information in a machine-readable form.

Specifically, this function returns an Isomorphism<3> that describes how the individual triangles of the link sit within the tetrahedra of the original triangulation. If p is the isomorphism returned, then p.tetImage(i) will indicate which tetrahedron tet of the 3-manifold triangulation contains the ith triangle of the link. Moreover, p.facePerm(i) will indicate exactly where the ith triangle sits within tet: it will send 3 to the vertex of t that the triangle links, and it will send 0,1,2 to the vertices of tet that are parallel to vertices 0,1,2 of this triangle.

Strictly speaking, this is an abuse of the Isomorphism<3> class (the domain is a triangulation of the wrong dimension, and the map is not 1-to-1 into the range tetrahedra). We use it anyway, but you should not attempt to call any high-level routines (such as Isomorphism<3>::apply).

This is the same isomorphism that was accessible through the old buildLinkDetail() function in Regina 6.0.1 and earlier.

Returns
details of how buildLink() labels the triangles of the vertex link.

◆ component()

Component< dim > * regina::detail::FaceBase< dim, subdim >::component
inlineinherited

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

Returns
the component containing this face.

◆ containsVertex()

template<int dim, int subdim>
static constexpr bool regina::detail::FaceNumberingAPI< dim, subdim >::containsVertex ( int  face,
int  vertex 
)
staticconstexprinherited

Tests whether the given subdim-face of a dim-dimensional simplex contains the given vertex of the simplex.

Parameters
facea subdim-face number in a dim-simplex; this must be between 0 and (dim+1 choose subdim+1)-1 inclusive.
vertexa vertex number in a dim-simplex; this must be between 0 and dim inclusive.
Returns
true if and only if the given subdim-face contains the given vertex.

◆ degree()

size_t regina::detail::FaceBase< dim, subdim >::degree
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 > , supportsUtf8 >::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.

◆ edge()

Face< dim, 1 > * regina::detail::FaceBase< dim, subdim >::edge ( int  i) const
inlineinherited

A dimension-specific alias for face<1>().

This alias is available for all facial dimensions subdim.

See face() for further information.

◆ edgeMapping()

Perm< dim+1 > regina::detail::FaceBase< dim, subdim >::edgeMapping ( int  face) const
inlineinherited

A dimension-specific alias for faceMapping<1>().

This alias is available for all facial dimensions subdim.

See faceMapping() for further information.

◆ embedding()

const FaceEmbedding< dim, subdim > & regina::detail::FaceBase< dim, subdim >::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, or equivalently you can iterate over the lightweight object returned by embeddings().

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.

◆ embeddings()

auto regina::detail::FaceBase< dim, subdim >::embeddings
inlineinherited

Returns an object that allows iteration through and random access to all of the ways in which this face appears within a top-dimensional simplex of the underlying triangluation.

The object that is returned is lightweight, and can be happily copied by value. The C++ type of the object is subject to change, so C++ users should use auto (just like this declaration does).

The returned object is guaranteed to be an instance of ListView, which means it offers basic container-like functions and supports range-based for loops. The elements of the list will be read-only objects of type FaceEmbedding<dim, subdim>. For example, your code might look like:

Face<dim, subdim>* face = ...;
for (const auto& emb : face->embeddings()) { ... }

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).

Using embeddings() is equivalent to iterating over the face itself. It generates a tiny amount of extra overhead, but also may be considered more readable. In particular, the code above is equivalent to both of the following alternatives:

Face<dim, subdim>* face = ...;
for (const auto& emb : *face) { ... }
Face<dim, subdim>* face = ...;
for (size_t i = 0; i < face->degree(); ++i) {
const auto& emb = face->embedding(i);
...
}
Returns
access to the list of all appearances of this face within a top-dimensional simplex of the underlying triangulation.

◆ end()

auto regina::detail::FaceBase< dim, subdim >::end
inlineinherited

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

See begin() for full details on how this iteration works, and what other alternatives are available.

The type that is returned will be a lightweight iterator type, guaranteed to satisfy the C++ LegacyRandomAccessIterator requirement. The precise C++ type of the iterator is subject to change, so C++ users should use auto (just like this declaration does).

Python
Not present. For Python users, Face implements the Python iterable interface. You can iterate over this face in the same way that you would iterate over any native Python container.
Returns
a "beyond the end" iterator that comes immediately after the last appearance.

◆ face()

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.

Precondition
The dimension of this face (subdim) is strictly positive (i.e., this face is not a vertex). Note that, without this constraint, there are no possible values for the template parameter lowerdim.
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.
Template Parameters
lowerdimthe dimension of subface to examine. This must be between 0 and (subdim - 1) inclusive.
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()

Perm< 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.

Precondition
The dimension of this face (subdim) is strictly positive (i.e., this face is not a vertex). Note that, without this constraint, there are no possible values for the template parameter lowerdim.
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.
Template Parameters
lowerdimthe dimension of subface to examine. This must be between 0 and (subdim - 1) inclusive.
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.

◆ faceNumber()

template<int dim, int subdim>
static constexpr int regina::detail::FaceNumberingAPI< dim, subdim >::faceNumber ( Perm< dim+1 >  vertices)
staticconstexprinherited

Identifies which subdim-face in a dim-dimensional simplex is represented by the first (subdim + 1) elements of the given permutation.

In other words, this routine identifies which subdim-face number within a dim-dimensional simplex spans vertices vertices[0, ..., subdim].

Parameters
verticesa permutation whose first (subdim + 1) elements represent some vertex numbers in a dim-simplex.
Returns
the corresponding subdim-face number in the dim-simplex. This will be between 0 and (dim+1 choose subdim+1)-1 inclusive.

◆ front()

const FaceEmbedding< dim, subdim > & regina::detail::FaceBase< dim, subdim >::front
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.

◆ hasBadIdentification()

bool regina::detail::FaceBase< dim, subdim >::hasBadIdentification
inlineinherited

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::FaceBase< dim, subdim >::hasBadLink
inlineinherited

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.

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.

Precondition
The dimension dim is one of Regina's standard dimensions. Any attempt to use this routine in higher dimensions dim will result in a compile-time error. This is because testing for bad links in higher dimensions can require solutions to problems that are proven to be undecidable.
Returns
true if the link of this face is not appropriate (thereby making the face invalid), or false if the link is appropriate.

◆ index()

size_t regina::detail::FaceBase< dim, subdim >::index
inlineinherited

Returns the index of this face within the underlying triangulation.

Returns
the index of this face.

◆ inMaximalForest()

bool regina::detail::FaceBase< dim, subdim >::inMaximalForest
inlineinherited

Determines whether a codimension-1-face represents a dual edge in the maximal forest that has been chosen for the dual 1-skeleton of the triangulation.

This routine is only available for faces of codimension 1; that is, (dim-1)-faces of a dim-dimensional triangulation.

When the skeletal structure of a triangulation is first computed, a maximal forest in the dual 1-skeleton of the triangulation is also constructed. Each dual edge in this maximal forest represents a (dim-1)-face of the (primal) triangulation.

This maximal forest will remain fixed until the triangulation changes, at which point it will be recomputed (as will all other skeletal objects, such as connected components and so on). There is no guarantee that, when it is recomputed, the maximal forest will use the same dual edges as before.

This routine identifies whether this (dim-1)-face belongs to the dual forest. In this sense it performs a similar role to Simplex::facetInMaximalForest(), but this routine is typically easier to use.

If the skeleton has already been computed, then this routine is very fast (since it just returns a precomputed answer).

Precondition
The facial dimension subdim is precisely dim-1.
Returns
true if and only if this (dim-1)-face represents a dual edge in the maximal forest.

◆ isBoundary()

bool regina::detail::FaceBase< dim, subdim >::isBoundary
inlineinherited

Determines if this face lies entirely on the boundary of the triangulation.

For dimensions in which ideal and/or invalid vertices are both possible and recognised: both ideal and invalid vertices are considered to be on the boundary.

Returns
true if and only if this face lies on the boundary.

◆ isIdeal()

bool regina::Face< 3, 0 >::isIdeal ( ) const
inline

Determines if this vertex is an ideal vertex.

This requires the vertex link to be closed and not a 2-sphere.

Returns
true if and only if this is an ideal vertex.

◆ isLinkClosed()

bool regina::Face< 3, 0 >::isLinkClosed ( ) const
inline

Determines if the link of this vertex is closed.

Returns
true if and only if the link of this vertex is closed.

◆ isLinkOrientable()

bool regina::detail::FaceBase< dim, subdim >::isLinkOrientable
inlineinherited

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.

◆ isStandard()

bool regina::Face< 3, 0 >::isStandard ( ) const
inline

Determines if this vertex is standard.

This requires the vertex link to be a sphere, disc, torus or Klein bottle.

Returns
true if and only if this vertex is standard.

◆ isValid()

bool regina::detail::FaceBase< dim, subdim >::isValid
inlineinherited

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).

◆ linkEulerChar()

long regina::Face< 3, 0 >::linkEulerChar ( ) const
inline

Returns the Euler characteristic of the vertex link.

This routine does not require a full triangulation of the vertex link, and so can be much faster than calling buildLink().eulerChar().

Returns
the Euler characteristic of the vertex link.

◆ linkingSurface()

NormalSurface regina::Face< 3, 0 >::linkingSurface ( ) const
inline

Returns the link of this vertex as a normal surface.

Note that vertex linking surfaces only ever contain triangles (not quadrilaterals). Moreover, vertex links are always thin (i.e., after constructing the frontier of a regular neighbourhood of the vertex, no further normalisation steps are required).

Returns
the corresponding vertex linking normal surface.

◆ linkType()

Vertex< 3 >::LinkType regina::Face< 3, 0 >::linkType ( ) const
inline

Returns a broad categorisation of the link of the vertex.

This considers topological information only, not the combinatorics of how the link is triangulated.

This routine does not require a full triangulation of the vertex link, and so can be much faster than analysing the result of buildLink().

This is the routine that used to be called link() in Regina 6.0.1 and earlier. It was renamed to linkType() in Regina 7.0, to clear the way for a different routine to be called link() in the future.

Returns
a broad categorisation of the vertex link.

◆ markedIndex()

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

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

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

Returns
the index at which this object is stored.

◆ ordering()

template<int dim, int subdim>
static constexpr Perm< dim+1 > regina::detail::FaceNumberingAPI< dim, subdim >::ordering ( int  face)
staticconstexprinherited

Given a subdim-face number within a dim-dimensional simplex, returns the corresponding canonical ordering of the simplex vertices.

If this canonical ordering is c, then c[0,...,subdim] will be the vertices of the given face in increasing numerical order. That is, c[0] < ... < c[subdim]. The remaining images c[(subdim + 1),...,dim] will be ordered arbitrarily.

Note that this is not the same permutation as returned by Simplex<dim>::faceMapping<subdim>():

  • ordering() is a static function, which returns the same permutation for the same face number, regardless of which dim-simplex we are looking at. The images of 0,...,subdim will always appear in increasing order, and the images of (subdim + 1),...,dim will be arbitrary.
  • faceMapping() examines the underlying face F of the triangulation and, across all appearances of F in different dim-simplices: (i) chooses the images of 0,...,subdim to map to the same respective vertices of F; and (ii) chooses the images of (subdim + 1),...,dim to maintain a "consistent orientation" constraint.
Parameters
faceidentifies which subdim-face of a dim-dimensional simplex to query. This must be between 0 and (dim+1 choose subdim+1)-1 inclusive.
Returns
the corresponding canonical ordering of the simplex vertices.

◆ pentachoron()

Face< dim, 4 > * regina::detail::FaceBase< dim, subdim >::pentachoron ( int  i) const
inlineinherited

A dimension-specific alias for face<4>().

This alias is available for facial dimensions subdim ≥ 5.

See face() for further information.

◆ pentachoronMapping()

Perm< dim+1 > regina::detail::FaceBase< dim, subdim >::pentachoronMapping ( int  face) const
inlineinherited

A dimension-specific alias for faceMapping<4>().

This alias is available for facial dimensions subdim ≥ 5.

See faceMapping() for further information.

◆ str()

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

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python
The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.
Returns
a short text representation of this object.

◆ tetrahedron()

Face< dim, 3 > * regina::detail::FaceBase< dim, subdim >::tetrahedron ( int  i) const
inlineinherited

A dimension-specific alias for face<3>().

This alias is available for facial dimensions subdim ≥ 4.

See face() for further information.

◆ tetrahedronMapping()

Perm< dim+1 > regina::detail::FaceBase< dim, subdim >::tetrahedronMapping ( int  face) const
inlineinherited

A dimension-specific alias for faceMapping<3>().

This alias is available for facial dimensions subdim ≥ 4.

See faceMapping() for further information.

◆ triangle()

Face< dim, 2 > * regina::detail::FaceBase< dim, subdim >::triangle ( int  i) const
inlineinherited

A dimension-specific alias for face<2>().

This alias is available for facial dimensions subdim ≥ 3.

See face() for further information.

◆ triangleMapping()

Perm< dim+1 > regina::detail::FaceBase< dim, subdim >::triangleMapping ( int  face) const
inlineinherited

A dimension-specific alias for faceMapping<2>().

This alias is available for facial dimensions subdim ≥ 3.

See faceMapping() for further information.

◆ triangulation()

Triangulation< dim > & regina::detail::FaceBase< dim, subdim >::triangulation
inlineinherited

Returns the triangulation to which this face belongs.

Returns
a reference to the triangulation containing this face.

◆ utf8()

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

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

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns
a short text representation of this object.

◆ vertex()

Face< dim, 0 > * regina::detail::FaceBase< dim, subdim >::vertex ( int  i) const
inlineinherited

A dimension-specific alias for face<0>().

This alias is available for all facial dimensions subdim.

See face() for further information.

◆ vertexMapping()

Perm< dim+1 > regina::detail::FaceBase< dim, subdim >::vertexMapping ( int  face) const
inlineinherited

A dimension-specific alias for faceMapping<0>().

This alias is available for all facial dimensions subdim.

See faceMapping() for further information.

◆ writeTextLong()

void regina::ShortOutput< Face< dim, subdim > , false >::writeTextLong ( std::ostream &  out) const
inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python
Not present. Instead you can call detail() from the subclass T, which returns this output as a string.
Parameters
outthe output stream to which to write.

◆ writeTextShort()

void regina::detail::FaceBase< dim, subdim >::writeTextShort ( std::ostream &  out) const
inherited

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

The class Face<dim, subdim> may safely override this function, since the output routines cast down to Face<dim, subdim> before calling it.

Python
Not present. Use str() instead.
Parameters
outthe output stream to which to write.

Member Data Documentation

◆ allowsInvalidFaces

constexpr bool regina::detail::FaceBase< dim, subdim >::allowsInvalidFaces
staticconstexprinherited

Indicates whether it is possible for a face of this dimension to be invalid.

◆ allowsNonOrientableLinks

constexpr bool regina::detail::FaceBase< dim, subdim >::allowsNonOrientableLinks
staticconstexprinherited

Indicates whether it is possible for a face of this dimension to have a non-orientable link.

◆ dimension

constexpr int regina::detail::FaceBase< dim, subdim >::dimension
staticconstexprinherited

A compile-time constant that gives the dimension of the triangulation containing this face.

◆ lexDim

template<int dim, int subdim>
constexpr int regina::detail::FaceNumberingAPI< dim, subdim >::lexDim = (lexNumbering ? subdim : oppositeDim)
staticconstexprprotectedinherited

Whichever of subdim or oppositeDim uses lexicographical face numbering.

◆ lexNumbering

template<int dim, int subdim>
constexpr bool regina::detail::FaceNumberingAPI< dim, subdim >::lexNumbering = (subdim <= oppositeDim)
staticconstexprinherited

true if faces are numbered in lexicographical order according to their vertices, or false if faces are numbered in reverse lexicographical order.

◆ nFaces

template<int dim, int subdim>
constexpr int regina::detail::FaceNumberingAPI< dim, subdim >::nFaces = binomSmall(dim + 1, lexDim + 1)
staticconstexprinherited

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

◆ oppositeDim

template<int dim, int subdim>
constexpr int regina::detail::FaceNumberingAPI< dim, subdim >::oppositeDim = (dim - 1 - subdim)
staticconstexprinherited

The dimension of the faces opposite these in a top-dimensional simplex of a dim-dimensional triangulation.

◆ subdimension

constexpr int regina::detail::FaceBase< dim, subdim >::subdimension
staticconstexprinherited

A compile-time constant that gives the dimension of this face.


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

Copyright © 1999-2023, 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).