SnapPea Triangulations

## Classes

class | regina::ExampleSnapPea
| This class offers routines for constructing various example SnapPea triangulations. More...
struct | regina::SnapPeaException
| A base class for all exceptions that are thrown from within the SnapPea kernel. More...
struct | regina::SnapPeaFatalError
| An exception that is thrown when the SnapPea kernel encounters a fatal error. More...
struct | regina::SnapPeaMemoryFull
| An exception that is thrown when the SnapPea kernel finds that all available memory has been exhausted. More...
class | regina::Cusp
| Represents a single cusp of a SnapPea triangulation. More...
class | regina::SnapPeaTriangulation
| Offers direct access to the SnapPea kernel from within Regina. More...
class | regina::XMLSnapPeaReader
| An XML packet reader that reads a single SnapPea triangulation. More...

## Typedefs

typedef ExampleSnapPea | regina::NExampleSnapPeaTriangulation
| Deprecated typedef for backward compatibility. More...
typedef Cusp | regina::NCusp
| Deprecated typedef for backward compatibility. More...
typedef SnapPeaTriangulation | regina::NSnapPeaTriangulation
| Deprecated typedef for backward compatibility. More...

## Enumerations

enum

regina::SnapPeaTriangulation::SolutionType {
regina::SnapPeaTriangulation::not_attempted, regina::SnapPeaTriangulation::geometric_solution, regina::SnapPeaTriangulation::nongeometric_solution, regina::SnapPeaTriangulation::flat_solution,
regina::SnapPeaTriangulation::degenerate_solution, regina::SnapPeaTriangulation::other_solution, regina::SnapPeaTriangulation::no_solution, regina::SnapPeaTriangulation::externally_computed
}

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

## Functions

static SnapPeaTriangulation * | regina::ExampleSnapPea::gieseking ()
| Returns a new triangulation of the Gieseking manifold. More...
static SnapPeaTriangulation * | regina::ExampleSnapPea::figureEight ()
| Returns a new triangulation of the figure eight knot complement. More...
static SnapPeaTriangulation * | regina::ExampleSnapPea::trefoil ()
| Returns a new triangulation of the trefoil knot complement. More...
static SnapPeaTriangulation * | regina::ExampleSnapPea::whiteheadLink ()
| Returns a new triangulation of the Whitehead link complement. More...
static SnapPeaTriangulation * | regina::ExampleSnapPea::x101 ()
| Returns a new triangulation of the census manifold `x101`. More...
| regina::SnapPeaFatalError::SnapPeaFatalError (const char *fromFunction, const char *fromFile)
| Creates a new exception, indicating where in the SnapPea kernel the error occurred. More...
Vertex< 3 > * | regina::Cusp::vertex () const
| Returns the corresponding vertex of the Regina triangulation (i.e., of the Triangulation<3> structure that is inherited by SnapPeaTriangulation). More...
bool | regina::Cusp::complete () const
| Returns whether this cusp is complete. More...
int | regina::Cusp::m () const
| Returns the first (meridian) filling coefficient on this cusp, or 0 if this cusp is complete. More...
int | regina::Cusp::l () const
| Returns the second (longitude) filling coefficient on this cusp, or 0 if this cusp is complete. More...
void | regina::Cusp::writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
| regina::XMLSnapPeaReader::XMLSnapPeaReader (XMLTreeResolver &resolver)
| Creates a new SnapPea triangulation reader. More...
virtual Packet * | regina::XMLSnapPeaReader::packet () override
| Returns the newly allocated packet that has been read by this element reader. More...
virtual XMLElementReader * | regina::XMLSnapPeaReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
| Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
virtual void | regina::XMLSnapPeaReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader) override
| Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...

## Variables

std::string | regina::SnapPeaFatalError::function
| The function from the SnapPea kernel in which the fatal error occurred. More...
std::string | regina::SnapPeaFatalError::file
| The source file from the SnapPea kernel in which the fatal error occurred. More...

## Friends

class | regina::Cusp::SnapPeaTriangulation
| Allow access to private members. More...

## Constructors and Destructors

| regina::SnapPeaTriangulation::SnapPeaTriangulation ()
| Creates a null triangulation, with no internal SnapPea data at all. More...
| regina::SnapPeaTriangulation::SnapPeaTriangulation (const std::string &fileNameOrContents)
| Creates a new SnapPea triangulation from the contents of SnapPea data file. More...
| regina::SnapPeaTriangulation::SnapPeaTriangulation (const SnapPeaTriangulation &tri)
| Creates a clone of the given SnapPea triangulation. More...
| regina::SnapPeaTriangulation::SnapPeaTriangulation (const Triangulation< 3 > &tri, bool ignored=false)
| Converts the given Regina triangulation to a SnapPea triangulation. More...
| regina::SnapPeaTriangulation::~SnapPeaTriangulation ()
| Destroys this triangulation. More...

## Basic Properties

bool | regina::SnapPeaTriangulation::isNull () const
| Determines whether this triangulation contains valid SnapPea data. More...
std::string | regina::SnapPeaTriangulation::name () const
| Returns SnapPea's internal name for this triangulation. More...

## Hyperbolic Structures

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). More...
double | regina::SnapPeaTriangulation::volume () const
| Computes the volume of the current solution to the hyperbolic gluing equations. More...
double | regina::SnapPeaTriangulation::volume (int &precision) const
| Computes the volume of the current solution to the hyperbolic gluing equations, and estimates the accuracy of the answer. More...
bool | regina::SnapPeaTriangulation::volumeZero () const
| Determines whether the current solution to the gluing equations has volume approximately zero. More...
const std::complex< double > & | regina::SnapPeaTriangulation::shape (unsigned tet) const
| Returns the shape of the given tetrahedron, with respect to the Dehn filled hyperbolic structure. More...
double | regina::SnapPeaTriangulation::minImaginaryShape () const
| Returns the minimum imaginary part found amongst all tetrahedron shapes, with respect to the Dehn filled hyperbolic structure. More...
MatrixInt * | regina::SnapPeaTriangulation::gluingEquations () const
| Returns a matrix describing Thurston's gluing equations. More...
MatrixInt * | regina::SnapPeaTriangulation::gluingEquationsRect () const
| Returns a matrix describing Thurston's gluing equations in a streamlined form. More...

## Cusps

unsigned | regina::SnapPeaTriangulation::countCusps () const
| Returns the total number of cusps (both filled and complete). More...
unsigned | regina::SnapPeaTriangulation::countCompleteCusps () const
| Returns the total number of complete cusps (that is, unfilled cusps). More...
unsigned | regina::SnapPeaTriangulation::countFilledCusps () const
| Returns the total number of filled cusps. More...
const Cusp * | regina::SnapPeaTriangulation::cusp (unsigned whichCusp=0) const
| Returns information about the given cusp of this manifold. More...
bool | regina::SnapPeaTriangulation::fill (int m, int l, unsigned whichCusp=0)
| Assigns a Dehn filling to the given cusp. More...
void | regina::SnapPeaTriangulation::unfill (unsigned whichCusp=0)
| Removes any filling on the given cusp. More...
Triangulation< 3 > * | regina::SnapPeaTriangulation::filledTriangulation (unsigned whichCusp) const
| Retriangulates to permanently fill the given cusp. More...
Triangulation< 3 > * | regina::SnapPeaTriangulation::filledTriangulation () const
| Retriangulates to permanently fill all non-complete cusps. More...
MatrixInt * | regina::SnapPeaTriangulation::slopeEquations () const
| Returns a matrix for computing boundary slopes of spun-normal surfaces at the cusps of the triangulation. More...

## Algebraic Invariants

const AbelianGroup * | regina::SnapPeaTriangulation::homologyFilled () const
| Returns the first homology group of the manifold with respect to the current Dehn filling (if any). More...
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). More...

## Manipulating SnapPea triangulations

SnapPeaTriangulation * | regina::SnapPeaTriangulation::protoCanonize () const
| Constructs the canonical cell decomposition, using an arbitrary retriangulation if this decomposition contains non-tetrahedron cells. More...
SnapPeaTriangulation * | regina::SnapPeaTriangulation::protoCanonise () const
| A synonym for protoCanonize(), which constructs the canonical cell decomposition using an arbitrary retriangulation if necessary. More...
Triangulation< 3 > * | regina::SnapPeaTriangulation::canonize () const
| Constructs the canonical retriangulation of the canonical cell decomposition. More...
Triangulation< 3 > * | regina::SnapPeaTriangulation::canonise () const
| A synonym for canonize(), which constructs the canonical retriangulation of the canonical cell decomposition. More...
void | regina::SnapPeaTriangulation::randomize ()
| Asks SnapPea to randomly retriangulate this manifold, using local moves that preserve the topology. More...
void | regina::SnapPeaTriangulation::randomise ()
| A synonym for randomize(), which asks SnapPea to randomly retriangulate this manifold. More...

## SnapPea kernel messages

static bool | regina::SnapPeaTriangulation::kernelMessagesEnabled ()
| Returns whether or not the SnapPea kernel writes diagnostic messages to standard output. More...
static void | regina::SnapPeaTriangulation::enableKernelMessages (bool enabled=true)
| Configures whether or not the SnapPea kernel should write diagnostic messages to standard output. More...
static void | regina::SnapPeaTriangulation::disableKernelMessages ()
| Specifies that the SnapPea kernel should not write diagnostic messages to standard output. More...

## SnapPea Input and Output

virtual std::string | regina::SnapPeaTriangulation::snapPea () const
| Returns a string containing the full contents of a SnapPea data file that describes this triangulation. More...
virtual 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. More...
virtual bool | regina::SnapPeaTriangulation::saveSnapPea (const char *filename) const
| Writes this triangulation to the given file using SnapPea's native file format. More...

## Packet Administration

virtual void | regina::SnapPeaTriangulation::writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
virtual void | regina::SnapPeaTriangulation::writeTextLong (std::ostream &out) const
| Writes a detailed text representation of this object to the given output stream. More...
virtual bool | regina::SnapPeaTriangulation::dependsOnParent () const
| Determines if this packet depends upon its parent. More...
static XMLPacketReader * | regina::SnapPeaTriangulation::xmlReader (Packet *parent, XMLTreeResolver &resolver)

## Packet Listener Interface

class | regina::XMLSnapPeaReader
virtual void | regina::SnapPeaTriangulation::packetWasChanged (Packet *packet)
| Called after the contents of the packet have been changed. More...
virtual Packet * | regina::SnapPeaTriangulation::internalClonePacket (Packet *parent) const
| Makes a newly allocated copy of this packet. More...
virtual void | regina::SnapPeaTriangulation::writeXMLPacketData (std::ostream &out) const
| Writes a chunk of XML containing the data for this packet only. More...

## Detailed Description

Interfaces for accessing the SnapPea kernel

## Typedef Documentation

## NCusp

typedef Cusp regina::NCusp

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NCusp has now been renamed to Cusp.

## NExampleSnapPeaTriangulation

typedef ExampleSnapPea regina::NExampleSnapPeaTriangulation

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NExampleSnapPeaTriangulation has now been renamed to ExampleSnapPea.

## NSnapPeaTriangulation

typedef SnapPeaTriangulation regina::NSnapPeaTriangulation

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NSnapPeaTriangulation has now been renamed to SnapPeaTriangulation.

## Enumeration Type Documentation

## SolutionType

enum regina::SnapPeaTriangulation::SolutionType

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

Although this enumeration is identical to SnapPea's own SolutionType, it is declared again in this class because Regina code should not in general be interacting 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.

## Function Documentation

## canonise()

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

inline

A synonym for canonize(), which constructs the canonical retriangulation of the canonical cell decomposition.

See canonize() for further details.

## canonize()

Triangulation<3>* regina::SnapPeaTriangulation::canonize | ( |  | ) | 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 protoCanonize() instead.

The resulting triangulation will be newly allocated, and it is the responsibility of the caller of this routine to destroy it.

If for any reason either Regina or SnapPea are unable to construct the canonical retriangulation of the canonical cell decomposition, this routine will return 0.

SnapPy:\n The function canonize() 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::protoCanonize() corresponds to SnapPy's `Manifold.canonize()` and the SnapPea kernel's `proto_canonize(manifold)`. Regina's routine SnapPeaTriangulation::canonize() 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. However, it guarantees that the manifold that it does compute is homeomorphic to the original.

Returns
  the canonical triangulation of the canonical cell decomposition, or 0 if this could not be constructed.

## complete()

bool regina::Cusp::complete | ( |  | ) | const

inline

Returns whether this cusp is complete.

SnapPy:\n In SnapPy, this field corresponds to querying
  `Manifold.cusp_info('is_complete')[cusp_number]`.

Returns
  `true` if this cusp is complete, or `false` if it is filled.

## 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:\n 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.

## 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.num_cusps()`.

Returns
  the total number of cusps.

## countFilledCusps()

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

inline

Returns the total number of filled cusps.

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

SnapPy:\n 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.

## 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:\n 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. They are preserved if you change the fillings (via fill() or unfill()). However, if you change the SnapPea triangulation itself (e.g., via randomize()), then all cusp objects will be deleted and replaced with new ones (using fresh data re-fetched from the SnapPea kernel).

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

  whichCusp | the index of a cusp according to SnapPea; this must be between 0 and countCusps()-1 inclusive.

Returns
  information about the given cusp, or 0 if this is a null triangulation.

## dependsOnParent()

bool regina::SnapPeaTriangulation::dependsOnParent | ( |  | ) | const

inline virtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
  `true` if and only if this packet depends on its parent.

Reimplemented from regina::Triangulation< 3 >.

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

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

  enabled | `true` if diagnostic messages should be enabled, or `false` otherwise.

## endContentSubElement()

virtual void regina::XMLSnapPeaReader::endContentSubElement | ( | const std::string & | subTagName,
|  | XMLElementReader * | subReader
| ) |  |

override virtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLPacketReader.

## figureEight()

static SnapPeaTriangulation* regina::ExampleSnapPea::figureEight | ( |  | ) |

static

Returns a new triangulation of the figure eight knot complement.

Returns
  a newly constructed SnapPea triangulation, which must be destroyed by the caller of this routine.

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

  m | the first (meridional) filling coefficient.
  l | the second (longitudinal) filling coefficient.
  whichCusp | the 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).

## filledTriangulation() [1/2]

Triangulation<3>* regina::SnapPeaTriangulation::filledTriangulation | ( |  | ) | const

Retriangulates to permanently fill all non-complete cusps.

This uses the current Dehn filling coefficients on the cusps, as set by fill().

If every cusp of this triangulation is complete, this routine will simply return a new clone of this triangulation.

If some but not all cusps are complete, then the result will be a new instance of SnapPeaTriangulation, and will have fewer cusps. Note that the remaining cusps may 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 all cusps of this triangulation have filling coefficients assigned, then the result will be a new instance of Triangulation<3> (not SnapPeaTriangulation), and will represent a closed manifold.

Whatever happens, the result will be a newly allocated triangulation, and it is the responsibility of the caller of this routine to destroy it. The original triangulation (this object) will be left unchanged. If this is a null triangulation, then this routine will simply return 0.

Returns
  the new filled triangulation, or 0 if this is a null triangulation.

## filledTriangulation() [2/2]

Triangulation<3>* regina::SnapPeaTriangulation::filledTriangulation | ( | unsigned | whichCusp | ) | const

Retriangulates to permanently fill the given cusp.

This uses the current Dehn filling coefficients on the cusp, as set by fill().

If this triangulation has more than one cusp to begin with, then the result will be a new instance of SnapPeaTriangulation, and will have one fewer cusp. Note that the remaining cusps may be reindexed, and all Cusp structures will be destroyed and rebuilt. Auxiliary information on the remaining cusps (such as filling coefficients and peripheral curves) will be preserved, and SnapPea will automatically attempt to compute a hyperbolic structure on the new triangulation.

If this triangulation has only one cusp, then the result will be a new instance of Triangulation<3> (not SnapPeaTriangulation), and will represent a closed manifold.

Either way, the result will be a newly allocated triangulation, and it is the responsibility of the caller of this routine to destroy it. The original triangulation (this object) will be left unchanged. If the given cusp is complete or if this is a null triangulation, then this routine will simply return 0.

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

  whichCusp | the index of the cusp to permanently fill according to SnapPea; this must be between 0 and countCusps()-1 inclusive.

Returns
  the new filled triangulation or 0 if the filling was not possible (as described above).

## 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 fundamentalGroup() routine from the parent Triangulation<3> class:

- This routine fundamentalGroupFilled() respects Dehn fillings, and directly uses SnapPea's code to compute fundamental groups.
- The inherited fundamentalGroup() 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 pointer 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.

Parameters

  simplifyPresentation | `true` 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.
  fillingsMayAffectGenerators | `true` 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.
  minimiseNumberOfGenerators | `true` 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.
  tryHardToShortenRelators | `true` 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, or 0 if this could not be computed.

## gieseking()

static SnapPeaTriangulation* regina::ExampleSnapPea::gieseking | ( |  | ) |

static

Returns a new triangulation of the Gieseking manifold.

Returns
  a newly constructed SnapPea triangulation, which must be destroyed by the caller of this routine.

## 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) + ... = 2 pi i`, and with right hand side `2 pi 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.gluing_equations()`.

Returns
  a newly allocated matrix with (number_of_rows + number_of_cusps) rows and (3 * number_of_tetrahedra) columns as described above, or 0 if this is a null triangulation.

## 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.gluing_equations(form='rect')`.

Returns
  a newly allocated matrix with (number_of_rows + number_of_cusps) rows and (2 * number_of_tetrahedra + 1) columns as described above, or 0 if this is a null triangulation.

## 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 return a null pointer.
- 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 and returns `null` in such cases), and then Regina uses exact integer arithmetic to solve for the abelian group invariants (i.e., Smith normal form).

The situations in which this routine might return `null` are the following:

- This is a null triangulation (i.e., isNull() returns `true`);
- The filling coefficients as stored in SnapPea are integers, but are so large that SnapPea was not able to build the relation matrix without integer overflow.

Note that each time the triangulation changes, the homology group will be deleted. Thus the pointer 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.

Returns
  the first homology group of the filled manifold, or 0 if this could not be computed.

## internalClonePacket()

Packet * regina::SnapPeaTriangulation::internalClonePacket | ( | Packet * | parent | ) | const

inline protected virtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters

  parent | the parent beneath which the new packet will eventually be inserted.

Returns
  the newly allocated packet.

Reimplemented from regina::Triangulation< 3 >.

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

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

## l()

int regina::Cusp::l | ( |  | ) | const

inline

Returns the second (longitude) filling coefficient on this cusp, or 0 if this cusp is complete.

SnapPy:\n In SnapPy, this field corresponds to querying
  `Manifold.cusp_info('filling')[cusp_number][1]`.

Returns
  the second filling coefficient.

## m()

int regina::Cusp::m | ( |  | ) | const

inline

Returns the first (meridian) filling coefficient on this cusp, or 0 if this cusp is complete.

SnapPy:\n In SnapPy, this field corresponds to querying
  `Manifold.cusp_info('filling')[cusp_number][0]`.

Returns
  the first filling coefficient.

## 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:\n 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.

## 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.name()`.

Returns
  SnapPea's name for this triangulation.

## packet()

Packet * regina::XMLSnapPeaReader::packet | ( |  | ) |

inline override virtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
  the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

## packetWasChanged()

virtual void regina::SnapPeaTriangulation::packetWasChanged | ( | Packet * | packet | ) |

virtual

Called after the contents of the packet have been changed.

Before the contents are changed, packetToBeChanged() will be called also.

The default implementation of this routine is to do nothing.

Parameters

  packet | the packet being listened to.

Reimplemented from regina::PacketListener.

## protoCanonise()

SnapPeaTriangulation * regina::SnapPeaTriangulation::protoCanonise | ( |  | ) | const

inline

A synonym for protoCanonize(), which constructs the canonical cell decomposition using an arbitrary retriangulation if necessary.

See canonize() for further details.

## protoCanonize()

SnapPeaTriangulation* regina::SnapPeaTriangulation::protoCanonize | ( |  | ) | 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 canonize() instead.

The resulting triangulation will be newly allocated, and it is the responsibility of the caller of this routine to destroy it.

If for any reason either Regina or SnapPea are unable to construct a triangulation of the canonical cell decomposition, then this routine will return 0.

SnapPy:\n The function canonize() 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::protoCanonize() corresponds to SnapPy's `Manifold.canonize()` and the SnapPea kernel's `proto_canonize(manifold)`. Regina's routine SnapPeaTriangulation::canonize() 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. However, it guarantees that the manifold that it does compute is homeomorphic to the original.

Returns
  the canonical triangulation of the canonical cell decomposition, or 0 if this could not be constructed.

## randomise()

void regina::SnapPeaTriangulation::randomise | ( |  | ) |

inline

A synonym for randomize(), which asks SnapPea to randomly retriangulate this manifold.

See randomize() for further details.

## randomize()

void regina::SnapPeaTriangulation::randomize | ( |  | ) |

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 randomizing, 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.randomize()`.

## saveSnapPea()

virtual bool regina::SnapPeaTriangulation::saveSnapPea | ( | const char * | filename | ) | const

virtual

Writes this triangulation to the given file using SnapPea's native file format.

Regarding what gets stored in the SnapPea data file:

- If you are calling this from one of Regina's own Triangulation<3> objects, then only the tetrahedron gluings and the manifold name will be stored (the name will be derived from the packet label). All other SnapPea-specific information (such as peripheral curves) will be marked as unknown (since Regina does not track such information itself), and of course other Regina-specific information (such as the Turaev-Viro invariants) will not be written to the SnapPea file at all.
- If you are calling this from the subclass SnapPeaTriangulation, then all additional SnapPea-specific information will be written to the file (indeed, the SnapPea kernel itself will be used to produce the file contents).

If this triangulation is empty, invalid, or contains boundary triangles (which SnapPea cannot represent), then the file will not be written and this routine will return `false`.

Internationalisation:\n 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

  filename | the name of the SnapPea file to which to write.

Returns
  `true` if and only if the file was successfully written.

Reimplemented from regina::Triangulation< 3 >.

## shape()

const std::complex< double > & regina::SnapPeaTriangulation::shape | ( | unsigned | 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.tetrahedra_shapes(part='rect')[tet]`.

Parameters

  tet | the index of a tetrahedron; this must be between 0 and size()-1 inclusive.

Returns
  the shape of the given tetrahedron, in rectangular form.

## 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:\n 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.

Author
  William Pettersson and Stephan Tillmann

Returns
  a newly allocated matrix with (2 * number_of_cusps) rows and (3 * number_of_tetrahedra) columns as described above, or 0 if this is a null triangulation.

## snapPea() [1/2]

virtual std::string regina::SnapPeaTriangulation::snapPea | ( |  | ) | const

virtual

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

Regarding what gets stored in the SnapPea data file:

- If you are calling this from one of Regina's own Triangulation<3> objects, then only the tetrahedron gluings and the manifold name will be stored (the name will be derived from the packet label). All other SnapPea-specific information (such as peripheral curves) will be marked as unknown (since Regina does not track such information itself), and of course other Regina-specific information (such as the Turaev-Viro invariants) will not be written to the SnapPea file at all.
- If you are calling this from the subclass SnapPeaTriangulation, then all additional SnapPea-specific information will be written to the file (indeed, the SnapPea kernel itself will be used to produce the file contents).

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

If this triangulation is empty, invalid, or contains boundary triangles (which SnapPea cannot represent), then the resulting string will be empty.

Returns
  a string containing the contents of the corresponding SnapPea data file.

Reimplemented from regina::Triangulation< 3 >.

## snapPea() [2/2]

virtual void regina::SnapPeaTriangulation::snapPea | ( | std::ostream & | out | ) | const

virtual

Writes the full contents of a SnapPea data file describing this triangulation to the given output stream.

Regarding what gets stored in the SnapPea data file:

- If you are calling this from one of Regina's own Triangulation<3> objects, then only the tetrahedron gluings and the manifold name will be stored (the name will be derived from the packet label). All other SnapPea-specific information (such as peripheral curves) will be marked as unknown (since Regina does not track such information itself), and of course other Regina-specific information (such as the Turaev-Viro invariants) will not be written to the SnapPea file at all.
- If you are calling this from the subclass SnapPeaTriangulation, then all additional SnapPea-specific information will be written to the file (indeed, the SnapPea kernel itself will be used to produce the file contents).

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

If this triangulation is empty, invalid, or contains boundary triangles (which SnapPea cannot represent), then nothing will be written to the output stream.

Python:\n Not present.

Parameters

  out | the output stream to which the SnapPea data file will be written.

Reimplemented from regina::Triangulation< 3 >.

## SnapPeaFatalError()

regina::SnapPeaFatalError::SnapPeaFatalError | ( | const char * | fromFunction,
|  | const char * | fromFile
| ) |  |

inline

Creates a new exception, indicating where in the SnapPea kernel the error occurred.

Parameters

  fromFunction | the function from the SnapPea kernel in which the error occurred.
  fromFile | the source file from the SnapPea kernel in which the error occurred.

## SnapPeaTriangulation() [1/4]

regina::SnapPeaTriangulation::SnapPeaTriangulation | ( |  | ) |

inline

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

## SnapPeaTriangulation() [2/4]

regina::SnapPeaTriangulation::SnapPeaTriangulation | ( | const SnapPeaTriangulation & | tri | ) |

Creates a clone of the given SnapPea triangulation.

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

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

Parameters

  tri | the SnapPea triangulation to clone.

## SnapPeaTriangulation() [3/4]

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 is successful, this constructor will immediately ask SnapPea to try to find a hyperbolic structure.

If this operation fails (e.g., if the given string does not represent a valid SnapPea data file), then this will be a null triangulation. You can test for this by calling isNull().

The triangulation will automatically be given a packet label based on the manifold name stored in the second line of the SnapPea data file.

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:\n 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).

Parameters

  fileNameOrContents | either the name of a SnapPea data file, or the contents of a SnapPea data file (which need not actually exist on the filesystem).

## SnapPeaTriangulation() [4/4]

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

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

## 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.solution_type()`.

Returns
  the solution type.

## startContentSubElement()

XMLElementReader * regina::XMLSnapPeaReader::startContentSubElement | ( | const std::string & | subTagName,
|  | const regina::xml::XMLPropertyDict & | subTagProps
| ) |  |

inline override virtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters

  subTagName | the name of the subelement opening tag.
  subTagProps | the properties associated with the subelement opening tag.

Returns
  a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLPacketReader.

## trefoil()

static SnapPeaTriangulation* regina::ExampleSnapPea::trefoil | ( |  | ) |

static

Returns a new triangulation of the trefoil knot complement.

Returns
  a newly constructed SnapPea triangulation, which must be destroyed by the caller of this routine.

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

  whichCusp | the index of the cusp to unfill according to SnapPea; this must be between 0 and countCusps()-1 inclusive.

## vertex()

Vertex< 3 > * regina::Cusp::vertex | ( |  | ) | const

inline

Returns the corresponding vertex of the Regina triangulation (i.e., of the Triangulation<3> structure that is inherited by SnapPeaTriangulation).

Note that cusp and vertex indexing might not be in sync; that is, SnapPea's `cusp(i)` need not correspond to Regina's `vertex(i)`.

This routine can be used to detect if/when cusp numbering and vertex numbering fall out of sync, and to translate between them if/when this happens.

## volume() [1/2]

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:\n In SnapPy, this routine corresponds to calling
  `Manifold.volume()`.

Returns
  the estimated volume of the underlying 3-manifold, or 0 if this is a null triangulation.

## volume() [2/2]

double regina::SnapPeaTriangulation::volume | ( | int & | precision | ) | 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:\n In SnapPy, this routine corresponds to calling
  `Manifold.volume(accuracy=True)`.

Python:\n The precision argument is not present.
  Instead, two routines are offered. The routine volume() takes no arguments and returns the volume only, whereas the routine volumeWithPrecision() takes no arguments and returns a (volume, precision) tuple.

Parameters

  precision | used to return an estimate of the number of decimal places of accuracy in the calculated volume.

Returns
  the estimated volume of the underlying 3-manifold, or 0 if this is a null triangulation.

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

## whiteheadLink()

static SnapPeaTriangulation* regina::ExampleSnapPea::whiteheadLink | ( |  | ) |

static

Returns a new triangulation of the Whitehead link complement.

Returns
  a newly constructed SnapPea triangulation, which must be destroyed by the caller of this routine.

## writeTextLong()

virtual void regina::SnapPeaTriangulation::writeTextLong | ( | std::ostream & | out | ) | const

virtual

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

This may be reimplemented by subclasses, but the parent Packet class offers a reasonable default implementation.

Python:\n Not present.

Parameters

  out | the output stream to which to write.

Reimplemented from regina::Triangulation< 3 >.

## writeTextShort() [1/2]

void regina::Cusp::writeTextShort | ( | std::ostream & | out | ) | const

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

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort() [2/2]

virtual void regina::SnapPeaTriangulation::writeTextShort | ( | std::ostream & | out | ) | const

virtual

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

This must be reimplemented by subclasses.

Python:\n Not present.

Parameters

  out | the output stream to which to write.

Reimplemented from regina::Triangulation< 3 >.

## writeXMLPacketData()

virtual void regina::SnapPeaTriangulation::writeXMLPacketData | ( | std::ostream & | out | ) | const

protected virtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters

  out | the output stream to which the XML should be written.

Reimplemented from regina::Triangulation< 3 >.

## x101()

static SnapPeaTriangulation* regina::ExampleSnapPea::x101 | ( |  | ) |

static

Returns a new triangulation of the census manifold `x101`.

Returns
  a newly constructed SnapPea triangulation, which must be destroyed by the caller of this routine.

## XMLSnapPeaReader()

regina::XMLSnapPeaReader::XMLSnapPeaReader | ( | XMLTreeResolver & | resolver | ) |

inline

Creates a new SnapPea triangulation reader.

Parameters

  resolver | the master resolver that will be used to fix dangling packet references after the entire XML file has been read.

## ~SnapPeaTriangulation()

regina::SnapPeaTriangulation::~SnapPeaTriangulation | ( |  | ) |

Destroys this triangulation.

All internal SnapPea data will also be destroyed.

## Variable Documentation

## file

std::string regina::SnapPeaFatalError::file

The source file from the SnapPea kernel in which the fatal error occurred.

## function

std::string regina::SnapPeaFatalError::function

The function from the SnapPea kernel in which the fatal error occurred.

## Friends

## SnapPeaTriangulation

friend class SnapPeaTriangulation

friend

Allow access to private members.

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