Represents a top-dimensional simplex in a dim-manifold triangulation. More...

#include <triangulation/generic.h>

Inheritance diagram for regina::Face< dim, dim >:

Public Types
using	FacetMask = typename IntOfMinBits<dim + 1>::utype
	An unsigned integer type with at least dim+1 bits.
using	LockMask = typename IntOfMinBits<dim + 2>::utype
	An unsigned integer type with at least dim+2 bits.

Public Member Functions
size_t	index () const
	Returns the index of this face within the underlying triangulation.
Triangulation< dim > &	triangulation () const
	Returns the triangulation to which this face belongs.
Component< dim > *	component () const
	Returns the component of the triangulation to which this face belongs.
BoundaryComponent< dim > *	boundaryComponent () const
	Returns the boundary component of the triangulation to which this face belongs.
bool	isBoundary () const
	Determines if this face lies entirely on the boundary of the triangulation.
size_t	degree () const
	Returns the degree of this face.
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.
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.
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.
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.
auto	__iter__ () const
	Provides Python support for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation.
const FaceEmbedding< dim, subdim > &	front () const
	Returns the first appearance of this face within a top-dimensional simplex of the underlying triangluation.
const FaceEmbedding< dim, subdim > &	back () const
	Returns the last appearance of this face within a top-dimensional simplex of the underlying triangluation.
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.
bool	isLinkOrientable () const
	Determines if the link of this face is orientable.
bool	isValid () const
	Determines if this face is valid.
bool	hasBadIdentification () const
	Determines if this face is identified with itself under a non-identity permutation.
bool	hasBadLink () const
	Determines if this face does not have an appropriate link.
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.
Face< dim, 0 > *	vertex (int i) const
	A dimension-specific alias for face<0>().
Face< dim, 1 > *	edge (int i) const
	A dimension-specific alias for face<1>().
Face< dim, 2 > *	triangle (int i) const
	A dimension-specific alias for face<2>().
Face< dim, 3 > *	tetrahedron (int i) const
	A dimension-specific alias for face<3>().
Face< dim, 4 > *	pentachoron (int i) const
	A dimension-specific alias for face<4>().
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.
Perm< dim+1 >	vertexMapping (int face) const
	A dimension-specific alias for faceMapping<0>().
Perm< dim+1 >	edgeMapping (int face) const
	A dimension-specific alias for faceMapping<1>().
Perm< dim+1 >	triangleMapping (int face) const
	A dimension-specific alias for faceMapping<2>().
Perm< dim+1 >	tetrahedronMapping (int face) const
	A dimension-specific alias for faceMapping<3>().
Perm< dim+1 >	pentachoronMapping (int face) const
	A dimension-specific alias for faceMapping<4>().
void	join (Face< dim, subdim > *you, Perm< dim > gluing)
	For boundary facets, joins this to another boundary facet using the given gluing.
bool	isLoop () const
	For edges, determines whether this face is a loop.
TriangleType	triangleType ()
	For triangles, returns the combinatorial type of this face.
int	triangleSubtype ()
	For triangles, returns the vertex or edge number in this face that plays a special role for this triangle's combinatorial type.
bool	formsMobiusBand ()
	For triangles, determines whether this face is wrapped up to form a Möbius band, possibly with or without additional identifications between its vertices and/or edges.
bool	formsCone ()
	For triangles, determines whether this face is wrapped up to form a cone, possibly with or without additional identifications between its vertices and/or edges.
void	lock ()
	Locks this codimension-1-face.
void	unlock ()
	Unlocks this codimension-1-face.
bool	isLocked () const
	Determines whether this codimension-1-face is locked.
void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream.
size_t	markedIndex () const
	Returns the index at which this object is stored in an MarkedVector.
void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output.
std::string	str () const
	Returns a short text representation of this object.
std::string	utf8 () const
	Returns a short text representation of this object using unicode characters.
std::string	detail () const
	Returns a detailed text representation of this object.
const std::string &	description () const
	Returns the description associated with this simplex.
void	setDescription (const std::string &desc)
	Sets the description associated with this simplex.
Simplex< dim > *	adjacentSimplex (int facet) const
	Returns the adjacent simplex that is glued to the given facet of this simplex.
Perm< dim+1 >	adjacentGluing (int facet) const
	Returns a permutation that indicates precisely how this simplex is glued to the adjacent simplex across the given facet.
int	adjacentFacet (int facet) const
	If the given facet of this simplex is glued to facet f of some adjacent simplex, then this routine returns the adjacent facet number f.
bool	hasBoundary () const
	Determines if this simplex has any facets that lie on the triangulation boundary.
void	join (int myFacet, Simplex< dim > *you, Perm< dim+1 > gluing)
	Joins the given facet of this simplex to some facet of another simplex.
Simplex< dim > *	unjoin (int myFacet)
	Unglues the given facet of this simplex from whatever it is joined to.
void	isolate ()
	Unglues this simplex from any adjacent simplices.
void	lockFacet (int facet)
	Locks the given facet of this top-dimensional simplex.
void	unlockFacet (int facet)
	Unlocks the given facet of this top-dimensional simplex.
void	unlockAll ()
	Unlocks this top-dimensional simplex and all of its facets.
bool	isFacetLocked (int facet) const
	Determines whether the given facet of this top-dimensional simplex is locked.
LockMask	lockMask () const
	Returns a bitmask indicating which of this simplex and/or its individual facets are locked.
Face< dim, 1 > *	edge (int i, int j) const
	Returns the edge of this simplex that connects the two given vertices of this simplex.
int	orientation () const
	Returns the orientation of this simplex in the dim-dimensional triangulation.
bool	facetInMaximalForest (int facet) const
	Determines whether the given facet of this simplex belongs to the maximal forest that has been chosen for the dual 1-skeleton of the underlying triangulation.

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

Static Public Attributes
static constexpr int	dimension
	A compile-time constant that gives the dimension of the triangulation containing this face.
static constexpr int	subdimension
	A compile-time constant that gives the dimension of this face.
static constexpr bool	allowsNonOrientableLinks
	Indicates whether it is possible for a face of this dimension to have a non-orientable link.
static constexpr bool	allowsInvalidFaces
	Indicates whether it is possible for a face of this dimension to be invalid.
static constexpr int	oppositeDim
	The dimension of the faces opposite these in a top-dimensional simplex of a dim-dimensional triangulation.
static constexpr bool	lexNumbering
	`true` if faces are numbered in lexicographical order according to their vertices, or `false` if faces are numbered in reverse lexicographical order.
static constexpr int	nFaces
	The total number of subdim-dimensional faces in each dim-dimensional simplex.

Protected Member Functions
	Face (Triangulation< dim > *tri)
	Creates a new simplex with no description and no facets joined to anything.
	Face (const Face &clone, Triangulation< dim > *tri)
	Creates a new simplex whose description and locks are cloned from the given simplex, and with no faces joined to anything.
	Face (const std::string &desc, Triangulation< dim > *tri)
	Creates a new simplex with the given description, no locks, and no facets joined to anything.
template<int useDim>
bool	sameDegreesAt (const SimplexBase &other, Perm< dim+1 > p) const
	Tests whether the useDim-face degrees of this and the given simplex are identical, under the given relabelling.
template<int... useDim>
bool	sameDegreesAt (const SimplexBase &other, Perm< dim+1 > p, std::integer_sequence< int, useDim... >) const
	Tests whether the k-face degrees of this and the given simplex are identical, under the given relabelling, for all faces whose dimensions are contained in the integer pack useDim.

Static Protected Attributes
static constexpr int	lexDim
	Whichever of subdim or oppositeDim uses lexicographical face numbering.

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

Detailed Description

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

Represents a top-dimensional simplex in a dim-manifold triangulation.

For example, for 3-manifolds this class represents a tetrahedron, and for 2-manifolds this class represents a triangle.

Although this is a specialisation of the Face class template, this class is typically referred to using the alias Simplex<dim>. For Regina's standard dimensions, you can also use the aliases Triangle<2>, Tetrahedron<3> and Pentachoron<4>.

Top-dimensional simplices cannot exist in isolation (without a triangulation object), and they cannot be created or destroyed directly. Instead, you create and destroy them via the underlying triangulation, by calling routines such as Triangulation<dim>::newSimplex() or Triangulation<dim>::removeSimplex().

Amongst other things, this class is used to view and change the gluings between top-dimensional simplices. For this we number the facets and vertices of each simplex 0,...,dim, so that facet i is opposite vertex i.

Each simplex may have an optional description. This is typically a human-readable piece of text. Descriptions are not required, and do not need to be unique.

For Regina's standard dimensions, this template is specialised and offers significant extra functionality. In order to use these specialised classes, you will need to include the corresponding triangulation headers (e.g., triangulation/dim2.h for dim = 2, or triangulation/dim3.h for dim = 3).

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

Python: Python does not support templates. Instead this class can be used by appending the dimension as a suffix (e.g., Simplex2 and Simplex3 for dimensions 2 and 3).

Template Parameters

dim	the dimension of the underlying triangulation. This must be between 2 and 15 inclusive.

Member Typedef Documentation

◆ FacetMask

template<int dim>

using regina::detail::SimplexBase< dim >::FacetMask = typename IntOfMinBits<dim + 1>::utype

inherited

An unsigned integer type with at least dim+1 bits.

This can be used as a bitmask for the dim+1 facets (or vertices) of a dim-simplex.

◆ LockMask

template<int dim>

using regina::detail::SimplexBase< dim >::LockMask = typename IntOfMinBits<dim + 2>::utype

inherited

An unsigned integer type with at least dim+2 bits.

The ith bit indicates whether facet i of the simplex is locked for 0 ≤ i ≤ dim, and the (dim+2)th bit indicates whether the simplex itself is locked.

Constructor & Destructor Documentation

◆ Face() [1/3]

template<int dim>

regina::Face< dim, dim >::Face ( Triangulation< dim > * tri )

inlineprotected

Creates a new simplex with no description and no facets joined to anything.

Parameters

tri	the triangulation to which the new simplex belongs.

◆ Face() [2/3]

template<int dim>

regina::Face< dim, dim >::Face	(	const Face< dim, dim > &	clone,
		Triangulation< dim > *	tri )

inlineprotected

Creates a new simplex whose description and locks are cloned from the given simplex, and with no faces joined to anything.

Parameters

clone	the simplex whose details should be cloned.
tri	the triangulation to which the new tetrahedron belongs.

◆ Face() [3/3]

template<int dim>

regina::Face< dim, dim >::Face	(	const std::string &	desc,
		Triangulation< dim > *	tri )

inlineprotected

Creates a new simplex with the given description, no locks, and no facets joined to anything.

Parameters

desc	the description to give the new simplex.
tri	the triangulation to which the new simplex belongs.

Member Function Documentation

◆ iter()

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

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.

◆ adjacentFacet()

template<int dim>

int regina::detail::SimplexBase< dim >::adjacentFacet ( int facet ) const

inlineinherited

If the given facet of this simplex is glued to facet f of some adjacent simplex, then this routine returns the adjacent facet number f.

The return value from this routine is identical to adjacentGluing(facet)[facet].

Precondition: The given facet of this simplex has some adjacent simplex (possibly this one) glued to it. In other words, adjacentSimplex(facet) is not null.

Parameters

facet the facet of this simplex that we are examining. This must be between 0 and dim inclusive.

Returns: the corresponding facet number of the adjacent simplex that is glued to the given facet of this simplex.

◆ adjacentGluing()

template<int dim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::adjacentGluing ( int facet ) const

inlineinherited

Returns a permutation that indicates precisely how this simplex is glued to the adjacent simplex across the given facet.

In detail: suppose that the given facet of this simplex is glued to an adjacent simplex A. Then this gluing induces a mapping from the vertices of this simplex to the vertices of A. We can express this mapping in the form of a permutation p, where:

for any v ≠ facet, the gluing identifies vertex v of this simplex with vertex p[v] of simplex A;
p[facet] indicates the facet of A that is on the other side of the gluing (i.e., the facet of A that is glued to the given facet of this simplex).

Precondition: The given facet of this simplex has some adjacent simplex (possibly this one) glued to it. In other words, adjacentSimplex(facet) is not null.

Parameters

facet the facet of this simplex that we are examining. This must be between 0 and dim inclusive.

Returns: a permutation that maps the vertices of this simplex to the vertices of the adjacent simplex, as described above.

◆ adjacentSimplex()

template<int dim>

Simplex< dim > * regina::detail::SimplexBase< dim >::adjacentSimplex ( int facet ) const

inlineinherited

Returns the adjacent simplex that is glued to the given facet of this simplex.

If there is no adjacent simplex (i.e., the given facet lies on the triangulation boundary), then this routine will return null.

Parameters

facet the facet of this simplex to examine; this must be between 0 and dim inclusive.

Returns: the adjacent simplex glued to the given facet, or null if the given facet lies on the boundary.

◆ back()

const FaceEmbedding< dim, subdim > & regina::detail::FaceBase< dim, subdim >::back ( ) const

inline

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 ( ) const

inline

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::Face< dim, dim >::Face

Face(Triangulation< dim > *tri)

Creates a new simplex with no description and no facets joined to anything.

Definition simplex.h:153

regina::Face< dim, dim >::face

Face< dim, lowerdim > * face(int face) const

Definition face.h:1450

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 ( ) const

inline

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.

◆ component()

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

inline

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

Returns: the component containing this face.

◆ containsVertex()

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

staticconstexpr

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 ( ) const

inline

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.

◆ description()

template<int dim>

const std::string & regina::detail::SimplexBase< dim >::description ( ) const

inlineinherited

Returns the description associated with this simplex.

Returns: the description of this simplex, or the empty string if no description is stored.

◆ detail()

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

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() [1/2]

template<int dim>

Face< dim, 1 > * regina::detail::SimplexBase< dim >::edge	(	int	i,
		int	j ) const

inlineinherited

Returns the edge of this simplex that connects the two given vertices of this simplex.

This is a convenience routine to avoid more cumbersome calls to Edge<dim>::faceNumber(). In dimensions 3 and 4 (where the array Edge<dim>::edgeNumber is defined), this routine is identical to calling edge(Edge<dim>::edgeNumber[i][j]).

Parameters

i	the vertex of this simplex that forms one endpoint of the edge; this must be between 0 and dim inclusive.
j	the vertex of this simplex that forms the other endpoint of the edge; this must be between 0 and dim inclusive, and must also be different from i.

Returns: the edge of this simplex that connects vertices i and j of this simplex.

◆ edge() [2/2]

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

inline

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

inline

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

inline

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 ( ) const

inline

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 ( ) const

inline

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

inline

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

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

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

staticconstexpr

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

For the special case subdim == 1 (i.e., edges in a dim-dimensional simplex), you can also call this function in the form faceNumber(u, v), where u and v are two distinct vertex numbers in the range 0 ≤ u,v ≤ dim: this will return the number of the edge spanned by simplex vertices u and v. It does not matter whether u is smaller or larger than v.

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.

◆ facetInMaximalForest()

template<int dim>

bool regina::detail::SimplexBase< dim >::facetInMaximalForest ( int facet ) const

inlineinherited

Determines whether the given facet of this simplex belongs to the maximal forest that has been chosen for the dual 1-skeleton of the underlying 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 which (dim-1)-faces of the triangulation belong to the dual forest. Because it lives in the Simplex class, this routine can even be used for those dimensions that do not have explicit classes for (dim-1)-faces of the triangulation.

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

Parameters

facet the facet of this simplex that we are examining. This must be between 0 and dim inclusive.

Returns: true if and only if the given facet of this simplex corresponds to a dual edge in the maximal forest chosen for the dual 1-skeleton.

◆ formsCone()

bool regina::detail::FaceBase< dim, subdim >::formsCone ( )

inline

For triangles, determines whether this face is wrapped up to form a cone, possibly with or without additional identifications between its vertices and/or edges.

Note that several different triangle types (as returned by triangleType()) can produce this result. Note also that a triangle can satisfy both formsMobiusBand() and formsCone().

The reason this routine is non-const is because the triangle type is cached when first computed.

Precondition: The facial dimension subdim is precisely 2, and the triangulation dimension dim is at least 3.

Returns: true if and only if this triangle forms a cone.

◆ formsMobiusBand()

bool regina::detail::FaceBase< dim, subdim >::formsMobiusBand ( )

inline

For triangles, determines whether this face is wrapped up to form a Möbius band, possibly with or without additional identifications between its vertices and/or edges.

Note that several different triangle types (as returned by triangleType()) can produce this result. Note also that a triangle can satisfy both formsMobiusBand() and formsCone().

The reason this routine is non-const is because the triangle type is cached when first computed.

Precondition: The facial dimension subdim is precisely 2, and the triangulation dimension dim is at least 3.

Returns: true if and only if this triangle forms a Mobius band.

◆ front()

const FaceEmbedding< dim, subdim > & regina::detail::FaceBase< dim, subdim >::front ( ) const

inline

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 ( ) const

inline

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 ( ) const

inline

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.

◆ hasBoundary()

template<int dim>

bool regina::detail::SimplexBase< dim >::hasBoundary ( ) const

inherited

Determines if this simplex has any facets that lie on the triangulation boundary.

In other words, this routine determines whether any facet of this simplex is not currently glued to an adjacent simplex.

Returns: true if and only if this simplex has any boundary facets.

◆ index()

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

inline

Returns the index of this face within the underlying triangulation.

Returns: the index of this face.

◆ inMaximalForest()

bool regina::detail::FaceBase< dim, subdim >::inMaximalForest ( ) const

inline

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 ( ) const

inline

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.

◆ isFacetLocked()

template<int dim>

bool regina::detail::SimplexBase< dim >::isFacetLocked ( int facet ) const

inlineinherited

Determines whether the given facet of this top-dimensional simplex is locked.

Essentially, locking a facet means that that facet must not change. See lockFacet() for full details on how locks work and what their implications are.

Note that you can also lock an entire top-dimensional simplex; see lock() for details. This routine does not test whether the top-dimensional simplex is locked; it only tests for a lock on the given facet.

See lockMask() for a convenient way to test in a single query whether this simplex and/or any of its facets are locked. Also, Triangulation<dim>::hasLocks() offers a simple way to test whether a triangulation has any locked dim-simplices or facets at all.

Parameters

facet indicates which facet of this simplex to examine; this must be between 0 and dim inclusive.

Returns: true if and only if the given facet of this simplex is locked.

◆ isLinkOrientable()

bool regina::detail::FaceBase< dim, subdim >::isLinkOrientable ( ) const

inline

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.

As of Regina 7.4.1, the orientability of the link will be calculated correctly even if the face is invalid due to a non-trivial self-identification.

Returns: true if and only if the link is orientable.

◆ isLocked()

bool regina::detail::FaceBase< dim, subdim >::isLocked ( ) const

inline

Determines whether this codimension-1-face is locked.

Essentially, locking a face of dimension (dim-1) means that the face must not change. See Simplex<dim>::lockFacet() for full details on how locks work and what their implications are.

This is equivalent to calling Simplex<dim>::isFacetLocked() from one of the simplices on either side of this (dim-1)-face.

See Triangulation<dim>::hasLocks() for a convenient way to test whether any top-dimensional simplex and/or (dim-1)-face is locked across an entire triangulation.

Precondition: The facial dimension subdim is precisely dim-1.

Returns: true if and only if this (dim-1)-face is locked.

◆ isLoop()

bool regina::detail::FaceBase< dim, subdim >::isLoop ( ) const

inline

For edges, determines whether this face is a loop.

A loop is an edge whose two endpoints are identified.

Precondition: The facial dimension subdim is precisely 1.

Returns: true if and only if this edge is a loop.

◆ isolate()

template<int dim>

void regina::detail::SimplexBase< dim >::isolate ( )

inherited

Unglues this simplex from any adjacent simplices.

As a result, every facet of this simplex will become a boundary facet, and this simplex will form its own separate component of the underlying triangulation.

If there were any adjacent simplices to begin with, these will be updated automatically.

This routine is safe to call even if there are no adjacent simplices (in which case it will do nothing).

Exceptions

LockViolation At least one facet of this simplex is non-boundary and currently locked. This exception will be thrown before any change is made. See lockFacet() for further details on how facet locks work and what their implications are.

◆ isValid()

bool regina::detail::FaceBase< dim, subdim >::isValid ( ) const

inline

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

◆ join() [1/2]

template<int dim>

void regina::detail::SimplexBase< dim >::join	(	int	myFacet,
		Simplex< dim > *	you,
		Perm< dim+1 >	gluing )

inherited

Joins the given facet of this simplex to some facet of another simplex.

The other simplex will be updated automatically (i.e., you only need to call join() from one side of the gluing).

You may join a facet of this simplex to some different facet of the same simplex (i.e., you may pass you == this), though you cannot join a facet to itself.

Precondition: This and the given simplex belong to the same triangulation.; The given facet of this simplex is not currently glued to anything.; The corresponding facet of the other simplex (i.e., facet gluing[myFacet] of you) is likewise not currently glued to anything.; We are not attempting to glue a facet to itself (i.e., we do not have both you == this and gluing[myFacet] == myFacet).

Exceptions

InvalidArgument	At least one of the conditions above fails; that is, either the two simplices being joined belong to different triangulations, or one of the two facets being joined is already joined to something, or you are trying to join the same facet of the same simplex to itself.
LockViolation	The given facet of this simplex is currently locked. This exception will be thrown before any change is made. See lockFacet() for further details on how facet locks work and what their implications are.

Parameters

myFacet	the facet of this simplex that will be glued to the given simplex you. This facet number must be between 0 and dim inclusive.
you	the other simplex that will be glued to the given facet of this simplex.
gluing	a permutation that describes how the vertices of this simplex will map to the vertices of you across the new gluing. This permutation should be in the form described by adjacentGluing().

◆ join() [2/2]

void regina::detail::FaceBase< dim, subdim >::join	(	Face< dim, subdim > *	you,
		Perm< dim >	gluing )

inline

For boundary facets, joins this to another boundary facet using the given gluing.

This is a convenience method that calls Simplex<dim>::join(). Where it differs is that:

you directly pass the two (dim-1)-faces that need to be joined, as opposed to working with dim-dimensional simplices;
the gluing permutation is relative to the inherent labellings of the vertices of the (dim-1)-faces, not the vertices of the top-dimensional simplices.

By "inherent labelling of vertices" of a face f we mean the way that the vertices of f are labelled according to FaceEmbedding::vertices(). This labelling is independent of the vertex numbers in any top-dimensional simplices that contain f.

Precondition: The facial dimension subdim is precisely dim-1.; This and the given face are distinct boundary facets of the same triangulation.

Warning: As soon as the join takes place, both this and the given facet will be destroyed (since the skeleton of a triangulation is rebuilt whenever the triangulation changes).

Exceptions

InvalidArgument	At least one of the preconditions above fails; that is, this and the given face are the same, or belong to different triangulations, or are not both boundary facets.
LockViolation	Either this or the given face is a locked facet. This exception will be thrown before any change is made. See Simplex::lockFacet() for further details on how facet locks work and what their implications are.

Parameters

you	the other boundary facet that this should be glued to.
gluing	a permutation that describes how the inherent vertices of this boundary facet will map to the inherent vertices of the given boundary facet across the new gluing.

◆ lock()

void regina::detail::FaceBase< dim, subdim >::lock ( )

inline

Locks this codimension-1-face.

Essentially, locking a face of dimension (dim-1) means that the face must not change. See Simplex<dim>::lockFacet() for full details on how locks work and what their implications are.

These locks are actually stored within the top-dimensional simplices on either side of this facet. This means that, even if the underlying triangulation changes (which means all (dim-1)-faces will be destroyed and re-created as part of the skeleton recomputation), this lock will nevertheless be preserved.

This is equivalent to calling Simplex<dim>::lockFacet() from one of the simplices on either side of this (dim-1)-face.

It is safe to call this function even if this face is already locked.

Precondition: The facial dimension subdim is precisely dim-1.

◆ lockFacet()

template<int dim>

void regina::detail::SimplexBase< dim >::lockFacet ( int facet )

inherited

Locks the given facet of this top-dimensional simplex.

Essentially, locking a facet means that that facet must not change. Specifically:

A locked boundary facet cannot be glued to some other top-dimensional simplex (e.g., via join()).
A locked internal (non-boundary) facet cannot made boundary by explicitly ungluing (e.g., via unjoin() or isolate()).
A locked facet cannot be removed completely (e.g., a facet internal to the region where a Pachner move is performed, or a facet internal to the region removed by a 2-0 move or edge collapse).
A locked facet cannot be subdivided (e.g., via Triangulation<dim>::subdivide().

There are some important exceptions to these rules:

We do allow moves on the triangulation that topologically "flatten" a region beside a locked facet F, as long as F survives topologically. For example, we allow 2-0 moves or edge collapses that merge F with a parallel (dim-1)-face, even if this changes F from internal to boundary (because F was merged with a boundary facet). Likewise, we allow boundary shellings that expose an internal locked facet to the boundary (because this is a "topological flattening", not just an arbitrary ungluing). In all such cases, the lock "moves" with F to its new (possibly merged, possibly boundary) location.
Further to the previous point: we do not allow boundary shellings that remove a locked boundary facet G. This is because G does not survive topologically (i.e., the resulting boundary facets after the shelling are not isotopies of G).
We also allow moves that "pry open" a (dim-1)-face F to become a pair of parallel faces F1, F2, between which new material is inserted. For example, this kind of operation happens with pinchEdge() and connected sum operations in dimension 3, and snapEdge() in dimension 4. In this case, the lock will move across to one of F1 or F2. In particular, if F was originally boundary then the lock will move to whichever of F1 or F2 is boundary after the operation is complete; otherwise the choice of F1 versus F2 is arbitrary.

Regina's own automatic retriangulation routines (such as Triangulation<dim>::simplify() or Triangulation<dim>::retriangulate()) will simply avoid changing any locked facets. If the user attempts to manually force a change (e.g., by calling Triangulation<dim>::subdivide()), then a FailedPrecondition exception will be thrown.

Regina will always ensure that the locks on facets are consistent. That is, if some facet F of some top-dimensional simplex is glued to some facet G of some top-dimensional simplex, then whenever F is locked/unlocked, Regina will automatically lock/unlock G also.

It is safe to call this function even if the given facet is already locked.

Note that you can also lock an entire top-dimensional simplex; see lock() for details. Locking a simplex does not imply that its facets will be automatically locked also, or vice versa; these are independent concepts.

The Triangulation copy constructor and assignment operators will preserve locks (i.e., the simplices/facets of the new triangulation will be locked in the same way as the simplices/facets of the source).

Locks will not interfere with the destruction of a triangulation (i.e., the Triangulation destructor does not check for locks).

Changing locks is considered a modification of the triangulation (in particular, if the triangulation is wrapped in a packet then the appropriate change events will be fired).

Parameters

facet indicates which facet of this simplex to lock; this must be between 0 and dim inclusive.

◆ lockMask()

template<int dim>

SimplexBase< dim >::LockMask regina::detail::SimplexBase< dim >::lockMask ( ) const

inlineinherited

Returns a bitmask indicating which of this simplex and/or its individual facets are locked.

Essentially, locking a top-dimensional simplex or one of its facets means that that simplex or facet must not change. See lock() and lockFacet() for full details on how locks work and what their implications are.

This routine returns a bitmask containing dim+2 bits (here we number the bits so that the 0th bit is the least significant). The kth bit is set if and only if the kth facet of this simplex is locked, for 0 ≤ k ≤ dim. Finally, the (dim+1)th bit is set if and only if this simplex itself is locked.

See also isLocked() and isFacetLocked() for a more convenient way to query the simplex and/or one of its facets individually, and Triangulation<dim>::hasLocks() for a simple way to query all top-dimensional simplices and their facets across the entire triangulation.

Returns: a bitmask indicating which of this simplex and/or its facets are locked. This bitmask will be returned using a native C++ unsigned integer type of the appropriate size.

◆ markedIndex()

size_t regina::MarkedElement::markedIndex ( ) const

inline

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

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

staticconstexpr

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.

◆ orientation()

template<int dim>

int regina::detail::SimplexBase< dim >::orientation ( ) const

inlineinherited

Returns the orientation of this simplex in the dim-dimensional triangulation.

The orientation of each top-dimensional simplex is always +1 or -1. In an orientable component of a triangulation, adjacent simplices have the same orientations if one could be transposed onto the other without reflection, and they have opposite orientations if a reflection would be required. In a non-orientable component, orientations are arbitrary (but they will still all be +1 or -1).

In each component, the top-dimensional simplex with smallest index will always have orientation +1. In particular, simplex 0 will always have orientation +1.

Returns: +1 or -1 according to the orientation of this simplex.

◆ pentachoron()

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

inline

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

inline

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

This alias is available for facial dimensions subdim ≥ 5.

See faceMapping() for further information.

◆ sameDegreesAt() [1/2]

template<int dim>

template<int useDim>

bool regina::detail::SimplexBase< dim >::sameDegreesAt	(	const SimplexBase< dim > &	other,
		Perm< dim+1 >	p ) const

inlineprotectedinherited

Tests whether the useDim-face degrees of this and the given simplex are identical, under the given relabelling.

Parameters

other	the simplex to compare against this.
p	a mapping from the vertices of this simplex to the vertices of other.

Returns: true if and only if, for every i, useDim-face number i of this simplex has the same degree as its image in other under the relabelling p.

◆ sameDegreesAt() [2/2]

template<int dim>

template<int... useDim>

bool regina::detail::SimplexBase< dim >::sameDegreesAt	(	const SimplexBase< dim > &	other,
		Perm< dim+1 >	p,
		std::integer_sequence< int, useDim... >	) const

inlineprotectedinherited

Tests whether the k-face degrees of this and the given simplex are identical, under the given relabelling, for all faces whose dimensions are contained in the integer pack useDim.

Parameters

other	the simplex to compare against this.
p	a mapping from the vertices of this simplex to the vertices of other.

Returns: true if and only if, for every i and every facial dimension k in the integer pack useDim, k-face number i of this simplex has the same degree as its image in other under the relabelling p.

◆ setDescription()

template<int dim>

void regina::detail::SimplexBase< dim >::setDescription ( const std::string & desc )

inlineinherited

Sets the description associated with this simplex.

This may be any text whatsoever; typically it is intended to be human-readable. Descriptions do not need to be unique.

To remove an existing description, you can simply set the description to the empty string.

Parameters

desc	the new description to assign to this simplex.

◆ str()

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

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

inline

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

inline

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

inline

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

inline

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

This alias is available for facial dimensions subdim ≥ 3.

See faceMapping() for further information.

◆ triangleSubtype()

int regina::detail::FaceBase< dim, subdim >::triangleSubtype ( )

inline

For triangles, returns the vertex or edge number in this face that plays a special role for this triangle's combinatorial type.

Note that only some triangle types have a special vertex or edge. The triangle type itself is returned by triangleType().

If one or more edges of this triangle are invalid due to bad self-identifications, then the triangle type might not be well-defined and so the return value will likewise be undefined.

The reason this routine is non-const is because the triangle type and subtype are cached when first computed.

Precondition: The facial dimension subdim is precisely 2, and the triangulation dimension dim is at least 3.

Returns: The vertex or edge number (0, 1 or 2) that plays a special role, or -1 if this triangle's combinatorial type has no special vertex or edge.

◆ triangleType()

TriangleType regina::detail::FaceBase< dim, subdim >::triangleType ( )

inline

For triangles, returns the combinatorial type of this face.

This will be one of the eight shapes described by the TriangleType enumeration, which indicates how the edges and vertices of the triangle are identified.

If one or more edges of this triangle are invalid due to bad self-identifications, then the triangle type might not be well-defined and so the return value will likewise be undefined.

The reason this routine is non-const is because the triangle type and subtype are cached when first computed.

Precondition: The facial dimension subdim is precisely 2, and the triangulation dimension dim is at least 3.

Returns: the combinatorial type of this triangle. This routine will never return TriangleType::Unknown.

◆ triangulation()

Triangulation< dim > & regina::detail::FaceBase< dim, subdim >::triangulation ( ) const

inline

Returns the triangulation to which this face belongs.

Returns: a reference to the triangulation containing this face.

◆ unjoin()

template<int dim>

Simplex< dim > * regina::detail::SimplexBase< dim >::unjoin ( int myFacet )

inherited

Unglues the given facet of this simplex from whatever it is joined to.

As a result, the given facet of this simplex will become a boundary facet.

If there was an adjacent simplex to begin with, then this other simplex will be updated automatically (i.e., you only need to call unjoin() from one side of the gluing).

This routine is safe to call even if the given facet is already a boundary facet (in which case it will do nothing).

Exceptions

LockViolation The given facet of this simplex is currently locked. This exception will be thrown before any change is made. See lockFacet() for further details on how facet locks work and what their implications are.

Parameters

myFacet the facet of this simplex whose gluing we will undo. This should be between 0 and dim inclusive.

Returns: the simplex that was originally glued to the given facet of this simplex, or null if this was already a boundary facet.

◆ unlock()

void regina::detail::FaceBase< dim, subdim >::unlock ( )

inline

Unlocks this codimension-1-face.

Essentially, locking a face of dimension (dim-1) means that the face must not change. See Simplex<dim>::lockFacet() for full details on how locks work and what their implications are.

This is equivalent to calling Simplex<dim>::unlockFacet() from one of the simplices on either side of this (dim-1)-face.

It is safe to call this function even if this face is already unlocked.

See Triangulation<dim>::unlockAll() for a convenient way to unlock all top-dimensional simplices and (dim-1)-faces across an entire triangulation.

Precondition: The facial dimension subdim is precisely dim-1.

◆ unlockAll()

template<int dim>

void regina::detail::SimplexBase< dim >::unlockAll ( )

inherited

Unlocks this top-dimensional simplex and all of its facets.

Essentially, locking a simplex or one of its facets means that that simplex or facet must not change. See lock() and lockFacet() for full details on how locks work and what their implications are.

Regina will always ensure that the locks on facets are consistent. That is, if some facet F of some top-dimensional simplex is glued to some facet G of some top-dimensional simplex, then whenever F is locked/unlocked, Regina will automatically lock/unlock G also.

It is safe to call this function even if this simplex and all of its facets are already unlocked.

See also Triangulation<dim>::unlockAll() for a simple way to unlock all dim-simplices and their facets across an entire triangulation.

◆ unlockFacet()

template<int dim>

void regina::detail::SimplexBase< dim >::unlockFacet ( int facet )

inherited

Unlocks the given facet of this top-dimensional simplex.

Essentially, locking a facet means that that facet must not change. See lockFacet() for full details on how locks work and what their implications are.

Regina will always ensure that the locks on facets are consistent. That is, if some facet F of some top-dimensional simplex is glued to some facet G of some top-dimensional simplex, then whenever F is locked/unlocked, Regina will automatically lock/unlock G also.

It is safe to call this function even if the given facet is already unlocked.

Note that you can also lock an entire top-dimensional simplex; see lock() for details. Unlocking a simplex does not imply that its facets will be automatically unlocked also, or vice versa; these are independent concepts.

See unlockAll() for a convenient way to unlock this simplex and all of its facets in a single function call. Also, Triangulation<dim>::unlockAll() offers a simple way to unlock all dim-simplices and their facets across an entire triangulation.

Parameters

facet indicates which facet of this simplex to unlock; this must be between 0 and dim inclusive.

◆ utf8()

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

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

inline

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

inline

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

inline

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

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.

Member Data Documentation

◆ allowsInvalidFaces

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

staticconstexpr

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

◆ allowsNonOrientableLinks

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

staticconstexpr

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

◆ dimension

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

staticconstexpr

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

◆ lexDim

int regina::detail::FaceNumberingAPI< dim, subdim >::lexDim

staticconstexprprotected

Whichever of subdim or oppositeDim uses lexicographical face numbering.

◆ lexNumbering

bool regina::detail::FaceNumberingAPI< dim, subdim >::lexNumbering

staticconstexpr

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

◆ nFaces

int regina::detail::FaceNumberingAPI< dim, subdim >::nFaces

staticconstexpr

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

◆ oppositeDim

int regina::detail::FaceNumberingAPI< dim, subdim >::oppositeDim

staticconstexpr

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

◆ subdimension

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

staticconstexpr

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

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

triangulation/generic/simplex.h
triangulation/generic/face.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ FacetMask

◆ LockMask

Constructor & Destructor Documentation

◆ Face() [1/3]

◆ Face() [2/3]

◆ Face() [3/3]

Member Function Documentation

◆ __iter__()

◆ adjacentFacet()

◆ adjacentGluing()

◆ adjacentSimplex()

◆ back()

◆ begin()

◆ boundaryComponent()

◆ component()

◆ containsVertex()

◆ degree()

◆ description()

◆ detail()

◆ edge() [1/2]

◆ edge() [2/2]

◆ edgeMapping()

◆ embedding()

◆ embeddings()

◆ end()

◆ face()

◆ faceMapping()

◆ faceNumber()

◆ facetInMaximalForest()

◆ formsCone()

◆ formsMobiusBand()

◆ front()

◆ hasBadIdentification()

◆ hasBadLink()

◆ hasBoundary()

◆ index()

◆ inMaximalForest()

◆ isBoundary()

◆ isFacetLocked()

◆ isLinkOrientable()

◆ isLocked()

◆ isLoop()

◆ isolate()

◆ isValid()

◆ join() [1/2]

◆ join() [2/2]

◆ lock()

◆ lockFacet()

◆ lockMask()

◆ markedIndex()

◆ ordering()

◆ orientation()

◆ pentachoron()

◆ pentachoronMapping()

◆ sameDegreesAt() [1/2]

◆ sameDegreesAt() [2/2]

◆ setDescription()

◆ str()

◆ tetrahedron()

◆ tetrahedronMapping()

◆ triangle()

◆ triangleMapping()

◆ triangleSubtype()

◆ triangleType()

◆ triangulation()

◆ unjoin()

◆ unlock()

◆ unlockAll()

◆ unlockFacet()

◆ utf8()

◆ vertex()

◆ iter()