regina::NSnapPeaTriangulation Class Reference
[Triangulations]

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

#include <nsnappeatriangulation.h>

Inheritance diagram for regina::NSnapPeaTriangulation:

regina::ShareableObject regina::boost::noncopyable

List of all members.

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.
 NSnapPeaTriangulation (const NTriangulation &tri, bool allowClosed=false)
 Creates a SnapPea clone of the given Regina triangulation.
 ~NSnapPeaTriangulation ()
 Destroys this triangulation.
bool isNull () const
 Determines whether this triangulation contains valid SnapPea data.
SolutionType solutionType () const
 Returns the type of solution found when solving for a complete hyperbolic structure.
double volume () const
 Computes the volume of the underlying 3-manifold.
double volume (int &precision) const
 Computes the volume of the underlying 3-manifold and estimates the accuracy of the answer.
void dump () const
 Dumps the underlying SnapPea data to standard output.
void saveAsSnapPea (const char *filename) const
 Saves the underlying triangulation as a native SnapPea file.
virtual void writeTextShort (std::ostream &out) const
 Writes this object in short text format to the given output stream.

Static Public Member Functions

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


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

Portions of the SnapPea kernel have been built into Regina as of version 4.2 (July 2005). SnapPea is copyright (c) 1991-2005 by Jeff Weeks, and is distributed under the terms of the GNU General Public License.

See http://www.geometrygames.org/SnapPea/ for further information on SnapPea.

Test:
Tested in the test suite, though not exhaustively.

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:
tri the 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 is written with a different purpose from 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.

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.

Warning:
Passing allowClosed as true can occasionally cause the program to crash! See the notes above for details.
Parameters:
tri the Regina triangulation to clone.
allowClosed true 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

void regina::NSnapPeaTriangulation::disableKernelMessages (  )  [inline, 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 enabled by default.

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.

void regina::NSnapPeaTriangulation::enableKernelMessages ( bool  enabled = true  )  [inline, static]

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

By default such diagnostic messages are enabled.

Parameters:
enabled true 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 different types of triangulations from SnapPea.

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

bool regina::NSnapPeaTriangulation::kernelMessagesEnabled (  )  [inline, static]

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

By default such diagnostic messages are enabled. To disable them, call disableKernelMessages().

Returns:
true if and only if diagonstic messages are enabled.

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:
filename the name of the SnapPea file to write.

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.

double regina::NSnapPeaTriangulation::volume ( int &  precision  )  const

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

Parameters:
precision used 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.

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.

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 fit on a single line and no newline should be written.

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

Implements regina::ShareableObject.


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

Copyright © 1999-2008, Ben Burton
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).