Regina Calculation Engine
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends
regina::NNormalSurface Class Reference

Represents a single normal surface in a 3-manifold. More...

#include <surfaces/nnormalsurface.h>

Inheritance diagram for regina::NNormalSurface:
regina::ShareableObject regina::NFilePropertyReader regina::boost::noncopyable

List of all members.

Public Member Functions

 NNormalSurface (NTriangulation *triang, NNormalSurfaceVector *newVector)
 Creates a new normal surface inside the given triangulation with the given coordinate vector.
virtual ~NNormalSurface ()
 Destroys this normal surface.
NNormalSurfaceclone () const
 Creates a newly allocated clone of this normal surface.
NNormalSurfacedoubleSurface () const
 Creates a newly allocated surface that is the double of this surface.
NLargeInteger getTriangleCoord (unsigned long tetIndex, int vertex) const
 Returns the number of triangular discs of the given type in this normal surface.
NLargeInteger getOrientedTriangleCoord (unsigned long tetIndex, int vertex, bool orientation) const
 Returns the number of oriented triangular discs of the given type in this normal surface.
NLargeInteger getQuadCoord (unsigned long tetIndex, int quadType) const
 Returns the number of oriented quadrilateral discs of the given type in this normal surface.
NLargeInteger getOrientedQuadCoord (unsigned long tetIndex, int quadType, bool orientation) const
 Returns the number of oriented quadrilateral discs of the given type in this normal surface.
NLargeInteger getOctCoord (unsigned long tetIndex, int octType) const
 Returns the number of octagonal discs of the given type in this normal surface.
NLargeInteger getEdgeWeight (unsigned long edgeIndex) const
 Returns the number of times this normal surface crosses the given edge.
NLargeInteger getFaceArcs (unsigned long faceIndex, int faceVertex) const
 Returns the number of arcs in which this normal surface intersects the given face in the given direction.
NDiscType getOctPosition () const
 Determines the first coordinate position at which this surface has a non-zero octagonal coordinate.
unsigned getNumberOfCoords () const
 Returns the number of coordinates in the specific underlying coordinate system being used.
NTriangulationgetTriangulation () const
 Returns the triangulation in which this normal surface resides.
const std::string & getName () const
 Returns the name associated with this normal surface.
void setName (const std::string &newName)
 Sets the name associated with this normal surface.
void writeTextShort (std::ostream &out) const
 The text representation will be in standard triangle-quad-oct coordinates.
void writeRawVector (std::ostream &out) const
 Writes the underlying coordinate vector to the given output stream in text format.
virtual void writeXMLData (std::ostream &out) const
 Writes a chunk of XML containing this normal surface and all of its properties.
void writeToFile (NFile &out) const
 Writes this normal surface and all of its properties to the given old-style binary file.
bool isEmpty () const
 Determines if this normal surface is empty (has no discs whatsoever).
bool isCompact () const
 Determines if this normal surface is compact (has finitely many discs).
NLargeInteger getEulerCharacteristic () const
 Returns the Euler characteristic of this surface.
bool isOrientable () const
 Returns whether or not this surface is orientable.
bool isTwoSided () const
 Returns whether or not this surface is two-sided.
bool isConnected () const
 Returns whether or not this surface is connected.
bool hasRealBoundary () const
 Determines if this surface has any real boundary, that is, whether it meets any boundary faces of the triangulation.
bool isVertexLinking () const
 Determines whether or not this surface is vertex linking.
virtual const NVertexisVertexLink () const
 Determines whether or not a rational multiple of this surface is the link of a single vertex.
virtual std::pair< const NEdge
*, const NEdge * > 
isThinEdgeLink () const
 Determines whether or not a rational multiple of this surface is the thin link of a single edge.
bool isSplitting () const
 Determines whether or not this surface is a splitting surface.
NLargeInteger isCentral () const
 Determines whether or not this surface is a central surface.
bool isCompressingDisc (bool knownConnected=false) const
 Determines whether this surface represents a compressing disc in the underlying 3-manifold.
bool isIncompressible () const
 Determines whether this is an incompressible surface within the surrounding 3-manifold.
NTriangulationcutAlong () const
 Cuts the associated triangulation along this surface and returns a newly created resulting triangulation.
NTriangulationcrush () const
 Crushes this surface to a point in the associated triangulation and returns a newly created resulting triangulation.
bool sameSurface (const NNormalSurface &other) const
 Determines whether this and the given surface in fact represent the same normal (or almost normal) surface.
bool locallyCompatible (const NNormalSurface &other) const
 Determines whether this and the given surface are locally compatible.
bool disjoint (const NNormalSurface &other) const
 Determines whether this and the given surface can be placed within the surrounding triangulation so that they do not intersect anywhere at all, without changing either normal isotopy class.
NMatrixIntboundarySlopes () const
 Computes the boundary slopes of this surface at each cusp of the triangulation.
const NNormalSurfaceVectorrawVector () const
 Gives read-only access to the raw vector that sits beneath this normal surface.
- Public Member Functions inherited from regina::ShareableObject
 ShareableObject ()
 Default constructor that does nothing.
virtual ~ShareableObject ()
 Default destructor that does nothing.
virtual void writeTextLong (std::ostream &out) const
 Writes this object in long text format to the given output stream.
std::string toString () const
 Returns the output from writeTextShort() as a string.
std::string toStringLong () const
 Returns the output from writeTextLong() as a string.
- Public Member Functions inherited from regina::NFilePropertyReader
virtual ~NFilePropertyReader ()
 Default destructor that does nothing.

Static Public Member Functions

static NNormalSurfacereadFromFile (NFile &in, int flavour, NTriangulation *triangulation)
 Reads a normal surface and all of its properties from the given old-style binary file.
static NNormalSurfacefindNonTrivialSphere (NTriangulation *tri)
 Searches for a non-vertex-linking normal 2-sphere within the given triangulation.
static NNormalSurfacefindVtxOctAlmostNormalSphere (NTriangulation *tri, bool quadOct=false)
 Searches the list of vertex octagonal almost normal surfaces for an almost normal 2-sphere within the given triangulation.

Protected Member Functions

virtual void readIndividualProperty (NFile &infile, unsigned propType)
 Reads an individual property from an old-style binary file.
void calculateOctPosition () const
 Calculates the position of the first non-zero octagon coordinate and stores it as a property.
void calculateEulerCharacteristic () const
 Calculates the Euler characteristic of this surface and stores it as a property.
void calculateOrientable () const
 Calculates whether this surface is orientable and/or two-sided and stores the results as properties.
void calculateRealBoundary () const
 Calculates whether this surface has any real boundary and stores the result as a property.

Protected Attributes

NNormalSurfaceVectorvector
 Contains the coordinates of the normal surface in whichever space is appropriate.
NTriangulationtriangulation
 The triangulation in which this normal surface resides.
std::string name
 An optional name associated with this surface.
NProperty< NDiscTypeoctPosition
 The position of the first non-zero octagonal coordinate, or NDiscType::NONE if there is no non-zero octagonal coordinate.
NProperty< NLargeIntegereulerChar
 The Euler characteristic of this surface.
NProperty< bool > orientable
 Is this surface orientable?
NProperty< bool > twoSided
 Is this surface two-sided?
NProperty< bool > connected
 Is this surface connected?
NProperty< bool > realBoundary
 Does this surface have real boundary (i.e.
NProperty< bool > compact
 Is this surface compact (i.e.

Friends

class regina::NXMLNormalSurfaceReader

Detailed Description

Represents a single normal surface in a 3-manifold.

Once the underlying triangulation changes, this normal surface object is no longer valid.

The information provided by the various query methods is independent of the underlying coordinate system being used. See the NNormalSurfaceVector class notes for details of what to do when introducing a new flavour of coordinate system.

Note that non-compact surfaces (surfaces with infinitely many discs, such as spun-normal surfaces) are allowed; in these cases, the corresponding coordinate lookup routines will return NLargeInteger::infinity where appropriate.

Test:
Included in the test suite.
Todo:

Feature: Calculation of Euler characteristic and orientability for non-compact surfaces.

Feature (long-term): Determine which faces in the solution space a normal surface belongs to.


Constructor & Destructor Documentation

regina::NNormalSurface::NNormalSurface ( NTriangulation triang,
NNormalSurfaceVector newVector 
)

Creates a new normal surface inside the given triangulation with the given coordinate vector.

Precondition:
The given coordinate vector represents a normal surface inside the given triangulation.
The given coordinate vector cannot be the null pointer.
Python:
Not present.
Parameters:
triangthe triangulation in which this normal surface resides.
newVectora vector containing the coordinates of the normal surface in whichever space is appropriate.
regina::NNormalSurface::~NNormalSurface ( )
inlinevirtual

Destroys this normal surface.

The underlying vector of coordinates will also be deallocated.


Member Function Documentation

NMatrixInt* regina::NNormalSurface::boundarySlopes ( ) const

Computes the boundary slopes of this surface at each cusp of the triangulation.

This is for use with spun-normal surfaces (for closed surfaces all boundary slopes are zero).

The results are returned in a matrix with V rows and two columns, where V is the number of vertices in the triangulation. If row i of the matrix contains the integers M and L, this indicates that at the ith cusp, the boundary curves have algebraic intersection number M with the meridian and L with the longitude. Equivalently, the boundary curves pass L times around the meridian and -M times around the longitude. The rational boundary slope is therefore -L/M, and there are gcd(L,M) boundary curves with this slope.

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.

If this triangulation contains more than one vertex, the rows in the resulting matrix are ordered by vertex number in the triangulation.

Regina can only compute boundary slopes if every vertex link in the triangulation is a torus, and if the underlying coordinate system is for normal surfaces (not almost normal surfaces). If these conditions are not met, this routine will return 0.

Author:
William Pettersson and Stephan Tillmann
Returns:
a newly allocated matrix with number_of_vertices rows and two columns as described above, or 0 if the boundary slopes cannot be computed.
void regina::NNormalSurface::calculateEulerCharacteristic ( ) const
protected

Calculates the Euler characteristic of this surface and stores it as a property.

Precondition:
This normal surface is compact (has finitely many discs).
void regina::NNormalSurface::calculateOctPosition ( ) const
protected

Calculates the position of the first non-zero octagon coordinate and stores it as a property.

void regina::NNormalSurface::calculateOrientable ( ) const
protected

Calculates whether this surface is orientable and/or two-sided and stores the results as properties.

Precondition:
This normal surface is compact (has finitely many discs).
void regina::NNormalSurface::calculateRealBoundary ( ) const
protected

Calculates whether this surface has any real boundary and stores the result as a property.

NNormalSurface* regina::NNormalSurface::clone ( ) const

Creates a newly allocated clone of this normal surface.

The name of the normal surface will not be copied to the clone; instead the clone will have an empty name.

Returns:
a clone of this normal surface.
NTriangulation* regina::NNormalSurface::crush ( ) const

Crushes this surface to a point in the associated triangulation and returns a newly created resulting triangulation.

The original triangulation is not changed.

Crushing the surface will produce a number of tetrahedra, triangular pillows and/or footballs. The pillows and footballs will then be flattened to faces and edges respectively (resulting in the possible changes mentioned below) to produce a proper triangulation.

Note that the new triangulation will have at most the same number of tetrahedra as the old triangulation, and will have strictly fewer tetrahedra if this surface is not vertex linking.

The act of flattening pillows and footballs as described above can lead to unintended topological side-effects, beyond the effects of merely cutting along this surface and identifying the new boundary surface(s) to points. Examples of these unintended side-effects can include connected sum decompositions, removal of 3-spheres and small Lens spaces and so on; a full list of possible changes is beyond the scope of this API documentation.

Warning:
This routine can have unintended topological side-effects, as described above.
In exceptional cases with non-orientable 3-manifolds, these side-effects might lead to invalid edges (edges whose midpoints are projective plane cusps).
Precondition:
This normal surface is compact and embedded.
This normal surface contains no octagonal discs.
Returns:
a pointer to the newly allocated resulting triangulation.
NTriangulation* regina::NNormalSurface::cutAlong ( ) const

Cuts the associated triangulation along this surface and returns a newly created resulting triangulation.

The original triangulation is not changed.

Note that, unlike crushing a surface to a point, this operation will not change the topology of the underlying 3-manifold beyond simply slicing along this surface.

Warning:
The number of tetrahedra in the new triangulation can be very large.
Precondition:
This normal surface is compact and embedded.
This normal surface contains no octagonal discs.
Returns:
a pointer to the newly allocated resulting triangulation.
bool regina::NNormalSurface::disjoint ( const NNormalSurface other) const

Determines whether this and the given surface can be placed within the surrounding triangulation so that they do not intersect anywhere at all, without changing either normal isotopy class.

This is a global constraint, and therefore gives a stronger test than locallyCompatible(). However, this global constraint is also much slower to test; the running time is proportional to the total number of normal discs in both surfaces.

Note that this routine has a number of preconditions. Most importantly, it will only work if both this and the given surface use the same flavour of coordinate system. Running this test over two surfaces with different coordinate systems could give unpredictable results, and might crash the program entirely.

Precondition:
Both this and the given normal surface live within the same 3-manifold triangulation.
Both this and the given normal surface are stored using the same flavour of coordinate system (i.e., the same subclass of NNormalSurfaceVector).
Both this and the given surface are compact (have finitely many discs), embedded, non-empty and connected.
Parameters:
otherthe other surface to test alongside this surface for potential intersections.
Returns:
true if both surfaces can be embedded without intersecting anywhere, or false if this and the given surface are forced to intersect at some point.
NNormalSurface* regina::NNormalSurface::doubleSurface ( ) const

Creates a newly allocated surface that is the double of this surface.

Returns:
the double of this normal surface.
static NNormalSurface* regina::NNormalSurface::findNonTrivialSphere ( NTriangulation tri)
static

Searches for a non-vertex-linking normal 2-sphere within the given triangulation.

If a non-vertex linking normal 2-sphere exists anywhere at all within the triangulation, then this routine is guaranteed to find one.

Note that the surface returned (if any) depends upon the triangulation, and so must be destroyed before the triangulation itself.

Warning:
Currently this routine is quite slow since it involves a full enumeration of vertex normal surfaces.
Todo:
Optimise (urgent): Use maximisation of Euler characteristic to make this routine much faster than a plain vertex enumeration.
Parameters:
trithe triangulation in which to search.
Returns:
a newly allocated non-vertex-linking normal sphere within the given triangulation, or 0 if no such sphere exists.
static NNormalSurface* regina::NNormalSurface::findVtxOctAlmostNormalSphere ( NTriangulation tri,
bool  quadOct = false 
)
static

Searches the list of vertex octagonal almost normal surfaces for an almost normal 2-sphere within the given triangulation.

This means that tubed almost normal 2-spheres or non-vertex octagonal almost normal 2-spheres will not be found.

This search can be done either in standard almost normal coordinates (with triangles, quadrilaterals and octagons), or in quadrilateral-octagon coordinates. This choice of coordinate system affects how we define "vertex". The default is to use standard coordinates (where the set of vertex surfaces is larger).

For "sufficiently nice" triangulations, if this routine fails to find an almost normal 2-sphere then we can be certain that the triangulation contains no almost normal 2-spheres at all. In particular, this is true for closed orientable one-vertex 0-efficient triangulations. For a proof in standard coordinates, see "0-efficient triangulations of 3-manifolds", William Jaco and J. Hyam Rubinstein, J. Differential Geom. 65 (2003), no. 1, 61–168. For a proof in quadrilateral-octagon coordinates, see "Quadrilateral-octagon coordinates for almost normal surfaces", Benjamin A. Burton, Experiment. Math. 19 (2010), 285-315.

Note that the surface that this routine returns (if any) depends upon the triangulation, and so this surface must be destroyed before the triangulation is destroyed.

Warning:
Currently this routine can be quite slow since it performs a full enumeration of vertex almost normal surfaces.
Todo:
Optimise: Use maximisation of Euler characteristic to make this routine much faster than a plain vertex enumeration.
Parameters:
trithe triangulation in which to search.
quadOcttrue if we should search for vertex surfaces in quadrilateral-octagon coordiantes, or false (the default) if we should search for surfaces in standard almost normal coordinates.
Returns:
a newly allocated vertex octagonal almost normal sphere within the given triangulation, or 0 if no such sphere exists.
NLargeInteger regina::NNormalSurface::getEdgeWeight ( unsigned long  edgeIndex) const
inline

Returns the number of times this normal surface crosses the given edge.

Parameters:
edgeIndexthe index in the triangulation of the edge in which we are interested; this should be between 0 and NTriangulation::getNumberOfEdges()-1 inclusive.
Returns:
the number of times this normal surface crosses the given edge.
NLargeInteger regina::NNormalSurface::getEulerCharacteristic ( ) const
inline

Returns the Euler characteristic of this surface.

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately.

Precondition:
This normal surface is compact (has finitely many discs).
Returns:
the Euler characteristic.
NLargeInteger regina::NNormalSurface::getFaceArcs ( unsigned long  faceIndex,
int  faceVertex 
) const
inline

Returns the number of arcs in which this normal surface intersects the given face in the given direction.

Parameters:
faceIndexthe index in the triangulation of the face in which we are interested; this should be between 0 and NTriangulation::getNumberOfFaces()-1 inclusive.
faceVertexthe vertex of the face (0, 1 or 2) around which the arcs of intersection that we are interested in lie; only these arcs will be counted.
Returns:
the number of times this normal surface intersect the given face with the given arc type.
const std::string & regina::NNormalSurface::getName ( ) const
inline

Returns the name associated with this normal surface.

Names are optional and need not be unique. The default name for a surface is the empty string.

Returns:
the name of associated with this surface.
unsigned regina::NNormalSurface::getNumberOfCoords ( ) const
inline

Returns the number of coordinates in the specific underlying coordinate system being used.

Returns:
the number of coordinates.
NLargeInteger regina::NNormalSurface::getOctCoord ( unsigned long  tetIndex,
int  octType 
) const
inline

Returns the number of octagonal discs of the given type in this normal surface.

An octagonal disc type is identified by specifying a tetrahedron and a vertex splitting of that tetrahedron that describes how the octagon partitions the tetrahedron vertices. See vertexSplit for more details on vertex splittings.

If you are using a coordinate system that adorns discs with additional information (such as orientation), this routine returns the total number of octagons in the given tetrahedron of the given type.

Parameters:
tetIndexthe index in the triangulation of the tetrahedron in which the requested octagons reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
octTypethe number of the vertex splitting that this octagon type represents; this should be between 0 and 2 inclusive.
Returns:
the number of octagonal discs of the given type.
NDiscType regina::NNormalSurface::getOctPosition ( ) const
inline

Determines the first coordinate position at which this surface has a non-zero octagonal coordinate.

In other words, if this routine returns the disc type t, then the octagonal coordinate returned by getOctCoord(t.tetIndex, t.type) is non-zero. Here NDiscType::type represents an octagon type within a tetrahedron, and takes values between 0 and 2 inclusive.

If this surface does not contain any octagons, this routine returns NDiscType::NONE instead.

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately. Moreover, if the underlying coordinate system does not support almost normal surfaces, then even the first call is fast (it returns NDiscType::NONE immediately).

Returns:
the position of the first non-zero octagonal coordinate, or NDiscType::NONE if there is no such coordinate.
NLargeInteger regina::NNormalSurface::getOrientedQuadCoord ( unsigned long  tetIndex,
int  quadType,
bool  orientation 
) const
inline

Returns the number of oriented quadrilateral discs of the given type in this normal surface.

This routine is for coordinate systems that support transversely oriented normal surfaces; for details see "The Thurston norm via normal surfaces", Stephan Tillmann and Daryl Cooper, Pacific Journal of Mathematics 239 (2009), 1-15.

An oriented triangular disc type is identified by specifying a tetrahedron, a vertex of that tetrahedron that the triangle surrounds, and a boolean orientation. The true orientation indicates a triangle whose "transverse" orientation points to the nearby vertex, and the false orientation indicates a triangle whose "transverse" orientation points to the opposite face.

An oriented quadrilateral disc type is identified by specifying a tetrahedron, a vertex splitting of that tetrahedron as described in getQuadCoord(), and a boolean orientation. The true orientation indicates a transverse orientation pointing to the edge containing vertex 0 of the tetrahedron, and the false orientation indicates a transverse orientation pointing to the opposite edge.

If the underlying coordinate system does not support transverse orientation, this routine will simply return zero.

Parameters:
tetIndexthe index in the triangulation of the tetrahedron in which the requested quadrilaterals reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
quadTypethe number of the vertex splitting that this quad type represents; this should be between 0 and 2 inclusive.
orientationthe orientation of the quadrilateral disc
Returns:
the number of quadrilateral discs of the given type.
NLargeInteger regina::NNormalSurface::getOrientedTriangleCoord ( unsigned long  tetIndex,
int  vertex,
bool  orientation 
) const
inline

Returns the number of oriented triangular discs of the given type in this normal surface.

This routine is for coordinate systems that support transversely oriented normal surfaces; for details see "The Thurston norm via normal surfaces", Stephan Tillmann and Daryl Cooper, Pacific Journal of Mathematics 239 (2009), 1-15.

An oriented triangular disc type is identified by specifying a tetrahedron, a vertex of that tetrahedron that the triangle surrounds, and a boolean orientation. The true orientation indicates a transverse orientation pointing to the nearby vertex, and the false orientation indicates a transverse orientation pointing to the opposite face.

If the underlying coordinate system does not support transverse orientation, this routine will simply return zero.

Parameters:
tetIndexthe index in the triangulation of the tetrahedron in which the requested triangles reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
vertexthe vertex of the given tetrahedron around which the requested triangles lie; this should be between 0 and 3 inclusive.
orientationthe orientation of the triangle
Returns:
the number of triangular discs of the given type.
NLargeInteger regina::NNormalSurface::getQuadCoord ( unsigned long  tetIndex,
int  quadType 
) const
inline

Returns the number of oriented quadrilateral discs of the given type in this normal surface.

A quadrilateral disc type is identified by specifying a tetrahedron and a vertex splitting of that tetrahedron that describes how the quadrilateral partitions the tetrahedron vertices. See vertexSplit for more details on vertex splittings.

If you are using a coordinate system that adorns discs with additional information (such as orientation), this routine returns the total number of quadrilaterals in the given tetrahedron of the given type.

Parameters:
tetIndexthe index in the triangulation of the tetrahedron in which the requested quadrilaterals reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
quadTypethe number of the vertex splitting that this quad type represents; this should be between 0 and 2 inclusive.
Returns:
the number of quadrilateral discs of the given type.
NLargeInteger regina::NNormalSurface::getTriangleCoord ( unsigned long  tetIndex,
int  vertex 
) const
inline

Returns the number of triangular discs of the given type in this normal surface.

A triangular disc type is identified by specifying a tetrahedron and a vertex of that tetrahedron that the triangle surrounds.

If you are using a coordinate system that adorns discs with additional information (such as orientation), this routine returns the total number of triangles in the given tetrahedron of the given type.

Parameters:
tetIndexthe index in the triangulation of the tetrahedron in which the requested triangles reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
vertexthe vertex of the given tetrahedron around which the requested triangles lie; this should be between 0 and 3 inclusive.
Returns:
the number of triangular discs of the given type.
NTriangulation * regina::NNormalSurface::getTriangulation ( ) const
inline

Returns the triangulation in which this normal surface resides.

Returns:
the underlying triangulation.
bool regina::NNormalSurface::hasRealBoundary ( ) const
inline

Determines if this surface has any real boundary, that is, whether it meets any boundary faces of the triangulation.

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately.

Returns:
true if and only if this surface has real boundary.
NLargeInteger regina::NNormalSurface::isCentral ( ) const
inline

Determines whether or not this surface is a central surface.

A central surface is a compact surface containing at most one normal or almost normal disc per tetrahedron. If this surface is central, the number of tetrahedra that it meets (i.e., the number of discs in the surface) will be returned.

Note that the results of this routine are not cached. Thus the results will be reevaluated every time this routine is called.

Todo:
Optimise: Cache results.
Returns:
the number of tetrahedra that this surface meets if it is a central surface, or 0 if it is not a central surface.
bool regina::NNormalSurface::isCompact ( ) const
inline

Determines if this normal surface is compact (has finitely many discs).

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately.

Returns:
true if and only if this normal surface is compact.
bool regina::NNormalSurface::isCompressingDisc ( bool  knownConnected = false) const

Determines whether this surface represents a compressing disc in the underlying 3-manifold.

Let this surface be D and let the underlying 3-manifold be M with boundary B. To be a compressing disc, D must be a properly embedded disc in M, and the boundary of D must not bound a disc in B.

The implementation of this routine is somewhat inefficient at present, since it cuts along the disc, retriangulates and then examines the resulting boundary components.

Precondition:
This normal surface is compact and embedded.
This normal surface contains no octagonal discs.
Todo:

Optimise: Reimplement this to avoid cutting along surfaces.

Bug: Check for absurdly large numbers of discs and bail accordingly.

Warning:
This routine might cut along the surface and retriangulate, and so may run out of memory if the normal coordinates are extremely large.
Parameters:
knownConnectedtrue if this normal surface is already known to be connected (for instance, if it came from an enumeration of vertex normal surfaces), or false if we should not assume any such information about this surface.
Returns:
true if this surface is a compressing disc, or false if this surface is not a compressing disc.
bool regina::NNormalSurface::isConnected ( ) const
inline

Returns whether or not this surface is connected.

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately.

Precondition:
This normal surface is compact (has finitely many discs).
Warning:
This routine explicitly builds the normal discs, and so may run out of memory if the normal coordinates are extremely large.
Returns:
true if this surface is connected, or false if this surface is disconnected.
bool regina::NNormalSurface::isEmpty ( ) const

Determines if this normal surface is empty (has no discs whatsoever).

bool regina::NNormalSurface::isIncompressible ( ) const

Determines whether this is an incompressible surface within the surrounding 3-manifold.

At present, this routine is only implemented for surfaces embedded within closed 3-manifold triangulations.

Let D be some disc embedded in the underlying 3-manifold, and let B be the boundary of D. We call D a compressing disc for this surface if (i) the intersection of D with this surface is the boundary B, and (ii) although B bounds a disc within the 3-manifold, it does not bound a disc within this surface.

We declare this surface to be incompressible if there are no such compressing discs. For our purposes, spheres are never considered incompressible (so if this surface is a sphere then this routine will always return false).

This test is designed exclusively for two-sided surfaces. If this surface is one-sided, the incompressibility test will be run on its two-sided double cover.

Warning:
This routine can become extremely slow, to the point of infeasibility. This is because the underlying algorithm cuts along this surface, retriangulates (possibly using a very large number of tetrahedra), and then runs a new (exponentially slow) normal surface enumeration.
Precondition:
The underlying 3-manifold triangulation is valid and closed.
The underlying 3-manifold is irreducible.
This normal surface is compact, embedded and connected.
This normal surface contains no octagonal discs.
Returns:
true if this surface is incompressible, or false if this surface is not incompressible (or if it is a sphere).
bool regina::NNormalSurface::isOrientable ( ) const
inline

Returns whether or not this surface is orientable.

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately.

Precondition:
This normal surface is compact (has finitely many discs).
Warning:
This routine explicitly builds the normal discs, and so may run out of memory if the normal coordinates are extremely large.
Returns:
true if this surface is orientable, or false if this surface is non-orientable.
bool regina::NNormalSurface::isSplitting ( ) const
inline

Determines whether or not this surface is a splitting surface.

A splitting surface is a compact surface containing precisely one quad per tetrahedron and no other normal (or almost normal) discs.

Note that the results of this routine are not cached. Thus the results will be reevaluated every time this routine is called.

Todo:
Optimise: Cache results.
Returns:
true if and only if this is a splitting surface.
std::pair< const NEdge *, const NEdge * > regina::NNormalSurface::isThinEdgeLink ( ) const
inlinevirtual

Determines whether or not a rational multiple of this surface is the thin link of a single edge.

If there are two different edges e1 and e2 for which this surface could be expressed as the thin link of either e1 or e2, the pair (e1,e2) will be returned. If this surface is the thin link of only one edge e, the pair (e,0) will be returned. If this surface is not the thin link of any edges, the pair (0,0) will be returned.

Note that the results of this routine are not cached. Thus the results will be reevaluated every time this routine is called.

Todo:
Optimise: Cache results.
Python:
This routine returns a tuple of size 2.
Returns:
a pair containing the edge(s) linked by this surface, as described above.
bool regina::NNormalSurface::isTwoSided ( ) const
inline

Returns whether or not this surface is two-sided.

This routine caches its results, which means that once it has been called for a particular surface, subsequent calls return the answer immediately.

Precondition:
This normal surface is compact (has finitely many discs).
Warning:
This routine explicitly builds the normal discs, and so may run out of memory if the normal coordinates are extremely large.
Returns:
true if this surface is two-sided, or false if this surface is one-sided.
const NVertex * regina::NNormalSurface::isVertexLink ( ) const
inlinevirtual

Determines whether or not a rational multiple of this surface is the link of a single vertex.

Note that the results of this routine are not cached. Thus the results will be reevaluated every time this routine is called.

Todo:
Optimise: Cache results.
Returns:
the vertex linked by this surface, or 0 if this surface is not the link of a single vertex.
bool regina::NNormalSurface::isVertexLinking ( ) const
inline

Determines whether or not this surface is vertex linking.

A vertex linking surface contains only triangles.

Note that the results of this routine are not cached. Thus the results will be reevaluated every time this routine is called.

Todo:
Optimise: Cache results.
Returns:
true if and only if this surface is vertex linking.
bool regina::NNormalSurface::locallyCompatible ( const NNormalSurface other) const

Determines whether this and the given surface are locally compatible.

Local compatibility means that, within each individual tetrahedron of the triangulation, it is possible to arrange the normal discs of both surfaces so that none intersect.

This is a local constraint, not a global constraint. That is, we do not insist that we can avoid intersections within all tetrahedra simultaneously. To test the global constraint, see the (much slower) routine disjoint() instead.

Local compatibility can be formulated in terms of normal disc types. Two normal (or almost normal) surfaces are locally compatible if and only if they together have at most one quadrilateral or octagonal disc type per tetrahedron.

Note again that this is a local constraint only. In particular, for almost normal surfaces, it does not insist that there is at most one octagonal disc type anywhere within the triangulation.

If one of the two surfaces breaks the local compatibility constraints on its own (for instance, it contains two different quadrilateral disc types within the same tetrahedron), then this routine will return false regardless of what the other surface contains.

Precondition:
Both this and the given normal surface live within the same 3-manifold triangulation.
Parameters:
otherthe other surface to test for local compatibility with this surface.
Returns:
true if the two surfaces are locally compatible, or false if they are not.
const NNormalSurfaceVector * regina::NNormalSurface::rawVector ( ) const
inline

Gives read-only access to the raw vector that sits beneath this normal surface.

Generally users should not need this function. However, it is provided here in case the need should arise (e.g., for reasons of efficiency).

Warning:
An NNormalSurface does not know what underlying coordinate system its raw vector uses. Unless you already know the coordinate system in advance (i.e., you created the surface yourself), it is best to keep to the coordinate-system-agnostic access functions such as NNormalSurfaceVector::getTriangleCoord() and NNormalSurfaceVector::getQuadCoord().
Python:
Not present.
Returns:
the underlying raw vector.
static NNormalSurface* regina::NNormalSurface::readFromFile ( NFile in,
int  flavour,
NTriangulation triangulation 
)
static

Reads a normal surface and all of its properties from the given old-style binary file.

The flavour of coordinate system being used must be known in advance and passed to this routine.

This routine reads precisely what writeToFile() writes.

Deprecated:
For the preferred way to read surfaces from file, see class NXMLNormalSurfaceReader instead.
Precondition:
The given file is currently opened for reading.
Python:
Not present.
Parameters:
inthe file from which to read.
flavourthe flavour of coordinate system that the normal surface will use.
triangulationthe triangulation within which this normal surface will lie.
Returns:
a newly allocated normal surface containing the information read from file.
virtual void regina::NNormalSurface::readIndividualProperty ( NFile infile,
unsigned  propType 
)
protectedvirtual

Reads an individual property from an old-style binary file.

The property type and bookmarking details should not read; merely the contents of the property that are written to file between NFile::writePropertyHeader() and NFile::writePropertyFooter(). See the NFile::writePropertyHeader() notes for details.

The property type of the property to be read will be passed in propType. If the property type is unrecognised, this routine should simply do nothing and return. If the property type is recognised, this routine should read the property and process it accordingly (e.g., store it in whatever data object is currently being read).

Parameters:
infilethe file from which to read the property. This should be open for reading and at the position immediately after writePropertyHeader() would have been called during the corresponding write operation.
propTypethe property type of the property about to be read.

Implements regina::NFilePropertyReader.

bool regina::NNormalSurface::sameSurface ( const NNormalSurface other) const

Determines whether this and the given surface in fact represent the same normal (or almost normal) surface.

Specifically, this routine examines (or computes) the number of normal or almost normal discs of each type, and returns true if and only if these counts are the same for both surfaces.

It does not matter what coordinate systems the two surfaces use. In particular, it does not matter if this and the given surface use different coordinate systems, and it does not matter if one surface uses an almost normal coordinate system and the other does not.

Precondition:
Both this and the given normal surface live within the same 3-manifold triangulation.
Parameters:
otherthe surface to be compared with this surface.
Returns:
true if both surfaces represent the same normal or almost normal surface, or false if not.
void regina::NNormalSurface::setName ( const std::string &  newName)
inline

Sets the name associated with this normal surface.

Names are optional and need not be unique. The default name for a surface is the empty string.

Parameters:
newNamethe new name to associate with this surface.
void regina::NNormalSurface::writeRawVector ( std::ostream &  out) const
inline

Writes the underlying coordinate vector to the given output stream in text format.

No indication will be given as to which coordinate system is being used or what each coordinate means. No newline will be written.

Python:
The paramater out does not exist, and is taken to be standard output.
Parameters:
outthe output stream to which to write.
void regina::NNormalSurface::writeTextShort ( std::ostream &  out) const
virtual

The text representation will be in standard triangle-quad-oct coordinates.

Octagonal coordinates will only be written if the surface is of a potentially almost normal flavour.

Python:
The paramater out does not exist, and is taken to be standard output.

Implements regina::ShareableObject.

void regina::NNormalSurface::writeToFile ( NFile out) const

Writes this normal surface and all of its properties to the given old-style binary file.

This routine writes precisely what readFromFile() reads.

Deprecated:
For the preferred way to write data to file, see writeXMLData() instead.
Precondition:
The given file is currently opened for writing.
Python:
Not present.
Parameters:
outthe file to which to write.
virtual void regina::NNormalSurface::writeXMLData ( std::ostream &  out) const
virtual

Writes a chunk of XML containing this normal surface and all of its properties.

This routine will be called from within NNormalSurfaceList::writeXMLPacketData().

Python:
Not present.
Parameters:
outthe output stream to which the XML should be written.

Member Data Documentation

NProperty<bool> regina::NNormalSurface::compact
mutableprotected

Is this surface compact (i.e.

does it only contain finitely many discs)?

NProperty<bool> regina::NNormalSurface::connected
mutableprotected

Is this surface connected?

NProperty<NLargeInteger> regina::NNormalSurface::eulerChar
mutableprotected

The Euler characteristic of this surface.

std::string regina::NNormalSurface::name
protected

An optional name associated with this surface.

NProperty<NDiscType> regina::NNormalSurface::octPosition
mutableprotected

The position of the first non-zero octagonal coordinate, or NDiscType::NONE if there is no non-zero octagonal coordinate.

Here NDiscType::type is an octagon type between 0 and 2 inclusive.

NProperty<bool> regina::NNormalSurface::orientable
mutableprotected

Is this surface orientable?

NProperty<bool> regina::NNormalSurface::realBoundary
mutableprotected

Does this surface have real boundary (i.e.

does it meet any boundary faces)?

NTriangulation* regina::NNormalSurface::triangulation
protected

The triangulation in which this normal surface resides.

NProperty<bool> regina::NNormalSurface::twoSided
mutableprotected

Is this surface two-sided?

NNormalSurfaceVector* regina::NNormalSurface::vector
protected

Contains the coordinates of the normal surface in whichever space is appropriate.


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

Copyright © 1999-2012, The Regina development team
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).