Helper class that provides core functionality for a top-dimensional simplex in a dim-manifold triangulation. More...

#include <triangulation/detail/simplex.h>

Inheritance diagram for regina::detail::SimplexBase< 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
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.

size_t	index () const
	Returns the index of this simplex in the underlying triangulation.

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	lock ()
	Locks this top-dimensional simplex.

void	lockFacet (int facet)
	Locks the given facet of this top-dimensional simplex.

void	unlock ()
	Unlocks 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	isLocked () const
	Determines whether this top-dimensional simplex is locked.

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.

Triangulation< dim > &	triangulation () const
	Returns the triangulation to which this simplex belongs.

Component< dim > *	component () const
	Returns the connected component of the triangulation to which this simplex belongs.

template<int subdim>
Face< dim, subdim > *	face (int face) const
	Returns the subdim-face of the underlying triangulation that appears as the given subdim-face of this simplex.

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

Face< dim, 1 > *	edge (int i, int j) const
	Returns the edge of this simplex that connects the two given vertices of this simplex.

template<int subdim>
Perm< dim+1 >	faceMapping (int face) const
	Examines the given subdim-face of this simplex, and returns the mapping between the underlying subdim-face of the triangulation and the individual vertices of this simplex.

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

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.

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream.

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream.

	SimplexBase (const SimplexBase &)=delete

SimplexBase &	operator= (const SimplexBase &)=delete

size_t	markedIndex () const
	Returns the index at which this object is stored in an MarkedVector.

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.

Static Public Attributes
static constexpr int	dimension = dim
	A compile-time constant that gives the dimension of the triangulation containing this simplex.

static constexpr int	subdimension = dim
	A compile-time constant that gives the dimension of this simplex.

Protected Member Functions
	SimplexBase (Triangulation< dim > *tri)
	Creates a new simplex with no description and no facets joined to anything.

	SimplexBase (const SimplexBase &clone, Triangulation< dim > *tri)
	Creates a new simplex whose description and locks are cloned from the given simplex, and with no facets joined to anything.

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

Friends
class	TriangulationBase< dim >

class	Triangulation< dim >

class	regina::XMLSimplexReader< dim >

class	regina::XMLTriangulationReader< dim >

Detailed Description

template<int dim>
class regina::detail::SimplexBase< dim >

Helper class that provides core functionality for a top-dimensional simplex in a dim-manifold triangulation.

Each top-dimensional simplex is represented by the class Simplex<dim>, which uses this as a base class. End users should not need to refer to SimplexBase directly.

See the Simplex template class notes for further information, including details of how the vertices and facets of each simplex are numbered.

Neither this class nor the "end user" class Simplex<dim> support value semantics: they cannot be copied, swapped, or manually constructed. Their memory is managed by the Triangulation class, and their locations in memory define them. See Simplex<dim> for further details.

Python: This base class is not present, but the "end user" class Simplex<dim> is.

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

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

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

◆ SimplexBase() [1/3]

template<int dim>

regina::detail::SimplexBase< dim >::SimplexBase ( 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.

◆ SimplexBase() [2/3]

template<int dim>

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

inlineprotected

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

Parameters

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

◆ SimplexBase() [3/3]

template<int dim>

regina::detail::SimplexBase< dim >::SimplexBase	(	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

◆ adjacentFacet()

template<int dim>

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

inline

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

inline

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

inline

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.

◆ component()

template<int dim>

Component< dim > * regina::detail::SimplexBase< dim >::component ( ) const

inline

Returns the connected component of the triangulation to which this simplex belongs.

Returns: the component containing this simplex.

◆ description()

template<int dim>

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

inline

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< SimplexBase< dim >, false >::detail ( ) const

inherited

Returns a detailed text representation of this object.

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

Returns: a detailed text representation of this object.

◆ edge() [1/2]

template<int dim>

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

inline

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

This alias is available for all dimensions dim.

See face() for further information.

◆ edge() [2/2]

template<int dim>

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

inline

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.

◆ edgeMapping()

template<int dim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::edgeMapping ( int face ) const

inline

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

This alias is available for all dimensions dim.

See faceMapping() for further information.

◆ face()

template<int dim>

template<int subdim>

Face< dim, subdim > * regina::detail::SimplexBase< dim >::face ( int face ) const

inline

Returns the subdim-face of the underlying triangulation that appears as the given subdim-face of this simplex.

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

Python: Python does not support templates. Instead, Python users should call this function in the form face(subdim, face); that is, the template parameter subdim becomes the first argument of the function.

Template Parameters

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

Parameters

face	the subdim-face of this simplex to examine. This should be between 0 and (dim+1 choose subdim+1)-1 inclusive.

Returns: the corresponding subdim-face of the triangulation.

◆ faceMapping()

template<int dim>

template<int subdim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::faceMapping ( int face ) const

inline

Examines the given subdim-face of this simplex, and returns the mapping between the underlying subdim-face of the triangulation and the individual vertices of this simplex.

Specifically:

Suppose several subdim-faces of several top-dimensional simplices are identified within the overall triangulation. Then we call this a single "<i>subdim</i>-face of the triangulation", and arbitrarily label its vertices (0, ..., subdim).
Now let F denote the subdim-face of the triangulation that corresponds to subdim-face number face of this simplex. Then this routine returns a map from vertices (0, ..., subdim) of F to the corresponding vertex numbers of this simplex.
In particular, if this routine returns the permutation p, then the images p[0,...,subdim] will be some permutation of the vertices Face<dim, subdim>::ordering[0,...,subdim].
If F also appears as face number k in some other simplex s, then for each i in the range 0 ≤ i ≤ subdim, vertex p[i] of this simplex will be identified with vertex s.faceMapping(k)[i] of simplex s.

If the link of the underlying subdim-face is orientable, then this permutation maps the remaining numbers (subdim+1, ..., dim) to the remaining vertex numbers of this simplex in a manner that preserves orientation as you walk through the many different simplices that contain the same underlying subdim-face. Specifically:

The images of (subdim+1, ..., dim) under this permutation imply an orientation for the (dim - subdim - 1)-face opposite F in this simplex. These orientations will be consistent for all simplices containing F.
For faces of codimension two (e.g., edges in a 3-manifold triangulation), this orientation condition is even stronger. Here the link of the face F must be a path (for a boundary face) or a cycle (for an internal face). In each simplex we can form a directed edge from the image of dim-1 to the image of dim under this permutation, and together these directed edges form a directed path or cycle that follows the link of the face F. Moreover, an iteration through the corresponding FaceEmbedding<dim, subdim> objects in order from F.begin() to F.end(), will follow this directed path in order from start to end. (In the case where the link of F is a cycle, the start point in the list of FaceEmbedding objects will be arbitrary.)

Note that, even if the link is orientable, there are still arbitrary decisions to be made for the images of (subdim+1, ..., dim), since there will always be (dim-subdim)!/2 possible mappings that yield the correct orientation.

If this simplex (and therefore the face F) belongs to an orientable component of the triangulation, then there will also be connections between faceMapping() and the orientations of the top-dimensional simplices (as returned by orientation()):

If subdim is less than (dim - 1), then the sign of the permutation returned by faceMapping() will always be equal to the orientation of this simplex.
If subdim is equal to (dim - 1), then the face F can only belong to either one or two top-dimensional simplices; let s0 and s1 be the simplices corresponding to F.embedding(0) and (if it exists) F.embedding(1) respectively. Then in the simplex s0, the sign of the faceMapping() permutation will match the orientation of s0, and in s1 (if it exists), the sign of the faceMapping() permutation will be negative the orientation of s1.

Note: This routine returns the same permutation as FaceEmbedding<dim, subdim>::vertices(), in the context of the FaceEmbedding<dim, subdim> object that refers to subdim-face number face of this simplex.

Python: Python does not support templates. Instead, Python users should call this function in the form faceMapping(subdim, face); that is, the template parameter subdim becomes the first argument of the function.

Template Parameters

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

Parameters

face	the subdim-face of this simplex to examine. This should be between 0 and (dim+1 choose subdim+1)-1 inclusive.

Returns: a mapping from the vertices of the underlying subdim-face of the triangulation to the vertices of this simplex.

◆ facetInMaximalForest()

template<int dim>

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

inline

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.

◆ hasBoundary()

template<int dim>

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

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

template<int dim>

size_t regina::detail::SimplexBase< dim >::index ( ) const

inline

Returns the index of this simplex in the underlying triangulation.

The index will be an integer between 0 and triangulation().size()-1 inclusive.

Note that indexing may change when a simplex is added to or removed from the underlying triangulation.

Returns: the index of this simplex.

◆ isFacetLocked()

template<int dim>

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

inline

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.

◆ isLocked()

template<int dim>

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

inline

Determines whether this top-dimensional simplex is locked.

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

Note that you can also lock the individual facets of a simplex (that is, its (dim-1)-faces); see lockFacet() for details. This routine does not test whether any facets of this simplex are locked; it only tests for a lock on the top-dimensional simplex itself.

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.

Returns: true if and only if this simplex is locked.

◆ isolate()

template<int dim>

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

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.

◆ join()

template<int dim>

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

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

◆ lock()

template<int dim>

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

inline

Locks this top-dimensional simplex.

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

A locked simplex cannot be removed completely (e.g., via Triangulation<dim>::removeSimplex() or via moves such as edge collapses or 2-0 moves).
A locked simplex cannot be subdivided (e.g., via Triangulation<dim>::subdivide(), or via a 1-(dim+1) Pachner move).
A locked simplex cannot be merged with adjacent simplices (e.g., via any of the other Pachner moves).

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

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

Note that you can also lock the individual facets of a simplex (that is, its (dim-1)-faces); see lockFacet() for details. Locking a simplex does not imply that its facets will be automatically locked also; 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).

◆ lockFacet()

template<int dim>

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

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

inline

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

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.

◆ orientation()

template<int dim>

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

inline

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

template<int dim>

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

inline

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

This alias is available for dimensions dim ≥ 5.

See face() for further information.

◆ pentachoronMapping()

template<int dim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::pentachoronMapping ( int face ) const

inline

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

This alias is available for dimensions dim ≥ 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

inlineprotected

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

inlineprotected

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 )

inline

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< SimplexBase< dim >, false >::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()

template<int dim>

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

inline

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

This alias is available for dimensions dim ≥ 4.

See face() for further information.

◆ tetrahedronMapping()

template<int dim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::tetrahedronMapping ( int face ) const

inline

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

This alias is available for dimensions dim ≥ 4.

See faceMapping() for further information.

◆ triangle()

template<int dim>

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

inline

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

This alias is available for dimensions dim ≥ 3.

See face() for further information.

◆ triangleMapping()

template<int dim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::triangleMapping ( int face ) const

inline

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

This alias is available for dimensions dim ≥ 3.

See faceMapping() for further information.

◆ triangulation()

template<int dim>

Triangulation< dim > & regina::detail::SimplexBase< dim >::triangulation ( ) const

inline

Returns the triangulation to which this simplex belongs.

Returns: a reference to the triangulation containing this simplex.

◆ unjoin()

template<int dim>

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

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

template<int dim>

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

inline

Unlocks this top-dimensional simplex.

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

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

Note that you can also lock the individual facets of a simplex (that is, its (dim-1)-faces); see lockFacet() for details. Unlocking a simplex does not imply that its facets will be automatically unlocked also; 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.

◆ unlockAll()

template<int dim>

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

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 )

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< SimplexBase< dim >, false >::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()

template<int dim>

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

inline

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

This alias is available for all dimensions dim.

See face() for further information.

◆ vertexMapping()

template<int dim>

Perm< dim+1 > regina::detail::SimplexBase< dim >::vertexMapping ( int face ) const

inline

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

This alias is available for all dimensions dim.

See faceMapping() for further information.

◆ writeTextLong()

template<int dim>

void regina::detail::SimplexBase< dim >::writeTextLong ( std::ostream & out ) const

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

Python: Not present. Use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

template<int dim>

void regina::detail::SimplexBase< dim >::writeTextShort ( std::ostream & out ) const

inline

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

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

◆ dimension

template<int dim>

int regina::detail::SimplexBase< dim >::dimension = dim

staticconstexpr

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

◆ subdimension

template<int dim>

int regina::detail::SimplexBase< dim >::subdimension = dim

staticconstexpr

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

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

triangulation/detail/simplex.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ FacetMask

◆ LockMask

Constructor & Destructor Documentation

◆ SimplexBase() [1/3]

◆ SimplexBase() [2/3]

◆ SimplexBase() [3/3]

Member Function Documentation

◆ adjacentFacet()

◆ adjacentGluing()

◆ adjacentSimplex()

◆ component()

◆ description()

◆ detail()

◆ edge() [1/2]

◆ edge() [2/2]

◆ edgeMapping()

◆ face()

◆ faceMapping()

◆ facetInMaximalForest()

◆ hasBoundary()

◆ index()

◆ isFacetLocked()

◆ isLocked()

◆ isolate()

◆ join()

◆ lock()

◆ lockFacet()

◆ lockMask()

◆ markedIndex()

◆ orientation()

◆ pentachoron()

◆ pentachoronMapping()

◆ sameDegreesAt() [1/2]

◆ sameDegreesAt() [2/2]

◆ setDescription()

◆ str()

◆ tetrahedron()

◆ tetrahedronMapping()

◆ triangle()

◆ triangleMapping()

◆ triangulation()

◆ unjoin()

◆ unlock()

◆ unlockAll()

◆ unlockFacet()

◆ utf8()

◆ vertex()

◆ vertexMapping()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ dimension

◆ subdimension