Regina 7.3 Calculation Engine
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
regina::SnapPeaTriangulation Class Reference

Offers direct access to the SnapPea kernel from within Regina. More...

#include <snappea/snappeatriangulation.h>

Inheritance diagram for regina::SnapPeaTriangulation:
regina::Triangulation< 3 > regina::PacketData< SnapPeaTriangulation > regina::Output< SnapPeaTriangulation > regina::detail::TriangulationBase< 3 > regina::Snapshottable< Triangulation< dim > > regina::PacketData< Triangulation< dim > > regina::Output< Triangulation< dim > > regina::TightEncodable< Triangulation< dim > >

Public Types

enum  SolutionType {
  not_attempted , geometric_solution , nongeometric_solution , flat_solution ,
  degenerate_solution , other_solution , no_solution , externally_computed
}
 Describes the different types of solution that can be found when solving for a hyperbolic structure. More...
 
enum  CoverEnumerationType { cyclic_covers , all_covers }
 Indicates which types of covers should be enumerated when calling enumerateCovers(). More...
 
enum  CoverType { unknown_cover , irregular_cover , regular_cover , cyclic_cover }
 Indicates the different types of covers that can be produced by enumerateCovers(). More...
 
using TuraevViroSet = std::map< std::pair< unsigned long, bool >, Cyclotomic >
 A map from (r, parity) pairs to Turaev-Viro invariants, as described by turaevViro(). More...
 

Public Member Functions

bool isReadOnlySnapshot () const
 Determines if this object is a read-only deep copy that was created by a snapshot. More...
 
std::shared_ptr< PacketOf< Triangulation< dim > > > packet ()
 Returns the packet that holds this data, if there is one. More...
 
std::shared_ptr< const PacketOf< Triangulation< dim > > > packet () const
 Returns the packet that holds this data, if there is one. More...
 
std::string anonID () const
 A unique string ID that can be used in place of a packet ID. 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...
 
std::string tightEncoding () const
 Returns the tight encoding of this object. More...
 
std::shared_ptr< PacketOf< SnapPeaTriangulation > > packet ()
 Returns the packet that holds this data, if there is one. More...
 
std::shared_ptr< const PacketOf< SnapPeaTriangulation > > packet () const
 Returns the packet that holds this data, if there is one. More...
 
std::string anonID () const
 A unique string ID that can be used in place of a packet ID. 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...
 
Constructors and Destructors
 SnapPeaTriangulation ()
 Creates a null triangulation, with no internal SnapPea data at all. More...
 
 SnapPeaTriangulation (const std::string &fileNameOrContents)
 Creates a new SnapPea triangulation from the contents of SnapPea data file. More...
 
 SnapPeaTriangulation (const SnapPeaTriangulation &src)
 Creates a new copy of the given SnapPea triangulation. More...
 
 SnapPeaTriangulation (SnapPeaTriangulation &&src) noexcept
 Moves the given SnapPea triangulation into this new triangulation. More...
 
 SnapPeaTriangulation (const Triangulation< 3 > &tri, bool ignored=false)
 Converts the given Regina triangulation to a SnapPea triangulation. More...
 
 SnapPeaTriangulation (const Link &link)
 Creates a new ideal SnapPea triangulation representing the complement of the given link in the 3-sphere. More...
 
 SnapPeaTriangulation (regina::snappea::Triangulation *data)
 Creates a new triangulation that holds the given raw data from the SnapPea kernel. More...
 
 ~SnapPeaTriangulation ()
 Destroys this triangulation. More...
 
Tetrahedra
SnapPeaTriangulationoperator= (const SnapPeaTriangulation &src)
 Sets this to be a (deep) copy of the given SnapPea triangulation. More...
 
SnapPeaTriangulationoperator= (SnapPeaTriangulation &&src)
 Moves the contents of the given triangulation into this triangulation. More...
 
void swap (SnapPeaTriangulation &other)
 Swaps the contents of this and the given SnapPea triangulation. More...
 
void nullify ()
 Sets this to be a null SnapPea triangulation. More...
 
Basic Properties
bool isNull () const
 Determines whether this triangulation contains valid SnapPea data. More...
 
std::string name () const
 Returns SnapPea's internal name for this triangulation. More...
 
Hyperbolic Structures
SolutionType solutionType () const
 Returns the type of solution found when solving for a hyperbolic structure, with respect to the current Dehn filling (if any). More...
 
double volume () const
 Computes the volume of the current solution to the hyperbolic gluing equations. More...
 
std::pair< double, int > volumeWithPrecision () const
 Computes the volume of the current solution to the hyperbolic gluing equations, and estimates the accuracy of the answer. More...
 
bool volumeZero () const
 Determines whether the current solution to the gluing equations has volume approximately zero. More...
 
const std::complex< double > & shape (size_t tet) const
 Returns the shape of the given tetrahedron, with respect to the Dehn filled hyperbolic structure. More...
 
double minImaginaryShape () const
 Returns the minimum imaginary part found amongst all tetrahedron shapes, with respect to the Dehn filled hyperbolic structure. More...
 
MatrixInt gluingEquations () const
 Returns a matrix describing Thurston's gluing equations. More...
 
MatrixInt gluingEquationsRect () const
 Returns a matrix describing Thurston's gluing equations in a streamlined form. More...
 
bool operator== (const SnapPeaTriangulation &other) const
 Determines whether this and the given SnapPea triangulation are, at some elementary level, the same. More...
 
bool operator!= (const SnapPeaTriangulation &other) const
 Determines whether this and the given SnapPea triangulation are, at some elementary level, different. More...
 
Cusps
unsigned countCusps () const
 Returns the total number of cusps (both filled and complete). More...
 
unsigned countCompleteCusps () const
 Returns the total number of complete cusps (that is, unfilled cusps). More...
 
unsigned countFilledCusps () const
 Returns the total number of filled cusps. More...
 
const Cuspcusp (unsigned whichCusp=0) const
 Returns information about the given cusp of this manifold. More...
 
auto cusps () const
 Returns an object that allows iteration through and random access to information about all of the cusps of this manifold. More...
 
bool fill (int m, int l, unsigned whichCusp=0)
 Assigns a Dehn filling to the given cusp. More...
 
void unfill (unsigned whichCusp=0)
 Removes any filling on the given cusp. More...
 
SnapPeaTriangulation filledPartial (unsigned whichCusp) const
 Retriangulates to permanently fill the given cusp. More...
 
SnapPeaTriangulation filledPartial () const
 Retriangulates to permanently fill some but not all cusps. More...
 
Triangulation< 3 > filledAll () const
 Retriangulates to permanently fill all cusps. More...
 
MatrixInt slopeEquations () const
 Returns a matrix for computing boundary slopes of spun-normal surfaces at the cusps of the triangulation. More...
 
Algebraic Invariants
const AbelianGrouphomologyFilled () const
 Returns the first homology group of the manifold with respect to the current Dehn filling (if any). More...
 
const GroupPresentationfundamentalGroupFilled (bool simplifyPresentation=true, bool fillingsMayAffectGenerators=true, bool minimiseNumberOfGenerators=true, bool tryHardToShortenRelators=true) const
 Returns the fundamental group of the manifold with respect to the current Dehn filling (if any). More...
 
template<typename Action , typename... Args>
size_t enumerateCovers (int sheets, CoverEnumerationType type, Action &&action, Args &&... args) const
 Enumerates connected k-sheeted covers of the underlying manifold. More...
 
Manipulating SnapPea triangulations
SnapPeaTriangulation protoCanonise () const
 Constructs the canonical cell decomposition, using an arbitrary retriangulation if this decomposition contains non-tetrahedron cells. More...
 
SnapPeaTriangulation protoCanonize () const
 An alias for protoCanonise(), which constructs the canonical cell decomposition using an arbitrary retriangulation if necessary. More...
 
Triangulation< 3 > canonise () const
 Constructs the canonical retriangulation of the canonical cell decomposition. More...
 
Triangulation< 3 > canonize () const
 An alias for canonise(), which constructs the canonical retriangulation of the canonical cell decomposition. More...
 
void randomise ()
 Asks SnapPea to randomly retriangulate this manifold, using local moves that preserve the topology. More...
 
void randomize ()
 An alias for randomise(), which asks SnapPea to randomly retriangulate this manifold. More...
 
SnapPea Input and Output
std::string snapPea () const
 Returns a string containing the full contents of a SnapPea data file that describes this triangulation. More...
 
void snapPea (std::ostream &out) const
 Writes the full contents of a SnapPea data file describing this triangulation to the given output stream. More...
 
bool saveSnapPea (const char *filename) const
 Writes this triangulation to the given file using SnapPea's native file format. More...
 
Constructors and Destructors
std::shared_ptr< PacketinAnyPacket ()
 Returns the packet that holds this data, even if it is held indirectly via a SnapPea triangulation. More...
 
std::shared_ptr< const PacketinAnyPacket () const
 Returns the packet that holds this data, even if it is held indirectly via a SnapPea triangulation. More...
 
SnapPeaTriangulationisSnapPea ()
 Returns the SnapPea triangulation that holds this data, if there is one. More...
 
const SnapPeaTriangulationisSnapPea () const
 Returns the SnapPea triangulation that holds this data, if there is one. More...
 
Tetrahedra
Tetrahedron< 3 > * newTetrahedron ()
 A dimension-specific alias for newSimplex(). More...
 
Tetrahedron< 3 > * newTetrahedron (const std::string &desc)
 A dimension-specific alias for newSimplex(). More...
 
template<int k>
std::array< Tetrahedron< 3 > *, k > newTetrahedra ()
 A dimension-specific alias for newSimplices(). More...
 
void newTetrahedra (size_t k)
 A dimension-specific alias for newSimplices(). More...
 
void removeTetrahedron (Tetrahedron< 3 > *tet)
 A dimension-specific alias for removeSimplex(). More...
 
void removeTetrahedronAt (size_t index)
 A dimension-specific alias for removeSimplexAt(). More...
 
void removeAllTetrahedra ()
 A dimension-specific alias for removeAllSimplices(). More...
 
void swap (Triangulation< 3 > &other)
 Swaps the contents of this and the given triangulation. More...
 
Skeletal Queries
bool hasBoundaryTriangles () const
 A dimension-specific alias for hasBoundaryFacets(). More...
 
size_t countBoundaryTriangles () const
 A dimension-specific alias for countBoundaryFacets(). More...
 
bool hasTwoSphereBoundaryComponents () const
 Determines if this triangulation contains any two-sphere boundary components. More...
 
bool hasNegativeIdealBoundaryComponents () const
 Determines if this triangulation contains any ideal boundary components with negative Euler characteristic. More...
 
bool hasMinimalBoundary () const
 Determines whether the boundary of this triangulation contains the smallest possible number of triangles. More...
 
bool hasMinimalVertices () const
 Determines whether this triangulation contains the smallest possible number of vertices for the 3-manifold that it represents. More...
 
Basic Properties
long eulerCharManifold () const
 Returns the Euler characteristic of the corresponding compact 3-manifold. More...
 
bool isIdeal () const
 Determines if this triangulation is ideal. More...
 
bool isStandard () const
 Determines if this triangulation is standard. More...
 
bool isClosed () const
 Determines if this triangulation is closed. More...
 
bool isOrdered () const
 Determines if this triangulation is ordered; that is, if tetrahedron vertices are labelled so that all gluing permutations are order-preserving on the tetrahedron faces. More...
 
Algebraic Properties
const AbelianGrouphomologyRel () const
 Returns the relative first homology group with respect to the boundary for this triangulation. More...
 
const AbelianGrouphomologyBdry () const
 Returns the first homology group of the boundary for this triangulation. More...
 
unsigned long homologyH2Z2 () const
 Returns the second homology group with coefficients in Z_2 for this triangulation. More...
 
Cyclotomic turaevViro (unsigned long r, bool parity=true, Algorithm alg=ALG_DEFAULT, ProgressTracker *tracker=nullptr) const
 Computes the given Turaev-Viro state sum invariant of this 3-manifold using exact arithmetic. More...
 
double turaevViroApprox (unsigned long r, unsigned long whichRoot=1, Algorithm alg=ALG_DEFAULT) const
 Computes the given Turaev-Viro state sum invariant of this 3-manifold using a fast but inexact floating-point approximation. More...
 
const TuraevViroSetallCalculatedTuraevViro () const
 Returns the cache of all Turaev-Viro state sum invariants that have been calculated for this 3-manifold. More...
 
std::array< long, 3 > longitudeCuts () const
 Identifies the algebraic longitude as a curve on the boundary of a triangulated knot complement. More...
 
Edge< 3 > * longitude ()
 Modifies a triangulated knot complement so that the algebraic longitude follows a single boundary edge, and returns this edge. More...
 
Edge< 3 > * meridian ()
 Modifies a triangulated knot complement so that the meridian follows a single boundary edge, and returns this edge. More...
 
std::pair< Edge< 3 > *, Edge< 3 > * > meridianLongitude ()
 Modifies a triangulated knot complement so that the meridian and algebraic longitude each follow a single boundary edge, and returns these two edges. More...
 
Normal Surfaces and Angle Structures
template<int subdim>
std::pair< NormalSurface, bool > linkingSurface (const Face< 3, subdim > &face) const
 Returns the link of the given face as a normal surface. More...
 
bool isZeroEfficient () const
 Determines if this triangulation is 0-efficient. More...
 
bool knowsZeroEfficient () const
 Is it already known whether or not this triangulation is 0-efficient? See isZeroEfficient() for further details. More...
 
bool hasSplittingSurface () const
 Determines whether this triangulation has a normal splitting surface. More...
 
std::optional< NormalSurfacenonTrivialSphereOrDisc () const
 Searches for a non-vertex-linking normal sphere or disc within this triangulation. More...
 
std::optional< NormalSurfaceoctagonalAlmostNormalSphere () const
 Searches for an octagonal almost normal 2-sphere within this triangulation. More...
 
const AngleStructurestrictAngleStructure () const
 Returns a strict angle structure on this triangulation, if one exists. More...
 
bool hasStrictAngleStructure () const
 Determines whether this triangulation supports a strict angle structure. More...
 
bool knowsStrictAngleStructure () const
 Is it already known (or trivial to determine) whether or not this triangulation supports a strict angle structure? See hasStrictAngleStructure() for further details. More...
 
const AngleStructuregeneralAngleStructure () const
 Returns a generalised angle structure on this triangulation, if one exists. More...
 
bool hasGeneralAngleStructure () const
 Determines whether this triangulation supports a generalised angle structure. More...
 
Skeletal Transformations
std::set< Edge< 3 > * > maximalForestInBoundary () const
 Produces a maximal forest in the 1-skeleton of the triangulation boundary. More...
 
std::set< Edge< 3 > * > maximalForestInSkeleton (bool canJoinBoundaries=true) const
 Produces a maximal forest in the triangulation's 1-skeleton. More...
 
bool intelligentSimplify ()
 Attempts to simplify the triangulation using fast and greedy heuristics. More...
 
bool simplifyToLocalMinimum (bool perform=true)
 Uses all known simplification moves to reduce the triangulation monotonically to some local minimum number of tetrahedra. More...
 
bool simplifyExhaustive (int height=1, unsigned threads=1, ProgressTrackerOpen *tracker=nullptr)
 Attempts to simplify this triangulation using a slow but exhaustive search through the Pachner graph. More...
 
template<typename Action , typename... Args>
bool retriangulate (int height, unsigned threads, ProgressTrackerOpen *tracker, Action &&action, Args &&... args) const
 Explores all triangulations that can be reached from this via Pachner moves, without exceeding a given number of additional tetrahedra. More...
 
bool minimiseBoundary ()
 Ensures that the boundary contains the smallest possible number of triangles, potentially adding tetrahedra to do this. More...
 
bool minimizeBoundary ()
 A deprecated synonym for minimiseBoundary(). More...
 
bool minimiseVertices ()
 Ensures that this triangulation contains the smallest possible number of vertices for the 3-manifold that it represents, potentially adding tetrahedra to do this. More...
 
bool minimizeVertices ()
 A deprecated synonym for minimiseVertices(). More...
 
bool fourFourMove (Edge< 3 > *e, int newAxis, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 4-4 move about the given edge. More...
 
bool twoZeroMove (Edge< 3 > *e, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 2-0 move about the given edge of degree 2. More...
 
bool twoZeroMove (Vertex< 3 > *v, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 2-0 move about the given vertex of degree 2. More...
 
bool twoOneMove (Edge< 3 > *e, int edgeEnd, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 2-1 move about the given edge. More...
 
bool zeroTwoMove (EdgeEmbedding< 3 > e0, int t0, EdgeEmbedding< 3 > e1, int t1, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 0-2 move about the (not necessarily distinct) triangles e0.tetrahedron()->triangle(e0.vertices()[t0]) and e1.tetrahedron()->triangle(e1.vertices()[t1]). More...
 
bool zeroTwoMove (Edge< 3 > *e, size_t t0, size_t t1, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 0-2 move about the (not necessarily distinct) triangles incident to e that are numbered t0 and t1. More...
 
bool zeroTwoMove (Triangle< 3 > *t0, int e0, Triangle< 3 > *t1, int e1, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a 0-2 move about the (not necessarily distinct) triangles t0 and t1. More...
 
bool openBook (Triangle< 3 > *t, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a book opening move about the given triangle. More...
 
bool closeBook (Edge< 3 > *e, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a book closing move about the given boundary edge. More...
 
bool shellBoundary (Tetrahedron< 3 > *t, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a boundary shelling move on the given tetrahedron. More...
 
bool collapseEdge (Edge< 3 > *e, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a collapse of an edge between two distinct vertices. More...
 
void reorderTetrahedraBFS (bool reverse=false)
 Reorders the tetrahedra of this triangulation using a breadth-first search, so that small-numbered tetrahedra are adjacent to other small-numbered tetrahedra. More...
 
bool order (bool forceOriented=false)
 Relabels tetrahedron vertices in this triangulation to give an ordered triangulation, if possible. More...
 
Decompositions
std::vector< Triangulation< 3 > > summands () const
 Computes the connected sum decomposition of this triangulation. More...
 
bool isSphere () const
 Determines whether this is a triangulation of a 3-sphere. More...
 
bool knowsSphere () const
 Is it already known (or trivial to determine) whether or not this is a triangulation of a 3-sphere? See isSphere() for further details. More...
 
bool isBall () const
 Determines whether this is a triangulation of a 3-dimensional ball. More...
 
bool knowsBall () const
 Is it already known (or trivial to determine) whether or not this is a triangulation of a 3-dimensional ball? See isBall() for further details. More...
 
bool isSolidTorus () const
 Determines whether this is a triangulation of the solid torus; that is, the unknot complement. More...
 
bool knowsSolidTorus () const
 Is it already known (or trivial to determine) whether or not this is a triangulation of a solid torus (that is, the unknot complement)? See isSolidTorus() for further details. More...
 
ssize_t recogniseHandlebody () const
 Determines whether this is a triangulation of an orientable handlebody, and if so, which genus. More...
 
bool knowsHandlebody () const
 Is it already known (or trivial to determine) whether or not this is a triangulation of an orientable handlebody? See recogniseHandlebody() for further details. More...
 
bool isTxI () const
 Determines whether or not the underlying 3-manifold is the product of a torus with an interval. More...
 
bool knowsTxI () const
 Is it already known (or trivial to determine) whether or not this is a triangulation of a the product of a torus with an interval? See isTxI() for further details. More...
 
bool isIrreducible () const
 Determines whether the underlying 3-manifold (which must be closed) is irreducible. More...
 
bool knowsIrreducible () const
 Is it already known (or trivial to determine) whether or not the underlying 3-manifold is irreducible? See isIrreducible() for further details. More...
 
bool hasCompressingDisc () const
 Searches for a compressing disc within the underlying 3-manifold. More...
 
bool knowsCompressingDisc () const
 Is it already known (or trivial to determine) whether or not the underlying 3-manifold contains a compressing disc? See hasCompressingDisc() for further details. More...
 
bool isHaken () const
 Determines whether the underlying 3-manifold (which must be closed and orientable) is Haken. More...
 
bool knowsHaken () const
 Is it already known (or trivial to determine) whether or not the underlying 3-manifold is Haken? See isHaken() for further details. More...
 
bool hasSimpleCompressingDisc () const
 Searches for a "simple" compressing disc inside this triangulation. More...
 
const TreeDecompositionniceTreeDecomposition () const
 Returns a nice tree decomposition of the face pairing graph of this triangulation. More...
 
Subdivisions, Extensions and Covers
bool idealToFinite ()
 Converts an ideal triangulation into a finite triangulation. More...
 
void pinchEdge (Edge< 3 > *e)
 Pinches an internal edge to a point. More...
 
void puncture (Tetrahedron< 3 > *tet=nullptr)
 Punctures this manifold by removing a 3-ball from the interior of the given tetrahedron. More...
 
Building Triangulations
Tetrahedron< 3 > * layerOn (Edge< 3 > *edge)
 Performs a layering upon the given boundary edge of the triangulation. More...
 
bool fillTorus (unsigned long cuts0, unsigned long cuts1, unsigned long cuts2, BoundaryComponent< 3 > *bc=nullptr)
 Fills a two-triangle torus boundary component by attaching a solid torus along a given curve. More...
 
bool fillTorus (Edge< 3 > *e0, Edge< 3 > *e1, Edge< 3 > *e2, unsigned long cuts0, unsigned long cuts1, unsigned long cuts2)
 Fills a two-triangle torus boundary component by attaching a solid torus along a given curve. More...
 
Tetrahedron< 3 > * insertLayeredSolidTorus (unsigned long cuts0, unsigned long cuts1)
 Inserts a new layered solid torus into the triangulation. More...
 
void connectedSumWith (const Triangulation &other)
 Forms the connected sum of this triangulation with the given triangulation. More...
 
Exporting Triangulations
std::string dehydrate () const
 Dehydrates this triangulation into an alphabetical string. More...
 
std::string recogniser () const
 Returns a string that expresses this triangulation in Matveev's 3-manifold recogniser format. More...
 
void recogniser (std::ostream &out) const
 Writes a string expressing this triangulation in Matveev's 3-manifold recogniser format to the given output stream. More...
 
std::string recognizer () const
 A synonym for recogniser(). More...
 
void recognizer (std::ostream &out) const
 A synonym for recognizer(std::ostream&). More...
 
bool saveRecogniser (const char *filename) const
 Writes this triangulation to the given file in Matveev's 3-manifold recogniser format. More...
 
bool saveRecognizer (const char *filename) const
 A synonym for saveRecogniser(). More...
 
Simplices
size_t size () const
 Returns the number of top-dimensional simplices in the triangulation. More...
 
auto simplices () const
 Returns an object that allows iteration through and random access to all top-dimensional simplices in this triangulation. More...
 
Simplex< dim > * simplex (size_t index)
 Returns the top-dimensional simplex at the given index in the triangulation. More...
 
const Simplex< dim > * simplex (size_t index) const
 Returns the top-dimensional simplex at the given index in the triangulation. More...
 
Simplex< dim > * newSimplex ()
 Creates a new top-dimensional simplex and adds it to this triangulation. More...
 
Simplex< dim > * newSimplex (const std::string &desc)
 Creates a new top-dimensional simplex with the given description and adds it to this triangulation. More...
 
std::array< Simplex< dim > *, k > newSimplices ()
 Creates k new top-dimensional simplices, adds them to this triangulation, and returns them in a std::array. More...
 
void newSimplices (size_t k)
 Creates k new top-dimensional simplices and adds them to this triangulation. More...
 
void removeSimplex (Simplex< dim > *simplex)
 Removes the given top-dimensional simplex from this triangulation. More...
 
void removeSimplexAt (size_t index)
 Removes the top-dimensional simplex at the given index in this triangulation. More...
 
void removeAllSimplices ()
 Removes all simplices from the triangulation. More...
 
void moveContentsTo (Triangulation< dim > &dest)
 Moves the contents of this triangulation into the given destination triangulation, without destroying any pre-existing contents. More...
 
Skeletal Queries
size_t countComponents () const
 Returns the number of connected components in this triangulation. More...
 
size_t countBoundaryComponents () const
 Returns the number of boundary components in this triangulation. More...
 
size_t countFaces () const
 Returns the number of subdim-faces in this triangulation. More...
 
size_t countFaces (int subdim) const
 Returns the number of subdim-faces in this triangulation, where the face dimension does not need to be known until runtime. More...
 
size_t countVertices () const
 A dimension-specific alias for countFaces<0>(). More...
 
size_t countEdges () const
 A dimension-specific alias for countFaces<1>(). More...
 
size_t countTriangles () const
 A dimension-specific alias for countFaces<2>(). More...
 
size_t countTetrahedra () const
 A dimension-specific alias for countFaces<3>(). More...
 
size_t countPentachora () const
 A dimension-specific alias for countFaces<4>(). More...
 
std::vector< size_t > fVector () const
 Returns the f-vector of this triangulation, which counts the number of faces of all dimensions. More...
 
auto components () const
 Returns an object that allows iteration through and random access to all components of this triangulation. More...
 
auto boundaryComponents () const
 Returns an object that allows iteration through and random access to all boundary components of this triangulation. More...
 
auto faces () const
 Returns an object that allows iteration through and random access to all subdim-faces of this triangulation, in a way that is optimised for C++ programmers. More...
 
auto faces (int subdim) const
 Returns an object that allows iteration through and random access to all subdim-faces of this triangulation, in a way that is optimised for Python programmers. More...
 
auto vertices () const
 A dimension-specific alias for faces<0>(). More...
 
auto edges () const
 A dimension-specific alias for faces<1>(). More...
 
auto triangles () const
 A dimension-specific alias for faces<2>(), or an alias for simplices() in dimension dim = 2. More...
 
auto tetrahedra () const
 A dimension-specific alias for faces<3>(), or an alias for simplices() in dimension dim = 3. More...
 
auto pentachora () const
 A dimension-specific alias for faces<4>(), or an alias for simplices() in dimension dim = 4. More...
 
Component< dim > * component (size_t index) const
 Returns the requested connected component of this triangulation. More...
 
BoundaryComponent< dim > * boundaryComponent (size_t index) const
 Returns the requested boundary component of this triangulation. More...
 
Face< dim, subdim > * face (size_t index) const
 Returns the requested subdim-face of this triangulation, in a way that is optimised for C++ programmers. More...
 
auto face (int subdim, size_t index) const
 Returns the requested subdim-face of this triangulation, in a way that is optimised for Python programmers. More...
 
Face< dim, 0 > * vertex (size_t index) const
 A dimension-specific alias for face<0>(). More...
 
Face< dim, 1 > * edge (size_t index) const
 A dimension-specific alias for face<1>(). More...
 
Face< dim, 2 > * triangle (size_t index)
 A dimension-specific alias for face<2>(), or an alias for simplex() in dimension dim = 2. More...
 
auto triangle (size_t index) const
 A dimension-specific alias for face<2>(), or an alias for simplex() in dimension dim = 2. More...
 
Face< dim, 3 > * tetrahedron (size_t index)
 A dimension-specific alias for face<3>(), or an alias for simplex() in dimension dim = 3. More...
 
auto tetrahedron (size_t index) const
 A dimension-specific alias for face<3>(), or an alias for simplex() in dimension dim = 3. More...
 
Face< dim, 4 > * pentachoron (size_t index)
 A dimension-specific alias for face<4>(), or an alias for simplex() in dimension dim = 4. More...
 
auto pentachoron (size_t index) const
 A dimension-specific alias for face<4>(), or an alias for simplex() in dimension dim = 4. More...
 
Face< dim, subdim > * translate (const Face< dim, subdim > *other) const
 Translates a face of some other triangulation into the corresponding face of this triangulation, using simplex numbers for the translation. More...
 
FacetPairing< dim > pairing () const
 Returns the dual graph of this triangulation, expressed as a facet pairing. More...
 
Basic Properties
bool isEmpty () const
 Determines whether this triangulation is empty. More...
 
bool isValid () const
 Determines if this triangulation is valid. More...
 
bool hasBoundaryFacets () const
 Determines if this triangulation has any boundary facets. More...
 
size_t countBoundaryFacets () const
 Returns the total number of boundary facets in this triangulation. More...
 
size_t countBoundaryFaces () const
 Returns the number of boundary subdim-faces in this triangulation. More...
 
size_t countBoundaryFaces (int subdim) const
 Returns the number of boundary subdim-faces in this triangulation, where the face dimension does not need to be known until runtime. More...
 
bool isOrientable () const
 Determines if this triangulation is orientable. More...
 
bool isConnected () const
 Determines if this triangulation is connected. More...
 
bool isOriented () const
 Determines if this triangulation is oriented; that is, if the vertices of its top-dimensional simplices are labelled in a way that preserves orientation across adjacent facets. More...
 
long eulerCharTri () const
 Returns the Euler characteristic of this triangulation. More...
 
Algebraic Properties
const GroupPresentationgroup () const
 Returns the fundamental group of this triangulation. More...
 
const GroupPresentationfundamentalGroup () const
 An alias for group(), which returns the fundamental group of this triangulation. More...
 
void simplifiedFundamentalGroup (GroupPresentation newGroup)
 Notifies the triangulation that you have simplified the presentation of its fundamental group. More...
 
AbelianGroup homology () const
 Returns the kth homology group of this triangulation, treating any ideal vertices as though they had been truncated. More...
 
AbelianGroup homology (int k) const
 Returns the kth homology group of this triangulation, treating any ideal vertices as though they had been truncated, where the parameter k does not need to be known until runtime. More...
 
MarkedAbelianGroup markedHomology () const
 Returns the kth homology group of this triangulation, without truncating ideal vertices, but with explicit coordinates that track the individual k-faces of this triangulation. More...
 
MarkedAbelianGroup markedHomology (int k) const
 Returns the kth homology group of this triangulation, without truncating ideal vertices, but with explicit coordinates that track the individual k-faces of this triangulation, where the parameter k does not need to be known until runtime. More...
 
MatrixInt boundaryMap () const
 Returns the boundary map from subdim-faces to (subdim-1)-faces of the triangulation. More...
 
MatrixInt boundaryMap (int subdim) const
 Returns the boundary map from subdim-faces to (subdim-1)-faces of the triangulation, where the face dimension does not need to be known until runtime. More...
 
MatrixInt dualBoundaryMap () const
 Returns the boundary map from dual subdim-faces to dual (subdim-1)-faces of the triangulation. More...
 
MatrixInt dualBoundaryMap (int subdim) const
 Returns the boundary map from dual subdim-faces to dual (subdim-1)-faces of the triangulation, where the face dimension does not need to be known until runtime. More...
 
MatrixInt dualToPrimal () const
 Returns a map from dual chains to primal chains that preserves homology classes. More...
 
MatrixInt dualToPrimal (int subdim) const
 Returns a map from dual chains to primal chains that preserves homology classes, where the chain dimension does not need to be known until runtime. More...
 
Skeletal Transformations
void orient ()
 Relabels the vertices of top-dimensional simplices in this triangulation so that all simplices are oriented consistently, if possible. More...
 
void reflect ()
 Relabels the vertices of top-dimensional simplices in this triangulation so that all simplices reflect their orientation. More...
 
bool pachner (Face< dim, k > *f, bool check=true, bool perform=true)
 Checks the eligibility of and/or performs a (dim + 1 - k)-(k + 1) Pachner move about the given k-face. More...
 
Subdivisions, Extensions and Covers
void makeDoubleCover ()
 Converts this triangulation into its double cover. More...
 
void subdivide ()
 Does a barycentric subdivision of the triangulation. More...
 
void barycentricSubdivision ()
 Deprecated routine that performs a barycentric subdivision of the triangulation. More...
 
bool finiteToIdeal ()
 Converts each real boundary component into a cusp (i.e., an ideal vertex). More...
 
Decompositions
std::vector< Triangulation< dim > > triangulateComponents () const
 Returns the individual connected components of this triangulation. More...
 
Isomorphism Testing
bool operator== (const Triangulation< dim > &other) const
 Determines if this triangulation is combinatorially identical to the given triangulation. More...
 
bool operator!= (const Triangulation< dim > &other) const
 Determines if this triangulation is not combinatorially identical to the given triangulation. More...
 
std::optional< Isomorphism< dim > > isIsomorphicTo (const Triangulation< dim > &other) const
 Determines if this triangulation is combinatorially isomorphic to the given triangulation. More...
 
std::optional< Isomorphism< dim > > isContainedIn (const Triangulation< dim > &other) const
 Determines if an isomorphic copy of this triangulation is contained within the given triangulation, possibly as a subcomplex of some larger component (or components). More...
 
bool findAllIsomorphisms (const Triangulation< dim > &other, Action &&action, Args &&... args) const
 Finds all ways in which this triangulation is combinatorially isomorphic to the given triangulation. More...
 
bool findAllSubcomplexesIn (const Triangulation< dim > &other, Action &&action, Args &&... args) const
 Finds all ways in which an isomorphic copy of this triangulation is contained within the given triangulation, possibly as a subcomplex of some larger component (or components). More...
 
bool makeCanonical ()
 Relabel the top-dimensional simplices and their vertices so that this triangulation is in canonical form. More...
 
Building Triangulations
void insertTriangulation (const Triangulation< dim > &source)
 Inserts a copy of the given triangulation into this triangulation. More...
 
Exporting Triangulations
Encoding::Signature isoSig () const
 Constructs the isomorphism signature of the given type for this triangulation. More...
 
std::pair< typename Encoding::Signature, Isomorphism< dim > > isoSigDetail () const
 Constructs the isomorphism signature for this triangulation, along with the relabelling that will occur when the triangulation is reconstructed from it. More...
 
void tightEncode (std::ostream &out) const
 Writes the tight encoding of this triangulation to the given output stream. More...
 
std::string dumpConstruction () const
 Returns C++ code that can be used to reconstruct this triangulation. More...
 

Static Public Member Functions

static Triangulation< dim > tightDecoding (const std::string &enc)
 Reconstructs an object of type T from its given tight encoding. More...
 
SnapPea kernel messages
static bool kernelMessagesEnabled ()
 Returns whether or not the SnapPea kernel writes diagnostic messages to standard output. More...
 
static void enableKernelMessages (bool enabled=true)
 Configures whether or not the SnapPea kernel should write diagnostic messages to standard output. More...
 
static void disableKernelMessages ()
 Specifies that the SnapPea kernel should not write diagnostic messages to standard output. More...
 
Importing Triangulations
static Triangulation< 3 > rehydrate (const std::string &dehydration)
 Rehydrates the given alphabetical string into a 3-dimensional triangulation. More...
 
static Triangulation< 3 > fromSnapPea (const std::string &snapPeaData)
 Extracts the tetrahedron gluings from a string that contains the full contents of a SnapPea data file. More...
 

Static Public Attributes

static constexpr int dimension
 A compile-time constant that gives the dimension of the triangulation. More...
 

Protected Member Functions

void swap (Snapshottable &other) noexcept
 Swap operation. More...
 
void takeSnapshot ()
 Must be called before modification and/or destruction of the type T contents. More...
 

Protected Attributes

MarkedVector< Simplex< dim > > simplices_
 The top-dimensional simplices that form the triangulation. More...
 
MarkedVector< Component< dim > > components_
 The connected components that form the triangulation. More...
 
MarkedVector< BoundaryComponent< dim > > boundaryComponents_
 The components that form the boundary of the triangulation. More...
 
std::array< size_t, dim > nBoundaryFaces_
 The number of boundary faces of each dimension. More...
 
bool valid_
 Is this triangulation valid? See isValid() for details on what this means. More...
 
uint8_t topologyLock_
 If non-zero, this will cause Triangulation<dim>::clearAllProperties() to preserve any computed properties that related to the manifold (as opposed to the specific triangulation). More...
 
PacketHeldBy heldBy_
 Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>. More...
 
PacketHeldBy heldBy_
 Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>. More...
 

Packet Administration

class Triangulation< 3 >
 
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...
 

Importing Triangulations

static Triangulation< dim > fromGluings (size_t size, std::initializer_list< std::tuple< size_t, int, size_t, Perm< dim+1 > > > gluings)
 Creates a triangulation from a hard-coded list of gluings. More...
 
static Triangulation< dim > fromGluings (size_t size, Iterator beginGluings, Iterator endGluings)
 Creates a triangulation from a list of gluings. More...
 
static Triangulation< dim > fromIsoSig (const std::string &sig)
 Recovers a full triangulation from an isomorphism signature. More...
 
static Triangulation< dim > fromSig (const std::string &sig)
 Alias for fromIsoSig(), to recover a full triangulation from an isomorphism signature. More...
 
static size_t isoSigComponentSize (const std::string &sig)
 Deduces the number of top-dimensional simplices in a connected triangulation from its isomorphism signature. More...
 
static Triangulation< dim > tightDecode (std::istream &input)
 Reconstructs a triangulation from its given tight encoding. More...
 
void cloneSkeleton (const TriangulationBase &src)
 Builds the skeleton of this triangulation as a clone of the skeleton of the given triangulation. More...
 
void ensureSkeleton () const
 Ensures that all "on demand" skeletal objects have been calculated. More...
 
bool calculatedSkeleton () const
 Determines whether the skeletal objects and properties of this triangulation have been calculated. More...
 
void clearBaseProperties ()
 Clears all properties that are managed by this base class. More...
 
void swapBaseData (TriangulationBase< dim > &other)
 Swaps all data that is managed by this base class, including simplices, skeletal data, cached properties and the snapshotting data, with the given triangulation. More...
 
void writeXMLBaseProperties (std::ostream &out) const
 Writes a chunk of XML containing properties of this triangulation. More...
 

Detailed Description

Offers direct access to the SnapPea kernel from within Regina.

An object of this class represents a 3-manifold triangulation, stored directly in the SnapPea kernel using SnapPea's internal format.

Regarding interaction with the SnapPea kernel:

Regarding the inherited Triangulation<3> interface:

Null triangulations appear more generally when Regina is unable to represent data in SnapPea's native format. You can test for a null triangulation by calling isNull(). Null triangulations can occur for several reasons, such as (but not limited to):

Regarding fillings: SnapPea can store and manipulate Dehn fillings on cusps, and the SnapPeaTriangulation class respects these where it can (but with restrictions on the possible filling coefficients; see below). However, Regina's own Triangulation<3> class knows nothing about fillings at all. Therefore:

For now, SnapPeaTriangulation only supports the following types of filling coefficients: on orientable cusps the filling coefficients must be coprime integers, and non non-orientable cusps the filling coefficients must be the integers (±1, 0). Any attempt to import a triangulation from a SnapPea file with filling coefficients outside these requirements will result in a null triangulation (as discussed above).

There are many places in the SnapPea kernel where SnapPea throws a fatal error. These fatal errors are converted into exceptions (in particular, SnapPeaFatalError and SnapPeaMemoryFull), which can be caught and handled politely. You should assume, unless you have good reason to believe otherwise (e.g., you have read and traced through the SnapPea source code), that any member function of this class that uses the SnapPea kernel could throw either of these exceptions.

Regina uses the variant of the SnapPea kernel that is shipped with SnapPy (standard precision), as well as some additional code written explicitly for SnapPy. The header regina-config.h includes a macro SNAPPY_VERSION that gives the exact version of SnapPy that is bundled into Regina, and you can query this at runtime by calling Regina's function regina::versionSnapPy().

Since Regina 7.0, SnapPeaTriangulation is no longer a "packet type" that can be inserted directly into the packet tree. Instead a SnapPeaTriangulation is now a standalone mathematatical object, which makes it slimmer and faster for ad-hoc use. The consequences of this are:

Regarding the packet interface, there is currently a deficiency when listening for change events on a PacketOf<SnapPeaTriangulation>:

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

The SnapPea kernel was originally written by Jeff Weeks. SnapPy, where this kernel is now maintained, is primarily developed by Marc Culler, Nathan Dunfield and Matthias Goerner, with contributions from many people. SnapPy and the corresponding SnapPea kernel are distributed under the terms of the GNU General Public License, version 2 or any later version, as published by the Free Software Foundation.

See http://snappy.computop.org/ for further information on SnapPea and its successor SnapPy.

Exceptions
SnapPeaFatalErrorThe SnapPea kernel detected a fatal error from which it could not recover. This could be thrown by any member function that uses the SnapPea kernel.
SnapPeaMemoryFullThe SnapPea kernel ran out of memory. This could be thrown by any member function that uses the SnapPea kernel.

Member Typedef Documentation

◆ TuraevViroSet

using regina::Triangulation< 3 >::TuraevViroSet = std::map<std::pair<unsigned long, bool>, Cyclotomic>
inherited

A map from (r, parity) pairs to Turaev-Viro invariants, as described by turaevViro().

Member Enumeration Documentation

◆ CoverEnumerationType

Indicates which types of covers should be enumerated when calling enumerateCovers().

This enumeration is identical to SnapPea's PermutationSubgroup enum, though the values here are named differently. The enumeration is declared again here because Regina code should not in general interact directly with the SnapPea kernel. Values may be freely converted between the two enumeration types by simple assignment and/or typecasting.

Warning
This enumeration must always be kept in sync with SnapPea's PermutationSubgroup enumeration.
Enumerator
cyclic_covers 

Indicates that only cyclic covers should be enumerated.

This corresponds to the SnapPea constant permutation_subgroup_Zn.

all_covers 

Indicates that all covers should be enumerated.

This corresponds to the SnapPea constant permutation_subgroup_Sn.

◆ CoverType

Indicates the different types of covers that can be produced by enumerateCovers().

This enumeration is identical to SnapPea's own CoveringType enum; it is declared again here because Regina code should not in general interact directly with the SnapPea kernel. Values may be freely converted between the two enumeration types by simple assignment and/or typecasting.

Warning
This enumeration must always be kept in sync with SnapPea's own CoveringType enumeration.
Enumerator
unknown_cover 

Indicates that SnapPea has not yet computed the covering type.

irregular_cover 

Indicates a covering where there exist two lifts of a point in the base manifold with no covering transformation that takes one to the other.

regular_cover 

Indicates a covering that is not cyclic, and where for any two lifts of a point in the base manfiold, there is a covering transformation taking one to the other.

cyclic_cover 

Indicates a cyclic covering.

◆ SolutionType

Describes the different types of solution that can be found when solving for a hyperbolic structure.

This enumeration is identical to SnapPea's own SolutionType enum; it is declared again here because Regina code should not in general interact directly with the SnapPea kernel. Values may be freely converted between the two enumeration types by simple assignment and/or typecasting.

Warning
This enumeration must always be kept in sync with SnapPea's own SolutionType enumeration.
Enumerator
not_attempted 

A solution has not been attempted.

geometric_solution 

All tetrahedra are positively oriented.

nongeometric_solution 

The overall volume is positive, but some tetrahedra are flat or negatively oriented.

No tetrahedra have shape 0, 1 or infinity.

flat_solution 

All tetrahedra are flat, but none have shape 0, 1 or infinity.

degenerate_solution 

At least one tetrahedron has shape 0, 1 or infinity.

other_solution 

The volume is zero or negative, but the solution is neither flat nor degenerate.

no_solution 

The gluing equations could not be solved.

externally_computed 

Tetrahedron shapes were inserted into the triangulation.

Constructor & Destructor Documentation

◆ SnapPeaTriangulation() [1/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( )
inline

Creates a null triangulation, with no internal SnapPea data at all.

◆ SnapPeaTriangulation() [2/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( const std::string &  fileNameOrContents)

Creates a new SnapPea triangulation from the contents of SnapPea data file.

The argument may be the name of a SnapPea file, or it may also be the contents of a SnapPea file (so the file itself need not actually exist on the filesystem).

This routine uses the SnapPea kernel to read the data file, and so all SnapPea-specific information will be preserved (including information that Regina itself does not store, such as peripheral curves).

If this operation fails (e.g., if the given string does not represent a valid SnapPea data file), then this routine will thrown an exception; see below for details.

If this routine returns (as opposed to throwing an exception), then it is guaranteed that this is not a null SnapPea triangulation. In this successful scenario, this constructor will ask SnapPea to try to find a hyperbolic structure before it returns.

Note
This constructor can be used in a Python session to pass data from SnapPy through to Regina's copy of the SnapPea kernel (which is strictly separate from SnapPy's), without losing any of SnapPy's internal information.
Warning
If (for some reason) you pass a filename that begins with "% Triangulation", then Regina will interpret this as the contents of a SnapPea file (not a filename).
Internationalisation
If the given argument is a filename, then this routine makes no assumptions about the character encoding used in the filename, and simply passes it through unchanged to low-level C/C++ file I/O routines. This routine assumes that the file contents, however, are in UTF-8 (the standard encoding used throughout Regina).
Exceptions
FileErrorThe SnapPea kernel could not read the given file, or could not parse the file contents (which could have been passed explicitly or could have been read from file).
Parameters
fileNameOrContentseither the name of a SnapPea data file, or the contents of a SnapPea data file (which need not actually exist on the filesystem).

◆ SnapPeaTriangulation() [3/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( const SnapPeaTriangulation src)

Creates a new copy of the given SnapPea triangulation.

If src is a null triangulation then this will be a null triangulation also. See isNull() for further details.

Parameters
srcthe SnapPea triangulation to copy.

◆ SnapPeaTriangulation() [4/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( SnapPeaTriangulation &&  src)
noexcept

Moves the given SnapPea triangulation into this new triangulation.

This is much faster than the copy constructor, but is still linear time. This is because every tetrahedron must be adjusted to point back to this new triangulation instead of src.

All tetrahedra, cusps and skeletal objects (faces, components and boundary components) that belong to src will be moved into this triangulation, and so any pointers or references to Tetrahedron<3>, Cusp, Face<3, subdim>, Component<3> or BoundaryComponent<3> objects will remain valid. Likewise, all cached properties will be moved into this triangulation.

The triangulation that is passed (src) will no longer be usable.

Note
This operator is marked noexcept, and in particular does not fire any change events. This is because this triangulation is freshly constructed (and therefore has no listeners yet), and because we assume that src is about to be destroyed (an action that will fire a packet destruction event).
Parameters
srcthe triangulation to move.

◆ SnapPeaTriangulation() [5/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( const Triangulation< 3 > &  tri,
bool  ignored = false 
)

Converts the given Regina triangulation to a SnapPea triangulation.

This copy will be independent (i.e., this triangulation will not be affected if tri is later changed or destroyed).

Since Regina works with more general kinds of trianguations than SnapPea, not all Regina triangulations can be represented in SnapPea format. If the conversion is unsuccessful, this will be marked as a null triangulation. You should always test isNull() to determine whether the conversion was successful.

Regarding the conversion:

  • If tri is of the subclass SnapPeaTriangulation, then this effectively acts as a copy constructor: all SnapPea-specific information will be cloned directly through the SnapPea kernel. If tri is a null SnapPea triangulation then this copy will be a null triangulation also.
  • If tri is of the parent class Triangulation<3>, then Regina will attempt to convert this triangulation to SnapPea format. If the conversion is successful, this constructor will immediately ask SnapPea to try to find a hyperbolic structure.

Regarding peripheral curves: native Regina triangulations do not store or use peripheral curves themselves, and so this constructor makes a default choice during the conversion process. Specifically:

  • If solution_type() is geometric_solution or nongeometric_solution, then on each torus cusp the meridian and longitude are chosen to be the (shortest, second shortest) basis, and their orientations follow the convention used by the SnapPy kernel. Be warned, however, that this choice might not be unique for some cusp shapes, and the resolution of such ambiguities might be machine-dependent.
  • If solution_type() is something else (e.g., degenerate or flat), or if SnapPea throws a fatal error when attempting to install the (shortest, second shortest) basis as described above, then Regina will accept whatever basis SnapPea installs by default. Be warned that this default basis may change (and indeed has changed in the past) across different versions of the SnapPea kernel.

Regarding internal vertices (i.e., vertices whose links are spheres): SnapPea is designed to work only with triangulations where every vertex is ideal. As a result:

  • You may pass a closed triangulation to this constructor, but SnapPea will automatically convert this into a filling of a cusped manifold, using an ideal triangulation.
  • You may also pass a triangulation that uses both ideal and internal vertices. In this case, SnapPea will retriangulate the manifold so that it uses ideal vertices only.

Even if SnapPea does not retriangulate the manifold (for the reasons described above), it is possible that the tetrahedron and vertex numbers might be changed in the new SnapPea triangulation. In particular, if the given Regina triangulation is orientable but not oriented, then you should expect these numbers to change.

Parameters
trithe Regina triangulation to clone.
ignoreda legacy parameter that is now ignored. (This argument was once required if you wanted to pass a closed triangluation to SnapPea.)

◆ SnapPeaTriangulation() [6/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( const Link link)

Creates a new ideal SnapPea triangulation representing the complement of the given link in the 3-sphere.

This is not the same triangulation that would be produced by calling SnapPeaTriangulation(link.complement()). By calling link.complement(), you through Regina's Triangulation<3> class and therefore lose the peripheral curves. Although the SnapPeaTriangulation constructor will install new peripheral curves, there is no guarantee that these are the same curves as before; in particular, there is no guarantee that these new curves will correspond in any way to the original link diagram.

In contrast, by calling SnapPeaTriangulation(link) directly, the link complement will be triangulated by the SnapPea kernel and not by Regina. As a result, the peripheral curves installed by SnapPea will be precisely the curves from the link diagram.

Exceptions
InvalidArgumentThe given link is empty, or it has so many crossings and/or components that SnapPea cannot handle it. (The latter problem will only occur if the number of crossings and/or components does not fit into a native C++ int.)
Parameters
linkthe link whose complement we should build.

◆ SnapPeaTriangulation() [7/7]

regina::SnapPeaTriangulation::SnapPeaTriangulation ( regina::snappea::Triangulation *  data)

Creates a new triangulation that holds the given raw data from the SnapPea kernel.

Typical users will not be able to call this constructor, since the SnapPea kernel headers are not part of Regina's public API and are not shipped with Regina's development headers.

This new triangulation will take ownership of data, and will use it directly as its native SnapPea representation. Nevertheless, this constructor is not constant time, since it also needs to construct a native Regina representation of the same triangulation.

The given SnapPea kernel data may be null, in which case this will become a null SnapPea triangulation.

Python
Not present. Regina's Python interface does not allow you to talk directly with the built-in copy of the SnapPea C kernel.
Parameters
datathe raw SnapPea kernel data to use in this triangulation.

◆ ~SnapPeaTriangulation()

regina::SnapPeaTriangulation::~SnapPeaTriangulation ( )

Destroys this triangulation.

All internal SnapPea data will also be destroyed.

Member Function Documentation

◆ allCalculatedTuraevViro()

const Triangulation< 3 >::TuraevViroSet & regina::Triangulation< 3 >::allCalculatedTuraevViro ( ) const
inlineinherited

Returns the cache of all Turaev-Viro state sum invariants that have been calculated for this 3-manifold.

This cache is updated every time turaevViro() is called, and is emptied whenever the triangulation is modified.

Turaev-Viro invariants are identified by an (r, parity) pair as described in the turaevViro() documentation. The cache is just a set that maps (r, parity) pairs to the corresponding invariant values.

For even values of r, the parity is ignored when calling turaevViro() (since the even and odd versions of the invariant contain essentially the same information). Therefore, in this cache, all even values of r will have the corresponding parities set to false.

Note
All invariants in this cache are now computed using exact arithmetic, as elements of a cyclotomic field. This is a change from Regina 4.96 and earlier, which computed floating-point approximations instead.
Python
This routine returns a Python dictionary. It also returns by value, not by reference (i.e., if more Turaev-Viro invariants are computed later on, the dictionary that was originally returned will not change as a result).
Returns
the cache of all Turaev-Viro invariants that have already been calculated.
See also
turaevViro

◆ anonID() [1/2]

std::string regina::PacketData< SnapPeaTriangulation >::anonID
inherited

A unique string ID that can be used in place of a packet ID.

This is an alternative to Packet::internalID(), and is designed for use when Held is not actually wrapped by a PacketOf<Held>. (An example of such a scenario is when a normal surface list needs to write its triangulation to file, but the triangulation is a standalone object that is not stored in a packet.)

The ID that is returned will:

  • remain fixed throughout the lifetime of the program for a given object, even if the contents of the object are changed;
  • not clash with the anonID() returned from any other object, or with the internalID() returned from any packet of any type;

These IDs are not preserved when copying or moving one object to another, and are not preserved when writing to a Regina data file and then reloading the file contents.

Warning
If this object is wrapped in a PacketOf<Held>, then anonID() and Packet::internalID() may return different values.

See Packet::internalID() for further details.

Returns
a unique ID that identifies this object.

◆ anonID() [2/2]

std::string regina::PacketData< Triangulation< dim > >::anonID
inherited

A unique string ID that can be used in place of a packet ID.

This is an alternative to Packet::internalID(), and is designed for use when Held is not actually wrapped by a PacketOf<Held>. (An example of such a scenario is when a normal surface list needs to write its triangulation to file, but the triangulation is a standalone object that is not stored in a packet.)

The ID that is returned will:

  • remain fixed throughout the lifetime of the program for a given object, even if the contents of the object are changed;
  • not clash with the anonID() returned from any other object, or with the internalID() returned from any packet of any type;

These IDs are not preserved when copying or moving one object to another, and are not preserved when writing to a Regina data file and then reloading the file contents.

Warning
If this object is wrapped in a PacketOf<Held>, then anonID() and Packet::internalID() may return different values.

See Packet::internalID() for further details.

Returns
a unique ID that identifies this object.

◆ barycentricSubdivision()

void regina::detail::TriangulationBase< dim >::barycentricSubdivision
inlineinherited

Deprecated routine that performs a barycentric subdivision of the triangulation.

Deprecated:
This routine has been renamed to subdivide(), both to shorten the name but also to make it clearer that this triangulation will be modified directly.
Precondition
dim is one of Regina's standard dimensions.

◆ boundaryComponent()

BoundaryComponent< dim > * regina::detail::TriangulationBase< dim >::boundaryComponent ( size_t  index) const
inlineinherited

Returns the requested boundary component of this triangulation.

Note that each time the triangulation changes, all boundary components will be deleted and replaced with new ones. Therefore this object should be considered temporary only.

Parameters
indexthe index of the desired boundary component; this must be between 0 and countBoundaryComponents()-1 inclusive.
Returns
the requested boundary component.

◆ boundaryComponents()

auto regina::detail::TriangulationBase< dim >::boundaryComponents
inlineinherited

Returns an object that allows iteration through and random access to all boundary components of this triangulation.

Note that, in Regina's standard dimensions, each ideal vertex forms its own boundary component, and some invalid vertices do also. See the BoundaryComponent class notes for full details on what constitutes a boundary component in standard and non-standard dimensions.

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. Note that the elements of the list will be pointers, so your code might look like:

for (BoundaryComponent<dim>* b : tri.boundaryComponents()) { ... }

The object that is returned will remain up-to-date and valid for as long as the triangulation exists. In contrast, however, remember that the individual boundary components within this list will be deleted and replaced each time the triangulation changes. Therefore it is best to treat this object as temporary only, and to call boundaryComponents() again each time you need it.

Returns
access to the list of all boundary components.

◆ boundaryMap() [1/2]

MatrixInt regina::detail::TriangulationBase< dim >::boundaryMap ( ) const
inherited

Returns the boundary map from subdim-faces to (subdim-1)-faces of the triangulation.

For C++ programmers who know subdim at compile time, you should use this template function boundaryMap<subdim>(), which is slightly faster than passing subdim as an ordinary runtime argument to boundaryMap(subdim).

See the non-templated boundaryMap(int) for full details on what this function computes and how the matrix it returns should be interpreted.

Precondition
This triangulation is valid and non-empty.
Python
Not present. Instead use the variant boundaryMap(subdim).
Template Parameters
subdimthe face dimension; this must be between 1 and dim inclusive.
Returns
the boundary map from subdim-faces to (subdim-1)-faces.

◆ boundaryMap() [2/2]

MatrixInt regina::detail::TriangulationBase< dim >::boundaryMap ( int  subdim) const
inlineinherited

Returns the boundary map from subdim-faces to (subdim-1)-faces of the triangulation, where the face dimension does not need to be known until runtime.

For C++ programmers who know subdim at compile time, you are better off using the template function boundaryMap<subdim>() instead, which is slightly faster.

This is the boundary map that you would use if you were building the homology groups manually from a chain complex.

Unlike homology(), this code does not use the dual skeleton: instead it uses the primal (i.e., ordinary) skeleton.

  • The main advantage of this is that you can easily match rows and columns of the returned matrix to faces of this triangulation.
  • The main disadvantage is that ideal vertices are not treated as though they were truncated; instead they are just treated as 0-faces that appear as part of the chain complex.

The matrix that is returned should be thought of as acting on column vectors. Specifically, the cth column of the matrix corresponds to the cth subdim-face of this triangulation, and the rth row corresponds to the rth (subdim-1)-face of this triangulation.

For the boundary map, we fix orientations as follows. In simplicial homology, for any k, the orientation of a k-simplex is determined by assigning labels 0,...,k to its vertices. For this routine, since every k-face f is already a k-simplex, these labels will just be the inherent vertex labels 0,...,k of the corresponding Face<k> object. If you need to convert these labels into vertex numbers of a top-dimensional simplex containing f, you can use either Simplex<dim>::faceMapping<k>(), or the equivalent routine FaceEmbedding<k>::vertices().

If you wish to convert these boundary maps to homology groups yourself, either the AbelianGroup class (if you do not need to track which face is which) or the MarkedAbelianGroup class (if you do need to track individual faces) can help you do this.

Note that, unlike many of the templated face-related routines, this routine explicitly supports the case subdim = dim.

Precondition
This triangulation is valid and non-empty.
Exceptions
InvalidArgumentThe face dimension subdim is outside the supported range (i.e., less than 1 or greater than dim).
Parameters
subdimthe face dimension; this must be between 1 and dim inclusive.
Returns
the boundary map from subdim-faces to (subdim-1)-faces.

◆ calculatedSkeleton()

bool regina::detail::TriangulationBase< dim >::calculatedSkeleton
inlineprotectedinherited

Determines whether the skeletal objects and properties of this triangulation have been calculated.

These are only calculated "on demand", when a skeletal property is first queried.

Returns
true if and only if the skeleton has been calculated.

◆ canonise()

Triangulation< 3 > regina::SnapPeaTriangulation::canonise ( ) const

Constructs the canonical retriangulation of the canonical cell decomposition.

Any fillings on the cusps of this SnapPea triangulation will be ignored. In the resulting canonical triangulation (which is one of Regina's native Triangulation<3> objects, not a SnapPea triangulation), these fillings will be completely forgotten.

The canonical cell decomposition is the one described in "Convex hulls and isometries of cusped hyperbolic 3-manifolds", Jeffrey R. Weeks, Topology Appl. 52 (1993), 127-149.

If the canonical cell decomposition is already a triangulation then we leave it untouched. Otherwise, the canonical retriangulation introduces internal (finite) vertices, and is defined as follows:

  • within each 3-cell of the original complex we introduce a new internal vertex, and cone the 3-cell boundary to this new vertex;
  • through each 2-cell of the original complex we insert the dual edge (joining the two new finite vertices on either side), and we replace the two cones on either side of the 2-cell with a ring of tetrahedra surrounding this dual edge.

See canonize_part_2.c in the SnapPea source code for details.

This routine discards the hyperbolic structure along with all SnapPea-specific information (such as peripheral curves and fillings), and simply returns one of Regina's native triangulations. If you need to preserve SnapPea-specific information then you should call protoCanonise() instead.

SnapPea is not always able to compute the canonical cell decomposition: if it fails then then this routine will throw an exception (see below for details).

SnapPy
The function canonise() means different things for SnapPy versus the SnapPea kernel. Here Regina follows the naming convention used in the SnapPea kernel. Specifically: Regina's routine SnapPeaTriangulation::protoCanonise() corresponds to SnapPy's Manifold.canonize() and the SnapPea kernel's proto_canonize(manifold). Regina's routine SnapPeaTriangulation::canonise() corresponds to the SnapPea kernel's canonize(manifold), and is not available through SnapPy at all.
Warning
The SnapPea kernel does not always compute the canonical cell decomposition correctly. Sometimes it gives the wrong answer, although in such a case it still guarantees that the manifold it does return is homeomorphic to the original. Sometimes it gives no answer at all, in which case this routine will throw an exception (see below).
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
UnsolvedCaseThe SnapPea kernel was unable to compute the canonical cell decomposition.
Returns
the canonical triangulation of the canonical cell decomposition.

◆ canonize()

Triangulation< 3 > regina::SnapPeaTriangulation::canonize ( ) const
inline

An alias for canonise(), which constructs the canonical retriangulation of the canonical cell decomposition.

See canonise() for further details.

This alias is provided as "glue" between the British spelling used throughout Regina and the American spelling used throughout the SnapPea kernel.

Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
UnsolvedCaseThe SnapPea kernel was unable to compute the canonical cell decomposition.
Returns
the canonical triangulation of the canonical cell decomposition.

◆ clearBaseProperties()

void regina::detail::TriangulationBase< dim >::clearBaseProperties ( )
protectedinherited

Clears all properties that are managed by this base class.

This includes deleting all skeletal objects and emptying the corresponding internal lists, as well as clearing other cached properties and deallocating the corresponding memory where required.

Note that TriangulationBase almost never calls this routine itself (the one exception is the copy assignment operator). Typically clearBaseProperties() is only ever called by Triangulation<dim>::clearAllProperties(), which in turn is called by "atomic" routines that change the triangluation (before firing packet change events), as well as the Triangulation<dim> destructor.

◆ cloneSkeleton()

void regina::detail::TriangulationBase< dim >::cloneSkeleton ( const TriangulationBase< 3 > &  src)
protectedinherited

Builds the skeleton of this triangulation as a clone of the skeleton of the given triangulation.

This clones all skeletal objects (e.g., faces, components and boundary components) and skeletal properties (e.g., validity and orientability). In general, this function clones the same properties and data that calculateSkeleton() computes.

For this parent class, cloneSkeleton() clones properties and data that are common to all dimensions. Some Triangulation<dim> subclasses may track additional skeletal properties or data, in which case they should reimplement this function (just as they also reimplement calculateSkeleton()). Their reimplementations must call this parent implementation.

This function is intended only for use by the copy constructor (and related "copy-like" constructors), and the copy assignment operator. Other code should typically not need to call this function directly.

The real point of this routine is to ensure that, when a triangulation is cloned, its skeleton is cloned with exactly the same numbering/labelling of its skeletal objects. To this end, it is fine to leave some "large" skeletal properties to be computed on demand where this is allowed (e.g., triangulated vertex links or triangulated boundary components, which are allowed to remain uncomputed until required, even when the full skeleton has been computed).

Precondition
No skeletal objects have been computed for this triangulation, and the corresponding internal lists are all empty.
The skeleton has been fully computed for the given source triangulation.
The given source triangulation is combinatorially identical to this triangulation (i.e., both triangulations have the same number of top-dimensional simplices, with gluings between the same pairs of numbered simplices using the same gluing permutations).
Warning
Any call to cloneSkeleton() must first cast down to Triangulation<dim>, to ensure that you are catching the subclass implementation if this exists. You should never directly call this parent implementation (unless of course you are reimplementing cloneSkeleton() in a Triangulation<dim> subclass).
Parameters
srcthe triangulation whose skeleton should be cloned.

◆ closeBook()

bool regina::Triangulation< 3 >::closeBook ( Edge< 3 > *  e,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a book closing move about the given boundary edge.

This involves taking a boundary edge of the triangulation and folding together the two boundary triangles on either side. This move is the inverse of the openBook() move, and is used to simplify the boundary of the triangulation. This move can be done if:

  • the edge e is a boundary edge;
  • the two vertices opposite e in the boundary triangles that contain e are valid and distinct;
  • the boundary component containing e contains more than two triangles.

There are in fact several other distinctness conditions on the nearby edges and triangles, but they follow automatically from the conditions above.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this operation will (trivially) preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument f) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given edge is an edge of this triangulation.
Parameters
ethe edge about which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ collapseEdge()

bool regina::Triangulation< 3 >::collapseEdge ( Edge< 3 > *  e,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a collapse of an edge between two distinct vertices.

This operation (when it is allowed) does not change the topology of the manifold, decreases the number of vertices by one, and also decreases the number of tetrahedra.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If you are trying to reduce the number of vertices without changing the topology, and if e is an edge connecting an internal vertex with some different vertex, then either collapseEdge() or pinchEdge() may be more appropriate for your situation (though you may find it easier just to call minimiseVertices() instead).

  • The advantage of collapseEdge() is that it decreases the number of tetrahedra, whereas pinchEdge() increases this number (but only by two).
  • The disadvantages of collapseEdge() are that it cannot always be performed, and its validity tests are expensive; pinchEdge() on the other hand can always be used for edges e of the type described above.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument e) can no longer be used.

The eligibility requirements for this move are somewhat involved, and are discussed in detail in the collapseEdge() source code for those who are interested.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given edge is an edge of this triangulation.
Parameters
ethe edge to collapse.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the given edge may be collapsed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ component()

Component< dim > * regina::detail::TriangulationBase< dim >::component ( size_t  index) const
inlineinherited

Returns the requested connected component of this triangulation.

Note that each time the triangulation changes, all component objects will be deleted and replaced with new ones. Therefore this component object should be considered temporary only.

Parameters
indexthe index of the desired component; this must be between 0 and countComponents()-1 inclusive.
Returns
the requested component.

◆ components()

auto regina::detail::TriangulationBase< dim >::components
inlineinherited

Returns an object that allows iteration through and random access to all components of this triangulation.

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. Note that the elements of the list will be pointers, so your code might look like:

for (Component<dim>* c : tri.components()) { ... }

The object that is returned will remain up-to-date and valid for as long as the triangulation exists. In contrast, however, remember that the individual component objects within this list will be deleted and replaced each time the triangulation changes. Therefore it is best to treat this object as temporary only, and to call components() again each time you need it.

Returns
access to the list of all components.

◆ connectedSumWith()

void regina::Triangulation< 3 >::connectedSumWith ( const Triangulation< 3 > &  other)
inherited

Forms the connected sum of this triangulation with the given triangulation.

This triangulation will be altered directly.

If this and the given triangulation are both oriented, then the result will be oriented also, and the connected sum will respect these orientations.

If one or both triangulations contains multiple connected components, this routine will connect the components containing tetrahedron 0 of each triangulation, and will copy any additional components across with no modification.

If either triangulation is empty, then the result will simply be a clone of the other triangulation.

This and/or the given triangulation may be bounded or ideal, or even invalid; in all cases the connected sum will be formed correctly. Note, however, that the result might possibly contain internal vertices (even if the original triangulations do not).

It is allowed to pass this triangulation as other.

Parameters
otherthe triangulation to sum with this.

◆ countBoundaryComponents()

size_t regina::detail::TriangulationBase< dim >::countBoundaryComponents
inlineinherited

Returns the number of boundary components in this triangulation.

Note that, in Regina's standard dimensions, each ideal vertex forms its own boundary component, and some invalid vertices do also. See the BoundaryComponent class notes for full details on what constitutes a boundary component in standard and non-standard dimensions.

Returns
the number of boundary components.

◆ countBoundaryFaces() [1/2]

size_t regina::detail::TriangulationBase< dim >::countBoundaryFaces
inlineinherited

Returns the number of boundary subdim-faces in this triangulation.

This is the fastest way to count faces if you know subdim at compile time.

Specifically, this counts the number of subdim-faces for which isBoundary() returns true. This may lead to some unexpected results in non-standard scenarios; see the documentation for the non-templated countBoundaryFaces(int) for details.

Python
Not present. Instead use the variant countBoundaryFaces(subdim).
Template Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
Returns
the number of boundary subdim-faces.

◆ countBoundaryFaces() [2/2]

size_t regina::detail::TriangulationBase< dim >::countBoundaryFaces ( int  subdim) const
inlineinherited

Returns the number of boundary subdim-faces in this triangulation, where the face dimension does not need to be known until runtime.

This routine takes linear time in the dimension dim. For C++ programmers who know subdim at compile time, you are better off using the template function countBoundaryFaces<subdim>() instead, which is fast constant time.

Specifically, this counts the number of subdim-faces for which isBoundary() returns true. This may lead to some unexpected results in non-standard scenarios; for example:

  • In non-standard dimensions, ideal vertices are not recognised and so will not be counted as boundary;
  • In an invalid triangulation, the number of boundary faces reported here may be smaller than the number of faces obtained when you triangulate the boundary using BoundaryComponent::build(). This is because "pinched" faces (where separate parts of the boundary are identified together) will only be counted once here, but will "spring apart" into multiple faces when the boundary is triangulated.
Exceptions
InvalidArgumentThe face dimension subdim is outside the supported range (i.e., negative or greater than dim-1).
Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
Returns
the number of boundary subdim-faces.

◆ countBoundaryFacets()

size_t regina::detail::TriangulationBase< dim >::countBoundaryFacets
inlineinherited

Returns the total number of boundary facets in this triangulation.

This routine counts facets of top-dimensional simplices that are not glued to some adjacent top-dimensional simplex.

This is equivalent to calling countBoundaryFaces<dim-1>().

Returns
the total number of boundary facets.

◆ countBoundaryTriangles()

size_t regina::Triangulation< 3 >::countBoundaryTriangles ( ) const
inlineinherited

A dimension-specific alias for countBoundaryFacets().

See countBoundaryFacets() for further information.

◆ countCompleteCusps()

unsigned regina::SnapPeaTriangulation::countCompleteCusps ( ) const
inline

Returns the total number of complete cusps (that is, unfilled cusps).

It is always true that countCompleteCusps() + countFilledCusps() == countCusps().

SnapPy
This has no corresponding routine in SnapPy, though the information is easily acessible via Manifold.cusp_info("is_complete").
Returns
the total number of complete cusps.

◆ countComponents()

size_t regina::detail::TriangulationBase< dim >::countComponents
inlineinherited

Returns the number of connected components in this triangulation.

Returns
the number of connected components.

◆ countCusps()

unsigned regina::SnapPeaTriangulation::countCusps ( ) const
inline

Returns the total number of cusps (both filled and complete).

This returns the same value as the inherited function Triangulation<3>::countBoundaryComponents().

SnapPy
In SnapPy, this routine corresponds to calling Manifold.num_cusps().
Returns
the total number of cusps.

◆ countEdges()

size_t regina::detail::TriangulationBase< dim >::countEdges
inlineinherited

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

This alias is available for all dimensions dim.

See countFaces() for further information.

◆ countFaces() [1/2]

size_t regina::detail::TriangulationBase< dim >::countFaces
inlineinherited

Returns the number of subdim-faces in this triangulation.

This is the fastest way to count faces if you know subdim at compile time.

For convenience, this routine explicitly supports the case subdim = dim. This is not the case for the routines face() and faces(), which give access to individual faces (the reason relates to the fact that top-dimensional simplices are built manually, whereas lower-dimensional faces are deduced properties).

Python
Not present. Instead use the variant countFaces(subdim).
Template Parameters
subdimthe face dimension; this must be between 0 and dim inclusive.
Returns
the number of subdim-faces.

◆ countFaces() [2/2]

size_t regina::detail::TriangulationBase< dim >::countFaces ( int  subdim) const
inlineinherited

Returns the number of subdim-faces in this triangulation, where the face dimension does not need to be known until runtime.

This routine takes linear time in the dimension dim. For C++ programmers who know subdim at compile time, you are better off using the template function countFaces<subdim>() instead, which is fast constant time.

For convenience, this routine explicitly supports the case subdim = dim. This is not the case for the routines face() and faces(), which give access to individual faces (the reason relates to the fact that top-dimensional simplices are built manually, whereas lower-dimensional faces are deduced properties).

Exceptions
InvalidArgumentThe face dimension subdim is outside the supported range (i.e., negative or greater than dim).
Parameters
subdimthe face dimension; this must be between 0 and dim inclusive.
Returns
the number of subdim-faces.

◆ countFilledCusps()

unsigned regina::SnapPeaTriangulation::countFilledCusps ( ) const
inline

Returns the total number of filled cusps.

It is always true that countCompleteCusps() + countFilledCusps() == countCusps().

SnapPy
This has no corresponding routine in SnapPy, though the information is easily acessible via Manifold.cusp_info("is_complete").
Returns
the total number of filled cusps.

◆ countPentachora()

size_t regina::detail::TriangulationBase< dim >::countPentachora
inlineinherited

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

This alias is available for dimensions dim ≥ 4.

See countFaces() for further information.

◆ countTetrahedra()

size_t regina::detail::TriangulationBase< dim >::countTetrahedra
inlineinherited

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

This alias is available for dimensions dim ≥ 3.

See countFaces() for further information.

◆ countTriangles()

size_t regina::detail::TriangulationBase< dim >::countTriangles
inlineinherited

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

This alias is available for all dimensions dim.

See countFaces() for further information.

◆ countVertices()

size_t regina::detail::TriangulationBase< dim >::countVertices
inlineinherited

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

This alias is available for all dimensions dim.

See countFaces() for further information.

◆ cusp()

const Cusp & regina::SnapPeaTriangulation::cusp ( unsigned  whichCusp = 0) const
inline

Returns information about the given cusp of this manifold.

This information includes the filling coefficients (if any), along with other combinatorial information.

SnapPy
In SnapPy, this routine corresponds to calling Manifold.cusp_info()[c], though the set of information returned about each cusp is different.

These Cusp objects should be considered temporary only; you should not hold onto references or pointers to them. If you need to hold on to information about a cusp, you can simply copy the Cusp object by value (an operation that is both cheap and safe).

In older versions of Regina, this routine would explicitly check for a null triangulation. Nowadays this is the responsibility of the user or programmer.

Warning
Be warned that cusp i might not correspond to vertex i of the triangulation. The Cusp::vertex() method (which is accessed through the cusp() routine) can help translate between SnapPea's cusp numbers and Regina's vertex numbers.
Parameters
whichCuspthe index of a cusp according to SnapPea; this must be between 0 and countCusps()-1 inclusive.
Returns
information about the given cusp.

◆ cusps()

auto regina::SnapPeaTriangulation::cusps ( ) const
inline

Returns an object that allows iteration through and random access to information about all of the cusps of this manifold.

This information includes the filling coefficients (if any), along with other combinatorial information.

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 Cusp. For example, your code might look like:

for (const Cusp& c : tri->cusps()) { ... }

These Cusp objects should be considered temporary only; you should not hold onto references or pointers to them. If you need to hold on to information about a cusp, you can simply copy the Cusp object by value (an operation that is both cheap and safe).

Warning
Be warned that cusp i might not correspond to vertex i of the triangulation. The Cusp::vertex() method (which is accessed through the cusp() routine) can help translate between SnapPea's cusp numbers and Regina's vertex numbers.
Returns
access to the list of all cusps of this manifold.

◆ dehydrate()

std::string regina::Triangulation< 3 >::dehydrate ( ) const
inherited

Dehydrates this triangulation into an alphabetical string.

A dehydration string is a compact text representation of a triangulation, introduced by Callahan, Hildebrand and Weeks for their cusped hyperbolic census (see below). The dehydration string of an n-tetrahedron triangulation consists of approximately (but not precisely) 5n/2 lower-case letters.

Dehydration strings come with some restrictions:

  • They rely on the triangulation being "canonical" in some combinatorial sense. This is not enforced here; instead a combinatorial isomorphism is applied to make the triangulation canonical, and this isomorphic triangulation is dehydrated instead. Note that the original triangulation is not changed.
  • They require the triangulation to be connected.
  • They require the triangulation to have no boundary triangles (though ideal triangulations are fine).
  • They can only support triangulations with at most 25 tetrahedra.

The routine rehydrate() can be used to recover a triangulation from a dehydration string. Note that the triangulation recovered might not be identical to the original, but it is guaranteed to be an isomorphic copy.

For a full description of the dehydrated triangulation format, see A Census of Cusped Hyperbolic 3-Manifolds, Callahan, Hildebrand and Weeks, Mathematics of Computation 68/225, 1999.

Exceptions
NotImplementedEither this triangulation is disconnected, it has boundary triangles, or it contains more than 25 tetrahedra.
Returns
a dehydrated representation of this triangulation (or an isomorphic variant of this triangulation).

◆ detail() [1/2]

std::string regina::Output< SnapPeaTriangulation , 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.

◆ detail() [2/2]

std::string regina::Output< Triangulation< 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.

◆ disableKernelMessages()

static void regina::SnapPeaTriangulation::disableKernelMessages ( )
static

Specifies that the SnapPea kernel should not write diagnostic messages to standard output.

Calling this routine is equivalent to calling enableKernelMessages(false).

Note that diagnostic messages are already disabled by default.

This routine (which interacts with static data) is thread-safe.

◆ dualBoundaryMap() [1/2]

MatrixInt regina::detail::TriangulationBase< dim >::dualBoundaryMap ( ) const
inherited

Returns the boundary map from dual subdim-faces to dual (subdim-1)-faces of the triangulation.

For C++ programmers who know subdim at compile time, you should use this template function dualBoundaryMap<subdim>(), which is slightly faster than passing subdim as an ordinary runtime argument to dualBoundaryMap(subdim).

See the non-templated dualBoundaryMap(int) for full details on what this function computes and how the matrix it returns should be interpreted.

Precondition
This triangulation is valid and non-empty.
Python
Not present. Instead use the variant dualBoundaryMap(subdim).
Template Parameters
subdimthe dual face dimension; this must be between 1 and dim inclusive if dim is one of Regina's standard dimensions, or between 1 and (dim - 1) inclusive otherwise.
Returns
the boundary map from dual subdim-faces to dual (subdim-1)-faces.

◆ dualBoundaryMap() [2/2]

MatrixInt regina::detail::TriangulationBase< dim >::dualBoundaryMap ( int  subdim) const
inlineinherited

Returns the boundary map from dual subdim-faces to dual (subdim-1)-faces of the triangulation, where the face dimension does not need to be known until runtime.

For C++ programmers who know subdim at compile time, you are better off using the template function dualBoundaryMap<subdim>() instead, which is slightly faster.

This function is analogous to boundaryMap(), but is designed to work with dual faces instead of ordinary (primal) faces. In particular, this is used in the implementation of homology(), which works with the dual skeleton in order to effectively truncate ideal vertices.

The matrix that is returned should be thought of as acting on column vectors. Specifically, the cth column of the matrix corresponds to the cth dual subdim-face of this triangulation, and the rth row corresponds to the rth dual (subdim-1)-face of this triangulation. Here we index dual faces in the same order as the (primal) faces of the triangulation that they are dual to, except that we omit primal boundary faces (i.e., primal faces for which Face::isBoundary() returns true). Therefore, for triangulations with boundary, the dual face indices and the corresponding primal face indices might not be equal.

For this dual boundary map, for positive dual face dimensions k, we fix the orientations of the dual k-faces as follows:

  • In simplicial homology, the orientation of a k-simplex is determined by assigning labels 0,...,k to its vertices.
  • Consider a dual k-face d, and let this be dual to the primal (dim-k)-face f. In general, d will not be a simplex. Let B denote the barycentre of f (which also appears as the "centre" point of d).
  • Let emb be an arbitrary FaceEmbedding<dim-k> for f (i.e., chosen from f.embeddings()), and let s be the corresponding top-dimensional simplex containing f (i.e., emb.simplex()). For the special case of dual edges (k = 1), this choice matters; here we choose emb to be the first embedding (that is, f.front()). For larger k this choice does not matter; see below for the reasons why.
  • Now consider how d intersects the top-dimensional simplex s. This intersection is a k-polytope with B as one of its vertices. We can extend this polytope away from B, pushing it all the way through the simplex s, until it becomes a k-simplex g whose vertices are B along with the k "unused" vertices of s that do not appear in f.
  • We can now define the orientation of the dual k-face d to be the orientation of this k-simplex g that contains it. All that remains now is to orient g by choosing a labelling 0,...,k for its vertices.
  • To orient g, we assign the label 0 to B, and we assign the labels 1,...,k to the "unused" vertices v[dim-k+1],...,v[dim] of s respectively, where v is the permutation emb.vertices().
  • Finally, we note that for k > 1, the orientation for d does not depend on the particular choice of s and emb: by the preconditions and the fact that this routine only considers duals of non-boundary faces, the link of f must be a sphere, and therefore the images of those "other" vertices are fixed in a way that preserves orientation as you walk around the link. See the documentation for Simplex<dim>::faceMapping() for details.
  • For the special case of dual edges (k = 1), the conditions above can be described more simply: the two endpoints of the dual edge d correspond to the two top-dimensional simplices on either side of the (dim-1)-face f, and we orient d by labelling these endpoints (0, 1) in the order (f.back(), f.front()).

If you wish to convert these boundary maps to homology groups yourself, either the AbelianGroup class (if you do not need to track which dual face is which) or the MarkedAbelianGroup class (if you do need to track individual dual faces) can help you do this.

Precondition
This triangulation is valid and non-empty.
Exceptions
InvalidArgumentThe face dimension subdim is outside the supported range (as documented for the subdim argument below).
Parameters
subdimthe dual face dimension; this must be between 1 and dim inclusive if dim is one of Regina's standard dimensions, or between 1 and (dim - 1) inclusive otherwise.
Returns
the boundary map from dual subdim-faces to dual (subdim-1)-faces.

◆ dualToPrimal() [1/2]

MatrixInt regina::detail::TriangulationBase< dim >::dualToPrimal ( ) const
inherited

Returns a map from dual chains to primal chains that preserves homology classes.

For C++ programmers who know subdim at compile time, you should use this template function dualToPrimal<subdim>(), which is slightly faster than passing subdim as an ordinary runtime argument to dualToPrimal(subdim).

See the non-templated dualToPrimal(int) for full details on what this function computes and how the matrix it returns should be interpreted.

Precondition
This trianguation is valid, non-empty, and non-ideal. Note that Regina can only detect ideal triangulations in standard dimensions; for higher dimensions it is the user's reponsibility to confirm this some other way.
Python
Not present. Instead use the variant dualToPrimal(subdim).
Template Parameters
subdimthe chain dimension; this must be between 0 and (dim - 1) inclusive.
Returns
the map from dual subdim-chains to primal subdim-chains.

◆ dualToPrimal() [2/2]

MatrixInt regina::detail::TriangulationBase< dim >::dualToPrimal ( int  subdim) const
inlineinherited

Returns a map from dual chains to primal chains that preserves homology classes, where the chain dimension does not need to be known until runtime.

For C++ programmers who know subdim at compile time, you are better off using the template function dualToPrimal<subdim>() instead, which is slightly faster.

The matrix that is returned should be thought of as acting on column vectors. Specifically, the cth column of the matrix corresponds to the cth dual subdim-face of this triangulation, and the rth row corresponds to the rth primal subdim-face of this triangulation.

We index and orient these dual and primal faces in the same manner as dualBoundaryMap() and boundaryMap() respectively. In particular, dual faces are indexed in the same order as the primal (dim-subdim)-faces of the triangulation that they are dual to, except that we omit primal boundary faces. See dualBoundaryMap() and boundaryMap() for further details.

The key feature of this map is that, if a column vector v represents a cycle c in the dual chain complex (i.e., it is a chain with zero boundary), and if this map is represented by the matrix M, then the vector M×v represents a cycle in the primal chain complex that belongs to the same subdimth homology class as c.

Regarding implementation: the map is constructed by (i) subdividing each dual face into smaller subdim-simplices whose vertices are barycentres of primal faces of different dimensions, (ii) moving each barycentre to vertex 0 of the corresponding face, and then (iii) discarding any resulting simplices with repeated vertices (which become "flattened" to a dimension less than subdim).

Precondition
This trianguation is valid, non-empty, and non-ideal. Note that Regina can only detect ideal triangulations in standard dimensions; for higher dimensions it is the user's reponsibility to confirm this some other way.
Exceptions
InvalidArgumentThe chain dimension subdim is outside the supported range (as documented for the subdim argument below).
Parameters
subdimthe chain dimension; this must be between 0 and (dim - 1) inclusive.
Returns
the map from dual subdim-chains to primal subdim-chains.

◆ dumpConstruction()

std::string regina::detail::TriangulationBase< dim >::dumpConstruction
inherited

Returns C++ code that can be used to reconstruct this triangulation.

This code will call Triangulation<dim>::fromGluings(), passing a hard-coded C++ initialiser list.

The main purpose of this routine is to generate this hard-coded initialiser list, which can be tedious and error-prone to write by hand.

Note that the number of lines of code produced grows linearly with the number of simplices. If this triangulation is very large, the returned string will be very large as well.

Returns
the C++ code that was generated.

◆ edge()

Face< dim, 1 > * regina::detail::TriangulationBase< dim >::edge ( size_t  index) const
inlineinherited

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

This alias is available for all dimensions dim.

See face() for further information.

◆ edges()

auto regina::detail::TriangulationBase< dim >::edges
inlineinherited

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

This alias is available for all dimensions dim.

See faces() for further information.

◆ enableKernelMessages()

static void regina::SnapPeaTriangulation::enableKernelMessages ( bool  enabled = true)
static

Configures whether or not the SnapPea kernel should write diagnostic messages to standard output.

By default such diagnostic messages are disabled.

This routine (which interacts with static data) is thread-safe.

Parameters
enabledtrue if diagnostic messages should be enabled, or false otherwise.

◆ ensureSkeleton()

void regina::detail::TriangulationBase< dim >::ensureSkeleton
inlineprotectedinherited

Ensures that all "on demand" skeletal objects have been calculated.

◆ enumerateCovers()

template<typename Action , typename... Args>
size_t regina::SnapPeaTriangulation::enumerateCovers ( int  sheets,
CoverEnumerationType  type,
Action &&  action,
Args &&...  args 
) const
inline

Enumerates connected k-sheeted covers of the underlying manifold.

The number of sheets k is passed as the first argument to this function.

Regina does this (with the help of SnapPea) by:

  • enumerating all transitive representations of the fundamental group into either the symmetric group S(k) or the cyclic group Z_k (according to the parameter type), using the SnapPea function find_representations(); and then
  • building the cover that corresponds to each representation, using the SnapPea function construct_cover().

If you are only interested in the corresponding index k subgroups of the fundamental group and not the triangulated covers themselves, then you may wish to consider the native Regina function GroupPresentation::enumerateCovers() instead. That function is highly optimised, and should be considerably faster as k grows.

Each covering space is produced once up to equivalence; here equivalent covers correspond to conjugate representations of the fundamental group.

To enumerate all k-sheeted covers up to equivalence, set type to all_covers. Be warned, however, that this becomes enormously slow as the number of sheets k grows. An alternative is to enumerate only cyclic covers by setting type to cyclic_covers; this significantly limits the set of covers produced but is also much faster for larger k.

For each cover that is produced, this routine will call action (which must be a function or some other callable object).

  • The first argument to action must be a SnapPea triangulation; this will be the newly produced cover. This argument will be passed as an rvalue; a typical action could (for example) take it by const reference and query it, or take it by value and modify it, or take it by rvalue reference and move it into more permanent storage.
  • The second argument to action must be of type SnapPeaTriangulation::CoverType. This will indicate the type of cover that has been constructed; see the SnapPeaTriangulation::CoverType documentation for details. In the same call to enumerateCovers() you may observe different types of covers being produced (i.e., this value is computed individually for each cover). You should, however, never see the value unknown_cover.
  • If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
  • action must return void.
  • action must not make changes to this original triangulation (i.e., the SnapPeaTriangulation upon which enumerateCovers() is being called).

Be aware that this routine does the bulk of its work before any covers are produced. Specifically, because of the design of the SnapPea kernel, this routine first enumerates all requested representations of the fundamental group (which is the slow part), and only then does it construct the cover and call action for each representation, one at a time.

Precondition
This is not a null triangulation.
Warning
If you are enumerating all covers, then the argument sheets should be very small.
The covers that are produced will typically use far more tetrahedra than necessary. If size is important then you should take a copy using Regina's native type Triangulation<3> and call intelligentSimplify() on that. Note that you cannot call intelligentSimplify() directly on a SnapPeaTriangulation, since (like all modifying functions inherited from Triangulation<3>) this will nullify the SnapPeaTriangulation. See the class notes for further explanation.
The API for this class or function has not yet been finalised. This means that the interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please check the detailed changelog with each new release to see if you need to make changes to your code.
Python
There are two versions of this function available in Python. The first form is enumerateCovers(sheets, type, action), which mirrors the C++ function: it takes action which may be a pure Python function, it returns the number of covers found, but it does not take an addition argument list (args). The second form is enumerateCovers(sheets, type), which returns a Python list containing all of the triangulated covers, each given as a pair (SnapPeaTriangulation, SnapPeaTriangulation::CoverType).
Parameters
sheetsthe number of sheets in the covers to produce (i.e., the number k in the description above); this must be a positive integer.
typeindicates whether to enumerate all covers (up to equivalence) or only cyclic covers.
actiona function (or other callable object) to call for each cover that is found.
argsany additional arguments that should be passed to action, following the initial triangulation and type arguments.
Returns
the total number of covers found.

◆ eulerCharManifold()

long regina::Triangulation< 3 >::eulerCharManifold ( ) const
inherited

Returns the Euler characteristic of the corresponding compact 3-manifold.

Instead of simply calculating V-E+F-T, this routine also:

  • treats ideal vertices as surface boundary components (i.e., effectively truncates them);
  • truncates invalid boundary vertices (i.e., boundary vertices whose links are not discs);
  • truncates the projective plane cusps at the midpoints of invalid edges (edges identified with themselves in reverse).

For ideal triangulations, this routine therefore computes the proper Euler characteristic of the manifold (unlike eulerCharTri(), which does not).

For triangulations whose vertex links are all spheres or discs, this routine and eulerCharTri() give identical results.

Returns
the Euler characteristic of the corresponding compact manifold.

◆ eulerCharTri()

long regina::detail::TriangulationBase< dim >::eulerCharTri
inlineinherited

Returns the Euler characteristic of this triangulation.

This will be evaluated strictly as the alternating sum of the number of i-faces (that is, countVertices() - countEdges() + countTriangles() - ...).

Note that this routine handles ideal triangulations in a non-standard way. Since it computes the Euler characteristic of the triangulation (and not the underlying manifold), this routine will treat each ideal boundary component as a single vertex, and not as an entire (dim-1)-dimensional boundary component.

In Regina's standard dimensions, for a routine that handles ideal boundary components properly (by treating them as (dim-1)-dimensional boundary components when computing Euler characteristic), you can use the routine eulerCharManifold() instead.

Returns
the Euler characteristic of this triangulation.

◆ face() [1/2]

auto regina::detail::TriangulationBase< dim >::face ( int  subdim,
size_t  index 
) const
inlineinherited

Returns the requested subdim-face of this triangulation, in a way that is optimised for Python programmers.

For C++ users, this routine is not very useful: since precise types must be know at compile time, this routine returns a std::variant v that could store a pointer to any class Face<dim, ...>. This means you cannot access the face directly: you will still need some kind of compile-time knowledge of subdim before you can extract and use an appropriate Face<dim, subdim> object from v. However, once you know subdim at compile time, you are better off using the (simpler and faster) routine face<subdim>() instead.

For Python users, this routine is much more useful: the return type can be chosen at runtime, and so this routine simply returns a Face<dim, subdim> object of the appropriate face dimension that you can use immediately.

The specific return type for C++ programmers will be std::variant<Face<dim, 0>*, ..., Face<dim, dim-1>*>.

Exceptions
InvalidArgumentThe face dimension subdim is outside the supported range (i.e., negative, or greater than or equal to dim).
Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
indexthe index of the desired face, ranging from 0 to countFaces<subdim>()-1 inclusive.
Returns
the requested face.

◆ face() [2/2]

Face< dim, subdim > * regina::detail::TriangulationBase< dim >::face ( size_t  index) const
inlineinherited

Returns the requested subdim-face of this triangulation, in a way that is optimised for C++ programmers.

Python
Not present. Instead use the variant face(subdim, index).
Template Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
Parameters
indexthe index of the desired face, ranging from 0 to countFaces<subdim>()-1 inclusive.
Returns
the requested face.

◆ faces() [1/2]

auto regina::detail::TriangulationBase< dim >::faces
inlineinherited

Returns an object that allows iteration through and random access to all subdim-faces of this triangulation, in a way that is optimised for C++ programmers.

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. Note that the elements of the list will be pointers, so your code might look like:

for (Face<dim, subdim>* f : tri.faces<subdim>()) { ... }

The object that is returned will remain up-to-date and valid for as long as the triangulation exists. In contrast, however, remember that the individual faces within this list will be deleted and replaced each time the triangulation changes. Therefore it is best to treat this object as temporary only, and to call faces() again each time you need it.

Python
Not present. Instead use the variant faces(subdim).
Template Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
Returns
access to the list of all subdim-faces.

◆ faces() [2/2]

auto regina::detail::TriangulationBase< dim >::faces ( int  subdim) const
inlineinherited

Returns an object that allows iteration through and random access to all subdim-faces of this triangulation, in a way that is optimised for Python programmers.

C++ users should not use this routine. The return type must be fixed at compile time, and so it is a std::variant that can hold any of the lightweight return types from the templated faces<subdim>() function. This means that the return value will still need compile-time knowledge of subdim to extract and use the appropriate face objects. However, once you know subdim at compile time, you are much better off using the (simpler and faster) routine faces<subdim>() instead.

For Python users, this routine is much more useful: the return type can be chosen at runtime, and so this routine returns a Python list of Face<dim, subdim> objects (holding all the subdim-faces of the triangulation), which you can use immediately.

Exceptions
InvalidArgumentThe face dimension subdim is outside the supported range (i.e., negative, or greater than or equal to dim).
Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
Returns
access to the list of all subdim-faces.

◆ fill()

bool regina::SnapPeaTriangulation::fill ( int  m,
int  l,
unsigned  whichCusp = 0 
)

Assigns a Dehn filling to the given cusp.

This routine will automatically ask SnapPea to update the hyperbolic structure according to the new filling coefficients.

The triangulation itself will not change; this routine will simply ask SnapPea to store the given filling coefficients alongside the cusp, to be used in operations such as computing hyperbolic structures. If you wish to retriangulate to permanently fill the cusp, call filledAll() or filledPartial() instead.

For orientable cusps only coprime filling coefficients are allowed, and for non-orientable cusps only (±1, 0) fillings are allowed. Although SnapPea can handle more general fillings, Regina will enforce these conditions; if they are not satisfied then it will do nothing and simply return false.

As a special case however, you may pass (0, 0) as the filling coefficients, in which case this routine will behave identically to unfill().

It is possible that, if the given integers are extremely large, SnapPea cannot convert the filling coefficients to its own internal floating-point representation. If this happens then this routine will again do nothing and simply return false.

Warning
Be warned that cusp i might not correspond to vertex i of the triangulation. The Cusp::vertex() method (which is accessed through the cusp() routine) can help translate between SnapPea's cusp numbers and Regina's vertex numbers.
Parameters
mthe first (meridional) filling coefficient.
lthe second (longitudinal) filling coefficient.
whichCuspthe index of the cusp to fill according to SnapPea; this must be between 0 and countCusps()-1 inclusive.
Returns
true if and only if the filling coefficients were accepted (according to the conditions outlined above).

◆ filledAll()

Triangulation< 3 > regina::SnapPeaTriangulation::filledAll ( ) const

Retriangulates to permanently fill all cusps.

This uses the current Dehn filling coefficients on the cusps, as set by fill(). The result will be a closed triangulation, of type Triangulation<3> (not SnapPeaTriangulation).

This routine requires every cusp to be non-complete. If one or more cusps is complete (i.e., has no filling coefficients assigned), then this routine will throw an exception.

This replaces the old filledTriangulation() routines from Regina 6.0.1 and earlier, which decided at runtime whether to return a Triangulation<3> or a SnapPeaTriangulation. Since this routine explicitly fills all cusps, it is able to guarantee an explicit return type of Triangulation<3> at compile time.

Precondition
All cusps of this manifold are non-complete (i.e., have filling coefficients assigned). This will be checked, and an exception will be thrown if this requirement is not met.
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
FailedPreconditionSome cusp of this manifold is complete.
Returns
the filled triangulation.

◆ filledPartial() [1/2]

SnapPeaTriangulation regina::SnapPeaTriangulation::filledPartial ( ) const

Retriangulates to permanently fill some but not all cusps.

This uses the current Dehn filling coefficients on the cusps, as set by fill(). The result will be another instance of SnapPeaTriangulation, with at least one cusp remaining.

This routine requires at least one cusp to be complete (i.e., to have no filling coefficients assigned), since most of the SnapPea kernel requires its triangulations to have at least one cusp.

  • If all cusps are complete, then the result will simply be a clone of this triangulation.
  • If some but not all cusps are complete, then the result will be a SnapPeaTriangulation with fewer cusps. The remaining cusps might be reindexed, and all Cusp structures will be destroyed and rebuilt. Auxiliary information on the remaining cusps (such as peripheral curves) will be preserved, and SnapPea will automatically attempt to compute a hyperbolic structure on the new triangulation.
  • If no cusps are complete (i.e., all cusps have filling coefficients), then this routine will throw an exception. For such scenarios you should call filledAll() instead.

This replaces the old filledTriangulation() routines from Regina 6.0.1 and earlier, which decided at runtime whether to return a Triangulation<3> or a SnapPeaTriangulation. Since this routine explicitly does not fill all cusps, it is able to guarantee an explicit return type of SnapPeaTriangulation at compile time.

Precondition
At least one cusp of this manifold is complete (i.e., has no filling coefficients assigned). This will be checked, and an exception will be thrown if this requirement is not met.
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
FailedPreconditionAll cusps of this manifold are non-complete.
Returns
the filled triangulation.

◆ filledPartial() [2/2]

SnapPeaTriangulation regina::SnapPeaTriangulation::filledPartial ( unsigned  whichCusp) const

Retriangulates to permanently fill the given cusp.

This uses the current Dehn filling coefficients on the cusp, as set by fill(). The result will be another instance of SnapPeaTriangulation, with at least one cusp remaining.

This routine requires the manifold to have at least two cusps (i.e., the cusp being filled, plus at least one other). This is because most of the SnapPea kernel routines require its triangulations to have at least one cusp.

The error conditions are as follows:

  • If the given cusp has no filling coefficients assigned (i.e., it is complete), then it cannot be filled: instead this routine will throw an exception.
  • If the manifold has only one cusp, then this routine will likewise throw an exception. For such scenarios you should call filledAll() instead, which will return a closed Regina triangulation.
  • Otherwise, if there is at least one other cusp, the result will be a SnapPeaTriangulation with one fewer cusp. The remaining cusps might be reindexed, and all Cusp structures will be destroyed and rebuilt. Auxiliary information on the remaining cusps (such as peripheral curves) will be preserved, and SnapPea will automatically attempt to compute a hyperbolic structure on the new triangulation.

This replaces the old filledTriangulation() routines from Regina 6.0.1 and earlier, which decided at runtime whether to return a Triangulation<3> or a SnapPeaTriangulation. Since this routine explicitly does not fill all cusps, it is able to guarantee an explicit return type of SnapPeaTriangulation at compile time.

Precondition
The given cusp is non-complete (i.e., has filling coefficients assigned), and the manifold has at least one other cusp. These preconditions will be checked, and an exception will be thrown if they are not met.
Warning
Be warned that cusp i might not correspond to vertex i of the triangulation. The Cusp::vertex() method (which is accessed through the cusp() routine) can help translate between SnapPea's cusp numbers and Regina's vertex numbers.
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
FailedPreconditionThe given cusp is complete, and/or it is the only cusp.
Parameters
whichCuspthe index of the cusp to permanently fill according to SnapPea; this must be between 0 and countCusps()-1 inclusive.
Returns
the filled triangulation.

◆ fillTorus() [1/2]

bool regina::Triangulation< 3 >::fillTorus ( Edge< 3 > *  e0,
Edge< 3 > *  e1,
Edge< 3 > *  e2,
unsigned long  cuts0,
unsigned long  cuts1,
unsigned long  cuts2 
)
inherited

Fills a two-triangle torus boundary component by attaching a solid torus along a given curve.

The three edges of the boundary component should be passed as the arguments e0, e1 and e2. The boundary component will then be filled with a solid torus whose meridional curve cuts these three edges cuts0, cuts1 and cuts2 times respectively.

For the filling to be performed successfully, the three given edges must belong to the same boundary component, and this boundary component must be a two-triangle torus. Moreover, the integers cuts0, cuts1 and cuts2 must be coprime, and two of them must add to give the third. If any of these conditions are not met, then this routine will do nothing and return false.

The triangulation will be simplified before returning.

There are two versions of fillTorus(); the other takes a boundary component, and sets e0, e1 and e2 to its three edges according to Regina's own edge numbering. This version of fillTorus() should be used when you know how the filling curve cuts each boundary edge but you do not know how these edges are indexed in the corresponding boundary component.

Parameters
e0one of the three edges of the boundary component to fill.
e1the second of the three edges of the boundary component to fill.
e2the second of the three edges of the boundary component to fill.
cuts0the number of times that the meridional curve of the new solid torus should cut the edge e0.
cuts1the number of times that the meridional curve of the new solid torus should cut the edge e1.
cuts2the number of times that the meridional curve of the new solid torus should cut the edge e2.
Returns
true if the boundary component was filled successfully, or false if one of the required conditions as described above is not satisfied.

◆ fillTorus() [2/2]

bool regina::Triangulation< 3 >::fillTorus ( unsigned long  cuts0,
unsigned long  cuts1,
unsigned long  cuts2,
BoundaryComponent< 3 > *  bc = nullptr 
)
inherited

Fills a two-triangle torus boundary component by attaching a solid torus along a given curve.

The boundary component to be filled should be passed as the argument bc; if the triangulation has exactly one boundary component then you may omit bc (i.e., pass null), and the (unique) boundary component will be inferred.

If the boundary component cannot be inferred, and/or if the selected boundary component is not a two-triangle torus, then this routine will do nothing and return false.

Otherwise the given boundary component will be filled with a solid torus whose meridional curve cuts the edges bc->edge(0), bc->edge(1) and bc->edge(2) a total of cuts0, cuts1 and cuts2 times respectively.

For the filling to be performed successfully, the integers cuts0, cuts1 and cuts2 must be coprime, and two of them must add to give the third. Otherwise, as above, this routine will do nothing and return false.

The triangulation will be simplified before returning.

There are two versions of fillTorus(); the other takes three explicit edges instead of a boundary component. You should use the other version if you know how the filling curve cuts each boundary edge but you do not know how these edges are indexed in the boundary component.

Parameters
cuts0the number of times that the meridional curve of the new solid torus should cut the edge bc->edge(0).
cuts1the number of times that the meridional curve of the new solid torus should cut the edge bc->edge(1).
cuts2the number of times that the meridional curve of the new solid torus should cut the edge bc->edge(2).
bcthe boundary component to fill. If the triangulation has precisely one boundary component then this may be null.
Returns
true if the boundary component was filled successfully, or false if one of the required conditions as described above is not satisfied.

◆ findAllIsomorphisms()

bool regina::detail::TriangulationBase< dim >::findAllIsomorphisms ( const Triangulation< dim > &  other,
Action &&  action,
Args &&...  args 
) const
inlineinherited

Finds all ways in which this triangulation is combinatorially isomorphic to the given triangulation.

This routine behaves identically to isIsomorphicTo(), except that instead of returning just one isomorphism, all such isomorphisms will be found and processed. See the isIsomorphicTo() notes for details on this.

For each isomorphism that is found, this routine will call action (which must be a function or some other callable object).

  • The first argument to action must be of type (const Isomorphism<dim>&); this will be a reference to the isomorphism that was found. If action wishes to keep the isomorphism, it should take a deep copy (not a reference), since the isomorphism may be changed and reused after action returns.
  • If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
  • action must return a bool. A return value of false indicates that the search for isomorphisms should continue, and a return value of true indicates that the search should terminate immediately.
  • This triangulation must remain constant while the search runs (i.e., action must not modify the triangulation).
Warning
For large dimensions, this routine can become extremely slow: its running time includes a factor of (dim+1)!.
Python
There are two versions of this function available in Python. The first form is findAllIsomorphisms(other, action), which mirrors the C++ function: it takes action which may be a pure Python function, the return value indicates whether action ever terminated the search, but it does not take an additonal argument list (args). The second form is findAllIsomorphisms(other), which returns a Python list containing all of the isomorphisms that were found.
Parameters
otherthe triangulation to compare with this one.
actiona function (or other callable object) to call for each isomorphism that is found.
argsany additional arguments that should be passed to action, following the initial isomorphism argument.
Returns
true if action ever terminated the search by returning true, or false if the search was allowed to run to completion.

◆ findAllSubcomplexesIn()

bool regina::detail::TriangulationBase< dim >::findAllSubcomplexesIn ( const Triangulation< dim > &  other,
Action &&  action,
Args &&...  args 
) const
inlineinherited

Finds all ways in which an isomorphic copy of this triangulation is contained within the given triangulation, possibly as a subcomplex of some larger component (or components).

This routine behaves identically to isContainedIn(), except that instead of returning just one isomorphism (which may be boundary incomplete and need not be onto), all such isomorphisms will be found and processed. See the isContainedIn() notes for details on this.

For each isomorphism that is found, this routine will call action (which must be a function or some other callable object).

  • The first argument to action must be of type (const Isomorphism<dim>&); this will be a reference to the isomorphism that was found. If action wishes to keep the isomorphism, it should take a deep copy (not a reference), since the isomorphism may be changed and reused after action returns.
  • If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
  • action must return a bool. A return value of false indicates that the search for isomorphisms should continue, and a return value of true indicates that the search should terminate immediately.
  • This triangulation must remain constant while the search runs (i.e., action must not modify the triangulation).
Warning
For large dimensions, this routine can become extremely slow: its running time includes a factor of (dim+1)!.
Python
There are two versions of this function available in Python. The first form is findAllSubcomplexesIn(other, action), which mirrors the C++ function: it takes action which may be a pure Python function, the return value indicates whether action ever terminated the search, but it does not take an additonal argument list (args). The second form is findAllSubcomplexesIn(other), which returns a Python list containing all of the isomorphisms that were found.
Parameters
otherthe triangulation in which to search for isomorphic copies of this triangulation.
actiona function (or other callable object) to call for each isomorphism that is found.
argsany additional arguments that should be passed to action, following the initial isomorphism argument.
Returns
true if action ever terminated the search by returning true, or false if the search was allowed to run to completion.

◆ finiteToIdeal()

bool regina::detail::TriangulationBase< dim >::finiteToIdeal
inherited

Converts each real boundary component into a cusp (i.e., an ideal vertex).

Only boundary components formed from real (dim-1)-faces will be affected; ideal boundary components are already cusps and so will not be changed.

One side-effect of this operation is that all spherical boundary components will be filled in with balls.

This operation is performed by attaching a new dim-simplex to each boundary (dim-1)-face, and then gluing these new simplices together in a way that mirrors the adjacencies of the underlying boundary facets. Each boundary component will thereby be pushed up through the new simplices and converted into a cusp formed using vertices of these new simplices.

In Regina's standard dimensions, where triangulations also support an idealToFinite() operation, this routine is a loose converse of that operation.

In dimension 2, every boundary component is spherical and so this routine simply fills all the punctures in the underlying surface. (In dimension 2, triangulations cannot have cusps).

Warning
If a real boundary component contains vertices whose links are not discs, this operation may have unexpected results.
Returns
true if changes were made, or false if the original triangulation contained no real boundary components.

◆ fourFourMove()

bool regina::Triangulation< 3 >::fourFourMove ( Edge< 3 > *  e,
int  newAxis,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 4-4 move about the given edge.

This involves replacing the four tetrahedra joined at that edge with four tetrahedra joined along a different edge. Consider the octahedron made up of the four original tetrahedra; this has three internal axes. The initial four tetrahedra meet along the given edge which forms one of these axes; the new tetrahedra will meet along a different axis. This move can be done iff (i) the edge is valid and non-boundary, and (ii) the four tetrahedra are distinct.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this 4-4 move will label the new tetrahedra in a way that preserves the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument e) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given edge is an edge of this triangulation.
Parameters
ethe edge about which to perform the move.
newAxisSpecifies which axis of the octahedron the new tetrahedra should meet along; this should be 0 or 1. Consider the four original tetrahedra in the order described by Edge<3>::embedding(0,...,3); call these tetrahedra 0, 1, 2 and
  1. If newAxis is 0, the new axis will separate tetrahedra 0 and 1 from 2 and 3. If newAxis is 1, the new axis will separate tetrahedra 1 and 2 from 3 and 0.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ fromGluings() [1/2]

Triangulation< dim > regina::detail::TriangulationBase< dim >::fromGluings ( size_t  size,
Iterator  beginGluings,
Iterator  endGluings 
)
staticinherited

Creates a triangulation from a list of gluings.

This routine is an analogue to the variant of fromGluings() that takes a C++ initialiser list; however, here the input data may be constructed at runtime (which makes it accessible to Python, amongst other things).

The iterator range (beginGluings, endGluings) should encode the list of gluings for the triangulation. Each iterator in this range must dereference to a tuple of the form (simp, facet, adj, gluing); here simp, facet and adj are all integers, and gluing is of type Perm<dim+1>. Each such tuple indicates that facet facet of top-dimensional simplex number simp should be glued to top-dimensional simplex number adj using the permutation gluing. In other words, such a tuple encodes the same information as calling simplex(simp).join(facet, simplex(adj), gluing) upon the triangulation being constructed.

Every gluing should be encoded from one direction only. This means, for example, that to build a closed 3-manifold triangulation with n tetrahedra, you would pass a list of 2n such tuples. If you attempt to make the same gluing twice (e.g., once from each direction), then this routine will throw an exception.

Any facet of a simplex that does not feature in the given list of gluings (either as a source or a destination) will be left as a boundary facet.

Note that, as usual, the top-dimensional simplices are numbered 0,...,(size-1), and the facets of each simplex are numbered 0,...,dim.

As an example, Python users can construct the figure eight knot complement as follows:

tri = Triangulation3.fromGluings(2, [
( 0, 0, 1, Perm4(1,3,0,2) ), ( 0, 1, 1, Perm4(2,0,3,1) ),
( 0, 2, 1, Perm4(0,3,2,1) ), ( 0, 3, 1, Perm4(2,1,0,3) )])
Note
The assumption is that the iterators dereference to a std::tuple<size_t, int, size_t, Perm<dim+1>>. However, this is not strictly necessary - the dereferenced type may be any type that supports std::get (and for which std::get<0..3>() yields suitable integer/permutation types).
Exceptions
InvalidArgumentThe given list of gluings does not correctly describe a triangulation with size top-dimensional simplices.
Python
The gluings should be passed as a single Python list of tuples (not an iterator pair).
Parameters
sizethe number of top-dimensional simplices in the triangulation to construct.
beginGluingsthe beginning of the list of gluings, as described above.
endGluingsa past-the-end iterator indicating the end of the list of gluings.
Returns
the reconstructed triangulation.

◆ fromGluings() [2/2]

Triangulation< dim > regina::detail::TriangulationBase< dim >::fromGluings ( size_t  size,
std::initializer_list< std::tuple< size_t, int, size_t, Perm< dim+1 > > >  gluings 
)
inlinestaticinherited

Creates a triangulation from a hard-coded list of gluings.

This routine takes a C++ initialiser list, which makes it useful for creating hard-coded examples directly in C++ code without needing to write a tedious sequence of calls to Simplex<dim>::join().

Each element of the initialiser list should be a tuple of the form (simp, facet, adj, gluing), which indicates that facet facet of top-dimensional simplex number simp should be glued to top-dimensional simplex number adj using the permutation gluing. In other words, such a tuple encodes the same information as calling simplex(simp).join(facet, simplex(adj), gluing) upon the triangulation being constructed.

Every gluing should be encoded from one direction only. This means, for example, that to build a closed 3-manifold triangulation with n tetrahedra, you would pass a list of 2n such tuples. If you attempt to make the same gluing twice (e.g., once from each direction), then this routine will throw an exception.

Any facet of a simplex that does not feature in the given list of gluings (either as a source or a destination) will be left as a boundary facet.

Note that, as usual, the top-dimensional simplices are numbered 0,...,(size-1), and the facets of each simplex are numbered 0,...,dim.

As an example, you can construct the figure eight knot complement using the following code:

Triangulation<3> tri = Triangulation<3>::fromGluings(2, {
{ 0, 0, 1, {1,3,0,2} }, { 0, 1, 1, {2,0,3,1} },
{ 0, 2, 1, {0,3,2,1} }, { 0, 3, 1, {2,1,0,3} }});
static Triangulation< dim > fromGluings(size_t size, std::initializer_list< std::tuple< size_t, int, size_t, Perm< dim+1 > > > gluings)
Creates a triangulation from a hard-coded list of gluings.
Definition: triangulation.h:4293
Note
If you have an existing triangulation that you would like to hard-code in this way, you can call dumpConstruction() to generate the corresponding C++ source code.
Exceptions
InvalidArgumentThe given list of gluings does not correctly describe a triangulation with size top-dimensional simplices.
Python
Not present. Instead, use the variant of fromGluings() that takes this same data using a Python list (which need not be constant).
Parameters
sizethe number of top-dimensional simplices in the triangulation to construct.
gluingsdescribes the gluings between these top-dimensional simplices, as described above.
Returns
the reconstructed triangulation.

◆ fromIsoSig()

static Triangulation< dim > regina::detail::TriangulationBase< dim >::fromIsoSig ( const std::string &  sig)
staticinherited

Recovers a full triangulation from an isomorphism signature.

See isoSig() for more information on isomorphism signatures. It will be assumed that the signature describes a triangulation of dimension dim.

Currently this routine only supports isomorphism signatures that were created with the default encoding (i.e., there was no Encoding template parameter passed to isoSig()).

Calling isoSig() followed by fromIsoSig() is not guaranteed to produce an identical triangulation to the original, but it is guaranteed to produce a combinatorially isomorphic triangulation. In other words, fromIsoSig() may reconstruct the triangulation with its simplices and/or vertices relabelled. The optional argument to isoSig() allows you to determine the precise relabelling that will be used, if you need to know it.

For a full and precise description of the isomorphism signature format for 3-manifold triangulations, see Simplification paths in the Pachner graphs of closed orientable 3-manifold triangulations, Burton, 2011, arXiv:1110.6080. The format for other dimensions is essentially the same, but with minor dimension-specific adjustments.

Warning
Do not mix isomorphism signatures between dimensions! It is possible that the same string could corresponding to both a p-dimensional triangulation and a q-dimensional triangulation for different dimensions p and q.
Exceptions
InvalidArgumentThe given string was not a valid dim-dimensional isomorphism signature created using the default encoding.
Parameters
sigthe isomorphism signature of the triangulation to construct. Note that isomorphism signatures are case-sensitive (unlike, for example, dehydration strings for 3-manifolds).
Returns
the reconstructed triangulation.

◆ fromSig()

Triangulation< dim > regina::detail::TriangulationBase< dim >::fromSig ( const std::string &  sig)
inlinestaticinherited

Alias for fromIsoSig(), to recover a full triangulation from an isomorphism signature.

This alias fromSig() is provided to assist with generic code that can work with both triangulations and links.

See fromIsoSig() for further details.

Exceptions
InvalidArgumentThe given string was not a valid dim-dimensional isomorphism signature created using the default encoding.
Parameters
sigthe isomorphism signature of the triangulation to construct. Note that isomorphism signatures are case-sensitive (unlike, for example, dehydration strings for 3-manifolds).
Returns
the reconstructed triangulation.

◆ fromSnapPea()

static Triangulation< 3 > regina::Triangulation< 3 >::fromSnapPea ( const std::string &  snapPeaData)
staticinherited

Extracts the tetrahedron gluings from a string that contains the full contents of a SnapPea data file.

All other SnapPea-specific information (such as peripheral curves, and the manifold name) will be ignored, since Regina's Triangulation<3> class does not track such information itself.

If you wish to preserve all SnapPea-specific information from the data file, you should work with the SnapPeaTriangulation class instead (which uses the SnapPea kernel directly, and can therefore store anything that SnapPea can).

If you wish to read a triangulation from a SnapPea file, you should likewise call the SnapPeaTriangulation constructor, giving the filename as argument. This will read all SnapPea-specific information (as described above), and also avoids constructing an enormous intermediate string.

Warning
This routine is "lossy", in that drops SnapPea-specific information (as described above). Unless you specifically need an Triangulation<3> (not an SnapPeaTriangulation) or you need to avoid calling routines from the SnapPea kernel, it is highly recommended that you create a SnapPeaTriangulation from the given file contents instead. See the string-based SnapPeaTriangulation constructor for how to do this.
Exceptions
InvalidArgumentThe given SnapPea data was not in the correct format.
Parameters
snapPeaDataa string containing the full contents of a SnapPea data file.
Returns
a native Regina triangulation extracted from the given SnapPea data.

◆ fundamentalGroup()

const GroupPresentation & regina::detail::TriangulationBase< dim >::fundamentalGroup
inlineinherited

An alias for group(), which returns the fundamental group of this triangulation.

See group() for further details, including how ideal vertices and invalid faces are managed.

Note
In Regina 7.2, the routine fundamentalGroup() was renamed to group() for brevity and for consistency with Link::group(). This more expressive name fundamentalGroup() will be kept as a long-term alias, and you are welcome to continue using it if you prefer.
Precondition
This triangulation has at most one component.
Warning
In dimension 3, if you are calling this from the subclass SnapPeaTriangulation then any fillings on the cusps will be ignored. (This is the same as for every routine implemented by Regina's Triangulation<3> class.) If you wish to compute the fundamental group with fillings, call SnapPeaTriangulation::fundamentalGroupFilled() instead.
Returns
the fundamental group.

◆ fundamentalGroupFilled()

const GroupPresentation & regina::SnapPeaTriangulation::fundamentalGroupFilled ( bool  simplifyPresentation = true,
bool  fillingsMayAffectGenerators = true,
bool  minimiseNumberOfGenerators = true,
bool  tryHardToShortenRelators = true 
) const

Returns the fundamental group of the manifold with respect to the current Dehn filling (if any).

Any complete cusps (without fillings) will be treated as though they had been truncated.

This is different from the inherited group() routine (and its alias fundamentalGroup()) from the parent Triangulation<3> class:

  • This routine fundamentalGroupFilled() respects Dehn fillings, and directly uses SnapPea's code to compute fundamental groups.
  • The inherited group() routine uses only Regina's code, and works purely within Regina's parent Triangulation<3> class. Since Triangulation<3> knows nothing about SnapPea or fillings, this means that any fillings on the cusps (which are specific to SnapPea triangulations) will be ignored.

Note that each time the triangulation changes, the fundamental group will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, fundamentalGroupFilled() should be called again; this will be instantaneous if the group has already been calculated.

Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
Parameters
simplifyPresentationtrue if SnapPea should attempt to simplify the group presentation, or false if it should be left unsimplified. Even if simplifyPresentation is false, this routine will always eliminate adjacent (x, x^-1) pairs.
fillingsMayAffectGeneratorstrue if SnapPea's choice of generators is allowed to depend on the Dehn fillings, or false if the choice of generators should be consistent across different fillings.
minimiseNumberOfGeneratorstrue if SnapPea's group simplification code should try to reduce the number of generators at the expense of increasing the total length of the relations, or false if it should do the opposite.
tryHardToShortenRelatorstrue if SnapPea's group simplification code should try to reduce the length of the relations by inserting one relation into another. In general this is a good thing, but it can be very costly for large presentations.
Returns
the fundamental group of the filled manifold.

◆ fVector()

std::vector< size_t > regina::detail::TriangulationBase< dim >::fVector
inlineinherited

Returns the f-vector of this triangulation, which counts the number of faces of all dimensions.

The vector that is returned will have length dim+1. If this vector is f, then f[k] will be the number of k-faces for each 0 ≤ k ≤ dim.

This routine is significantly more heavyweight than countFaces(). Its advantage is that, unlike the templatised countFaces(), it allows you to count faces whose dimensions are not known until runtime.

Returns
the f-vector of this triangulation.

◆ generalAngleStructure()

const AngleStructure & regina::Triangulation< 3 >::generalAngleStructure ( ) const
inlineinherited

Returns a generalised angle structure on this triangulation, if one exists.

A generalised angle structure must satisfy the same matching equations as all angle structures do, but there is no constraint on the signs of the angles; in particular, negative angles are allowed. If a generalised angle structure does exist, then this routine is guaranteed to return one.

This routine is designed for scenarios where you already know that a generalised angle structure exists. This means:

  • If no generalised angle structure exists, this routine will throw an exception, which will incur a significant overhead.
  • It should be rare that you do not know in advance whether a generalised angle structure exists (see the simple conditions in the note below). However, if you don't yet know, you should call hasGeneralAngleStructure() first. If the answer is no, this will avoid the overhead of throwing and catching exceptions. If the answer is yes, this will have the side-effect of caching the angle structure, which means your subsequent call to generalAngleStructure() will be essentially instantaneous.

The underlying algorithm simply solves a system of linear equations, and so should be fast even for large triangulations.

The result of this routine is cached internally: as long as the triangulation does not change, multiple calls to generalAngleStructure() will return identical angle structures, and every call after the first be essentially instantaneous.

If the triangulation does change, however, then the cached angle structure will be deleted, and any reference that was returned before will become invalid.

Note
For a valid triangulation with no boundary faces, a generalised angle structure exists if and only if every vertex link is a torus or Klein bottle. The "only if" direction is a simple Euler characteristic calculation; for the "if" direction see "Angle structures and normal surfaces", Feng Luo and Stephan Tillmann, Trans. Amer. Math. Soc. 360:6 (2008), pp. 2849-2866).
Exceptions
NoSolutionNo generalised angle structure exists on this triangulation.
Returns
a generalised angle structure on this triangulation, if one exists.

◆ gluingEquations()

MatrixInt regina::SnapPeaTriangulation::gluingEquations ( ) const

Returns a matrix describing Thurston's gluing equations.

This will be with respect to the current Dehn filling (if any).

Each row of this matrix will describe a single equation. The first countEdges() rows will list the edge equations, and the following 2 * countCompleteCusps() + countFilledCusps() rows will list the cusp equations.

The edge equations will be ordered arbitrarily. The cusp equations will be presented in pairs ordered by cusp index (as stored by SnapPea); within each pair the meridian equation will appear before the longitude equation. The Cusp::vertex() method (which is accessed through the cusp() routine) can help translate between SnapPea's cusp numbers and Regina's vertex numbers.

The matrix will contain 3 * size() columns. The first three columns represent shape parameters z, 1/(1-z) and (z-1)/z for the first tetrahedron; the next three columns represent shape parameters z, 1/(1-z) and (z-1)/z for the second tetrahedron, and so on. By Regina's edge numbering conventions, z corresponds to edges 0 and 5 of the tetrahedron, 1/(1-z) corresponds to edges 1 and 4 of the tetrahedron, and (z-1)/z corresponds to edges 2 and 3 of the tetrahedron.

More specifically, a row of the form a b c d e f ... describes an equation with left hand side a log(z0) + b log(1/(1-z0)) + c log((z0-1)/z) + d log(z1) + ..., and with right hand side 2Ï€i for an edge equation or 0 for a cusp equation.

See also gluingEquationsRect(), which returns the gluing equations in a more streamlined form.

SnapPy
In SnapPy, this routine corresponds to calling Manifold.gluing_equations().
Precondition
This is not a null triangulation.
Returns
a matrix with (number_of_rows + number_of_cusps) rows and (3 * number_of_tetrahedra) columns as described above.

◆ gluingEquationsRect()

MatrixInt regina::SnapPeaTriangulation::gluingEquationsRect ( ) const

Returns a matrix describing Thurston's gluing equations in a streamlined form.

This will be with respect to the current Dehn filling (if any).

Each row of this matrix will describe a single equation. The rows begin with the edge equations (in arbitrary order) followed by the cusp equations (ordered by cusp index); for precise details see the documentation for gluingEquations(), which uses the same ordering.

The matrix will contain 2 * size() + 1 columns. Let k = size()-1, and suppose the shape parameters for tetrahedra 0, 1, ..., k are z0, z1, ..., zk (here each shape parameter corresponds to edges 0 and 5 of the corresponding tetrahedron). Then a row of the form a0 a1 ... ak b0 b1 ... bk c describes the equation z0^a0 z1^a1 ... zk^ak (1-z0)^b0 (1-z1)^b1 ... (1-zk)^bk = c, where c will always be 1 or -1.

See also gluingEquations(), which returns the gluing equations in a more transparent term-by-term form.

SnapPy
In SnapPy, this routine corresponds to calling Manifold.gluing_equations(form="rect").
Precondition
This is not a null triangulation.
Returns
a matrix with (number_of_rows + number_of_cusps) rows and (2 * number_of_tetrahedra + 1) columns as described above.

◆ group()

const GroupPresentation & regina::detail::TriangulationBase< dim >::group ( ) const
inherited

Returns the fundamental group of this triangulation.

The fundamental group is computed in the dual 2-skeleton. This means:

  • If the triangulation contains any ideal vertices, the fundamental group will be calculated as if each such vertex had been truncated.
  • Likewise, if the triangulation contains any invalid faces of dimension 0,1,...,(dim-3), these will effectively be truncated also.
  • In contrast, if the triangulation contains any invalid (dim-2)-faces (i.e., codimension-2-faces that are identified with themselves under a non-trivial map), the fundamental group will be computed without truncating the centroid of the face. For instance, if a 3-manifold triangulation has an edge identified with itself in reverse, then the fundamental group will be computed without truncating the resulting projective plane cusp. This means that, if a barycentric subdivision is performed on a such a triangulation, the result of group() might change.

Bear in mind that each time the triangulation changes, the fundamental group will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, group() should be called again; this will be instantaneous if the group has already been calculated.

Before Regina 7.2, this routine was called fundamentalGroup(). It has since been renamed to group() for brevity and for consistency with Link::group(). The more expressive name fundamentalGroup() will be kept, and you are welcome to use that instead if you prefer.

Precondition
This triangulation has at most one component.
Warning
In dimension 3, if you are calling this from the subclass SnapPeaTriangulation then any fillings on the cusps will be ignored. (This is the same as for every routine implemented by Regina's Triangulation<3> class.) If you wish to compute the fundamental group with fillings, call SnapPeaTriangulation::fundamentalGroupFilled() instead.
Returns
the fundamental group.

◆ hasBoundaryFacets()

bool regina::detail::TriangulationBase< dim >::hasBoundaryFacets
inlineinherited

Determines if this triangulation has any boundary facets.

This routine returns true if and only if the triangulation contains some top-dimension simplex with at least one facet that is not glued to an adjacent simplex.

Returns
true if and only if there are boundary facets.

◆ hasBoundaryTriangles()

bool regina::Triangulation< 3 >::hasBoundaryTriangles ( ) const
inlineinherited

A dimension-specific alias for hasBoundaryFacets().

See hasBoundaryFacets() for further information.

◆ hasCompressingDisc()

bool regina::Triangulation< 3 >::hasCompressingDisc ( ) const
inherited

Searches for a compressing disc within the underlying 3-manifold.

Let M be the underlying 3-manifold and let B be its boundary. By a compressing disc, we mean a disc D properly embedded in M, where the boundary of D lies in B but does not bound a disc in B.

This routine will first call the heuristic routine hasSimpleCompressingDisc() in the hope of obtaining a fast answer. If this fails, it will do one of two things:

  • If the triangulation is orientable and 1-vertex, it will use the linear programming and crushing machinery outlined in "Computing closed essential surfaces in knot complements", Burton, Coward and Tillmann, SCG '13, p405-414, 2013. This is often extremely fast, even for triangulations with many tetrahedra.
  • If the triangulation is non-orientable or has multiple vertices then it will run a full enumeration of vertex normal surfaces, as described in "Algorithms for the complete decomposition of a closed 3-manifold", Jaco and Tollefson, Illinois J. Math. 39 (1995), 358-406. As the number of tetrahedra grows, this can become extremely slow.

This routine will work on a copy of this triangulation, not the original. In particular, the copy will be simplified, which means that there is no harm in calling this routine on an unsimplified triangulation.

If this triangulation has no boundary components, this routine will simply return false.

Precondition
This triangulation is valid and is not ideal.
The underlying 3-manifold is irreducible.
Warning
This routine can be infeasibly slow for large triangulations (particularly those that are non-orientable or have multiple vertices), since it may need to perform a full enumeration of vertex normal surfaces, and since it might perform "large" operations on these surfaces such as cutting along them. See hasSimpleCompressingDisc() for a "heuristic shortcut" that is faster but might not give a definitive answer.
Returns
true if the underlying 3-manifold contains a compressing disc, or false if it does not.

◆ hasGeneralAngleStructure()

bool regina::Triangulation< 3 >::hasGeneralAngleStructure ( ) const
inherited

Determines whether this triangulation supports a generalised angle structure.

A generalised angle structure must satisfy the same matching equations as all angle structures do, but there is no constraint on the signs of the angles; in particular, negative angles are allowed.

This routine returns false if and only if generalAngleStructure() throws an exception. However, if you do not know whether a generalised angle structure exists, then this routine is faster:

  • If there is no generalised angle structure, this routine will avoid the overhead of throwing and catching exceptions.
  • If there is a generalised angle structure, this routine will find and cache this angle structure, which means that any subsequent call to generalAngleStructure() to retrieve its details will be essentially instantaneous.

The underlying algorithm simply solves a system of linear equations, and so should be fast even for large triangulations.

Note
For a valid triangulation with no boundary faces, a generalised angle structure exists if and only if every vertex link is a torus or Klein bottle. The "only if" direction is a simple Euler characteristic calculation; for the "if" direction see "Angle structures and normal surfaces", Feng Luo and Stephan Tillmann, Trans. Amer. Math. Soc. 360:6 (2008), pp. 2849-2866).
Even if the condition above is true and it is clear that a generalised angle structure should exist, this routine will still do the extra work to compute an explicit solution (in order to fulfil the promise made in the generalAngleStructure() documentation).
Returns
true if and only if a generalised angle structure exists on this triangulation.

◆ hasMinimalBoundary()

bool regina::Triangulation< 3 >::hasMinimalBoundary ( ) const
inherited

Determines whether the boundary of this triangulation contains the smallest possible number of triangles.

This is true if and only if, amongst all real boundary components, every sphere or projective plane boundary component has precisely two triangles, and every other boundary component has precisely one vertex.

For the purposes of this routine, ideal boundary components are ignored.

If this routine returns false, you can call minimiseBoundary() to make the number of boundary triangles minimal.

Precondition
This triangulation is valid.
Returns
true if and only if the boundary contains the smallest possible number of triangles.

◆ hasMinimalVertices()

bool regina::Triangulation< 3 >::hasMinimalVertices ( ) const
inherited

Determines whether this triangulation contains the smallest possible number of vertices for the 3-manifold that it represents.

This is true if and only if:

  • amongst all real boundary components, every sphere or projective plane boundary component has precisely two triangles, and every other boundary component has precisely one vertex;
  • amongst all connected components, every closed component has precisely one vertex, and every component with real or ideal boundary has no internal vertices at all.

If this routine returns false, you can call minimiseVertices() to make the number of vertices minimal.

Precondition
This triangulation is valid.
Returns
true if and only if this triangulation contains the smallest possible number of vertices.

◆ hasNegativeIdealBoundaryComponents()

bool regina::Triangulation< 3 >::hasNegativeIdealBoundaryComponents ( ) const
inlineinherited

Determines if this triangulation contains any ideal boundary components with negative Euler characteristic.

Returns
true if and only if there is at least one such boundary component.

◆ hasSimpleCompressingDisc()

bool regina::Triangulation< 3 >::hasSimpleCompressingDisc ( ) const
inherited

Searches for a "simple" compressing disc inside this triangulation.

Let M be the underlying 3-manifold and let B be its boundary. By a compressing disc, we mean a disc D properly embedded in M, where the boundary of D lies in B but does not bound a disc in B.

By a simple compressing disc, we mean a compressing disc that has a very simple combinatorial structure (here "simple" is subject to change; see the warning below). Examples include the compressing disc inside a 1-tetrahedron solid torus, or a compressing disc formed from a single internal triangle surrounded by three boundary edges.

The purpose of this routine is to avoid working with normal surfaces within a large triangulation where possible. This routine is relatively fast, and if it returns true then this 3-manifold definitely contains a compressing disc. If this routine returns false then there might or might not be a compressing disc; the user will need to perform a full normal surface enumeration using hasCompressingDisc() to be sure.

This routine will work on a copy of this triangulation, not the original. In particular, the copy will be simplified, which means that there is no harm in calling this routine on an unsimplified triangulation.

If this triangulation has no boundary components, this routine will simply return false.

For further information on this test, see "The Weber-Seifert dodecahedral space is non-Haken", Benjamin A. Burton, J. Hyam Rubinstein and Stephan Tillmann, Trans. Amer. Math. Soc. 364:2 (2012), pp. 911-932.

Warning
The definition of "simple" is subject to change in future releases of Regina. That is, this routine may be expanded over time to identify more types of compressing discs (thus making it more useful as a "heuristic shortcut").
Precondition
This triangulation is valid and is not ideal.
Returns
true if a simple compressing disc was found, or false if not. Note that even with a return value of false, there might still be a compressing disc (just not one with a simple combinatorial structure).

◆ hasSplittingSurface()

bool regina::Triangulation< 3 >::hasSplittingSurface ( ) const
inherited

Determines whether this triangulation has a normal splitting surface.

See NormalSurface::isSplitting() for details regarding normal splitting surfaces.

In the special case where this is the empty triangulation, this routine returns false.

As of Regina 6.0, this routine is now fast (small polynomial time), and works even for triangulations with more than one connected component. Thanks to Robert Haraway.

Returns
true if and only if this triangulation has a normal splitting surface.

◆ hasStrictAngleStructure()

bool regina::Triangulation< 3 >::hasStrictAngleStructure ( ) const
inherited

Determines whether this triangulation supports a strict angle structure.

Recall that a strict angle structure is one in which every angle is strictly between 0 and π.

This routine returns false if and only if strictAngleStructure() throws an exception. However, if you do not know whether a strict angle structure exists, then this routine is faster:

  • If there is no strict angle structure, this routine will avoid the overhead of throwing and catching exceptions.
  • If there is a strict angle structure, this routine will find and cache this angle structure, which means that any subsequent call to strictAngleStructure() to retrieve its details will be essentially instantaneous.

The underlying algorithm runs a single linear program (it does not enumerate all vertex angle structures). This means that it is likely to be fast even for large triangulations.

Returns
true if and only if a strict angle structure exists on this triangulation.

◆ hasTwoSphereBoundaryComponents()

bool regina::Triangulation< 3 >::hasTwoSphereBoundaryComponents ( ) const
inlineinherited

Determines if this triangulation contains any two-sphere boundary components.

Returns
true if and only if there is at least one two-sphere boundary component.

◆ homology() [1/2]

AbelianGroup regina::detail::TriangulationBase< dim >::homology ( ) const
inherited

Returns the kth homology group of this triangulation, treating any ideal vertices as though they had been truncated.

For C++ programmers who know subdim at compile time, you should use this template function homology<subdim>(), which is slightly faster than passing subdim as an ordinary runtime argument to homology(subdim).

See the non-templated homology(int) for full details on exactly what this function computes.

Precondition
Unless you are computing first homology (k = 1), this triangulation must be valid, and every face that is not a vertex must have a ball or sphere link. The link condition already forms part of the validity test if dim is one of Regina's standard dimensions, but in higher dimensions it is the user's own responsibility to ensure this. See isValid() for details.
Exceptions
FailedPreconditionThis triangulation is invalid, and the homology dimension k is not 1.
Python
Not present. Instead use the variant homology(k).
Template Parameters
kthe dimension of the homology group to return; this must be between 1 and (dim - 1) inclusive if dim is one of Regina's standard dimensions, or between 1 and (dim - 2) inclusive if not.
Returns
the kth homology group.

◆ homology() [2/2]

AbelianGroup regina::detail::TriangulationBase< dim >::homology ( int  k) const
inlineinherited

Returns the kth homology group of this triangulation, treating any ideal vertices as though they had been truncated, where the parameter k does not need to be known until runtime.

For C++ programmers who know k at compile time, you are better off using the template function homology<k>() instead, which is slightly faster.

A problem with computing homology is that, if dim is not one of Regina's standard dimensions, then Regina cannot actually detect ideal vertices (since in general this requires solving undecidable problems). Currently we resolve this by insisting that, in higher dimensions, the homology dimension k is at most (dim-2); the underlying algorithm will then effectively truncate all vertices (since truncating "ordinary" vertices whose links are spheres or balls does not affect the kth homology in such cases).

In general, this routine insists on working with a valid triangulation (see isValid() for what this means). However, for historical reasons, if you are computing first homology (k = 1) then your triangulation is allowed to be invalid, though the results might or might not be useful to you. The homology will be computed using the dual skeleton: what this means is that any invalid faces of dimension 0,1,...,(dim-3) will be treated as though their centroids had been truncated, but any invalid (dim-2)-faces will be treated without such truncation. A side-effect is that, after performing a barycentric on an invalid triangulation, the group returned by homology<1>() might change.

Warning
In dimension 3, if you are calling this from the subclass SnapPeaTriangulation then any fillings on the cusps will be ignored. (This is the same as for every routine implemented by Regina's Triangulation<3> class.) If you wish to compute homology with fillings, call SnapPeaTriangulation::homologyFilled() instead.
Precondition
Unless you are computing first homology (k = 1), this triangulation must be valid, and every face that is not a vertex must have a ball or sphere link. The link condition already forms part of the validity test if dim is one of Regina's standard dimensions, but in higher dimensions it is the user's own responsibility to ensure this. See isValid() for details.
Exceptions
FailedPreconditionThis triangulation is invalid, and the homology dimension k is not 1.
InvalidArgumentThe homology dimension k is outside the supported range. This range depends upon the triangulation dimension dim; for details see the documentation below for the argument k.
Python
Like the C++ template function homology<k>(), you can omit the homology dimension k; this will default to 1.
Parameters
kthe dimension of the homology group to return; this must be between 1 and (dim - 1) inclusive if dim is one of Regina's standard dimensions, or between 1 and (dim - 2) inclusive if not.
Returns
the kth homology group.

◆ homologyBdry()

const AbelianGroup & regina::Triangulation< 3 >::homologyBdry ( ) const
inherited

Returns the first homology group of the boundary for this triangulation.

Note that ideal vertices are considered part of the boundary.

Bear in mind that each time the triangulation changes, the homology groups will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, homologyBdry() should be called again; this will be instantaneous if the group has already been calculated.

This routine is fairly fast, since it deduces the homology of each boundary component through knowing what kind of surface it is.

Precondition
This triangulation is valid.
Exceptions
FailedPreconditionThis triangulation is invalid.
Returns
the first homology group of the boundary.

◆ homologyFilled()

const AbelianGroup & regina::SnapPeaTriangulation::homologyFilled ( ) const

Returns the first homology group of the manifold with respect to the current Dehn filling (if any).

Any complete cusps (without fillings) will be treated as though they had been truncated.

This is different from the inherited homology() routine from the parent Triangulation<3> class:

  • This routine homologyFilled() respects Dehn fillings, and uses a combination of both SnapPea's and Regina's code to compute homology groups. There may be situations in which the SnapPea kernel cannot perform its part of the computation (see below), in which case this routine will throw a SnapPeaUnsolvedCase exception.
  • The inherited homology() routine uses only Regina's code, and works purely within Regina's parent Triangulation<3> class. Since Triangulation<3> knows nothing about SnapPea or fillings, this means that any fillings on the cusps (which are specific to SnapPea triangulations) will be ignored. The homology() routine will always return a solution.

This routine uses exact arithmetic, and so you are guaranteed that - if it returns a result at all - that this result does not suffer from integer overflows. Essentially, the process is this:

  • SnapPea constructs a filled relation matrix using machine integer arithmetic, but detects overflow (in which case this routine will throw an exception);
  • Regina then uses exact integer arithmetic to solve for the abelian group invariants (i.e., Smith normal form).

Note that each time the triangulation changes, the homology group will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, homologyFilled() should be called again; this will be instantaneous if the group has already been calculated.

Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
SnapPeaUnsolvedCaseSnapPea detected an overflow when attempting to create the filled relation matrix.
Returns
the first homology group of the filled manifold.

◆ homologyH2Z2()

unsigned long regina::Triangulation< 3 >::homologyH2Z2 ( ) const
inlineinherited

Returns the second homology group with coefficients in Z_2 for this triangulation.

If this triangulation contains any ideal vertices, the homology group will be calculated as if each such vertex had been truncated. The algorithm used calculates the relative first homology group with respect to the boundary and uses homology and cohomology theorems to deduce the second homology group.

This group will simply be the direct sum of several copies of Z_2, so the number of Z_2 terms is returned.

Precondition
This triangulation is valid.
Exceptions
FailedPreconditionThis triangulation is invalid.
Returns
the number of Z_2 terms in the second homology group with coefficients in Z_2.

◆ homologyRel()

const AbelianGroup & regina::Triangulation< 3 >::homologyRel ( ) const
inherited

Returns the relative first homology group with respect to the boundary for this triangulation.

Note that ideal vertices are considered part of the boundary.

Bear in mind that each time the triangulation changes, the homology groups will be deleted. Thus the reference that is returned from this routine should not be kept for later use. Instead, homologyRel() should be called again; this will be instantaneous if the group has already been calculated.

Precondition
This triangulation is valid.
Exceptions
FailedPreconditionThis triangulation is invalid.
Returns
the relative first homology group with respect to the boundary.

◆ idealToFinite()

bool regina::Triangulation< 3 >::idealToFinite ( )
inherited

Converts an ideal triangulation into a finite triangulation.

All ideal or invalid vertices are truncated and thus converted into real boundary components made from unglued faces of tetrahedra.

Note that this operation is a loose converse of finiteToIdeal().

Warning
Currently, this routine subdivides all tetrahedra as if all vertices (not just some) were ideal. This may lead to more tetrahedra than are necessary.
Currently, the presence of an invalid edge will force the triangulation to be subdivided regardless of the value of parameter forceDivision. The final triangulation will still have the projective plane cusp caused by the invalid edge.
Todo:
Optimise (long-term): Have this routine only use as many tetrahedra as are necessary, leaving finite vertices alone.
Returns
true if and only if the triangulation was changed.
Author
David Letscher

◆ inAnyPacket() [1/2]

std::shared_ptr< Packet > regina::Triangulation< 3 >::inAnyPacket ( )
inherited

Returns the packet that holds this data, even if it is held indirectly via a SnapPea triangulation.

This routine is similar to PacketOf<Triangulation<3>>::packet(). In particular, if this triangulation is held directly by a 3-dimensional triangulation packet p, then this routine will return p.

The difference is when this triangulation is held "indirectly" by a SnapPea triangulation packet q (i.e., this is the inherited Triangulation<3> data belonging to the SnapPea triangulation). In such a scenario, Triangulation<3>::packet() will return null (since there is no "direct" 3-dimensional triangulation packet), but inAnyPacket() will return q (since the triangulation is still "indirectly" held by a different type of packet).

Returns
the packet that holds this data (directly or indirectly), or null if this data is not held by either a 3-dimensional triangulation packet or a SnapPea triangulation packet.

◆ inAnyPacket() [2/2]

std::shared_ptr< const Packet > regina::Triangulation< 3 >::inAnyPacket ( ) const
inherited

Returns the packet that holds this data, even if it is held indirectly via a SnapPea triangulation.

This routine is similar to PacketOf<Triangulation<3>>::packet(). In particular, if this triangulation is held directly by a 3-dimensional triangulation packet p, then this routine will return p.

The difference is when this triangulation is held "indirectly" by a SnapPea triangulation packet q (i.e., this is the inherited Triangulation<3> data belonging to the SnapPea triangulation). In such a scenario, Triangulation<3>::packet() will return null (since there is no "direct" 3-dimensional triangulation packet), but inAnyPacket() will return q (since the triangulation is still "indirectly" held by a different type of packet).

Returns
the packet that holds this data (directly or indirectly), or null if this data is not held by either a 3-dimensional triangulation packet or a SnapPea triangulation packet.

◆ insertLayeredSolidTorus()

Tetrahedron< 3 > * regina::Triangulation< 3 >::insertLayeredSolidTorus ( unsigned long  cuts0,
unsigned long  cuts1 
)
inherited

Inserts a new layered solid torus into the triangulation.

The meridinal disc of the layered solid torus will intersect the three edges of the boundary torus in cuts0, cuts1 and (cuts0 + cuts1) points respectively.

The boundary torus will always consist of faces 012 and 013 of the tetrahedron containing this boundary torus (this tetrahedron will be returned). In face 012, edges 12, 02 and 01 will meet the meridinal disc cuts0, cuts1 and (cuts0 + cuts1) times respectively. The only exceptions are if these three intersection numbers are (1,1,2) or (0,1,1), in which case edges 12, 02 and 01 will meet the meridinal disc (1, 2 and 1) or (1, 1 and 0) times respectively.

The new tetrahedra will be inserted at the end of the list of tetrahedra in the triangulation.

Precondition
0 ≤ cuts0 ≤ cuts1;
gcd(cuts0, cuts1) = 1.
Parameters
cuts0the smallest of the three desired intersection numbers.
cuts1the second smallest of the three desired intersection numbers.
Returns
the tetrahedron containing the boundary torus.
See also
LayeredSolidTorus

◆ insertTriangulation()

void regina::detail::TriangulationBase< dim >::insertTriangulation ( const Triangulation< dim > &  source)
inherited

Inserts a copy of the given triangulation into this triangulation.

The top-dimensional simplices of source will be copied into this triangulation in the same order in which they appear in source. That is, if the original size of this triangulation was S, then the simplex at index i in source will be copied into this triangulation as a new simplex at index S+i.

The copies will use the same vertex numbering and descriptions as the original simplices from source, and any gluings between the simplices of source will likewise be copied across as gluings between their copies in this triangulation.

This routine behaves correctly when source is this triangulation.

Parameters
sourcethe triangulation whose copy will be inserted.

◆ intelligentSimplify()

bool regina::Triangulation< 3 >::intelligentSimplify ( )
inherited

Attempts to simplify the triangulation using fast and greedy heuristics.

This routine will attempt to reduce the number of tetrahedra, the number of vertices and the number of boundary triangles (with the number of tetrahedra as its priority).

Currently this routine uses simplifyToLocalMinimum() and minimiseVertices() in combination with random 4-4 moves, book opening moves and book closing moves.

Although intelligentSimplify() works very well most of the time, it can occasionally get stuck; in such cases you may wish to try the more powerful but (much) slower simplifyExhaustive() instead.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Warning
Running this routine multiple times upon the same triangulation may return different results, since the implementation makes random decisions. More broadly, the implementation of this routine (and therefore its results) may change between different releases of Regina.
Todo:
Optimise: Include random 2-3 moves to get out of wells.
Returns
true if and only if the triangulation was successfully simplified. Otherwise this triangulation will not be changed.

◆ isBall()

bool regina::Triangulation< 3 >::isBall ( ) const
inherited

Determines whether this is a triangulation of a 3-dimensional ball.

This routine is based on isSphere(), which in turn combines Rubinstein's 3-sphere recognition algorithm with Jaco and Rubinstein's 0-efficiency prime decomposition algorithm.

Warning
The algorithms used in this routine rely on normal surface theory and so can be very slow for larger triangulations (although faster tests are used where possible). The routine knowsBall() can be called to see if this property is already known or if it happens to be very fast to calculate for this triangulation.
Returns
true if and only if this is a triangulation of a 3-dimensional ball.

◆ isClosed()

bool regina::Triangulation< 3 >::isClosed ( ) const
inlineinherited

Determines if this triangulation is closed.

This is the case if and only if it has no boundary. Note that ideal triangulations are not closed.

Returns
true if and only if this triangulation is closed.

◆ isConnected()

bool regina::detail::TriangulationBase< dim >::isConnected
inlineinherited

Determines if this triangulation is connected.

This routine returns false only if there is more than one connected component. In particular, it returns true for the empty triangulation.

Returns
true if and only if this triangulation is connected.

◆ isContainedIn()

std::optional< Isomorphism< dim > > regina::detail::TriangulationBase< dim >::isContainedIn ( const Triangulation< dim > &  other) const
inlineinherited

Determines if an isomorphic copy of this triangulation is contained within the given triangulation, possibly as a subcomplex of some larger component (or components).

Specifically, this routine determines if there is a boundary incomplete combinatorial isomorphism from this triangulation to other. Boundary incomplete isomorphisms are described in detail in the Isomorphism class notes.

In particular, note that facets of top-dimensional simplices that lie on the boundary of this triangulation need not correspond to boundary facets of other, and that other may contain more top-dimensional simplices than this triangulation.

If a boundary incomplete isomorphism is found, the details of this isomorphism are returned. Thus, to test whether an isomorphism exists, you can just call if (isContainedIn(other)).

If more than one such isomorphism exists, only one will be returned. For a routine that returns all such isomorphisms, see findAllSubcomplexesIn().

Warning
For large dimensions, this routine can become extremely slow: its running time includes a factor of (dim+1)!.
Parameters
otherthe triangulation in which to search for an isomorphic copy of this triangulation.
Returns
details of the isomorphism if such a copy is found, or no value otherwise.

◆ isEmpty()

bool regina::detail::TriangulationBase< dim >::isEmpty
inlineinherited

Determines whether this triangulation is empty.

An empty triangulation is one with no simplices at all.

Returns
true if and only if this triangulation is empty.

◆ isHaken()

bool regina::Triangulation< 3 >::isHaken ( ) const
inherited

Determines whether the underlying 3-manifold (which must be closed and orientable) is Haken.

In other words, this routine determines whether the underlying 3-manifold contains an embedded closed two-sided incompressible surface.

Currently Hakenness testing is available only for irreducible manifolds. This routine will first test whether the manifold is irreducible and, if it is not, will return false immediately.

Precondition
This triangulation is valid, closed, orientable and connected.
Warning
This routine could be very slow for larger triangulations.
Returns
true if and only if the underlying 3-manifold is irreducible and Haken.

◆ isIdeal()

bool regina::Triangulation< 3 >::isIdeal ( ) const
inlineinherited

Determines if this triangulation is ideal.

This is the case if and only if one of the vertex links is closed and not a 2-sphere. Note that the triangulation is not required to be valid.

Returns
true if and only if this triangulation is ideal.

◆ isIrreducible()

bool regina::Triangulation< 3 >::isIrreducible ( ) const
inherited

Determines whether the underlying 3-manifold (which must be closed) is irreducible.

In other words, this routine determines whether every embedded sphere in the underlying 3-manifold bounds a ball.

If the underlying 3-manifold is orientable, this routine will use fast crushing and branch-and-bound methods. If the underlying 3-manifold is non-orientable, it will use a (much slower) full enumeration of vertex normal surfaces.

Warning
The algorithms used in this routine rely on normal surface theory and might be slow for larger triangulations.
Precondition
This triangulation is valid, closed, orientable and connected.
Returns
true if and only if the underlying 3-manifold is irreducible.

◆ isIsomorphicTo()

std::optional< Isomorphism< dim > > regina::detail::TriangulationBase< dim >::isIsomorphicTo ( const Triangulation< dim > &  other) const
inlineinherited

Determines if this triangulation is combinatorially isomorphic to the given triangulation.

Two triangulations are isomorphic if and only it is possible to relabel their top-dimensional simplices and the (dim+1) vertices of each simplex in a way that makes the two triangulations combinatorially identical, as returned by isIdenticalTo().

Equivalently, two triangulations are isomorphic if and only if there is a one-to-one and onto boundary complete combinatorial isomorphism from this triangulation to other, as described in the Isomorphism class notes.

In particular, note that this triangulation and other must contain the same number of top-dimensional simplices for such an isomorphism to exist.

If the triangulations are isomorphic, then this routine returns one such boundary complete isomorphism (i.e., one such relabelling). Otherwise it returns no value. Thus, to test whether an isomorphism exists, you can just call if (isIsomorphicTo(other)).

There may be many such isomorphisms between the two triangulations. If you need to find all such isomorphisms, you may call findAllIsomorphisms() instead.

If you need to ensure that top-dimensional simplices are labelled the same in both triangulations (i.e., that the triangulations are related by the identity isomorphism), you should call the stricter test isIdenticalTo() instead.

Warning
For large dimensions, this routine can become extremely slow: its running time includes a factor of (dim+1)!.
Todo:
Optimise: Improve the complexity by choosing a simplex mapping from each component and following gluings to determine the others.
Parameters
otherthe triangulation to compare with this one.
Returns
details of the isomorphism if the two triangulations are combinatorially isomorphic, or no value otherwise.

◆ isNull()

bool regina::SnapPeaTriangulation::isNull ( ) const
inline

Determines whether this triangulation contains valid SnapPea data.

A null SnapPea triangulation can occur (for instance) when converting unusual types of Regina triangulation into SnapPea format, or when reading broken SnapPea data files. See the SnapPeaTriangulation class notes for details.

Returns
true if this is a null triangulation, or false if this triangulation contains valid SnapPea data.

◆ isOrdered()

bool regina::Triangulation< 3 >::isOrdered ( ) const
inherited

Determines if this triangulation is ordered; that is, if tetrahedron vertices are labelled so that all gluing permutations are order-preserving on the tetrahedron faces.

Equivalently, this tests whether the edges of the triangulation can all be oriented such that they induce a consistent ordering on the vertices of each tetrahedron.

Triangulations are not ordered by default, and indeed some cannot be ordered at all. The routine order() will attempt to relabel tetrahedron vertices to give an ordered triangulation.

Returns
true if and only if all gluing permutations are order preserving on the tetrahedron faces.
Author
Matthias Goerner

◆ isOrientable()

bool regina::detail::TriangulationBase< dim >::isOrientable
inlineinherited

Determines if this triangulation is orientable.

Returns
true if and only if this triangulation is orientable.

◆ isOriented()

bool regina::detail::TriangulationBase< dim >::isOriented
inherited

Determines if this triangulation is oriented; that is, if the vertices of its top-dimensional simplices are labelled in a way that preserves orientation across adjacent facets.

Specifically, this routine returns true if and only if every gluing permutation has negative sign.

Note that orientable triangulations are not always oriented by default. You can call orient() if you need the top-dimensional simplices to be oriented consistently as described above.

A non-orientable triangulation can never be oriented.

Returns
true if and only if all top-dimensional simplices are oriented consistently.
Author
Matthias Goerner

◆ isoSig()

Encoding::Signature regina::detail::TriangulationBase< dim >::isoSig ( ) const
inherited

Constructs the isomorphism signature of the given type for this triangulation.

Support for different types of signature is new to Regina 7.0 (see below for details); all isomorphism signatures created in Regina 6.0.1 or earlier are of the default type IsoSigClassic.

An isomorphism signature is a compact representation of a triangulation that uniquely determines the triangulation up to combinatorial isomorphism. That is, for any fixed signature type T, two triangulations of dimension dim are combinatorially isomorphic if and only if their isomorphism signatures of type T are the same.

The length of an isomorphism signature is proportional to n log n, where n is the number of top-dimenisonal simplices. The time required to construct it is worst-case O((dim!) n² log² n). Whilst this is fine for large triangulations, it becomes very slow for large dimensions; the main reason for introducing different signature types is that some alternative types can be much faster to compute in practice.

Whilst the format of an isomorphism signature bears some similarity to dehydration strings for 3-manifolds, they are more general: isomorphism signatures can be used with any triangulations, including closed, bounded and/or disconnected triangulations, as well as triangulations with many simplices. Note also that 3-manifold dehydration strings are not unique up to isomorphism (they depend on the particular labelling of tetrahedra).

The routine fromIsoSig() can be used to recover a triangulation from an isomorphism signature (only if the default encoding has been used, but it does not matter which signature type was used). The triangulation recovered might not be identical to the original, but it will be combinatorially isomorphic. If you need the precise relabelling, you can call isoSigDetail() instead.

Regina supports several different variants of isomorphism signatures, which are tailored to different computational needs; these are currently determined by the template parameters Type and Encoding:

  • The Type parameter identifies which signature type is to be constructed. Essentially, different signature types use different rules to determine which labelling of a triangulation is "canonical". The default type IsoSigClassic is slow (it never does better than the worst-case time described above); its main advantage is that it is consistent with the original implementation of isomorphism signatures in Regina 4.90.
  • The Encoding parameter controls how Regina encodes a canonical labelling into a final signature. The default encoding IsoSigPrintable returns a std::string consisting entirely of printable characters in the 7-bit ASCII range. Importantly, this default encoding is currently the only encoding from which Regina can reconstruct a triangulation from its isomorphism signature.

You may instead pass your own type and/or encoding parameters as template arguments. Currently this facility is for internal use only, and the requirements for type and encoding parameters may change in future versions of Regina. At present:

  • The Type parameter should be a class that is constructible from a componenent reference, and that offers the member functions simplex(), perm() and next(); see the implementation of IsoSigClassic for details.
  • The Encoding parameter should be a class that offers a Signature type alias, and static functions emptySig() and encode(). See the implementation of IsoSigPrintable for details.

For a full and precise description of the classic isomorphism signature format for 3-manifold triangulations, see Simplification paths in the Pachner graphs of closed orientable 3-manifold triangulations, Burton, 2011, arXiv:1110.6080. The format for other dimensions is essentially the same, but with minor dimension-specific adjustments.

Python
Although this is a templated function, all of the variants supplied with Regina are available to Python users. For the default type and encoding, you can simply call isoSig(). For other signature types, you should call the function as isoSig_Type, where the suffix Type is an abbreviated version of the Type template parameter; one such example is isoSig_EdgeDegrees (for the case where Type is the class IsoSigEdgeDegrees). Currently Regina only offers one encoding (the default), and so there are no suffixes for encodings.
Warning
Do not mix isomorphism signatures between dimensions! It is possible that the same string could corresponding to both a p-dimensional triangulation and a q-dimensional triangulation for different dimensions p and q.
Returns
the isomorphism signature of this triangulation.

◆ isoSigComponentSize()

static size_t regina::detail::TriangulationBase< dim >::isoSigComponentSize ( const std::string &  sig)
staticinherited

Deduces the number of top-dimensional simplices in a connected triangulation from its isomorphism signature.

See isoSig() for more information on isomorphism signatures. It will be assumed that the signature describes a triangulation of dimension dim.

Currently this routine only supports isomorphism signatures that were created with the default encoding (i.e., there was no Encoding template parameter passed to isoSig()).

If the signature describes a connected triangulation, this routine will simply return the size of that triangulation (e.g., the number of tetrahedra in the case dim = 3). You can also pass an isomorphism signature that describes a disconnected triangulation; however, this routine will only return the number of top-dimensional simplices in the first connected component. If you need the total size of a disconnected triangulation, you will need to reconstruct the full triangulation by calling fromIsoSig() instead.

This routine is very fast, since it only examines the first few characters of the isomorphism signature (in which the size of the first component is encoded). However, a side-effect of this is that it is possible to pass an invalid isomorphism signature and still receive a positive result. If you need to test whether a signature is valid or not, you must call fromIsoSig() instead, which will examine the entire signature in full.

Warning
Do not mix isomorphism signatures between dimensions! It is possible that the same string could corresponding to both a p-dimensional triangulation and a q-dimensional triangulation for different dimensions p and q.
Parameters
sigthe isomorphism signature of a dim-dimensional triangulation. Note that isomorphism signature are case-sensitive (unlike, for example, dehydration strings for 3-manifolds).
Returns
the number of top-dimensional simplices in the first connected component, or 0 if this could not be determined because the given string was not a valid isomorphism signature created using the default encoding.

◆ isoSigDetail()

std::pair< typename Encoding::Signature, Isomorphism< dim > > regina::detail::TriangulationBase< dim >::isoSigDetail ( ) const
inherited

Constructs the isomorphism signature for this triangulation, along with the relabelling that will occur when the triangulation is reconstructed from it.

Essentially, an isomorphism signature is a compact representation of a triangulation that uniquely determines the triangulation up to combinatorial isomorphism. See isoSig() for much more detail on isomorphism signatures as well as the support for different signature types and encodings.

As described in the isoSig() notes, you can call fromIsoSig() to recover a triangulation from an isomorphism signature (assuming the default encoding was used). Whilst the triangulation that is recovered will be combinatorially isomorphic to the original, it might not be identical. This routine returns not only the isomorphism signature, but also an isomorphism that describes the precise relationship between this triangulation and the reconstruction from fromIsoSig().

Specifically, if this routine returns the pair (sig, relabelling), this means that the triangulation reconstructed from fromIsoSig(sig) will be identical to relabelling(this).

Python
Although this is a templated function, all of the variants supplied with Regina are available to Python users. For the default type and encoding, you can simply call isoSigDetail(). For other signature types, you should call the function as isoSigDetail_Type, where the suffix Type is an abbreviated version of the Type template parameter; one such example is isoSigDetail_EdgeDegrees (for the case where Type is the class IsoSigEdgeDegrees). Currently Regina only offers one encoding (the default), and so there are no suffixes for encodings.
Precondition
This triangulation must be non-empty and connected. The facility to return a relabelling for disconnected triangulations may be added to Regina in a later release.
Exceptions
FailedPreconditionThis triangulation is either empty or disconnected.
Returns
a pair containing (i) the isomorphism signature of this triangulation, and (ii) the isomorphism between this triangulation and the triangulation that would be reconstructed from fromIsoSig().

◆ isReadOnlySnapshot()

bool regina::Snapshottable< Triangulation< dim > >::isReadOnlySnapshot ( ) const
inlineinherited

Determines if this object is a read-only deep copy that was created by a snapshot.

Recall that, if an image I of type T has a snapshot pointing to it, and if that image I is about to be modified or destroyed, then the snapshot will make an internal deep copy of I and refer to that instead.

The purpose of this routine is to identify whether the current object is such a deep copy. This may be important information, since a snapshot's deep copy is read-only: it must not be modified or destroyed by the outside world. (Of course the only way to access this deep copy is via const reference from the SnapshotRef dereference operators, but there are settings in which this constness is "forgotten", such as Regina's Python bindings.)

Returns
true if and only if this object is a deep copy that was taken by a Snapshot object of some original type T image.

◆ isSnapPea() [1/2]

SnapPeaTriangulation * regina::Triangulation< 3 >::isSnapPea ( )
inherited

Returns the SnapPea triangulation that holds this data, if there is one.

This routine essentially replaces a dynamic_cast, since the class Triangulation<3> is not polymorphic.

If this object in fact belongs to a SnapPeaTriangulation t (through its inherited Triangulation<3> interface), then this routine will return t. Otherwise it will return null.

Returns
the SnapPea triangulation that holds this data, or null if this data is not part of a SnapPea triangulation.

◆ isSnapPea() [2/2]

const SnapPeaTriangulation * regina::Triangulation< 3 >::isSnapPea ( ) const
inherited

Returns the SnapPea triangulation that holds this data, if there is one.

This routine essentially replaces a dynamic_cast, since the class Triangulation<3> is not polymorphic.

If this object in fact belongs to a SnapPeaTriangulation t (through its inherited Triangulation<3> interface), then this routine will return t. Otherwise it will return null.

Returns
the SnapPea triangulation that holds this data, or null if this data is not part of a SnapPea triangulation.

◆ isSolidTorus()

bool regina::Triangulation< 3 >::isSolidTorus ( ) const
inherited

Determines whether this is a triangulation of the solid torus; that is, the unknot complement.

This routine can be used on a triangulation with real boundary triangles, or on an ideal triangulation (in which case all ideal vertices will be assumed to be truncated).

Warning
The algorithms used in this routine rely on normal surface theory and so might be very slow for larger triangulations (although faster tests are used where possible). The routine knowsSolidTorus() can be called to see if this property is already known or if it happens to be very fast to calculate for this triangulation.
Returns
true if and only if this is either a real (compact) or ideal (non-compact) triangulation of the solid torus.

◆ isSphere()

bool regina::Triangulation< 3 >::isSphere ( ) const
inherited

Determines whether this is a triangulation of a 3-sphere.

This routine relies upon a combination of Rubinstein's 3-sphere recognition algorithm and Jaco and Rubinstein's 0-efficiency prime decomposition algorithm.

Warning
The algorithms used in this routine rely on normal surface theory and so can be very slow for larger triangulations (although faster tests are used where possible). The routine knowsSphere() can be called to see if this property is already known or if it happens to be very fast to calculate for this triangulation.
Returns
true if and only if this is a 3-sphere triangulation.

◆ isStandard()

bool regina::Triangulation< 3 >::isStandard ( ) const
inlineinherited

Determines if this triangulation is standard.

This is the case if and only if every vertex is standard. See Vertex<3>::isStandard() for further details.

Returns
true if and only if this triangulation is standard.

◆ isTxI()

bool regina::Triangulation< 3 >::isTxI ( ) const
inherited

Determines whether or not the underlying 3-manifold is the product of a torus with an interval.

This routine can be used on a triangulation with real boundary triangles, or ideal boundary components, or a mix of both. If there are any ideal vertices, they will be treated as though they were truncated.

The underlying algorithm is due to Robert C. Haraway, III; see https://journals.carleton.ca/jocg/index.php/jocg/article/view/433 for details.

Warning
This algorithm ultimately relies on isSolidTorus(), which might run slowly for large triangulations.
Returns
true if and only if this is a triangulation (either real, ideal or a combination) of the product of the torus with an interval.

◆ isValid()

bool regina::detail::TriangulationBase< dim >::isValid
inlineinherited

Determines if this triangulation is valid.

There are several conditions that might make a dim-dimensional triangulation invalid:

  1. if some face is identified with itself under a non-identity permutation (e.g., an edge is identified with itself in reverse, or a triangle is identified with itself under a rotation);
  2. if some subdim-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 this 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 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 a triangulation is invalid then you can call Face<dim, subdim>::isValid() to discover exactly which face(s) are responsible, and you can call Face<dim, subdim>::hasBadIdentification() and/or Face<dim, subdim>::hasBadLink() to discover exactly which conditions fail.

Note that all invalid vertices are considered to be on the boundary; see isBoundary() for details.

Returns
true if and only if this triangulation is valid.

◆ isZeroEfficient()

bool regina::Triangulation< 3 >::isZeroEfficient ( ) const
inherited

Determines if this triangulation is 0-efficient.

A triangulation is 0-efficient if its only normal spheres and discs are vertex linking, and if it has no 2-sphere boundary components.

Returns
true if and only if this triangulation is 0-efficient.

◆ kernelMessagesEnabled()

static bool regina::SnapPeaTriangulation::kernelMessagesEnabled ( )
static

Returns whether or not the SnapPea kernel writes diagnostic messages to standard output.

By default such diagnostic messages are disabled. To enable them, call enableKernelMessages().

This routine (which interacts with static data) is thread-safe.

Returns
true if and only if diagonstic messages are enabled.

◆ knowsBall()

bool regina::Triangulation< 3 >::knowsBall ( ) const
inherited

Is it already known (or trivial to determine) whether or not this is a triangulation of a 3-dimensional ball? See isBall() for further details.

If this property is indeed already known, future calls to isBall() will be very fast (simply returning the precalculated value).

If this property is not already known, this routine will nevertheless run some very fast preliminary tests to see if the answer is obviously no. If so, it will store false as the precalculated value for isBall() and this routine will return true.

Otherwise a call to isBall() may potentially require more significant work, and so this routine will return false.

Warning
This routine does not actually tell you whether this triangulation forms a ball; it merely tells you whether the answer has already been computed (or is very easily computed).
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsCompressingDisc()

bool regina::Triangulation< 3 >::knowsCompressingDisc ( ) const
inherited

Is it already known (or trivial to determine) whether or not the underlying 3-manifold contains a compressing disc? See hasCompressingDisc() for further details.

If this property is indeed already known, future calls to hasCompressingDisc() will be very fast (simply returning the precalculated value).

If this property is not already known, this routine will nevertheless run some very fast preliminary tests to see if the answer is obviously no. If so, it will store false as the precalculated value for hasCompressingDisc() and this routine will return true.

Otherwise a call to hasCompressingDisc() may potentially require more significant work, and so this routine will return false.

Warning
This routine does not actually tell you whether the underlying 3-manifold has a compressing disc; it merely tells you whether the answer has already been computed (or is very easily computed).
Precondition
This triangulation is valid and is not ideal.
The underlying 3-manifold is irreducible.
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsHaken()

bool regina::Triangulation< 3 >::knowsHaken ( ) const
inherited

Is it already known (or trivial to determine) whether or not the underlying 3-manifold is Haken? See isHaken() for further details.

If this property is indeed already known, future calls to isHaken() will be very fast (simply returning the precalculated value).

Warning
This routine does not actually tell you whether the underlying 3-manifold is Haken; it merely tells you whether the answer has already been computed (or is very easily computed).
Precondition
This triangulation is valid, closed, orientable and connected.
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsHandlebody()

bool regina::Triangulation< 3 >::knowsHandlebody ( ) const
inherited

Is it already known (or trivial to determine) whether or not this is a triangulation of an orientable handlebody? See recogniseHandlebody() for further details.

If this property is indeed already known, future calls to recogniseHandlebody() will be very fast (simply returning the precalculated value).

If this property is not already known, this routine will nevertheless run some very fast preliminary tests to see if the answer is obviously no. If so, it will store false as the precalculated value for recogniseHandlebody() and this routine will return true.

Otherwise a call to recogniseHandlebody() may potentially require more significant work, and so this routine will return false.

Warning
This routine does not actually tell you whether this triangulation forms an orientable handlebody; it merely tells you whether the answer has already been computed (or is very easily computed).
Returns
true if and only if this property is already known or trivial to calculate.
Author
Alex He

◆ knowsIrreducible()

bool regina::Triangulation< 3 >::knowsIrreducible ( ) const
inherited

Is it already known (or trivial to determine) whether or not the underlying 3-manifold is irreducible? See isIrreducible() for further details.

If this property is indeed already known, future calls to isIrreducible() will be very fast (simply returning the precalculated value).

Warning
This routine does not actually tell you whether the underlying 3-manifold is irreducible; it merely tells you whether the answer has already been computed (or is very easily computed).
Precondition
This triangulation is valid, closed, orientable and connected.
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsSolidTorus()

bool regina::Triangulation< 3 >::knowsSolidTorus ( ) const
inherited

Is it already known (or trivial to determine) whether or not this is a triangulation of a solid torus (that is, the unknot complement)? See isSolidTorus() for further details.

If this property is indeed already known, future calls to isSolidTorus() will be very fast (simply returning the precalculated value).

If this property is not already known, this routine will nevertheless run some very fast preliminary tests to see if the answer is obviously no. If so, it will store false as the precalculated value for isSolidTorus() and this routine will return true.

Otherwise a call to isSolidTorus() may potentially require more significant work, and so this routine will return false.

Warning
This routine does not actually tell you whether this triangulation forms a solid torus; it merely tells you whether the answer has already been computed (or is very easily computed).
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsSphere()

bool regina::Triangulation< 3 >::knowsSphere ( ) const
inherited

Is it already known (or trivial to determine) whether or not this is a triangulation of a 3-sphere? See isSphere() for further details.

If this property is indeed already known, future calls to isSphere() will be very fast (simply returning the precalculated value).

If this property is not already known, this routine will nevertheless run some very fast preliminary tests to see if the answer is obviously no. If so, it will store false as the precalculated value for isSphere() and this routine will return true.

Otherwise a call to isSphere() may potentially require more significant work, and so this routine will return false.

Warning
This routine does not actually tell you whether this triangulation forms a 3-sphere; it merely tells you whether the answer has already been computed (or is very easily computed).
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsStrictAngleStructure()

bool regina::Triangulation< 3 >::knowsStrictAngleStructure ( ) const
inherited

Is it already known (or trivial to determine) whether or not this triangulation supports a strict angle structure? See hasStrictAngleStructure() for further details.

If this property is indeed already known, future calls to strictAngleStructure() and hasStrictAngleStructure() will be very fast (simply returning the precalculated solution).

Warning
This routine does not actually tell you whether the triangulation supports a strict angle structure; it merely tells you whether the answer has already been computed (or is very easily computed).
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsTxI()

bool regina::Triangulation< 3 >::knowsTxI ( ) const
inherited

Is it already known (or trivial to determine) whether or not this is a triangulation of a the product of a torus with an interval? See isTxI() for further details.

If this property is indeed already known, future calls to isTxI() will be very fast (simply returning the precalculated value).

If this property is not already known, this routine will nevertheless run some very fast preliminary tests to see if the answer is obviously no. If so, it will store false as the precalculated value for isTxI() and this routine will return true.

Otherwise a call to isTxI() may potentially require more significant work, and so this routine will return false.

Warning
This routine does not actually tell you whether this triangulation forms the product of the torus with an interval; it merely tells you whether the answer has already been computed (or is very easily computed).
Returns
true if and only if this property is already known or trivial to calculate.

◆ knowsZeroEfficient()

bool regina::Triangulation< 3 >::knowsZeroEfficient ( ) const
inlineinherited

Is it already known whether or not this triangulation is 0-efficient? See isZeroEfficient() for further details.

If this property is already known, future calls to isZeroEfficient() will be very fast (simply returning the precalculated value).

Warning
This routine does not actually tell you whether this triangulation is 0-efficient; it merely tells you whether the answer has already been computed.
Returns
true if and only if this property is already known.

◆ layerOn()

Tetrahedron< 3 > * regina::Triangulation< 3 >::layerOn ( Edge< 3 > *  edge)
inherited

Performs a layering upon the given boundary edge of the triangulation.

See the Layering class notes for further details on what a layering entails.

The new tetrahedron will be returned, and the new boundary edge that it creates will be edge 5 (i.e., the edge joining vertices 2 and 3) of this tetrahedron.

Precondition
The given edge is a boundary edge of this triangulation, and the two boundary triangles on either side of it are distinct.
Parameters
edgethe boundary edge upon which to layer.
Returns
the new tetrahedron provided by the layering.

◆ linkingSurface()

template<int subdim>
std::pair< NormalSurface, bool > regina::Triangulation< 3 >::linkingSurface ( const Face< 3, subdim > &  face) const
inherited

Returns the link of the given face as a normal surface.

Constructing the link of a face begins with building the frontier of a regular neighbourhood of the face. If this is already a normal surface, then then link is called thin. Otherwise the usual normalisation steps are performed until the surface becomes normal; note that these normalisation steps could change the topology of the surface, and in some pathological cases could even reduce it to the empty surface.

Template Parameters
subdimthe dimension of the face to link; this must be between 0 and 2 inclusive.
Precondition
The given face is a face of this triangulation.
Returns
a pair (s, thin), where s is the face linking normal surface, and thin is true if and only if this link is thin (i.e., no additional normalisation steps were required).

◆ longitude()

Edge< 3 > * regina::Triangulation< 3 >::longitude ( )
inherited

Modifies a triangulated knot complement so that the algebraic longitude follows a single boundary edge, and returns this edge.

Assuming that this triangulation represents the complement of a knot in the 3-sphere, this routine:

  • identifies the algebraic longitude of the knot complement; that is, identifies the non-trivial simple closed curve on the boundary whose homology in the 3-manifold is trivial;
  • layers additional tetrahedra on the boundary if necessary so that this curve is represented by a single boundary edge;
  • returns that (possibly new) boundary edge.

Whilst this routine returns less information than meridianLongitude(), it (1) runs much faster since it is based on fast algebraic calculations, and (2) guarantees to terminate. In contrast, meridianLongitude() must repeatedly try to test for 3-spheres, and (as a result of only using fast 3-sphere recognition heuristics) does not guarantee to terminate.

At present this routine is fairly restrictive in what triangulations it can work with: it requires the triangulation to be one-vertex and have real (not ideal) boundary. These restrictions may be eased in future versions of Regina.

If the algebraic longitude is already represented by a single boundary edge, then it is guaranteed that this routine will not modify the triangulation, and will simply return this boundary edge.

Precondition
The underlying 3-manifold is known to be the complement of a knot in the 3-sphere.
This triangulation has precisely one vertex, and its (unique) boundary component is formed from two triangles.
Warning
This routine may modify the triangluation, as explained above, which will have the side-effect of invalidating any existing Vertex, Edge or Triangle references.
If you have an ideal triangulation of a knot complement, you must first run idealToFinite() and then simplify the resulting triangulation to have two boundary triangles.
Exceptions
FailedPreconditionThis triangulation is not a valid one-vertex orientable triangulation with homology Z, and with a two-triangle torus as its one and only boundary component. Note that this does not capture all of the preconditions for this routine, but it does capture those that are easy to test.
UnsolvedCaseAn integer overflow occurred during the computation.
Returns
the boundary edge representing the algebraic longitude of the knot (after this triangulation has been modified if necessary).

◆ longitudeCuts()

std::array< long, 3 > regina::Triangulation< 3 >::longitudeCuts ( ) const
inherited

Identifies the algebraic longitude as a curve on the boundary of a triangulated knot complement.

Specifically, assuming that this triangulation represents the complement of a knot in the 3-sphere, this routine identifies the non-trivial simple closed curve on the boundary whose homology in the 3-manifold is trivial.

The curve will be returned as a triple of integers, indicating how many times the longitude intersects each of the three boundary edges. It is always true that the largest of these three integers will be the sum of the other two.

At present this routine is fairly restrictive in what triangulations it can work with: it requires the triangulation to be one-vertex and have real (not ideal) boundary. These restrictions may be eased in future versions of Regina.

Precondition
The underlying 3-manifold is known to be the complement of a knot in the 3-sphere.
This triangulation has precisely one vertex, and its (unique) boundary component is formed from two triangles.
Warning
If you have an ideal triangulation of a knot complement, you must first run idealToFinite() and then simplify the resulting triangulation to have two boundary triangles.
Exceptions
FailedPreconditionThis triangulation is not a valid one-vertex orientable triangulation with homology Z, and with a two-triangle torus as its one and only boundary component. Note that this does not capture all of the preconditions for this routine, but it does capture those that are easy to test.
UnsolvedCaseAn integer overflow occurred during the computation.
Returns
a triple of non-negative integers indicating how many times the longitude intersects each of the three boundary edges. Specifically, if the returned tuple is t and the unique boundary component is bc, then for each k = 0,1,2, the element t[k] indicates the (absolute) number of times that the longitude intersects the edge bc->edge(k).

◆ makeCanonical()

bool regina::detail::TriangulationBase< dim >::makeCanonical ( )
inherited

Relabel the top-dimensional simplices and their vertices so that this triangulation is in canonical form.

This is essentially the lexicographically smallest labelling when the facet gluings are written out in order.

Two triangulations are isomorphic if and only if their canonical forms are identical.

The lexicographic ordering assumes that the facet gluings are written in order of simplex index and then facet number. Each gluing is written as the destination simplex index followed by the gluing permutation (which in turn is written as the images of 0,1,...,dim in order).

Precondition
This routine currently works only when the triangulation is connected. It may be extended to work with disconnected triangulations in later versions of Regina.
Returns
true if the triangulation was changed, or false if the triangulation was in canonical form to begin with.

◆ makeDoubleCover()

void regina::detail::TriangulationBase< dim >::makeDoubleCover
inherited

Converts this triangulation into its double cover.

Each orientable component will be duplicated, and each non-orientable component will be converted into its orientable double cover.

◆ markedHomology() [1/2]

MarkedAbelianGroup regina::detail::TriangulationBase< dim >::markedHomology
inlineinherited

Returns the kth homology group of this triangulation, without truncating ideal vertices, but with explicit coordinates that track the individual k-faces of this triangulation.

For C++ programmers who know subdim at compile time, you should use this template function markedHomology<subdim>(), which is slightly faster than passing subdim as an ordinary runtime argument to markedHomology(subdim).

See the non-templated markedHomology(int) for full details on what this function computes, some important caveats to be aware of, and how the group that it returns should be interpreted.

Precondition
This triangulation is valid and non-empty.
Exceptions
FailedPreconditionThis triangulation is empty or invalid.
Python
Not present. Instead use the variant markedHomology(k).
Template Parameters
kthe dimension of the homology group to compute; this must be between 1 and (dim-1) inclusive.
Returns
the kth homology group of the union of all simplices in this triangulation, as described above.

◆ markedHomology() [2/2]

MarkedAbelianGroup regina::detail::TriangulationBase< dim >::markedHomology ( int  k) const
inlineinherited

Returns the kth homology group of this triangulation, without truncating ideal vertices, but with explicit coordinates that track the individual k-faces of this triangulation, where the parameter k does not need to be known until runtime.

For C++ programmers who know k at compile time, you are better off using the template function markedHomology<k>() instead, which is slightly faster.

This is a specialised homology routine; you should only use it if you need to understand how individual k-faces (or chains of k-faces) appear within the homology group.

  • The major disadvantage of this routine is that it does not truncate ideal vertices. Instead it computes the homology of the union of all top-dimensional simplices, working directly with the boundary maps between (k+1)-faces, k-faces and (k-1)-faces of the triangulation. If your triangulation is ideal, then this routine will almost certainly not give the correct homology group for the underlying manifold. If, however, all of your vertex links are spheres or balls (i.e., the triangulation is closed or all of its boundary components are built from unglued (dim-1)-faces), then the homology of the manifold will be computed correctly.
  • The major advantage is that, instead of returning a simpler AbelianGroup, this routine returns a MarkedAbelianGroup. This allows you to track chains of individual k-faces of the triangulation as they appear within the homology group. Specifically, the chain complex cordinates with this MarkedAbelianGroup represent precisely the k-faces of the triangulation in the same order as they appear in the list faces<k>(), using the inherent orientation provided by Face<dim, k>.
Precondition
This triangulation is valid and non-empty.
Exceptions
FailedPreconditionThis triangulation is empty or invalid.
InvalidArgumentThe homology dimension k is outside the supported range (i.e., less than 1 or greater than or equal to dim).
Python
Like the C++ template function markedHomology<k>(), you can omit the homology dimension k; this will default to 1.
Parameters
kthe dimension of the homology group to compute; this must be between 1 and (dim-1) inclusive.
Returns
the kth homology group of the union of all simplices in this triangulation, as described above.

◆ maximalForestInBoundary()

std::set< Edge< 3 > * > regina::Triangulation< 3 >::maximalForestInBoundary ( ) const
inherited

Produces a maximal forest in the 1-skeleton of the triangulation boundary.

Note that the edge pointers returned will become invalid once the triangulation has changed.

Returns
a set containing the edges of the maximal forest.

◆ maximalForestInSkeleton()

std::set< Edge< 3 > * > regina::Triangulation< 3 >::maximalForestInSkeleton ( bool  canJoinBoundaries = true) const
inherited

Produces a maximal forest in the triangulation's 1-skeleton.

It can be specified whether or not different boundary components may be joined by the maximal forest.

An edge leading to an ideal vertex is still a candidate for inclusion in the maximal forest. For the purposes of this algorithm, any ideal vertex will be treated as any other vertex (and will still be considered part of its own boundary component).

Note that the edge pointers returned will become invalid once the triangulation has changed.

Parameters
canJoinBoundariestrue if and only if different boundary components are allowed to be joined by the maximal forest.
Returns
a set containing the edges of the maximal forest.

◆ meridian()

Edge< 3 > * regina::Triangulation< 3 >::meridian ( )
inherited

Modifies a triangulated knot complement so that the meridian follows a single boundary edge, and returns this edge.

Assuming that this triangulation represents the complement of a knot in the 3-sphere, this routine:

  • identifies the meridian of the knot complement;
  • layers additional tetrahedra on the boundary if necessary so that this curve is represented by a single boundary edge;
  • returns that (possibly new) boundary edge.

This routine uses fast heuristics to locate the meridian; as a result, it does not guarantee to terminate (but if you find a case where it does not, please let the Regina developers know!). If it does return then it guarantees that the result is correct.

This routine uses a similar algorithm to meridianLongitude(), with the same problem that it could be slow and might not terminate. However, meridian() has the advantage that it might produce a smaller triangulation, since there is no need to arrange for the longitude to be a boundary edge also.

At present this routine is fairly restrictive in what triangulations it can work with: it requires the triangulation to be one-vertex and have real (not ideal) boundary. These restrictions may be eased in future versions of Regina.

If the meridian is already represented by a single boundary edge, then it is guaranteed that, if this routine does terminate, it will not modify the triangulation, and will simply return this boundary edge.

Precondition
The underlying 3-manifold is known to be the complement of a knot in the 3-sphere.
This triangulation has precisely one vertex, and its (unique) boundary component is formed from two triangles.
Warning
This routine may modify the triangluation, as explained above, which will have the side-effect of invalidating any existing Vertex, Edge or Triangle references.
If you have an ideal triangulation of a knot complement, you must first run idealToFinite() and then simplify the resulting triangulation to have two boundary triangles.
Exceptions
FailedPreconditionThis triangulation is not a valid one-vertex orientable triangulation with homology Z, and with a two-triangle torus as its one and only boundary component. Note that this does not capture all of the preconditions for this routine, but it does capture those that are easy to test.
UnsolvedCaseAn integer overflow occurred during the computation.
Returns
the boundary edge representing the meridian (after this triangulation has been modified if necessary).

◆ meridianLongitude()

std::pair< Edge< 3 > *, Edge< 3 > * > regina::Triangulation< 3 >::meridianLongitude ( )
inherited

Modifies a triangulated knot complement so that the meridian and algebraic longitude each follow a single boundary edge, and returns these two edges.

Assuming that this triangulation represents the complement of a knot in the 3-sphere, this routine:

  • identifies the meridian of the knot complement, and also the algebraic longitude (i.e., the non-trivial simple closed curve on the boundary whose homology in the 3-manifold is trivial);
  • layers additional tetrahedra on the boundary if necessary so that each of these curves is represented by a single boundary edge;
  • returns these two (possibly new) boundary edges.

This routine uses fast heuristics to locate the meridian; as a result, it does not guarantee to terminate (but if you find a case where it does not, please let the Regina developers know!). If it does return then it guarantees that the result is correct.

Whilst this routine returns more information than longitude(), note that longitude() (1) runs much faster since it is based on fast algebraic calculations, and (2) guarantees to terminate.

At present this routine is fairly restrictive in what triangulations it can work with: it requires the triangulation to be one-vertex and have real (not ideal) boundary. These restrictions may be eased in future versions of Regina.

If the meridian and algebraic longitude are already both represented by single boundary edges, then it is guaranteed that, if this routine does terminate, it will not modify the triangulation, and will simply return these two boundary edges.

Precondition
The underlying 3-manifold is known to be the complement of a knot in the 3-sphere.
This triangulation has precisely one vertex, and its (unique) boundary component is formed from two triangles.
Warning
This routine may modify the triangluation, as explained above, which will have the side-effect of invalidating any existing Vertex, Edge or Triangle references.
If you have an ideal triangulation of a knot complement, you must first run idealToFinite() and then simplify the resulting triangulation to have two boundary triangles.
Exceptions
FailedPreconditionThis triangulation is not a valid one-vertex orientable triangulation with homology Z, and with a two-triangle torus as its one and only boundary component. Note that this does not capture all of the preconditions for this routine, but it does capture those that are easy to test.
UnsolvedCaseAn integer overflow occurred during the computation.
Returns
a pair (m, l), where m is the boundary edge representing the meridian and l is the boundary edge representing the algebraic longitude of the knot complement (after this triangulation has been modified if necessary).

◆ minImaginaryShape()

double regina::SnapPeaTriangulation::minImaginaryShape ( ) const

Returns the minimum imaginary part found amongst all tetrahedron shapes, with respect to the Dehn filled hyperbolic structure.

Tetrahedron shapes are given in rectangular form using a fixed coordinate system, as described in the documentation for shape().

If this is a null triangulation, or if solutionType() is no_solution or not_attempted (i.e., we did not or could not solve for a hyperbolic structure), then this routine will simply return zero.

SnapPy
This has no corresponding routine in SnapPy, though the information is easily acessible via Manifold.tetrahedra_shapes(part="rect").
Returns
the minimum imaginary part amongst all tetrahedron shapes.

◆ minimiseBoundary()

bool regina::Triangulation< 3 >::minimiseBoundary ( )
inherited

Ensures that the boundary contains the smallest possible number of triangles, potentially adding tetrahedra to do this.

This routine is for use with algorithms that require minimal boundaries (e.g., torus boundaries must contain exactly two triangles). As noted above, it may in fact increase the total number of tetrahedra in the triangulation (though the implementation does make efforts not to do this).

Once this routine is finished, every boundary component will have exactly one vertex, except for sphere and projective plane boundaries which will have exactly two triangles (but three and two vertices respectively).

The changes that this routine performs can always be expressed using only close book moves and/or layerings. In particular, this routine never creates new vertices, and it never creates a non-vertex-linking normal disc or sphere if there was not one before.

Although this routine only modifies real boundary components, it is fine if the triangulation also contains ideal boundary components (and these simply will be left alone). If the triangulation contains internal vertices, these will likewise be left untouched. If you wish to remove internal vertices also, then you should call minimiseVertices() instead.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Precondition
This triangulation is valid.
Exceptions
FailedPreconditionThis triangulation is not valid.
Returns
true if the triangulation was changed, or false if every boundary component was already minimal to begin with.

◆ minimiseVertices()

bool regina::Triangulation< 3 >::minimiseVertices ( )
inherited

Ensures that this triangulation contains the smallest possible number of vertices for the 3-manifold that it represents, potentially adding tetrahedra to do this.

This routine is for use with algorithms that require a minimal number of vertices (e.g., one-vertex triangulations of closed manifolds, or k-vertex triangulations of the complements of k-component links). As noted above, this routine may in fact increase the total number of tetrahedra in the triangulation (though the implementation does make efforts not to do this).

Once this routine is finished:

  • every real boundary component will have exactly one vertex, except for sphere and projective plane boundaries which will have three and two vertices respectively (i.e., the minimum possible);
  • for each component of the triangulation that contains one or more boundary components (either real and/or ideal), there will be no internal vertices at all;
  • for each component of the triangulation that has no boundary components (i.e., that represents a closed 3-manifold), there will be precisely one vertex.

The changes that this routine performs can always be expressed using only close book moves, layerings, collapse edge moves, and/or pinch edge moves. In particular, this routine never creates new vertices.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Precondition
This triangulation is valid.
Exceptions
FailedPreconditionThis triangulation is not valid.
Returns
true if the triangulation was changed, or false if the number of vertices was already minimal to begin with.

◆ minimizeBoundary()

bool regina::Triangulation< 3 >::minimizeBoundary ( )
inlineinherited

A deprecated synonym for minimiseBoundary().

This ensures that the boundary contains the smallest possible number of triangles, potentially adding tetrahedra to do this.

See minimiseBoundary() for further details.

Deprecated:
Regina uses British English throughout its API. This synonym was a special case where Regina used to offer both British and American alternatives, but this will be removed in a future release. See the page on spelling throughout Regina for further details.
Precondition
This triangulation is valid.
Returns
true if the triangulation was changed, or false if every boundary component was already minimal to begin with.

◆ minimizeVertices()

bool regina::Triangulation< 3 >::minimizeVertices ( )
inlineinherited

A deprecated synonym for minimiseVertices().

This ensures that the triangulation contains the smallest possible number of vertices, potentially adding tetrahedra to do this.

See minimiseVertices() for further details.

Deprecated:
Regina uses British English throughout its API. This synonym was a special case where Regina used to offer both British and American alternatives, but this will be removed in a future release. See the page on spelling throughout Regina for further details.
Precondition
This triangulation is valid.
Returns
true if the triangulation was changed, or false if the number of vertices was already minimal to begin with.

◆ moveContentsTo()

void regina::detail::TriangulationBase< dim >::moveContentsTo ( Triangulation< dim > &  dest)
inherited

Moves the contents of this triangulation into the given destination triangulation, without destroying any pre-existing contents.

All top-dimensional simplices that currently belong to dest will remain there (and will keep the same indices in dest). All top-dimensional simplices that belong to this triangulation will be moved into dest also (but in general their indices will change).

This triangulation will become empty as a result.

Any pointers or references to Simplex<dim> objects will remain valid.

If your intention is to replace the simplices in dest (i.e., you do not need to preserve the original contents), then consider using the move assignment operator instead (which is more streamlined and also moves across any cached properties from the source triangulation).

Precondition
dest is not this triangulation.
Parameters
destthe triangulation into which simplices should be moved.

◆ name()

std::string regina::SnapPeaTriangulation::name ( ) const

Returns SnapPea's internal name for this triangulation.

This is the manifold name stored in the SnapPea kernel, which is typically different from the packet label assigned by Regina.

If this is a null triangulation then the empty string will be returned.

SnapPy
In SnapPy, this routine corresponds to calling Manifold.name().
Returns
SnapPea's name for this triangulation.

◆ newSimplex() [1/2]

Simplex< dim > * regina::detail::TriangulationBase< dim >::newSimplex
inherited

Creates a new top-dimensional simplex and adds it to this triangulation.

The new simplex will have an empty description. All (dim+1) facets of the new simplex will be boundary facets.

The new simplex will become the last simplex in this triangulation; that is, it will have index size()-1.

Returns
the new simplex.

◆ newSimplex() [2/2]

Simplex< dim > * regina::detail::TriangulationBase< dim >::newSimplex ( const std::string &  desc)
inherited

Creates a new top-dimensional simplex with the given description and adds it to this triangulation.

All (dim+1) facets of the new simplex will be boundary facets.

Descriptions are optional, may have any format, and may be empty. How descriptions are used is entirely up to the user.

The new simplex will become the last simplex in this triangulation; that is, it will have index size()-1.

Parameters
descthe description to give to the new simplex.
Returns
the new simplex.

◆ newSimplices() [1/2]

std::array< Simplex< dim > *, k > regina::detail::TriangulationBase< dim >::newSimplices
inherited

Creates k new top-dimensional simplices, adds them to this triangulation, and returns them in a std::array.

The main purpose of this routine is to support structured binding; for example:

auto [r, s, t] = ans.newSimplices<3>();
r->join(0, s, {1, 2, 3, 0});
...

All new simplices will have empty descriptions, and all facets of each new simplex will be boundary facets.

The new simplices will become the last k simplices in this triangulation. Specifically, if the return value is the array ret, then each simplex ret[i] will have index size()-k+i in the overall triangulation.

Python
For Python users, the two variants of newSimplices() are essentially merged: the argument k is passed as an ordinary runtime argument, and the new top-dimensional simplices will be returned in a Python tuple of size k.
Template Parameters
kthe number of new top-dimensional simplices to add; this must be non-negative.
Returns
an array containing all of the new simplices, in the order in which they were added.

◆ newSimplices() [2/2]

void regina::detail::TriangulationBase< dim >::newSimplices ( size_t  k)
inherited

Creates k new top-dimensional simplices and adds them to this triangulation.

This is similar to the templated routine newSimplices<k>(), but with two key differences:

  • This routine has the disadvantage that it does not return the new top-dimensional simplices, which means you cannot use it with structured binding.
  • This routine has the advantage that k does not need to be known until runtime, which means this routine is accessible to Python users.

All new simplices will have empty descriptions, and all facets of each new simplex will be boundary facets.

The new simplices will become the last k simplices in this triangulation.

Python
For Python users, the two variants of newSimplices() are essentially merged: the argument k is passed as an ordinary runtime argument, and the new top-dimensional simplices will be returned in a Python tuple of size k.
Parameters
kthe number of new top-dimensional simplices to add; this must be non-negative.

◆ newTetrahedra() [1/2]

template<int k>
std::array< Tetrahedron< 3 > *, k > regina::Triangulation< 3 >::newTetrahedra
inlineinherited

A dimension-specific alias for newSimplices().

See newSimplices() for further information.

◆ newTetrahedra() [2/2]

void regina::Triangulation< 3 >::newTetrahedra ( size_t  k)
inlineinherited

A dimension-specific alias for newSimplices().

See newSimplices() for further information.

◆ newTetrahedron() [1/2]

Tetrahedron< 3 > * regina::Triangulation< 3 >::newTetrahedron ( )
inlineinherited

A dimension-specific alias for newSimplex().

See newSimplex() for further information.

◆ newTetrahedron() [2/2]

Tetrahedron< 3 > * regina::Triangulation< 3 >::newTetrahedron ( const std::string &  desc)
inlineinherited

A dimension-specific alias for newSimplex().

See newSimplex() for further information.

◆ niceTreeDecomposition()

const TreeDecomposition & regina::Triangulation< 3 >::niceTreeDecomposition ( ) const
inlineinherited

Returns a nice tree decomposition of the face pairing graph of this triangulation.

This can (for example) be used in implementing algorithms that are fixed-parameter tractable in the treewidth of the face pairing graph.

See TreeDecomposition for further details on tree decompositions, and see TreeDecomposition::makeNice() for details on what it means to be a nice tree decomposition.

This routine is fast: it will use a greedy algorithm to find a tree decomposition with (hopefully) small width, but with no guarantees that the width of this tree decomposition is the smallest possible.

The tree decomposition will be cached, so that if this routine is called a second time (and the underlying triangulation has not been changed) then the same tree decomposition will be returned immediately.

Returns
a nice tree decomposition of the face pairing graph of this triangulation.

◆ nonTrivialSphereOrDisc()

std::optional< NormalSurface > regina::Triangulation< 3 >::nonTrivialSphereOrDisc ( ) const
inherited

Searches for a non-vertex-linking normal sphere or disc within this triangulation.

If such a surface exists within this triangulation, this routine is guaranteed to find one.

Returns
a non-vertex-linking normal sphere or disc, or no value if none exists.

◆ nullify()

void regina::SnapPeaTriangulation::nullify ( )

Sets this to be a null SnapPea triangulation.

◆ octagonalAlmostNormalSphere()

std::optional< NormalSurface > regina::Triangulation< 3 >::octagonalAlmostNormalSphere ( ) const
inherited

Searches for an octagonal almost normal 2-sphere within this triangulation.

If such a surface exists, this routine is guaranteed to find one.

Precondition
This triangulation is valid, closed, orientable, connected, and 0-efficient. These preconditions are almost certainly more restrictive than they need to be, but we stay safe for now.
Returns
an octagonal almost normal 2-sphere, or no value if none exists.

◆ openBook()

bool regina::Triangulation< 3 >::openBook ( Triangle< 3 > *  t,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a book opening move about the given triangle.

This involves taking a triangle meeting the boundary along two edges, and ungluing it to create two new boundary triangles (thus exposing the tetrahedra it initially joined). This move is the inverse of the closeBook() move, and is used to open the way for new shellBoundary() moves.

This move can be done if:

  • the triangle meets the boundary in precisely two edges (and thus also joins two tetrahedra);
  • the vertex between these two edges is a standard boundary vertex (its link is a disc);
  • the remaining edge of the triangle (which is internal to the triangulation) is valid.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this operation will (trivially) preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument f) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given triangle is a triangle of this triangulation.
Parameters
tthe triangle about which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ operator!=() [1/2]

bool regina::SnapPeaTriangulation::operator!= ( const SnapPeaTriangulation other) const
inline

Determines whether this and the given SnapPea triangulation are, at some elementary level, different.

This routine checks only those things that can be checked exactly, without going through the SnapPea kernel and without requiring floating-point comparisons.

In particular, it does check whether:

  • the tetrahedron numbers, vertex labels and gluings are the same in both triangulations (i.e., the tests performed by Regina's native Triangulation<3> comparison operators);
  • the same numbered cusps correspond to the same numbered vertices of the triangulation;
  • each pair of corresponding cusps are either both not filled, or both filled using the same coefficients.

It does not check wehether corresponding tetrahedron shapes are the same, or if the volumes are "sufficiently close", or even whether the SnapPea kernel has produced the same solution type for both triangulations.

Two null SnapPea triangulations will be considered equal.

Parameters
otherthe SnapPea triangulation to compare with this.
Returns
true if and only this and the given triangulation are different, according to the criteria described above.

◆ operator!=() [2/2]

bool regina::detail::TriangulationBase< dim >::operator!= ( const Triangulation< dim > &  other) const
inlineinherited

Determines if this triangulation is not combinatorially identical to the given triangulation.

Here "identical" means that the triangulations have the same number of top-dimensional simplices, with gluings between the same pairs of numbered simplices using the same gluing permutations. In other words, "identical" means that the triangulations are isomorphic via the identity isomorphism.

For the less strict notion of isomorphic triangulations, which allows relabelling of the top-dimensional simplices and their vertices, see isIsomorphicTo() instead.

This test does not examine the textual simplex descriptions, as seen in Simplex<dim>::description(); these may still differ. It also does not test whether lower-dimensional faces are numbered identically (vertices, edges and so on); this routine is only concerned with top-dimensional simplices.

(At the time of writing, two identical triangulations will always number their lower-dimensional faces in the same way. However, it is conceivable that in future versions of Regina there may be situations in which identical triangulations can acquire different numberings for vertices, edges, and so on.)

Parameters
otherthe triangulation to compare with this.
Returns
true if and only if the two triangulations are not combinatorially identical.

◆ operator=() [1/2]

SnapPeaTriangulation & regina::SnapPeaTriangulation::operator= ( const SnapPeaTriangulation src)

Sets this to be a (deep) copy of the given SnapPea triangulation.

Warning
If you wish to copy the contents of one SnapPea triangulation into another, you must cast both to SnapPeaTriangulation before calling the assignment operator. If either argument is presented as the parent class Triangulation<3>, then the Triangulation<3> assignment operator will be called instead; the result will be that (just like when you call any of the Triangulation<3> edit routines) this SnapPea triangulation will be reset to a null triangulation. See the SnapPeaTriangulation class notes for further discussion.
Returns
a reference to this triangulation.

◆ operator=() [2/2]

SnapPeaTriangulation & regina::SnapPeaTriangulation::operator= ( SnapPeaTriangulation &&  src)

Moves the contents of the given triangulation into this triangulation.

This is much faster than copy assignment, but is still linear time. This is because every tetrahedron must be adjusted to point back to this triangulation instead of src.

All tetrahedra, cusps and skeletal objects (faces, components and boundary components) that belong to src will be moved into this triangulation, and so any pointers or references to Tetrahedron<3>, Cusp, Face<3, subdim>, Component<3> or BoundaryComponent<3> objects will remain valid. Likewise, all cached properties will be moved into this triangulation.

The triangulation that is passed (src) will no longer be usable.

Warning
If you wish to move the contents of one SnapPea triangulation into another, you must cast both to SnapPeaTriangulation before calling the assignment operator. If either argument is presented as the parent class Triangulation<3>, then the Triangulation<3> assignment operator will be called instead; the result will be that (just like when you call any of the Triangulation<3> edit routines) this SnapPea triangulation will be reset to a null triangulation. See the SnapPeaTriangulation class notes for further discussion.
Note
This operator is not marked noexcept, since it fires change events on this triangulation which may in turn call arbitrary code via any registered packet listeners. It deliberately does not fire change events on src, since it assumes that src is about to be destroyed (which will fire a destruction event instead).
Parameters
srcthe triangulation to move.
Returns
a reference to this triangulation.

◆ operator==() [1/2]

bool regina::SnapPeaTriangulation::operator== ( const SnapPeaTriangulation other) const

Determines whether this and the given SnapPea triangulation are, at some elementary level, the same.

This routine checks only those things that can be checked exactly, without going through the SnapPea kernel and without requiring floating-point comparisons.

In particular, it does check whether:

  • the tetrahedron numbers, vertex labels and gluings are the same in both triangulations (i.e., the tests performed by Regina's native Triangulation<3> comparison operators);
  • the same numbered cusps correspond to the same numbered vertices of the triangulation;
  • each pair of corresponding cusps are either both not filled, or both filled using the same coefficients.

It does not check wehether corresponding tetrahedron shapes are the same, or if the volumes are "sufficiently close", or even whether the SnapPea kernel has produced the same solution type for both triangulations.

Two null SnapPea triangulations will be considered equal.

Parameters
otherthe SnapPea triangulation to compare with this.
Returns
true if and only this and the given triangulation are the same, according to the criteria described above.

◆ operator==() [2/2]

bool regina::detail::TriangulationBase< dim >::operator== ( const Triangulation< dim > &  other) const
inherited

Determines if this triangulation is combinatorially identical to the given triangulation.

Here "identical" means that the triangulations have the same number of top-dimensional simplices, with gluings between the same pairs of numbered simplices using the same gluing permutations. In other words, "identical" means that the triangulations are isomorphic via the identity isomorphism.

For the less strict notion of isomorphic triangulations, which allows relabelling of the top-dimensional simplices and their vertices, see isIsomorphicTo() instead.

This test does not examine the textual simplex descriptions, as seen in Simplex<dim>::description(); these may still differ. It also does not test whether lower-dimensional faces are numbered identically (vertices, edges and so on); this routine is only concerned with top-dimensional simplices.

(At the time of writing, two identical triangulations will always number their lower-dimensional faces in the same way. However, it is conceivable that in future versions of Regina there may be situations in which identical triangulations can acquire different numberings for vertices, edges, and so on.)

In Regina 6.0.1 and earlier, this comparison was called isIdenticalTo().

Parameters
otherthe triangulation to compare with this.
Returns
true if and only if the two triangulations are combinatorially identical.

◆ order()

bool regina::Triangulation< 3 >::order ( bool  forceOriented = false)
inherited

Relabels tetrahedron vertices in this triangulation to give an ordered triangulation, if possible.

To be an ordered triangulation, all face gluings (when restricted to the tetrahedron face) must be order preserving. In other words, it must be possible to orient all edges of the triangulation in such a fashion that they are consistent with the ordering of the vertices in each tetrahedron.

If it is possible to order this triangulation, the vertices of each tetrahedron will be relabelled accordingly and this routine will return true. Otherwise, this routine will return false and the triangulation will not be changed.

Warning
This routine may be slow, since it backtracks through all possible edge orientations until a consistent one has been found.
Parameters
forceOrientedtrue if the triangulation must be both ordered and oriented, in which case this routine will return false if the triangulation cannot be oriented and ordered at the same time. See orient() for further details.
Returns
true if the triangulation has been successfully ordered as described above, or false if not.
Author
Matthias Goerner

◆ orient()

void regina::detail::TriangulationBase< dim >::orient
inherited

Relabels the vertices of top-dimensional simplices in this triangulation so that all simplices are oriented consistently, if possible.

This routine works by flipping vertices (dim - 1) and dim of each top-dimensional simplices that has negative orientation. The result will be a triangulation where the top-dimensional simplices have their vertices labelled in a way that preserves orientation across adjacent facets. In particular, every gluing permutation will have negative sign.

If this triangulation includes both orientable and non-orientable components, the orientable components will be oriented as described above and the non-orientable components will be left untouched.

◆ pachner()

bool regina::detail::TriangulationBase< dim >::pachner ( Face< dim, k > *  f,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a (dim + 1 - k)-(k + 1) Pachner move about the given k-face.

This involves replacing the (dim + 1 - k) top-dimensional simplices meeting that k-face with (k + 1) new top-dimensional simplices joined along a new internal (dim - k)-face. This can be done iff (i) the given k-face is valid and non-boundary; (ii) the (dim + 1 - k) top-dimensional simplices that contain it are distinct; and (iii) these simplices are joined in such a way that the link of the given k-face is the standard triangulation of the (dim - 1 - k)-sphere as the boundary of a (dim - k)-simplex.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal. In In the special case k = dim, the move is always legal and so the check argument will simply be ignored.

Note that after performing this move, all skeletal objects (facets, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument v) can no longer be used.

If this triangulation is currently oriented, then this Pachner move will label the new top-dimensional simplices in a way that preserves the orientation.

See the page on Pachner moves on triangulations for definitions and terminology relating to Pachner moves. After the move, the new belt face will be formed from vertices 0,1,...,(dim - k) of simplices().back().

Warning
For the case k = dim in Regina's standard dimensions, the labelling of the belt face has changed as of Regina 5.96 (the first prerelease for Regina 6.0). In versions 5.1 and earlier, the belt face was simplices().back()->vertex(dim), and as of version 5.96 it is now simplices().back()->vertex(0).
Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given k-face is a k-face of this triangulation.
Parameters
fthe k-face about which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.
Template Parameters
kthe dimension of the given face. This must be between 0 and (dim) inclusive. You can still perform a Pachner move about a 0-face dim-face, but these moves use specialised implementations (as opposed to this generic template implementation).

◆ packet() [1/4]

std::shared_ptr< PacketOf< SnapPeaTriangulation > > regina::PacketData< SnapPeaTriangulation >::packet ( )
inlineinherited

Returns the packet that holds this data, if there is one.

If this object is being held by a packet p of type PacketOf<Held>, then that packet p will be returned. Otherwise, if this is a "standalone" object of type Held, then this routine will return null.

There is a special case when dealing with a packet q that holds a SnapPea triangulation. Here q is of type PacketOf<SnapPeaTriangulation>, and it holds a Triangulation<3> "indirectly" in the sense that Packetof<SnapPeaTriangulation> derives from SnapPeaTriangulation, which in turn derives from Triangulation<3>. In this scenario:

The function inAnyPacket() is specific to Triangulation<3>, and is not offered for other Held types.

Returns
the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ packet() [2/4]

std::shared_ptr< PacketOf< Triangulation< dim > > > regina::PacketData< Triangulation< dim > >::packet ( )
inlineinherited

Returns the packet that holds this data, if there is one.

If this object is being held by a packet p of type PacketOf<Held>, then that packet p will be returned. Otherwise, if this is a "standalone" object of type Held, then this routine will return null.

There is a special case when dealing with a packet q that holds a SnapPea triangulation. Here q is of type PacketOf<SnapPeaTriangulation>, and it holds a Triangulation<3> "indirectly" in the sense that Packetof<SnapPeaTriangulation> derives from SnapPeaTriangulation, which in turn derives from Triangulation<3>. In this scenario:

The function inAnyPacket() is specific to Triangulation<3>, and is not offered for other Held types.

Returns
the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ packet() [3/4]

std::shared_ptr< const PacketOf< SnapPeaTriangulation > > regina::PacketData< SnapPeaTriangulation >::packet ( ) const
inlineinherited

Returns the packet that holds this data, if there is one.

See the non-const version of this function for further details, and in particular for how this functions operations in the special case of a packet that holds a SnapPea triangulation.

Returns
the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ packet() [4/4]

std::shared_ptr< const PacketOf< Triangulation< dim > > > regina::PacketData< Triangulation< dim > >::packet ( ) const
inlineinherited

Returns the packet that holds this data, if there is one.

See the non-const version of this function for further details, and in particular for how this functions operations in the special case of a packet that holds a SnapPea triangulation.

Returns
the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ pairing()

FacetPairing< dim > regina::detail::TriangulationBase< dim >::pairing
inlineinherited

Returns the dual graph of this triangulation, expressed as a facet pairing.

Calling tri.pairing() is equivalent to calling FacetPairing<dim>(tri).

Precondition
This triangulation is not empty.
Returns
the dual graph of this triangulation.

◆ pentachora()

auto regina::detail::TriangulationBase< dim >::pentachora
inlineinherited

A dimension-specific alias for faces<4>(), or an alias for simplices() in dimension dim = 4.

This alias is available for dimensions dim ≥ 4.

See faces() for further information.

◆ pentachoron() [1/2]

Face< dim, 4 > * regina::detail::TriangulationBase< dim >::pentachoron ( size_t  index)
inlineinherited

A dimension-specific alias for face<4>(), or an alias for simplex() in dimension dim = 4.

This alias is available for dimensions dim ≥ 4.

See face() for further information.

◆ pentachoron() [2/2]

auto regina::detail::TriangulationBase< dim >::pentachoron ( size_t  index) const
inlineinherited

A dimension-specific alias for face<4>(), or an alias for simplex() in dimension dim = 4.

This alias is available for dimensions dim ≥ 4. It returns a const pentachoron pointer in dimension dim = 4, and a non-const pentachoron pointer in all higher dimensions.

See face() for further information.

◆ pinchEdge()

void regina::Triangulation< 3 >::pinchEdge ( Edge< 3 > *  e)
inherited

Pinches an internal edge to a point.

Topologically, this collapses the edge to a point with no further side-effects, and it increases the number of tetrahedra by two.

This operation can be performed on any internal edge, without further constraints. Two particularly useful settings are:

  • If the edge joins an internal vertex with some different vertex (which may be internal, boundary, ideal or invalid), then this move does not change the topology of the manifold at all, and it reduces the total number of vertices by one. In this sense, it acts as an alternative to collapseEdge(), and unlike collapseEdge() it can always be performed.
  • If the edge runs from an internal vertex back to itself, then this move effectively drills out the edge, leaving an ideal torus or Klein bottle boundary component.

We do not allow e to lie entirely on the triangulation boundary, because the implementation actually collapses an internal curve parallel to e, not the edge e itself (and so if e is a boundary edge then the topological effect would not be as intended). We do allow e to be an internal edge with both endpoints on the boundary, but note that in this case the resulting topological operation would render the triangulation invalid.

If you are trying to reduce the number of vertices without changing the topology, and if e is an edge connecting an internal vertex with some different vertex, then either collapseEdge() or pinchEdge() may be more appropriate for your situation (though you may find it easier just to call minimiseVertices() instead).

  • The advantage of collapseEdge() is that it decreases the number of tetrahedra, whereas pinchEdge() increases this number (but only by two).
  • The disadvantages of collapseEdge() are that it cannot always be performed, and its validity tests are expensive; pinchEdge() on the other hand can always be used for edges e of the type described above.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument e) can no longer be used.

Precondition
The given edge is an internal edge of this triangulation (that is, e does not lie entirely within the boundary).
Parameters
ethe edge to collapse.

◆ protoCanonise()

SnapPeaTriangulation regina::SnapPeaTriangulation::protoCanonise ( ) const

Constructs the canonical cell decomposition, using an arbitrary retriangulation if this decomposition contains non-tetrahedron cells.

Any fillings on the cusps of this SnapPea triangulation will be ignored for the purposes of canonisation, though they will be copied over to the new SnapPea triangulation that is returned.

The canonical cell decomposition is the one described in "Convex hulls and isometries of cusped hyperbolic 3-manifolds", Jeffrey R. Weeks, Topology Appl. 52 (1993), 127-149.

If the canonical cell decomposition is already a triangulation then we leave it untouched, and otherwise we triangulate it arbitrarily. Either way, we preserve the hyperbolic structure.

If you need a canonical triangulation (as opposed to an arbitrary retriangulation), then you should call canonise() instead.

SnapPea is not always able to triangulate the canonical cell decomposition: if it fails then then this routine will throw an exception (see below for details).

SnapPy
The function canonise() means different things for SnapPy versus the SnapPea kernel. Here Regina follows the naming convention used in the SnapPea kernel. Specifically: Regina's routine SnapPeaTriangulation::protoCanonise() corresponds to SnapPy's Manifold.canonize() and the SnapPea kernel's proto_canonize(manifold). Regina's routine SnapPeaTriangulation::canonise() corresponds to the SnapPea kernel's canonize(manifold), and is not available through SnapPy at all.
Warning
The SnapPea kernel does not always compute the canonical cell decomposition correctly. Sometimes it gives the wrong answer, although in such a case it still guarantees that the manifold it does return is homeomorphic to the original. Sometimes it gives no answer at all, in which case this routine will throw an exception (see below).
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
UnsolvedCaseThe SnapPea kernel was unable to triangulate the canonical cell decomposition.
Returns
a triangulation of the canonical cell decomposition.

◆ protoCanonize()

SnapPeaTriangulation regina::SnapPeaTriangulation::protoCanonize ( ) const
inline

An alias for protoCanonise(), which constructs the canonical cell decomposition using an arbitrary retriangulation if necessary.

See protoCanonise() for further details.

This alias is provided as "glue" between the British spelling used throughout Regina and the American spelling used throughout the SnapPea kernel.

Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
UnsolvedCaseThe SnapPea kernel was unable to triangulate the canonical cell decomposition.
Returns
a triangulation of the canonical cell decomposition.

◆ puncture()

void regina::Triangulation< 3 >::puncture ( Tetrahedron< 3 > *  tet = nullptr)
inherited

Punctures this manifold by removing a 3-ball from the interior of the given tetrahedron.

If no tetrahedron is specified (i.e., the tetrahedron pointer is null), then the puncture will be taken from the interior of tetrahedron 0.

The puncture will not meet the boundary of the tetrahedron, so nothing will go wrong if the tetrahedron has boundary facets and/or ideal vertices. A side-effect of this, however, is that the resulting triangulation will contain additional vertices, and will almost certainly be far from minimal. It is highly recommended that you run intelligentSimplify() if you do not need to preserve the combinatorial structure of the new triangulation.

The puncturing is done by subdividing the original tetrahedron. The new tetrahedra will have orientations consistent with the original tetrahedra, so if the triangulation was originally oriented then it will also be oriented after this routine has been called. See isOriented() for further details on oriented triangulations.

The new sphere boundary will be formed from two triangles; specifically, face 0 of the last and second-last tetrahedra of the triangulation. These two triangles will be joined so that vertex 1 of each tetrahedron coincides, and vertices 2,3 of one map to vertices 3,2 of the other.

Precondition
This triangulation is non-empty, and if tet is non-null then it is in fact a tetrahedron of this triangulation.
Parameters
tetthe tetrahedron inside which the puncture will be taken. This may be null (the default), in which case the first tetrahedron will be used.

◆ randomise()

void regina::SnapPeaTriangulation::randomise ( )

Asks SnapPea to randomly retriangulate this manifold, using local moves that preserve the topology.

This can help when SnapPea is having difficulty finding a hyperbolic structure.

This routine uses SnapPea's own internal retriangulation code.

After randomising, this routine will immediately ask SnapPea to try to find a hyperbolic structure.

If this is a null SnapPea triangulation, this routine does nothing.

SnapPy
In SnapPy, this routine corresponds to calling Manifold.randomize().

◆ randomize()

void regina::SnapPeaTriangulation::randomize ( )
inline

An alias for randomise(), which asks SnapPea to randomly retriangulate this manifold.

See randomise() for further details.

This alias is provided as "glue" between the British spelling used throughout Regina and the American spelling used throughout the SnapPea kernel.

◆ recogniseHandlebody()

ssize_t regina::Triangulation< 3 >::recogniseHandlebody ( ) const
inherited

Determines whether this is a triangulation of an orientable handlebody, and if so, which genus.

Specifically, this routine returns the genus if this is indeed a handlebody, and returns -1 otherwise. This routine can be used on a triangulation with real boundary triangles, or on an ideal triangulation (in which case all ideal vertices will be assumed to be truncated).

Warning
The algorithms used in this routine rely on normal surface theory and so might be very slow for larger triangulations (although faster tests are used where possible). The routine knowsHandlebody() can be called to see if this property is already known or if it happens to be very fast to calculate for this triangulation.
Returns
the genus if this is a triangulation of an orientable handlebody, or -1 otherwise.
Author
Alex He

◆ recogniser() [1/2]

std::string regina::Triangulation< 3 >::recogniser ( ) const
inherited

Returns a string that expresses this triangulation in Matveev's 3-manifold recogniser format.

Recogniser exports are currently not available for triangulations that are invalid or contain boundary triangles. If either of these conditions is true then this routine will throw an exception.

Exceptions
NotImplementedThis triangulation is either invalid or has boundary triangles.
Returns
a string containing the 3-manifold recogniser data.

◆ recogniser() [2/2]

void regina::Triangulation< 3 >::recogniser ( std::ostream &  out) const
inherited

Writes a string expressing this triangulation in Matveev's 3-manifold recogniser format to the given output stream.

Recogniser exports are currently not available for triangulations that are invalid or contain boundary triangles. If either of these conditions is true then this routine will throw an exception.

Exceptions
NotImplementedThis triangulation is either invalid or has boundary triangles.
Python
Not present. Instead call recogniser() with no arguments, which returns this data as a string.
Parameters
outthe output stream to which the recogniser data file will be written.

◆ recognizer() [1/2]

std::string regina::Triangulation< 3 >::recognizer ( ) const
inherited

A synonym for recogniser().

This returns a string that expresses this triangulation in Matveev's 3-manifold recogniser format.

Recogniser exports are currently not available for triangulations that are invalid or contain boundary triangles. If either of these conditions is true then this routine will throw an exception.

Exceptions
NotImplementedThis triangulation is either invalid or has boundary triangles.
Returns
a string containing the 3-manifold recogniser data.

◆ recognizer() [2/2]

void regina::Triangulation< 3 >::recognizer ( std::ostream &  out) const
inlineinherited

A synonym for recognizer(std::ostream&).

This writes a string expressing this triangulation in Matveev's 3-manifold recogniser format to the given output stream.

Recogniser exports are currently not available for triangulations that are invalid or contain boundary triangles. If either of these conditions is true then this routine will throw an exception.

Exceptions
NotImplementedThis triangulation is either invalid or has boundary triangles.
Python
Not present. Instead call recognizer() with no arguments, which returns this data as a string.
Parameters
outthe output stream to which the recogniser data file will be written.

◆ reflect()

void regina::detail::TriangulationBase< dim >::reflect
inherited

Relabels the vertices of top-dimensional simplices in this triangulation so that all simplices reflect their orientation.

In particular, if this triangulation is oriented, then it will be converted into an isomorphic triangulation with the opposite orientation.

This routine works by flipping vertices (dim - 1) and dim of every top-dimensional simplex.

◆ rehydrate()

static Triangulation< 3 > regina::Triangulation< 3 >::rehydrate ( const std::string &  dehydration)
staticinherited

Rehydrates the given alphabetical string into a 3-dimensional triangulation.

For a full description of the dehydrated triangulation format, see A Census of Cusped Hyperbolic 3-Manifolds, Callahan, Hildebrand and Weeks, Mathematics of Computation 68/225, 1999.

The converse routine dehydrate() can be used to extract a dehydration string from an existing triangulation. Dehydration followed by rehydration might not produce a triangulation identical to the original, but it is guaranteed to produce an isomorphic copy. See dehydrate() for the reasons behind this.

Exceptions
InvalidArgumentThe given string could not be rehydrated.
Parameters
dehydrationa dehydrated representation of the triangulation to construct. Case is irrelevant; all letters will be treated as if they were lower case.
Returns
the rehydrated triangulation.

◆ removeAllSimplices()

void regina::detail::TriangulationBase< dim >::removeAllSimplices
inlineinherited

Removes all simplices from the triangulation.

As a result, this triangulation will become empty.

All of the simplices that belong to this triangulation will be destroyed immediately.

◆ removeAllTetrahedra()

void regina::Triangulation< 3 >::removeAllTetrahedra ( )
inlineinherited

A dimension-specific alias for removeAllSimplices().

See removeAllSimplices() for further information.

◆ removeSimplex()

void regina::detail::TriangulationBase< dim >::removeSimplex ( Simplex< dim > *  simplex)
inlineinherited

Removes the given top-dimensional simplex from this triangulation.

The given simplex will be unglued from any adjacent simplices (if any), and will be destroyed immediately.

Precondition
The given simplex is a top-dimensional simplex in this triangulation.
Parameters
simplexthe simplex to remove.

◆ removeSimplexAt()

void regina::detail::TriangulationBase< dim >::removeSimplexAt ( size_t  index)
inlineinherited

Removes the top-dimensional simplex at the given index in this triangulation.

This is equivalent to calling removeSimplex(simplex(index)).

The given simplex will be unglued from any adjacent simplices (if any), and will be destroyed immediately.

Parameters
indexspecifies which top-dimensionalsimplex to remove; this must be between 0 and size()-1 inclusive.

◆ removeTetrahedron()

void regina::Triangulation< 3 >::removeTetrahedron ( Tetrahedron< 3 > *  tet)
inlineinherited

A dimension-specific alias for removeSimplex().

See removeSimplex() for further information.

◆ removeTetrahedronAt()

void regina::Triangulation< 3 >::removeTetrahedronAt ( size_t  index)
inlineinherited

A dimension-specific alias for removeSimplexAt().

See removeSimplexAt() for further information.

◆ reorderTetrahedraBFS()

void regina::Triangulation< 3 >::reorderTetrahedraBFS ( bool  reverse = false)
inherited

Reorders the tetrahedra of this triangulation using a breadth-first search, so that small-numbered tetrahedra are adjacent to other small-numbered tetrahedra.

Specifically, the reordering will operate as follows. Tetrahedron 0 will remain tetrahedron 0. Its immediate neighbours will be numbered 1, 2, 3 and 4 (though if these neighbours are not distinct then of course fewer labels will be required). Their immediate neighbours will in turn be numbered 5, 6, and so on, ultimately following a breadth-first search throughout the entire triangulation.

If the optional argument reverse is true, then tetrahedron numbers will be assigned in reverse order. That is, tetrahedron 0 will become tetrahedron n-1, its neighbours will become tetrahedra n-2 down to n-5, and so on.

Parameters
reversetrue if the new tetrahedron numbers should be assigned in reverse order, as described above.

◆ retriangulate()

template<typename Action , typename... Args>
bool regina::Triangulation< 3 >::retriangulate ( int  height,
unsigned  threads,
ProgressTrackerOpen tracker,
Action &&  action,
Args &&...  args 
) const
inlineinherited

Explores all triangulations that can be reached from this via Pachner moves, without exceeding a given number of additional tetrahedra.

Specifically, this routine will iterate through all triangulations that can be reached from this triangulation via 2-3 and 3-2 Pachner moves, without ever exceeding height additional tetrahedra beyond the original number.

For every such triangulation (including this starting triangulation), this routine will call action (which must be a function or some other callable object).

  • action must take the following initial argument(s). Either (a) the first argument must be a triangulation (the precise type is discussed below), representing the triangluation that has been found; or else (b) the first two arguments must be of types const std::string& followed by a triangulation, representing both the triangulation and an isomorphism signature. The second form is offered in order to avoid unnecessary recomputation within the action function; however, note that the signature might not be of the IsoSigClassic type (i.e., it might not match the output from the default version of isoSig()). If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
  • The triangulation argument will be passed as an rvalue; a typical action could (for example) take it by const reference and query it, or take it by value and modify it, or take it by rvalue reference and move it into more permanent storage.
  • action must return a boolean. If action ever returns true, then this indicates that processing should stop immediately (i.e., no more triangulations will be processed).
  • action may, if it chooses, make changes to this triangulation (i.e., the original triangulation upon which retriangulate() was called). This will not affect the search: all triangulations that this routine visits will be obtained via Pachner moves from the original form of this triangulation, before any subsequent changes (if any) were made.
  • action will only be called once for each triangulation (including this starting triangulation). In other words, no triangulation will be revisited a second time in a single call to retriangulate().

This routine can be very slow and very memory-intensive, since the number of triangulations it visits may be superexponential in the number of tetrahedra, and it records every triangulation that it visits (so as to avoid revisiting the same triangulation again). It is highly recommended that you begin with height = 1, and if necessary try increasing height one at a time until this routine becomes too expensive to run.

If height is negative, then there will be no bound on the number of additional tetrahedra. This means that the routine will never terminate, unless action returns true for some triangulation that is passed to it.

Since Regina 7.0, this routine will not return until the exploration of triangulations is complete, regardless of whether a progress tracker was passed. If you need the old behaviour (where passing a progress tracker caused the enumeration to start in the background), simply call this routine in a new detached thread.

To assist with performance, this routine can run in parallel (multithreaded) mode; simply pass the number of parallel threads in the argument threads. Even in multithreaded mode, this routine will not return until processing has finished (i.e., either action returned true, or the search was exhausted). All calls to action will be protected by a mutex (i.e., different threads will never be calling action at the same time); as a corollary, the action should avoid expensive operations where possible (otherwise it will become a serialisation bottleneck in the multithreading).

Precondition
This triangulation is connected.
Exceptions
FailedPreconditionThis triangulation has more than one connected component. If a progress tracker was passed, it will be marked as finished before the exception is thrown.
Warning
The API for this class or function has not yet been finalised. This means that the interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please check the detailed changelog with each new release to see if you need to make changes to your code.
Python
This function is available in Python, and the action argument may be a pure Python function. However, its form is more restricted: the arguments tracker and args are removed, so you call it as retriangulate(height, threads, action). Moreover, action must take exactly two arguments (const std::string&, Triangulation<3>&&) representing a signature and the triangulation, as described in option (b) above.
Parameters
heightthe maximum number of additional tetrahedra to allow beyond the number of tetrahedra originally present in the triangulation, or a negative number if this should not be bounded.
threadsthe number of threads to use. If this is 1 or smaller then the routine will run single-threaded.
trackera progress tracker through which progress will be reported, or null if no progress reporting is required.
actiona function (or other callable object) to call for each triangulation that is found.
argsany additional arguments that should be passed to action, following the initial triangulation argument(s).
Returns
true if some call to action returned true (thereby terminating the search early), or false if the search ran to completion.

◆ saveRecogniser()

bool regina::Triangulation< 3 >::saveRecogniser ( const char *  filename) const
inherited

Writes this triangulation to the given file in Matveev's 3-manifold recogniser format.

Recogniser exports are currently not available for triangulations that are invalid or contain boundary triangles. If either of these conditions is true then the file will not be written, and this routine will return false.

Internationalisation
This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.
Parameters
filenamethe name of the Recogniser file to which to write.
Returns
true if and only if the file was successfully written.

◆ saveRecognizer()

bool regina::Triangulation< 3 >::saveRecognizer ( const char *  filename) const
inlineinherited

A synonym for saveRecogniser().

This writes this triangulation to the given file in Matveev's 3-manifold recogniser format.

Precondition
This triangulation is not invalid, and does not contain any boundary triangles.
Internationalisation
This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.
Parameters
filenamethe name of the Recogniser file to which to write.
Returns
true if and only if the file was successfully written.

◆ saveSnapPea()

bool regina::SnapPeaTriangulation::saveSnapPea ( const char *  filename) const

Writes this triangulation to the given file using SnapPea's native file format.

Unlike Triangulation<3>::saveSnapPea(), this routine uses the SnapPea kernel to produce the file contents. This means it will include not just the tetrahedron gluings, but also other SnapPea-specific information that Regina does not use (e.g., peripheral curves).

If this is a null triangulation, then the file will not be written and this routine will return false.

Internationalisation
This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.
Parameters
filenamethe name of the SnapPea file to which to write.
Returns
true if and only if the file was successfully written.

◆ shape()

const std::complex< double > & regina::SnapPeaTriangulation::shape ( size_t  tet) const
inline

Returns the shape of the given tetrahedron, with respect to the Dehn filled hyperbolic structure.

Tetrahedron shapes are given in rectangular form, and using a fixed coordinate system (fixed alignment, in SnapPea's terminology).

If this is a null triangulation, or if solutionType() is no_solution or not_attempted (i.e., we did not or could not solve for a hyperbolic structure), then this routine will simply return zero.

This routine is fast constant time (unlike in SnapPea, where the corresponding routine get_tet_shape takes linear time). Therefore you can happily call this routine repeatedly without a significant performance penalty.

SnapPy
In SnapPy, this routine corresponds to calling Manifold.tetrahedra_shapes(part="rect")[tet].
Parameters
tetthe index of a tetrahedron; this must be between 0 and size()-1 inclusive.
Returns
the shape of the given tetrahedron, in rectangular form.

◆ shellBoundary()

bool regina::Triangulation< 3 >::shellBoundary ( Tetrahedron< 3 > *  t,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a boundary shelling move on the given tetrahedron.

This involves simply popping off a tetrahedron that touches the boundary. This can be done if:

  • all edges of the tetrahedron are valid;
  • precisely one, two or three faces of the tetrahedron lie in the boundary;
  • if one face lies in the boundary, then the opposite vertex does not lie in the boundary, and no two of the remaining three edges are identified;
  • if two faces lie in the boundary, then the remaining edge does not lie in the boundary, and the remaining two faces of the tetrahedron are not identified.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this operation will (trivially) preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given tetrahedron is a tetrahedron of this triangulation.
Parameters
tthe tetrahedron upon which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ simplex() [1/2]

Simplex< dim > * regina::detail::TriangulationBase< dim >::simplex ( size_t  index)
inlineinherited

Returns the top-dimensional simplex at the given index in the triangulation.

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

Parameters
indexspecifies which simplex to return; this value should be between 0 and size()-1 inclusive.
Returns
the indexth top-dimensional simplex.

◆ simplex() [2/2]

const Simplex< dim > * regina::detail::TriangulationBase< dim >::simplex ( size_t  index) const
inlineinherited

Returns the top-dimensional simplex at the given index in the triangulation.

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

Parameters
indexspecifies which simplex to return; this value should be between 0 and size()-1 inclusive.
Returns
the indexth top-dimensional simplex.

◆ simplices()

auto regina::detail::TriangulationBase< dim >::simplices
inlineinherited

Returns an object that allows iteration through and random access to all top-dimensional simplices in this triangulation.

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. Note that the elements of the list will be pointers, so your code might look like:

for (Simplex<dim>* s : tri.simplices()) { ... }

The object that is returned will remain up-to-date and valid for as long as the triangulation exists: even as simplices are added and/or removed, it will always reflect the simplices that are currently in the triangulation. Nevertheless, it is recommended to treat this object as temporary only, and to call simplices() again each time you need it.

Returns
access to the list of all top-dimensional simplices.

◆ simplifiedFundamentalGroup()

void regina::detail::TriangulationBase< dim >::simplifiedFundamentalGroup ( GroupPresentation  newGroup)
inlineinherited

Notifies the triangulation that you have simplified the presentation of its fundamental group.

The old group presentation will be replaced by the (hopefully simpler) group that is passed.

This routine is useful for situations in which some external body (such as GAP) has simplified the group presentation better than Regina can.

Regina does not verify that the new group presentation is equivalent to the old, since this is - well, hard.

If the fundamental group has not yet been calculated for this triangulation, then this routine will store the new group as the fundamental group, under the assumption that you have worked out the group through some other clever means without ever having needed to call group() at all.

Note that this routine will not fire a packet change event.

Parameters
newGroupa new (and hopefully simpler) presentation of the fundamental group of this triangulation.

◆ simplifyExhaustive()

bool regina::Triangulation< 3 >::simplifyExhaustive ( int  height = 1,
unsigned  threads = 1,
ProgressTrackerOpen tracker = nullptr 
)
inherited

Attempts to simplify this triangulation using a slow but exhaustive search through the Pachner graph.

This routine is more powerful but much slower than intelligentSimplify().

Specifically, this routine will iterate through all triangulations that can be reached from this triangulation via 2-3 and 3-2 Pachner moves, without ever exceeding height additional tetrahedra beyond the original number.

If at any stage it finds a triangulation with fewer tetrahedra than the original, then this routine will call intelligentSimplify() to shrink the triangulation further if possible and will then return true. If it cannot find a triangulation with fewer tetrahedra then it will leave this triangulation unchanged and return false.

This routine can be very slow and very memory-intensive: the number of triangulations it visits may be superexponential in the number of tetrahedra, and it records every triangulation that it visits (so as to avoid revisiting the same triangulation again). It is highly recommended that you begin with height = 1, and if this fails then try increasing height one at a time until either you find a simplification or the routine becomes too expensive to run.

If height is negative, then there will be no bound on the number of additional tetrahedra. This means that the routine will not terminate until a simpler triangulation is found. If no simpler diagram exists then the only way to terminate this function is to cancel the operation via a progress tracker (read on for details).

If you want a fast simplification routine, you should call intelligentSimplify() instead. The benefit of simplifyExhaustive() is that, for very stubborn triangulations where intelligentSimplify() finds itself stuck at a local minimum, simplifyExhaustive() is able to "climb out" of such wells.

Since Regina 7.0, this routine will not return until either the triangulation is simplified or the exhaustive search is complete, regardless of whether a progress tracker was passed. If you need the old behaviour (where passing a progress tracker caused the exhaustive search to start in the background), simply call this routine in a new detached thread.

To assist with performance, this routine can run in parallel (multithreaded) mode; simply pass the number of parallel threads in the argument threads. Even in multithreaded mode, this routine will not return until processing has finished (i.e., either the triangulation was simplified or the search was exhausted).

If this routine is unable to simplify the triangulation, then the triangulation will not be changed.

Precondition
This triangulation is connected.
Exceptions
FailedPreconditionThis triangulation has more than one connected component. If a progress tracker was passed, it will be marked as finished before the exception is thrown.
Python
The global interpreter lock will be released while this function runs, so you can use it with Python-based multithreading.
Parameters
heightthe maximum number of additional tetrahedra to allow beyond the number of tetrahedra originally present in the triangulation, or a negative number if this should not be bounded.
threadsthe number of threads to use. If this is 1 or smaller then the routine will run single-threaded.
trackera progress tracker through which progress will be reported, or nullptr if no progress reporting is required.
Returns
true if and only if the triangulation was successfully simplified to fewer tetrahedra.

◆ simplifyToLocalMinimum()

bool regina::Triangulation< 3 >::simplifyToLocalMinimum ( bool  perform = true)
inherited

Uses all known simplification moves to reduce the triangulation monotonically to some local minimum number of tetrahedra.

End users will probably not want to call this routine. You should call intelligentSimplify() if you want a fast (and usually effective) means of simplifying a triangulation, or you should call simplifyExhaustive() if you are still stuck and you want to try a slower but more powerful method instead.

The moves used by this routine include 3-2, 2-0 (edge and vertex), 2-1 and boundary shelling moves.

Moves that do not reduce the number of tetrahedra (such as 4-4 moves or book opening moves) are not used in this routine. Such moves do however feature in intelligentSimplify().

If this triangulation is currently oriented, then this operation will preserve the orientation.

Warning
The implementation of this routine (and therefore its results) may change between different releases of Regina.
Parameters
performtrue if we are to perform the simplifications, or false if we are only to investigate whether simplifications are possible (defaults to true).
Returns
if perform is true, this routine returns true if and only if the triangulation was changed to reduce the number of tetrahedra; if perform is false, this routine returns true if and only if it determines that it is capable of performing such a change.

◆ size()

size_t regina::detail::TriangulationBase< dim >::size
inlineinherited

Returns the number of top-dimensional simplices in the triangulation.

Returns
The number of top-dimensional simplices.

◆ slopeEquations()

MatrixInt regina::SnapPeaTriangulation::slopeEquations ( ) const

Returns a matrix for computing boundary slopes of spun-normal surfaces at the cusps of the triangulation.

This matrix includes a pair of rows for each cusp in the triangulation: one row for determining the algebraic intersection number with the meridian, followed by one row for determining the algebraic intersection number with the longitude.

If the triangulation has more than one cusp, these pairs are ordered by cusp index (as stored by SnapPea). You can examine cusp(cusp_number).vertex() to map these to Regina's vertex indices if needed.

For the purposes of this routine, any fillings on the cusps of this SnapPea triangulation will be ignored.

This matrix is constructed so that, if M and L are the rows for the meridian and longitude at some cusp, then for any spun-normal surface with quadrilateral coordinates q, the boundary curves have algebraic intersection number M.q with the meridian and L.q with the longitude. Equivalently, the boundary curves pass L.q times around the meridian and -M.q times around the longitude. To compute these slopes directly from a normal surface, see NormalSurface::boundaryIntersections().

The orientations of the boundary curves of a spun-normal surface are chosen so that if meridian and longitude are a positive basis as vieved from the cusp, then as one travels along an oriented boundary curve, the spun-normal surface spirals into the cusp to one's right and down into the manifold to one's left.

SnapPy
This has no corresponding routine in SnapPy.
Precondition
All vertex links in this triangulation must be tori.
Warning
If this triangulation was constructed from a Regina triangulation (of class Triangulation<3>), then Regina will have no information about what meridian and longitude the user wishes to use (since Regina does not keep track of peripheral curves on cusps). Therefore Regina will give boundary slopes relative to the (shortest, second-shortest) basis, as described in the constructor SnapPeaTriangulation(const Triangulation<3>&, bool). This might not be what the user expects.
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
Author
William Pettersson and Stephan Tillmann
Returns
a matrix with (2 * number_of_cusps) rows and (3 * number_of_tetrahedra) columns as described above.

◆ snapPea() [1/2]

std::string regina::SnapPeaTriangulation::snapPea ( ) const

Returns a string containing the full contents of a SnapPea data file that describes this triangulation.

In particular, this string can be used in a Python session to pass the triangulation directly to SnapPy (without writing to the filesystem).

Unlike Triangulation<3>::snapPea(), this routine uses the SnapPea kernel to produce the file contents. This means it will include not just the tetrahedron gluings, but also other SnapPea-specific information that Regina does not use (e.g., peripheral curves).

If you wish to export a triangulation to a SnapPea file, you should call saveSnapPea() instead (which has better performance, and does not require you to construct an enormous intermediate string).

Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
Returns
a string containing the contents of the corresponding SnapPea data file.

◆ snapPea() [2/2]

void regina::SnapPeaTriangulation::snapPea ( std::ostream &  out) const

Writes the full contents of a SnapPea data file describing this triangulation to the given output stream.

Unlike Triangulation<3>::snapPea(), this routine uses the SnapPea kernel to produce the file contents. This means it will include not just the tetrahedron gluings, but also other SnapPea-specific information that Regina does not use (e.g., peripheral curves).

If you wish to extract the SnapPea data file as a string, you should call the zero-argument routine snapPea() instead. If you wish to write to a real SnapPea data file on the filesystem, you should call saveSnapPea() (which is also available in Python).

Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
Python
Not present. Instead use the variant of snapPea() that takes no arguments and returns a string.
Parameters
outthe output stream to which the SnapPea data file will be written.

◆ solutionType()

SolutionType regina::SnapPeaTriangulation::solutionType ( ) const

Returns the type of solution found when solving for a hyperbolic structure, with respect to the current Dehn filling (if any).

SnapPy
In SnapPy, this routine corresponds to calling Manifold.solution_type().
Returns
the solution type.

◆ str() [1/2]

std::string regina::Output< SnapPeaTriangulation , 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.

◆ str() [2/2]

std::string regina::Output< Triangulation< 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.

◆ strictAngleStructure()

const AngleStructure & regina::Triangulation< 3 >::strictAngleStructure ( ) const
inlineinherited

Returns a strict angle structure on this triangulation, if one exists.

Recall that a strict angle structure is one in which every angle is strictly between 0 and π. If a strict angle structure does exist, then this routine is guaranteed to return one.

This routine is designed for scenarios where you already know that a strict angle structure exists. This means:

  • If no strict angle structure exists, this routine will throw an exception, which will incur a significant overhead.
  • If you do not know in advance whether a strict angle structure exists, you should call hasStrictAngleStructure() first. If the answer is no, this will avoid the overhead of throwing and catching exceptions. If the answer is yes, this will have the side-effect of caching the strict angle structure, which means your subsequent call to strictAngleStructure() will be essentially instantaneous.

The underlying algorithm runs a single linear program (it does not enumerate all vertex angle structures). This means that it is likely to be fast even for large triangulations.

The result of this routine is cached internally: as long as the triangulation does not change, multiple calls to strictAngleStructure() will return identical angle structures, and every call after the first be essentially instantaneous.

If the triangulation does change, however, then the cached angle structure will be deleted, and any reference that was returned before will become invalid.

Exceptions
NoSolutionNo strict angle structure exists on this triangulation.
Returns
a strict angle structure on this triangulation, if one exists.

◆ subdivide()

void regina::detail::TriangulationBase< dim >::subdivide
inherited

Does a barycentric subdivision of the triangulation.

This is done in-place, i.e., the triangulation will be modified directly.

Each top-dimensional simplex s is divided into (dim + 1) factorial sub-simplices by placing an extra vertex at the centroid of every face of every dimension. Each of these sub-simplices t is described by a permutation p of (0, ..., dim). The vertices of such a sub-simplex t are:

  • vertex p[0] of s;
  • the centre of edge (p[0], p[1]) of s;
  • the centroid of triangle (p[0], p[1], p[2]) of s;
  • ...
  • the centroid of face (p[0], p[1], p[2], p[dim]) of s, which is the entire simplex s itself.

The sub-simplices have their vertices numbered in a way that mirrors the original simplex s:

  • vertex p[0] of s will be labelled p[0] in t;
  • the centre of edge (p[0], p[1]) of s will be labelled p[1] in t;
  • the centroid of triangle (p[0], p[1], p[2]) of s will be labelled p[2] in t;
  • ...
  • the centroid of s itself will be labelled p[dim] in t.

In particular, if this triangulation is currently oriented, then this barycentric subdivision will preserve the orientation.

If simplex s has index i in the original triangulation, then its sub-simplex corresponding to permutation p will have index ((dim + 1)! * i + p.orderedSnIndex()) in the resulting triangulation. In other words: sub-simplices are ordered first according to the original simplex that contains them, and then according to the lexicographical ordering of the corresponding permutations p.

Precondition
dim is one of Regina's standard dimensions. This precondition is a safety net, since in higher dimensions the triangulation would explode too quickly in size (and for the highest dimensions, possibly beyond the limits of size_t).
Warning
In dimensions 3 and 4, both the labelling and ordering of sub-simplices in the subdivided triangulation has changed as of Regina 5.1. (Earlier versions of Regina made no guarantee about the labelling and ordering; these guarantees are also new to Regina 5.1).
Todo:
Lock the topological properties of the underlying manifold, to avoid recomputing them after the subdivision. However, only do this for valid triangulations (since we can have scenarios where invalid triangulations becoming valid and ideal after subdivision, which may change properties such as Triangulation<4>::knownSimpleLinks).

◆ summands()

std::vector< Triangulation< 3 > > regina::Triangulation< 3 >::summands ( ) const
inherited

Computes the connected sum decomposition of this triangulation.

The prime summands will be returned as a vector of triangulations; this triangulation will not be modified.

As far as possible, the summands will be represented using 0-efficient triangulations (i.e., triangulations that contain no non-vertex-linking normal spheres). Specifically, for every summand, either:

  • the triangulation of the summand that is produced will be 0-efficient; or
  • the summand is one of RP3, the product S2xS1, or the twisted product S2x~S1. In each of these cases there is no possible 0-efficient triangulation of the summand, and so the triangulation that is produced will just be minimal (i.e., two tetrahedra).

For non-orientable triangulations, this routine is only guaranteed to succeed if the original manifold contains no embedded two-sided projective planes. If the manifold does contain embedded two-sided projective planes, then this routine might still succeed but it might fail; however, such a failure will always be detected, and in such a case this routine will throw an exception (as detailed below).

Note that this routine is currently only available for closed triangulations; see the list of preconditions for full details. If this triangulation is a 3-sphere then this routine will return an empty list.

This function is new to Regina 7.0, and it has some important changes of behaviour from the old connectedSumDecomposition() from Regina 6.0.1 and earlier:

  • This function does not insert the resulting components into the packet tree.
  • If this routine fails because of an embedded two-sided projective plane, then it throws an exception instead of returning -1.
  • This function does not assign labels to the new summands.

The underlying algorithm appears in "A new approach to crushing 3-manifold triangulations", Discrete and Computational Geometry 52:1 (2014), pp. 116-139. This algorithm is based on the Jaco-Rubinstein 0-efficiency algorithm, and works in both orientable and non-orientable settings.

Warning
Users are strongly advised to check for exceptions if embedded two-sided projective planes are a possibility, since in such a case this routine might fail (as explained above). Note however that this routine might still succeed, and so success is not a proof that no embedded two-sided projective planes exist.
The algorithms used in this routine rely on normal surface theory and so can be very slow for larger triangulations. For 3-sphere testing, see the routine isSphere() which uses faster methods where possible.
Precondition
This triangulation is valid, closed and connected.
Exceptions
UnsolvedCaseThe original manifold is non-orientable and contains one or more embedded two-sided projective planes, and this routine was not able to recover from this situation.
Returns
a list of triangulations of prime summands.

◆ swap() [1/3]

void regina::SnapPeaTriangulation::swap ( SnapPeaTriangulation other)

Swaps the contents of this and the given SnapPea triangulation.

All information contained in this triangulation, including both Regina's and SnapPea's internal data as well as all cached properties, will be moved to other. Likewise, all information contained in other will be moved to this triangulation.

In particular, any pointers or references to Tetrahedron<3>, Face<3, subdim> and/or Cusp objects will remain valid.

This routine will behave correctly if other is in fact this triangulation.

Warning
If you wish to swap the contents of two SnapPea triangulations, you must cast both to SnapPeaTriangulation before calling swap(). If either argument is presented as the parent class Triangulation<3>, then the Triangulation<3> swap() will be called instead; the result will be that (just like when you call any of the Triangulation<3> edit routines) both SnapPea triangulations will be reset to null triangulations. See the SnapPeaTriangulation class notes for further discussion.
Note
This swap function is not marked noexcept, since it fires change events on both triangulations which may in turn call arbitrary code via any registered packet listeners.
Parameters
otherthe SnapPea triangulation whose contents should be swapped with this.

◆ swap() [2/3]

void regina::Snapshottable< Triangulation< dim > >::swap ( Snapshottable< Triangulation< dim > > &  other)
inlineprotectednoexceptinherited

Swap operation.

This should only be called when the entire type T contents of this object and other are being swapped. If one object has a current snapshot, then the other object will move in as the new image for that same snapshot. This avoids a deep copies of this object and/or other, even though both objects are changing.

In particular, if the swap function for T calls this base class function (as it should), then there is no need to call takeSnapshot() from either this object or src.

Parameters
otherthe snapshot image being swapped with this.

◆ swap() [3/3]

void regina::Triangulation< 3 >::swap ( Triangulation< 3 > &  other)
inherited

Swaps the contents of this and the given triangulation.

All tetrahedra that belong to this triangulation will be moved to other, and all tetrahedra that belong to other will be moved to this triangulation. Likewise, all skeletal objects (such as lower-dimensional faces, components, and boundary components) and all cached properties (such as homology and fundamental group) will be swapped.

In particular, any pointers or references to Tetrahedron<3> and/or Face<3, subdim> objects will remain valid.

This routine will behave correctly if other is in fact this triangulation.

Note
This swap function is not marked noexcept, since it fires change events on both triangulations which may in turn call arbitrary code via any registered packet listeners.
Parameters
otherthe triangulation whose contents should be swapped with this.

◆ swapBaseData()

void regina::detail::TriangulationBase< dim >::swapBaseData ( TriangulationBase< dim > &  other)
protectedinherited

Swaps all data that is managed by this base class, including simplices, skeletal data, cached properties and the snapshotting data, with the given triangulation.

Note that TriangulationBase never calls this routine itself. Typically swapBaseData() is only ever called by Triangulation<dim>::swap().

Parameters
otherthe triangulation whose data should be swapped with this.

◆ takeSnapshot()

void regina::Snapshottable< Triangulation< dim > >::takeSnapshot ( )
inlineprotectedinherited

Must be called before modification and/or destruction of the type T contents.

See the Snapshot class notes for a full explanation of how this requirement works.

There are a few exceptions where takeSnapshot() does not need to be called: these are where type T move, copy and/or swap operations call the base class operations (as they should). See the Snapshottable move, copy and swap functions for details.

If this object has a current snapshot, then this function will trigger a deep copy with the snapshot.

After this function returns, this object is guaranteed to be completely unenrolled from the snapshotting machinery.

◆ tetrahedra()

auto regina::detail::TriangulationBase< dim >::tetrahedra
inlineinherited

A dimension-specific alias for faces<3>(), or an alias for simplices() in dimension dim = 3.

This alias is available for dimensions dim ≥ 3.

See faces() for further information.

◆ tetrahedron() [1/2]

Face< dim, 3 > * regina::detail::TriangulationBase< dim >::tetrahedron ( size_t  index)
inlineinherited

A dimension-specific alias for face<3>(), or an alias for simplex() in dimension dim = 3.

This alias is available for dimensions dim ≥ 3.

See face() for further information.

◆ tetrahedron() [2/2]

auto regina::detail::TriangulationBase< dim >::tetrahedron ( size_t  index) const
inlineinherited

A dimension-specific alias for face<3>(), or an alias for simplex() in dimension dim = 3.

This alias is available for dimensions dim ≥ 3. It returns a const tetrahedron pointer in dimension dim = 3, and a non-const tetrahedron pointer in all higher dimensions.

See face() for further information.

◆ tightDecode()

Triangulation< dim > regina::detail::TriangulationBase< dim >::tightDecode ( std::istream &  input)
staticinherited

Reconstructs a triangulation from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be read from the given input stream. If the input stream contains leading whitespace then it will be treated as an invalid encoding (i.e., this routine will throw an exception). The input routine may contain further data: if this routine is successful then the input stream will be left positioned immediately after the encoding, without skipping any trailing whitespace.

Exceptions
InvalidInputThe given input stream does not begin with a tight encoding of a dim-dimensional triangulation.
Python
Not present. Use tightDecoding() instead, which takes a string as its argument.
Parameters
inputan input stream that begins with the tight encoding for a dim-dimensional triangulation.
Returns
the triangulation represented by the given tight encoding.

◆ tightDecoding()

static Triangulation< dim > regina::TightEncodable< Triangulation< dim > >::tightDecoding ( const std::string &  enc)
inlinestaticinherited

Reconstructs an object of type T from its given tight encoding.

See the page on tight encodings for details.

The tight encoding should be given as a string. If this string contains leading whitespace or any trailing characters at all (including trailing whitespace), then it will be treated as an invalid encoding (i.e., this routine will throw an exception).

Exceptions
InvalidArgumentThe given string is not a tight encoding of an object of type T.
Parameters
encthe tight encoding for an object of type T.
Returns
the object represented by the given tight encoding.

◆ tightEncode()

void regina::detail::TriangulationBase< dim >::tightEncode ( std::ostream &  out) const
inherited

Writes the tight encoding of this triangulation to the given output stream.

See the page on tight encodings for details.

Python
Not present. Use tightEncoding() instead, which returns a string.
Parameters
outthe output stream to which the encoded string will be written.

◆ tightEncoding()

std::string regina::TightEncodable< Triangulation< dim > >::tightEncoding ( ) const
inlineinherited

Returns the tight encoding of this object.

See the page on tight encodings for details.

Exceptions
FailedPreconditionThis may be thrown for some classes T if the object is in an invalid state. If this is possible, then a more detailed explanation of "invalid" can be found in the class documentation for T, under the member function T::tightEncode(). See FacetPairing::tightEncode() for an example of this.
Returns
the resulting encoded string.

◆ translate()

Face< dim, subdim > * regina::detail::TriangulationBase< dim >::translate ( const Face< dim, subdim > *  other) const
inlineinherited

Translates a face of some other triangulation into the corresponding face of this triangulation, using simplex numbers for the translation.

Typically this routine would be used when the given face comes from a triangulation that is combinatorially identical to this, and you wish to obtain the corresponding face of this triangulation.

Specifically: if other refers to face i of top-dimensional simplex number k of some other triangulation, then this routine will return face i of top-dimensional simplex number k of this triangulation. Note that this routine does not use the face indices within each triangulation (which is outside the user's control), but rather the simplex numbering (which the user has full control over).

This routine behaves correctly even if other is a null pointer.

Precondition
This triangulation contains at least as many top-dimensional simplices as the triangulation containing other (though, as noted above, in typical scenarios both triangulations would actually be combinatorially identical).
Template Parameters
subdimthe face dimension; this must be between 0 and dim-1 inclusive.
Parameters
otherthe face to translate.
Returns
the corresponding face of this triangulation.

◆ triangle() [1/2]

Face< dim, 2 > * regina::detail::TriangulationBase< dim >::triangle ( size_t  index)
inlineinherited

A dimension-specific alias for face<2>(), or an alias for simplex() in dimension dim = 2.

This alias is available for all dimensions dim.

See face() for further information.

◆ triangle() [2/2]

auto regina::detail::TriangulationBase< dim >::triangle ( size_t  index) const
inlineinherited

A dimension-specific alias for face<2>(), or an alias for simplex() in dimension dim = 2.

This alias is available for all dimensions dim. It returns a const triangle pointer in dimension dim = 2, and a non-const triangle pointer in all higher dimensions.

See face() for further information.

◆ triangles()

auto regina::detail::TriangulationBase< dim >::triangles
inlineinherited

A dimension-specific alias for faces<2>(), or an alias for simplices() in dimension dim = 2.

This alias is available for all dimensions.

See faces() for further information.

◆ triangulateComponents()

std::vector< Triangulation< dim > > regina::detail::TriangulationBase< dim >::triangulateComponents
inherited

Returns the individual connected components of this triangulation.

This triangulation will not be modified.

This function is new to Regina 7.0, and it has two important changes of behaviour from the old splitIntoComponents() from Regina 6.0.1 and earlier:

  • This function does not insert the resulting components into the packet tree.
  • This function does not assign labels to the new components.
Returns
a list of individual component triangulations.

◆ turaevViro()

Cyclotomic regina::Triangulation< 3 >::turaevViro ( unsigned long  r,
bool  parity = true,
Algorithm  alg = ALG_DEFAULT,
ProgressTracker tracker = nullptr 
) const
inherited

Computes the given Turaev-Viro state sum invariant of this 3-manifold using exact arithmetic.

The initial data for the Turaev-Viro invariant is as described in the paper of Turaev and Viro, "State sum invariants of 3-manifolds and quantum 6j-symbols", Topology, vol. 31, no. 4, 1992, pp 865-902. In particular, Section 7 of this paper describes the initial data as determined by an integer r ≥ 3, and a root of unity q₀ of degree 2r for which q₀² is a primitive root of unity of degree r. There are several cases to consider:

  • r may be even. In this case qâ‚€ must be a primitive (2r)th root of unity, and the invariant is computed as an element of the cyclotomic field of order 2r. There is no need to specify which root of unity is used, since switching between different roots of unity corresponds to an automorphism of the underlying cyclotomic field (i.e., it does not yield any new information). Therefore, if r is even, the additional argument parity is ignored.
  • r may be odd, and qâ‚€ may be a primitive (2r)th root of unity. This case corresponds to passing the argument parity as true. Here the invariant is again computed as an element of the cyclotomic field of order 2r. As before, there is no need to give further information as to which root of unity is used, since switching between roots of unity does not yield new information.
  • r may be odd, and qâ‚€ may be a primitive (r)th root of unity. This case corresponds to passing the argument parity as false. In this case the invariant is computed as an element of the cyclotomic field of order r. Again, there is no need to give further information as to which root of unity is used.

This routine works entirely within the relevant cyclotomic field, which yields exact results but adds a significant overhead to the running time. If you want a fast floating-point approximation, you can call turaevViroApprox() instead.

Unlike this routine, turaevViroApprox() requires a precise specification of which root of unity is used (since it returns a numerical real value). The numerical value obtained by calling turaevViroApprox(r, whichRoot) should be the same as turaevViro(r, parity).evaluate(whichRoot), where parity is true or false according to whether whichRoot is odd or even respectively. Of course in practice the numerical values might be very different, since turaevViroApprox() performs significantly more floating point operations, and so is subject to a much larger potential numerical error.

If the requested Turaev-Viro invariant has already been computed, then the result will be cached and so this routine will be very fast (since it just returns the previously computed result). Otherwise the computation could be quite slow, particularly for larger triangulations and/or larger values of r.

Since Regina 7.0, this routine will not return until the Turaev-Viro computation is complete, regardless of whether a progress tracker was passed. If you need the old behaviour (where passing a progress tracker caused the computation to start in the background), simply call this routine in a new detached thread.

Precondition
This triangulation is valid, closed and non-empty.
Python
The global interpreter lock will be released while this function runs, so you can use it with Python-based multithreading.
Parameters
rthe integer r as described above; this must be at least 3.
paritydetermines for odd r whether qâ‚€ is a primitive 2rth or rth root of unity, as described above.
algthe algorithm with which to compute the invariant. If you are not sure, the default value (ALG_DEFAULT) is a safe choice. This should be treated as a hint only: if the algorithm you choose is not supported for the given parameters (r and parity), then Regina will use another algorithm instead.
trackera progress tracker through will progress will be reported, or nullptr if no progress reporting is required.
Returns
the requested Turaev-Viro invariant, or an uninitialised field element if the calculation was cancelled via the given progress tracker.
See also
allCalculatedTuraevViro

◆ turaevViroApprox()

double regina::Triangulation< 3 >::turaevViroApprox ( unsigned long  r,
unsigned long  whichRoot = 1,
Algorithm  alg = ALG_DEFAULT 
) const
inherited

Computes the given Turaev-Viro state sum invariant of this 3-manifold using a fast but inexact floating-point approximation.

The initial data for the Turaev-Viro invariant is as described in the paper of Turaev and Viro, "State sum invariants of 3-manifolds and quantum 6j-symbols", Topology, vol. 31, no. 4, 1992, pp 865-902. In particular, Section 7 describes the initial data as determined by an integer r ≥ 3 and a root of unity q₀ of degree 2r for which q₀² is a primitive root of unity of degree r.

The argument whichRoot specifies which root of unity is used for q₀. Specifically, q₀ will be the root of unity e^(2πi * whichRoot / 2r). There are additional preconditions on whichRoot to ensure that q₀² is a primitive root of unity of degree r; see below for details.

This same invariant can be computed by calling turaevViro(r, parity).evaluate(whichRoot), where parity is true or false according to whether whichRoot is odd or even respectively. Calling turaevViroApprox() is significantly faster (since it avoids the overhead of working in cyclotomic fields), but may also lead to a much larger numerical error (since this routine might perform an exponential number of floating point operations, whereas the alternative only uses floating point for the final call to Cyclotomic::evaluate()).

These invariants, although computed in the complex field, should all be reals. Thus the return type is an ordinary double.

Precondition
This triangulation is valid, closed and non-empty.
The argument whichRoot is strictly between 0 and 2r, and has no common factors with r.
Parameters
rthe integer r as described above; this must be at least 3.
whichRootspecifies which root of unity is used for qâ‚€, as described above.
algthe algorithm with which to compute the invariant. If you are not sure, the default value (ALG_DEFAULT) is a safe choice. This should be treated as a hint only: if the algorithm you choose is not supported for the given parameters (r and whichRoot), then Regina will use another algorithm instead.
Returns
the requested Turaev-Viro invariant.
See also
allCalculatedTuraevViro

◆ twoOneMove()

bool regina::Triangulation< 3 >::twoOneMove ( Edge< 3 > *  e,
int  edgeEnd,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 2-1 move about the given edge.

This involves taking an edge meeting only one tetrahedron just once and merging that tetrahedron with one of the tetrahedra joining it.

This can be done assuming the following conditions:

  • The edge must be valid and non-boundary.
  • The two remaining faces of the tetrahedron are not joined, and the tetrahedron face opposite the given endpoint of the edge is not boundary.
  • Consider the second tetrahedron to be merged (the one joined along the face opposite the given endpoint of the edge). Moreover, consider the two edges of this second tetrahedron that run from the (identical) vertices of the original tetrahedron not touching e to the vertex of the second tetrahedron not touching the original tetrahedron. These edges must be distinct and may not both be in the boundary.

There are additional "distinct and not both boundary" conditions on faces of the second tetrahedron, but those follow automatically from the final condition above.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this 2-1 move will label the new tetrahedra in a way that preserves the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument e) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given edge is an edge of this triangulation.
Parameters
ethe edge about which to perform the move.
edgeEndthe end of the edge opposite that at which the second tetrahedron (to be merged) is joined. The end is 0 or 1, corresponding to the labelling (0,1) of the vertices of the edge as described in EdgeEmbedding<3>::vertices().
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ twoZeroMove() [1/2]

bool regina::Triangulation< 3 >::twoZeroMove ( Edge< 3 > *  e,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 2-0 move about the given edge of degree 2.

This involves taking the two tetrahedra joined at that edge and squashing them flat. This can be done if:

  • the edge is valid and non-boundary;
  • the two tetrahedra are distinct;
  • the edges opposite e in each tetrahedron are distinct and not both boundary;
  • if triangles f1 and f2 from one tetrahedron are to be flattened onto triangles g1 and g2 of the other respectively, then (a) f1 and g1 are distinct, (b) f2 and g2 are distinct, (c) we do not have both f1 = g2 and g1 = f2, (d) we do not have both f1 = f2 and g1 = g2, and (e) we do not have two of the triangles boundary and the other two identified.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument e) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given edge is an edge of this triangulation.
Parameters
ethe edge about which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ twoZeroMove() [2/2]

bool regina::Triangulation< 3 >::twoZeroMove ( Vertex< 3 > *  v,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 2-0 move about the given vertex of degree 2.

This involves taking the two tetrahedra joined at that vertex and squashing them flat. This can be done if:

  • the vertex is non-boundary and has a 2-sphere vertex link;
  • the two tetrahedra are distinct;
  • the triangles opposite v in each tetrahedron are distinct and not both boundary;
  • the two tetrahedra meet each other on all three faces touching the vertex (as opposed to meeting each other on one face and being glued to themselves along the other two).

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this operation will preserve the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument v) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must be known in advance that the move is legal.
The given vertex is a vertex of this triangulation.
Parameters
vthe vertex about which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.

◆ unfill()

void regina::SnapPeaTriangulation::unfill ( unsigned  whichCusp = 0)

Removes any filling on the given cusp.

After removing the filling, this routine will automatically ask SnapPea to update the hyperbolic structure.

If the given cusp is already complete, then this routine safely does nothing.

Warning
Be warned that cusp i might not correspond to vertex i of the triangulation. The Cusp::vertex() method (which is accessed through the cusp() routine) can help translate between SnapPea's cusp numbers and Regina's vertex numbers.
Parameters
whichCuspthe index of the cusp to unfill according to SnapPea; this must be between 0 and countCusps()-1 inclusive.

◆ utf8() [1/2]

std::string regina::Output< Triangulation< 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.

◆ utf8() [2/2]

std::string regina::Output< SnapPeaTriangulation , 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()

Face< dim, 0 > * regina::detail::TriangulationBase< dim >::vertex ( size_t  index) const
inlineinherited

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

This alias is available for all dimensions dim.

See face() for further information.

◆ vertices()

auto regina::detail::TriangulationBase< dim >::vertices
inlineinherited

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

This alias is available for all dimensions dim.

See faces() for further information.

◆ volume()

double regina::SnapPeaTriangulation::volume ( ) const

Computes the volume of the current solution to the hyperbolic gluing equations.

This will be with respect to the current Dehn filling (if any).

SnapPy
In SnapPy, this routine corresponds to calling Manifold.volume().
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
Returns
the estimated volume of the underlying 3-manifold.

◆ volumeWithPrecision()

std::pair< double, int > regina::SnapPeaTriangulation::volumeWithPrecision ( ) const

Computes the volume of the current solution to the hyperbolic gluing equations, and estimates the accuracy of the answer.

This will be with respect to the current Dehn filling (if any).

SnapPy
In SnapPy, this routine corresponds to calling Manifold.volume(accuracy=True).
Exceptions
SnapPeaIsNullThis is a null SnapPea triangulation.
Returns
a pair whose first element is the estimated volume of the underlying 3-manifold, and whose second element is an estimate of the number of decimal places of accuracy in this volume.

◆ volumeZero()

bool regina::SnapPeaTriangulation::volumeZero ( ) const

Determines whether the current solution to the gluing equations has volume approximately zero.

This test is not rigorous.

This requires (i) the volume itself to be very close to zero in an absolute sense, (ii) the volume to be zero within SnapPea's own estimated precision, and (iii) SnapPea's estimated precision to be sufficiently good in an absolute sense.

Returns
true if and only if the volume of the current solution is approximately zero according to the constraints outlined above.

◆ writeTextLong()

void regina::SnapPeaTriangulation::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
outthe output stream to which to write.

◆ writeTextShort()

void regina::SnapPeaTriangulation::writeTextShort ( std::ostream &  out) const

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

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

◆ writeXMLBaseProperties()

void regina::detail::TriangulationBase< dim >::writeXMLBaseProperties ( std::ostream &  out) const
protectedinherited

Writes a chunk of XML containing properties of this triangulation.

This routine covers those properties that are managed by this base class TriangulationBase and that have already been computed for this triangulation.

This routine is typically called from within Triangulation<dim>::writeXMLPacketData(). The XML elements that it writes are child elements of the tri element.

Parameters
outthe output stream to which the XML should be written.

◆ zeroTwoMove() [1/3]

bool regina::Triangulation< 3 >::zeroTwoMove ( Edge< 3 > *  e,
size_t  t0,
size_t  t1,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 0-2 move about the (not necessarily distinct) triangles incident to e that are numbered t0 and t1.

This involves fattening up these two triangles into a new pair of tetrahedra around a new degree-two edge d; this is the inverse of performing a 2-0 move about the edge d. This can be done if and only if the following conditions are satisfied:

  • The edge e is valid.
  • The numbers t0 and t1 are both less than or equal to e->degree(), and strictly less than e->degree() if e is non-boundary. This ensures that t0 and t1 correspond to sensible triangle numbers (as described below).

The triangles incident to e are numbered as follows:

  • For each i from 0 up to e->degree(), we assign the number i to the triangle emb.tetrahedron()->triangle(emb.vertices()[3]), where emb denotes e->embedding(i).
  • If e is a boundary edge, then we additionally assign the number e->degree() to the boundary triangle emb.tetrahedron()->triangle(emb.vertices()[2]), where this time emb denotes e->back().

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this 0-2 move will label the new tetrahedra in a way that preserves the orientation.

The implementation of this routine simply translates the given arguments to call the variant of zeroTwoMove() that takes a pair of edge embeddings (and other associated arguments).

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the argument e) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must by known in advance that the move is legal.
The given edge e is an edge of this triangulation.
Parameters
ethe common edge of the two triangles about which to perform the move.
t0the number assigned to one of two triangles about which to perform the move.
t1the number assigned to the other triangle about which to perform the move.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.
Author
Alex He

◆ zeroTwoMove() [2/3]

bool regina::Triangulation< 3 >::zeroTwoMove ( EdgeEmbedding< 3 >  e0,
int  t0,
EdgeEmbedding< 3 >  e1,
int  t1,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 0-2 move about the (not necessarily distinct) triangles e0.tetrahedron()->triangle(e0.vertices()[t0]) and e1.tetrahedron()->triangle(e1.vertices()[t1]).

This involves fattening up these two triangles into a new pair of tetrahedra around a new degree-two edge d; this is the inverse of performing a 2-0 move about the edge d. This can be done if and only if the following conditions are satisfied:

  • e0 and e1 are both embeddings of the same edge e.
  • t0 and t1 are both either 2 or 3; this ensures that the triangles about which we perform the move are triangles that are incident with e.
  • The edge e is valid.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this 0-2 move will label the new tetrahedra in a way that preserves the orientation.

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the arguments e0 and e1) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must by known in advance that the move is legal.
The edge e is an edge of this triangulation.
Parameters
e0an embedding of the common edge e of the two triangles about which to perform the move.
t0one of the two triangles about which to perform the move (associated to the edge embedding e0).
e1another embedding of the edge e.
t1the other triangle about which to perform move (associated to the edge embedding e1).
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.
Author
Alex He

◆ zeroTwoMove() [3/3]

bool regina::Triangulation< 3 >::zeroTwoMove ( Triangle< 3 > *  t0,
int  e0,
Triangle< 3 > *  t1,
int  e1,
bool  check = true,
bool  perform = true 
)
inherited

Checks the eligibility of and/or performs a 0-2 move about the (not necessarily distinct) triangles t0 and t1.

This involves fattening up these two triangles into a new pair of tetrahedra around a new degree-two edge d; this is the inverse of performing a 2-0 move about the edge d. This can be done if and only if the following conditions are satisfied:

  • The edges t0->edge(e0) and t1->edge(e1) are the same edge e of this triangulation.
  • The edge e is valid.

If the routine is asked to both check and perform, the move will only be performed if the check shows it is legal.

If this triangulation is currently oriented, then this 0-2 move will label the new tetrahedra in a way that preserves the orientation.

The implementation of this routine simply translates the given arguments to call the variant of zeroTwoMove() that takes a pair of edge embeddings (and other associated arguments).

Note that after performing this move, all skeletal objects (triangles, components, etc.) will be reconstructed, which means any pointers to old skeletal objects (such as the arguments t0 and t1) can no longer be used.

Precondition
If the move is being performed and no check is being run, it must by known in advance that the move is legal.
The given triangles t0 and t1 are triangles of this triangulation.
The numbers e0 and e1 are both 0, 1 or 2.
Parameters
t0one of the two triangles about which to perform the move.
e0the edge at which t0 meets the other triangle about which to perform the move.
t1the other triangle about which to perform the move.
e1the edge at which t1 meets t0.
checktrue if we are to check whether the move is allowed (defaults to true).
performtrue if we are to perform the move (defaults to true).
Returns
If check is true, the function returns true if and only if the requested move may be performed without changing the topology of the manifold. If check is false, the function simply returns true.
Author
Alex He

Member Data Documentation

◆ boundaryComponents_

MarkedVector<BoundaryComponent<dim> > regina::detail::TriangulationBase< dim >::boundaryComponents_
protectedinherited

The components that form the boundary of the triangulation.

◆ components_

MarkedVector<Component<dim> > regina::detail::TriangulationBase< dim >::components_
protectedinherited

The connected components that form the triangulation.

This list is only filled if/when the skeleton of the triangulation is computed.

◆ compressingDisc_

std::optional<bool> regina::Triangulation< 3 >::compressingDisc_
inherited

Does this 3-manifold contain a compressing disc?

◆ dimension

constexpr int regina::detail::TriangulationBase< dim >::dimension
staticconstexprinherited

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

◆ H1Bdry_

std::optional<AbelianGroup> regina::Triangulation< 3 >::H1Bdry_
inherited

First homology group of the boundary.

◆ H1Rel_

std::optional<AbelianGroup> regina::Triangulation< 3 >::H1Rel_
inherited

Relative first homology group of the triangulation with respect to the boundary.

◆ H2_

std::optional<AbelianGroup> regina::Triangulation< 3 >::H2_
inherited

Second homology group of the triangulation.

◆ haken_

std::optional<bool> regina::Triangulation< 3 >::haken_
inherited

Is this 3-manifold Haken? This property must only be stored for triangulations that are known to represent closed, connected, orientable, irreducible 3-manifolds.

◆ handlebody_

std::optional<ssize_t> regina::Triangulation< 3 >::handlebody_
inherited

Is this a triangulation of an orientable handlebody? If so, this stores the genus; if not, this stores -1.

◆ heldBy_ [1/2]

PacketHeldBy regina::PacketData< Triangulation< dim > >::heldBy_
protectedinherited

Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>.

As a special case, this field is also used to indicate when a Triangulation<3> is in fact the inherited data for a SnapPeaTriangulation. See the PacketHeldBy enumeration for more details on the different values that this data member can take.

◆ heldBy_ [2/2]

PacketHeldBy regina::PacketData< SnapPeaTriangulation >::heldBy_
protectedinherited

Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>.

As a special case, this field is also used to indicate when a Triangulation<3> is in fact the inherited data for a SnapPeaTriangulation. See the PacketHeldBy enumeration for more details on the different values that this data member can take.

◆ irreducible_

std::optional<bool> regina::Triangulation< 3 >::irreducible_
inherited

Is this 3-manifold irreducible?

◆ nBoundaryFaces_

std::array<size_t, dim> regina::detail::TriangulationBase< dim >::nBoundaryFaces_
protectedinherited

The number of boundary faces of each dimension.

◆ negativeIdealBoundaryComponents_

std::optional<bool> regina::Triangulation< 3 >::negativeIdealBoundaryComponents_
inherited

Does the triangulation contain any boundary components that are ideal and have negative Euler characteristic?

◆ niceTreeDecomposition_

std::optional<TreeDecomposition> regina::Triangulation< 3 >::niceTreeDecomposition_
inherited

A nice tree decomposition of the face pairing graph of this triangulation.

◆ simplices_

MarkedVector<Simplex<dim> > regina::detail::TriangulationBase< dim >::simplices_
protectedinherited

The top-dimensional simplices that form the triangulation.

◆ splittingSurface_

std::optional<bool> regina::Triangulation< 3 >::splittingSurface_
inherited

Does the triangulation have a normal splitting surface?

◆ threeSphere_

std::optional<bool> regina::Triangulation< 3 >::threeSphere_
inherited

Is this a triangulation of a 3-sphere?

◆ topologyLock_

uint8_t regina::detail::TriangulationBase< dim >::topologyLock_
protectedinherited

If non-zero, this will cause Triangulation<dim>::clearAllProperties() to preserve any computed properties that related to the manifold (as opposed to the specific triangulation).

This allows you to avoid recomputing expensive invariants when the underlying manifold is retriangulated.

This property should be managed by creating and destroying TopologyLock objects. The precise value of topologyLock_ indicates the number of TopologyLock objects that currently exist for this triangulation.

◆ turaevViroCache_

TuraevViroSet regina::Triangulation< 3 >::turaevViroCache_
inherited

The set of Turaev-Viro invariants that have already been calculated.

See allCalculatedTuraevViro() for details.

◆ twoSphereBoundaryComponents_

std::optional<bool> regina::Triangulation< 3 >::twoSphereBoundaryComponents_
inherited

Does the triangulation contain any 2-sphere boundary components?

◆ TxI_

std::optional<bool> regina::Triangulation< 3 >::TxI_
inherited

Is this a triangulation of the product TxI?

◆ valid_

bool regina::detail::TriangulationBase< dim >::valid_
protectedinherited

Is this triangulation valid? See isValid() for details on what this means.

◆ zeroEfficient_

std::optional<bool> regina::Triangulation< 3 >::zeroEfficient_
inherited

Is the triangulation zero-efficient?


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

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