Regina Calculation Engine
Public Types | Public Member Functions | Static Public Member Functions | List of all members
regina::NSnapPeaTriangulation Class Reference

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

#include <snappea/nsnappeatriangulation.h>

Inheritance diagram for regina::NSnapPeaTriangulation:
regina::ShareableObject regina::boost::noncopyable

Public Types

enum  SolutionType {
  not_attempted, geometric_solution, nongeometric_solution, flat_solution,
  degenerate_solution, other_solution, no_solution
}
 Describes the different types of solution that can be found when solving for a complete hyperbolic structure. More...
 

Public Member Functions

 NSnapPeaTriangulation (const NSnapPeaTriangulation &tri)
 Creates a SnapPea clone of the given SnapPea triangulation. More...
 
 NSnapPeaTriangulation (const NTriangulation &tri, bool allowClosed=false)
 Creates a SnapPea clone of the given Regina triangulation. More...
 
 ~NSnapPeaTriangulation ()
 Destroys this triangulation. More...
 
bool isNull () const
 Determines whether this triangulation contains valid SnapPea data. More...
 
SolutionType solutionType () const
 Returns the type of solution found when solving for a complete hyperbolic structure. More...
 
double volume () const
 Computes the volume of the underlying 3-manifold. More...
 
double volume (int &precision) const
 Computes the volume of the underlying 3-manifold and estimates the accuracy of the answer. More...
 
NMatrixIntslopeEquations () const
 Returns a matrix for computing boundary slopes of spun-normal surfaces at the cusps of the triangulation. More...
 
NTriangulationcanonize () const
 Constructs the canonical retriangulation of the canonical cell decomposition. More...
 
void randomize ()
 Asks SnapPea to randomly retriangulate its internal representation of the manifold. More...
 
bool verifyTriangulation (const NTriangulation &triangulation) const
 Verifies that the tetrahedron face gluings from this SnapPea triangulation match the given Regina triangulation precisely. More...
 
NTriangulationtoRegina () const
 Creates a new Regina triangulation that mirrors the internal SnapPea structure. More...
 
void dump () const
 Dumps the underlying SnapPea data to standard output. More...
 
void saveAsSnapPea (const char *filename) const
 Saves the underlying triangulation as a native SnapPea file. More...
 
virtual void writeTextShort (std::ostream &out) const
 Writes this object in short text format to the given output stream. More...
 
- Public Member Functions inherited from regina::ShareableObject
 ShareableObject ()
 Default constructor that does nothing. More...
 
virtual ~ShareableObject ()
 Default destructor that does nothing. More...
 
virtual void writeTextLong (std::ostream &out) const
 Writes this object in long text format to the given output stream. More...
 
std::string str () const
 Returns the output from writeTextShort() as a string. More...
 
std::string toString () const
 A deprecated alias for str(), which returns the output from writeTextShort() as a string. More...
 
std::string detail () const
 Returns the output from writeTextLong() as a string. More...
 
std::string toStringLong () const
 A deprecated alias for detail(), which returns the output from writeTextLong() as a string. More...
 

Static Public Member Functions

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

Additional Inherited Members

- Protected Member Functions inherited from regina::boost::noncopyable
 noncopyable ()
 A constructor which does nothing. More...
 
 ~noncopyable ()
 A destructor which does nothing. More...
 

Detailed Description

Offers direct access to the SnapPea kernel from within Regina.

An object of this class represents a 3-manifold triangulation, stored in SnapPea's internal format. Such an object may be constructed by cloning either a standard Regina triangulation or another SnapPea triangulation.

Note that not all Regina triangulations can be represented in SnapPea format, since Regina works with more general kinds of triangulation than SnapPea does. You should always call isNull() to test whether any Regina-to-SnapPea conversion was successful.

This class is designed to act as the sole conduit between the Regina calculation engine and the SnapPea kernel. Regina code should not interact with the SnapPea kernel other than through this class.

Regina uses the variant of the SnapPea kernel that is shipped with SnapPy, as well as some additional code written explicitly for SnapPy. The SnapPea kernel was written by Jeff Weeks, and SnapPy was written by Marc Culler, Nathan Dunfield, and others. 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.

Test:
Included in the test suite.

Member Enumeration Documentation

Describes the different types of solution that can be found when solving for a complete 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 either positively oriented or flat, though the entire solution is not flat and no tetrahedra are degenerate.

nongeometric_solution 

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

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.

Constructor & Destructor Documentation

regina::NSnapPeaTriangulation::NSnapPeaTriangulation ( const NSnapPeaTriangulation tri)

Creates a SnapPea clone of the given SnapPea triangulation.

This SnapPea triangulation stands independent of tri, so 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.

Note that the tetrahedron and vertex numbers might be changed in the new SnapPea triangulation.

Parameters
trithe SnapPea triangulation to clone.
regina::NSnapPeaTriangulation::NSnapPeaTriangulation ( const NTriangulation tri,
bool  allowClosed = false 
)

Creates a SnapPea clone of the given Regina triangulation.

This SnapPea triangulation stands independent of tri, so this triangulation will not be affected if tri is later changed or destroyed.

Note that, 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.

If the conversion is successful, this constructor will immediately ask SnapPea to try to find a complete hyperbolic structure.

SnapPea is designed primarily to work with ideal triangulations only. Passing closed triangulations can occasionally cause the SnapPea kernel to raise a fatal error, which in turn will crash the entire program. Thus by default, closed triangulations are never converted (a null SnapPea triangulation will be created instead). See the optional argument allowClosed for how to change this behaviour.

Note also that the tetrahedron and vertex numbers might be changed in the new SnapPea triangulation. In particular, if the given triangulation is orientable but not oriented, then you should expect these numbers to change.

Warning
Passing allowClosed as true can occasionally cause the program to crash! See the notes above for details.
Parameters
trithe Regina triangulation to clone.
allowClosedtrue if closed triangulations should be considered, or false if all closed triangulations should give null SnapPea data (the default). See above for details.
regina::NSnapPeaTriangulation::~NSnapPeaTriangulation ( )

Destroys this triangulation.

All internal SnapPea data will also be destroyed.

Member Function Documentation

NTriangulation* regina::NSnapPeaTriangulation::canonize ( ) const

Constructs the canonical retriangulation of the canonical cell decomposition.

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. The canoical retriangulation is defined as follows: If the canonical cell decomposition is already a triangulation then we leave it untouched. Otherwise: (i) within each 3-cell of the original complex we introduce a new internal (finite) vertex and cone the 3-cell boundary to this new vertex, and (ii) for each 2-cell of the original complex we replace the two new cones on either side with a ring of tetrahedra surrounding a new edge that connects the two new vertices on either side. See canonize_part_2.c in the SnapPea source code for details.

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.

Warning
This matches the triangulation produced by SnapPea's version of canonize(). However, it does not match the triangulation produced by SnapPy's version of canonize(). This is because SnapPy returns an arbitrary simplicial subdivision of the canonical cell decomposition, whereas SnapPea follows this with a canonical retriangulation.
Precondition
This is an ideal triangulation, not a closed triangulation.
Returns
the canonical triangulation of the canonical cell decomposition, or 0 if this could not be constructed.
static void regina::NSnapPeaTriangulation::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.

void regina::NSnapPeaTriangulation::dump ( ) const
inline

Dumps the underlying SnapPea data to standard output.

This routine should be regarded primarily as a diagnostic tool for investigating how the SnapPea kernel has modified and/or analysed a triangulation.

Note that the SnapPea data is written using C-style output (i.e., using the stdout file pointer), which may or may not cause unexpected behaviour when used in conjunction with std::cout.

If this triangulation does not contain any valid SnapPea data, this routine will do nothing. See isNull() for further details.

static void regina::NSnapPeaTriangulation::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.
bool regina::NSnapPeaTriangulation::isNull ( ) const
inline

Determines whether this triangulation contains valid SnapPea data.

A null SnapPea triangulation can occur when converting unusual types of Regina triangulation into SnapPea format, since Regina is written to deal with more general types of triangulations than SnapPea.

Returns
true if this is a null triangulation, or false if this triangulation contains valid SnapPea data.
static bool regina::NSnapPeaTriangulation::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.
void regina::NSnapPeaTriangulation::randomize ( )

Asks SnapPea to randomly retriangulate its internal representation of the manifold.

This can help when SnapPea is having difficulty finding a complete hyperbolic structure.

This routine uses SnapPea's own retriangulation code. It is highly likely that, after calling randomize(), the internal SnapPea representation of the manifold will not match the original triangulation passed from Regina. In other words, calling verifyTriangulation() with your original Regina triangulation will most likely return false.

After randomizing, this routine will immediately ask SnapPea to try to find a complete hyperbolic structure.

If this is a null SnapPea triangulation, this routine does nothing.

void regina::NSnapPeaTriangulation::saveAsSnapPea ( const char *  filename) const

Saves the underlying triangulation as a native SnapPea file.

Like dump(), this routine is provided primarily as a diagnostic tool.

For a general export-to-SnapPea method, users are referred to regina::writeSnapPea() instead, which avoids the internal SnapPea conversion entirely and simply writes Regina's native triangulation data in SnapPea's text format.

Passing an empty string as the filename will cause the SnapPea data to be written to standard output, just like dump(). See the dump() documentation for caveats when combining the C-style output of this routine with std::cout.

If this triangulation does not contain any valid SnapPea data, this routine will do nothing. See isNull() for further details.

Parameters
filenamethe name of the SnapPea file to write.
NMatrixInt* regina::NSnapPeaTriangulation::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, and one row for determining the algebraic intersection number with the longitude. If the triangulation has more than one cusp, these pairs are ordered by vertex number in the triangulation. Within each pair, the meridian row always appears before the longitude row.

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 NNormalSurface::boundarySlopes().

This code makes use of the SnapPy kernel, and the choice of meridian and longitude on each cusp follows SnapPy's conventions. In particular, we use the orientations for meridian and longitude from SnapPy. 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.

Precondition
All vertex links in this triangulation must be tori.
Author
William Pettersson and Stephan Tillmann
Returns
a newly allocated matrix with (2 * number_of_cusps) rows and (3 * number_of_tetrahedron) columns as described above, or 0 if this is a null triangulation.
SolutionType regina::NSnapPeaTriangulation::solutionType ( ) const

Returns the type of solution found when solving for a complete hyperbolic structure.

Note that SnapPea distinguishes between a complete hyperbolic structure and a Dehn filled hyperbolic structure. At the present time Regina does not concern itself with Dehn fillings, so only the complete solution type is offered here.

Returns
the solution type.
NTriangulation * regina::NSnapPeaTriangulation::toRegina ( ) const
inline

Creates a new Regina triangulation that mirrors the internal SnapPea structure.

Note that this might be different from the original triangulation that was passed into the NSnapPeaTriangulation constructor, since the SnapPea kernel can sometimes relabel tetrahedra and/or retriangulate the manifold.

The resulting triangulation will be newly created, and it is the responsibility of the caller of this routine to eventually delete it.

Returns
a new Regina triangulation, or null if this is a null SnapPea triangulation (see isNull()).
bool regina::NSnapPeaTriangulation::verifyTriangulation ( const NTriangulation triangulation) const

Verifies that the tetrahedron face gluings from this SnapPea triangulation match the given Regina triangulation precisely.

This is useful if you are not sure whether SnapPea will relabel and/or retriangulate.

This routine is equivalent to testing whether the given triangulation is identical to the triangulation returned by toRegina().

Parameters
triangulationthe triangulation to compare with this SnapPea triangulation.
Returns
true if the tetrahedron face gluings match precisely, or false if the face gluings do not match or if this is a null triangulation.
double regina::NSnapPeaTriangulation::volume ( ) const

Computes the volume of the underlying 3-manifold.

Returns
the volume of the underlying 3-manifold, or 0 if this is a null triangulation.
double regina::NSnapPeaTriangulation::volume ( int &  precision) const

Computes the volume of the underlying 3-manifold and estimates the accuracy of the answer.

Parameters
precisionused to return an estimate of the number of decimal places of accuracy in the calculated volume.
Python:
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.
Returns
the volume of the underlying 3-manifold, or 0 if this is a null triangulation.
virtual void regina::NSnapPeaTriangulation::writeTextShort ( std::ostream &  out) const
virtual

Writes this object in short text format to the given output stream.

The output should be human-readable, should fit on a single line, and should not end with a newline.

Python:
The parameter out does not exist; standard output will be used.
Parameters
outthe output stream to which to write.

Implements regina::ShareableObject.


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

Copyright © 1999-2013, 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@debian.org).