regina::Face< 3, 3 > Class Template Reference
3-Manifold Triangulations

Represents a tetrahedron within a 3-manifold triangulation. More...

`#include <triangulation/dim3.h>`

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

## Public Types

typedef IntOfMinSize<(dim/8)+1 >::utype | FacetMask
| An unsigned integer type with at least dim+1 bits. More...

## Public Member Functions

Simplex< 3 > * | adjacentTetrahedron (int face) const
| A dimension-specific alias for adjacentSimplex(). More...
int | adjacentFace (int face) const
| A dimension-specific alias for adjacentFacet(). More...
const std::string & | description () const
| Returns the description associated with this simplex. More...
void | setDescription (const std::string &desc)
| Sets the description associated with this simplex. More...
size_t | index () const
| Returns the index of this simplex in the underlying triangulation. More...
Simplex< dim > * | adjacentSimplex (int facet) const
| Returns the adjacent simplex that is glued to the given facet of this simplex. More...
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. More...
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. More...
bool | hasBoundary () const
| Determines if this simplex has any facets that lie on the triangulation boundary. More...
void | join (int myFacet, Simplex< dim > *you, Perm< dim+1 > gluing)
| Joins the given facet of this simplex to some facet of another simplex. More...
Simplex< dim > * | unjoin (int myFacet)
| Unglues the given facet of this simplex from whatever it is joined to. More...
void | isolate ()
| Unglues this simplex from any adjacent simplices. More...
Triangulation< dim > * | triangulation () const
| Returns the triangulation to which this simplex belongs. More...
Component< dim > * | component () const
| Returns the connected component of the triangulation to which this simplex belongs. More...
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. More...
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. More...
int | orientation () const
| Returns the orientation of this simplex in the dim-dimensional triangulation. More...
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. More...
void | writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
void | writeTextLong (std::ostream &out) const
| Writes a detailed text representation of this object to the given output stream. More...
size_t | markedIndex () const
| Returns the index at which this object is stored in an MarkedVector. More...
std::string | str () const
| Returns a short text representation of this object. More...
std::string | utf8 () const
| Returns a short text representation of this object using unicode characters. More...
std::string | detail () const
| Returns a detailed text representation of this object. More...

## Protected Member Functions

bool | sameDegrees (const SimplexFacesSuite< dim, subdim > &other, Perm< dim+1 > p) const
| Tests whether the k-face degrees of this and the given simplex are identical, under the given relabelling, for all faces of all dimensions k ≤ subdim. More...
bool | sameDegrees (const SimplexFaces< dim, subdim > &other, Perm< dim+1 > p) const
| Tests whether the subdim-face degrees of this and the given simplex are identical, under the given relabelling. More...
void | clear ()
| Resets all face pointers to null. More...

## Protected Attributes

Face< dim, subdim > * | face_ [FaceNumbering< dim, subdim >::nFaces]
| The faces of the underlying triangulation that form the individual subdim-faces of this simplex. More...
Perm< dim+1 > | mapping_ [FaceNumbering< dim, subdim >::nFaces]
| For each subdim-face of this simplex, maps vertices (0,1,...,subdim) of the underlying subdim-face of the triangulation to the corresponding vertices of this simplex, as described by faceMapping(). More...

## Friends

class | Triangulation< 3 >
class | detail::TriangulationBase< 3 >
| Allow access to private members. More...

## Detailed Description

### template<>
class regina::Face< 3, 3 >

Represents a tetrahedron within a 3-manifold triangulation.

This class is typically referred to by the aliases Simplex<3> or Tetrahedron<3> (or, for Python users, `Simplex3` and `Tetrahedron3`).

The class template Face<dim, dim> specialises the generic Face class template in order to work with top-dimensional simplices in a triangulation. This class Face<3, 3> specialises it further to add dimension-specific aliases for dimension 3.

See the documentation for the partial specialisation Face<dim, dim> for an overview of how a top-dimensional simplex class works.

## Member Typedef Documentation

## FacetMask

typedef IntOfMinSize<(dim / 8) + 1>::utype regina::detail::SimplexBase< dim >::FacetMask

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.

## Member Function Documentation

## adjacentFace()

int regina::Face< 3, 3 >::adjacentFace | ( | int | face | ) | const

inline

A dimension-specific alias for adjacentFacet().

See adjacentFacet() for further information.

## adjacentFacet()

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

inline inherited

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

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

inline inherited

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

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

inline inherited

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

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 0 if the given facet lies on the boundary.

## adjacentTetrahedron()

Simplex< 3 > * regina::Face< 3, 3 >::adjacentTetrahedron | ( | int | face | ) | const

inline

A dimension-specific alias for adjacentSimplex().

See adjacentSimplex() for further information.

## clear()

template<int dim, int subdim>

void regina::detail::SimplexFaces< dim, subdim >::clear | ( |  | ) |

inline protected inherited

Resets all face pointers to null.

The faces themselves are not destroyed, and the mapping permutations are not touched.

## component()

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

inline inherited

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

Returns
  the component containing this simplex.

## description()

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

inline inherited

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.

## face()

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

inline inherited

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.

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

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

inline inherited

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.

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.

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

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

inline inherited

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

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::SimplexBase< dim >::index | ( |  | ) | const

inline inherited

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.

## isolate()

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

## join()

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

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

## markedIndex()

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

inline inherited

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

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

inline inherited

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

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

## sameDegrees() [1/2]

template<int dim, int subdim>

bool regina::detail::SimplexFaces< dim, subdim >::sameDegrees | ( | const SimplexFaces< dim, subdim > & | other,
|  | Perm< dim+1 > | p
| ) |  | const

protected inherited

Tests whether the subdim-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, subdim-face number i of this simplex has the same degree as its image in other under the relabelling p.

## sameDegrees() [2/2]

bool regina::detail::SimplexFacesSuite< dim >::sameDegrees | ( | const SimplexFacesSuite< dim, subdim > & | other,
|  | Perm< dim+1 > | p
| ) |  | const

inline protected inherited

Tests whether the k-face degrees of this and the given simplex are identical, under the given relabelling, for all faces of all dimensions k ≤ subdim.

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 ≤ subdim, k-face number i of this simplex has the same degree as its image in other under the relabelling p.

## setDescription()

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

inline inherited

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 fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
  In addition to str(), this is also used as the Python "stringification" function `__str__()`.

Returns
  a short text representation of this object.

## triangulation()

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

inline inherited

Returns the triangulation to which this simplex belongs.

Returns
  the triangulation containing this simplex.

## unjoin()

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

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 0 if this was already a boundary facet.

## 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 fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
  a short text representation of this object.

## writeTextLong()

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

inherited

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

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort()

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

inline inherited

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

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## Friends And Related Function Documentation

## detail::TriangulationBase< 3 >

friend class detail::TriangulationBase< 3 >

friend

Allow access to private members.

## Member Data Documentation

## face_

template<int dim, int subdim>

Face<dim, subdim>* regina::detail::SimplexFaces< dim, subdim >::face_[FaceNumbering< dim, subdim >::nFaces]

protected inherited

The faces of the underlying triangulation that form the individual subdim-faces of this simplex.

## mapping_

template<int dim, int subdim>

Perm<dim+1> regina::detail::SimplexFaces< dim, subdim >::mapping_[FaceNumbering< dim, subdim >::nFaces]

protected inherited

For each subdim-face of this simplex, maps vertices (0,1,...,subdim) of the underlying subdim-face of the triangulation to the corresponding vertices of this simplex, as described by faceMapping().

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

- triangulation/dim3/tetrahedron3.h

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