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

#include <triangulation/dim3.h>

Inheritance diagram for regina::Face< 3, 0 >:

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

regina::detail::FaceBase< 3, 0 >::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

face	a subdim-face number in a dim-simplex; this must be between 0 and (dim+1 choose subdim+1)-1 inclusive.
vertex	a 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

index the 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

lowerdim the dimension of subface to examine. This must be between 0 and (subdim - 1) inclusive.

Parameters

face	the 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

lowerdim the dimension of subface to examine. This must be between 0 and (subdim - 1) inclusive.

Parameters

face	the 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

vertices a 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:

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

face	identifies 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

out	the 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

out	the output stream to which to write.

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:

triangulation/dim3/vertex3.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ LinkType

Constructor & Destructor Documentation

◆ ~Face()

Member Function Documentation

◆ __iter__()

◆ back()

◆ begin()

◆ boundaryComponent()

◆ buildLink()

◆ buildLinkInclusion()

◆ component()

◆ containsVertex()

◆ degree()

◆ detail()

◆ edge()

◆ edgeMapping()

◆ embedding()

◆ embeddings()

◆ end()

◆ face()

◆ faceMapping()

◆ faceNumber()

◆ front()

◆ hasBadIdentification()

◆ hasBadLink()

◆ index()

◆ inMaximalForest()

◆ isBoundary()

◆ isIdeal()

◆ isLinkClosed()

◆ isLinkOrientable()

◆ isStandard()

◆ isValid()

◆ linkEulerChar()

◆ linkingSurface()

◆ linkType()

◆ markedIndex()

◆ ordering()

◆ pentachoron()

◆ pentachoronMapping()

◆ str()

◆ tetrahedron()

◆ tetrahedronMapping()

◆ triangle()

◆ triangleMapping()

◆ triangulation()

◆ utf8()

◆ vertex()

◆ vertexMapping()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ allowsInvalidFaces

◆ allowsNonOrientableLinks

◆ dimension

◆ lexDim

◆ lexNumbering

◆ nFaces

◆ oppositeDim

◆ subdimension

◆ iter()