regina::NNormalSurface Class Reference
[Normal Surfaces]

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

#include <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 getQuadCoord (unsigned long tetIndex, int quadType) const
 Returns the number of quadrilateral discs of the given type in this normal surface.
NLargeInteger getOctCoord (unsigned long tetIndex, int octType) const
 Returns the number of octahedral 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.
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 isCompact () const
 Determines if this normal surface is compact (has finitely many discs).
NLargeInteger getEulerCharacteristic () const
 Returns the Euler characteristic of this surface.
NTriBool isOrientable () const
 Returns whether or not this surface is orientable.
NTriBool isTwoSided () const
 Returns whether or not this surface is two-sided.
NTriBool 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 link of a single thin 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.
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 knownCanCrush () const
 Determines whether this surface can be crushed to a point in the associated triangulation with no unintended topological side-effects.

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)
 Searches the 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 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.
void calculateKnownCanCrush () const
 Calculates whether it can be quickly determined that this surface can be crushed to a point without unintended topological side-effects.

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
< NLargeInteger
eulerChar
 The Euler characteristic of this surface.
NProperty< NTriBoolorientable
 Is this surface orientable?
NProperty< NTriBooltwoSided
 Is this surface two-sided?
NProperty< NTriBoolconnected
 Is this surface connected?
NProperty< bool > realBoundary
 Does this surface have real boundary (i.e.
NProperty< bool > compact
 Is this surface compact (i.e.
NProperty< bool > canCrush
 Can this surface be crushed without unintended topological side-effects?

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:
Tested in the test suite, though not exhaustively.
Todo:
Feature: Calculation of Euler characteristic and orientability for non-compact surfaces.
Todo:
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:
triang the triangulation in which this normal surface resides.
newVector a vector containing the coordinates of the normal surface in whichever space is appropriate.

regina::NNormalSurface::~NNormalSurface (  )  [inline, virtual]

Destroys this normal surface.

The underlying vector of coordinates will also be deallocated.


Member Function Documentation

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

Creates a newly allocated clone of this normal surface.

Returns:
a clone of this normal surface.

NNormalSurface* regina::NNormalSurface::doubleSurface (  )  const

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

Returns:
the double of this normal surface.

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.

Parameters:
tetIndex the index in the triangulation of the tetrahedron in which the requested triangles reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
vertex the 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.

NLargeInteger regina::NNormalSurface::getQuadCoord ( unsigned long  tetIndex,
int  quadType 
) const [inline]

Returns the number of 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.

Parameters:
tetIndex the index in the triangulation of the tetrahedron in which the requested quadrilaterals reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
quadType the 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::getOctCoord ( unsigned long  tetIndex,
int  octType 
) const [inline]

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

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

Parameters:
tetIndex the index in the triangulation of the tetrahedron in which the requested octahedrons reside; this should be between 0 and NTriangulation::getNumberOfTetrahedra()-1 inclusive.
octType the number of the vertex splitting that this octahedron type represents; this should be between 0 and 2 inclusive.
Returns:
the number of octahedral discs of the given type.

NLargeInteger regina::NNormalSurface::getEdgeWeight ( unsigned long  edgeIndex  )  const [inline]

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

Parameters:
edgeIndex the 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::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:
faceIndex the index in the triangulation of the face in which we are interested; this should be between 0 and NTriangulation::getNumberOfFaces()-1 inclusive.
faceVertex the 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.

unsigned regina::NNormalSurface::getNumberOfCoords (  )  const [inline]

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

Returns:
the number of coordinates.

NTriangulation * regina::NNormalSurface::getTriangulation (  )  const [inline]

Returns the triangulation in which this normal surface resides.

Returns:
the underlying triangulation.

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.

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:
newName the new name to associate with this surface.

void regina::NNormalSurface::writeTextShort ( std::ostream &  out  )  const [virtual]

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

Octahedral 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::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:
out the output stream 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:
out the output stream to which the XML should be written.

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:
out the file to which to write.

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:
in the file from which to read.
flavour the flavour of coordinate system that the normal surface will use.
triangulation the triangulation within which this normal surface will lie.
Returns:
a newly allocated normal surface containing the information read from file.

bool regina::NNormalSurface::isCompact (  )  const [inline]

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

Returns:
true if and only if this normal surface is compact.

NLargeInteger regina::NNormalSurface::getEulerCharacteristic (  )  const [inline]

Returns the Euler characteristic of this surface.

Precondition:
This normal surface is compact (has finitely many discs).
Returns:
the Euler characteristic.

NTriBool regina::NNormalSurface::isOrientable (  )  const [inline]

Returns whether or not this surface is orientable.

This routine returns an NTriBool since it is possible that the result cannot be determined (for instance, if there are too many normal discs).

Precondition:
This normal surface is compact (has finitely many discs).
Returns:
true if this surface is orientable, false if this surface is non-orientable and unknown if orientability cannot be determined.

NTriBool regina::NNormalSurface::isTwoSided (  )  const [inline]

Returns whether or not this surface is two-sided.

This routine returns an NTriBool since it is possible that the result cannot be determined (for instance, if there are too many normal discs).

Precondition:
This normal surface is compact (has finitely many discs).
Returns:
true if this surface is two-sided, false if this surface is one-sided and unknown if two-sidedness cannot be determined.

NTriBool regina::NNormalSurface::isConnected (  )  const [inline]

Returns whether or not this surface is connected.

This routine returns an NTriBool since it is possible that the result cannot be determined (for instance, if there are too many normal discs).

Precondition:
This normal surface is compact (has finitely many discs).
Returns:
true if this surface is connected, false if this surface is not connected and unknown if connectedness cannot be determined.

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.

Returns:
true if and only if this surface has real boundary.

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.

const NVertex * regina::NNormalSurface::isVertexLink (  )  const [inline, virtual]

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.

std::pair< const NEdge *, const NEdge * > regina::NNormalSurface::isThinEdgeLink (  )  const [inline, virtual]

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

If there are two different thin edges e1 and e2 for which this surface could be expressed as either the link of e1 or the link of e2, the pair (e1,e2) will be returned. If this surface is the link of only one thin edge e, the pair (e,0) will be returned. If this surface is not the link of any thin 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 thin edge(s) linked by this surface, as described above.

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.

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.

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.

This routine has not been implemented and so currently returns an empty triangulation.

Precondition:
This normal surface is compact and embedded.

This normal surface contains no octahedral discs.

Todo:
Feature: Implement this routine.
Returns:
a pointer to the newly allocated resulting triangulation.

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.

Routine knownCanCrush() can be used to help identify whether these unintended side-effects might occur.

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

Returns:
a pointer to the newly allocated resulting triangulation.

bool regina::NNormalSurface::knownCanCrush (  )  const [inline]

Determines whether this surface can be crushed to a point in the associated triangulation with no unintended topological side-effects.

Note that this routine cannot determine that there will be unintended side-effects; it will either determine that there won't be unintended side-effects or it will remain inconclusive.

Unintended side-effects include any topological change other than the pure topological effects of cutting along this surface and then identifying the new boundary surface(s) to points.

These unintended side-effects can occur when the algorithm used by the crush() routine collapses pillows and footballs to obtain a proper triangulation. Some examples of the side-effects that can occur are given in the documentation for the crush() routine.

Warning:
Currently this routine always returns false, i.e., an inconclusive result. Its abilities are expected to improve with future releases.
Precondition:
This normal surface is compact and embedded.

This normal surface contains no octahedral discs.

Todo:
Feature: Implement this routine! At least for embedded 2-spheres.
Returns:
true if this routine determines that this surface can be crushed without unintended side-effects, or false if this routine cannot produce a definite answer.

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:
tri the 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  )  [static]

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

Only the vertex octagonal almost normal surfaces will be examined, i.e., if there is a tubed almost normal 2-sphere or a non-vertex octagonal almost normal 2-sphere then it is not guaranteed to be found.

In some cases however (such as with closed orientable one-vertex 0-efficient triangulations), it is known that if any almost normal 2-sphere exists then an octagonal almost normal 2-sphere exists at a vertex of the solution space (and so will be found by this routine). It is up to the caller of this routine to decide whether results such as this are applicable to the problem at hand.

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 performs a full enumeration of vertex almost normal surfaces.
Todo:
Optimise (urgent): Use maximisation of Euler characteristic to make this routine much faster than a plain vertex enumeration.
Parameters:
tri the triangulation in which to search.
Returns:
a newly allocated vertex octagonal almost normal sphere within the given triangulation, or 0 if no such sphere exists.

virtual void regina::NNormalSurface::readIndividualProperty ( NFile infile,
unsigned  propType 
) [protected, virtual]

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:
infile the 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.
propType the property type of the property about to be read.

Implements regina::NFilePropertyReader.

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

void regina::NNormalSurface::calculateKnownCanCrush (  )  const [protected]

Calculates whether it can be quickly determined that this surface can be crushed to a point without unintended topological side-effects.

If conclusive, the result is stored as a property.


Member Data Documentation

NNormalSurfaceVector* regina::NNormalSurface::vector [protected]

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

NTriangulation* regina::NNormalSurface::triangulation [protected]

The triangulation in which this normal surface resides.

std::string regina::NNormalSurface::name [protected]

An optional name associated with this surface.

NProperty<NLargeInteger> regina::NNormalSurface::eulerChar [mutable, protected]

The Euler characteristic of this surface.

NProperty<NTriBool> regina::NNormalSurface::orientable [mutable, protected]

Is this surface orientable?

NProperty<NTriBool> regina::NNormalSurface::twoSided [mutable, protected]

Is this surface two-sided?

NProperty<NTriBool> regina::NNormalSurface::connected [mutable, protected]

Is this surface connected?

NProperty<bool> regina::NNormalSurface::realBoundary [mutable, protected]

Does this surface have real boundary (i.e.

does it meet any boundary faces)?

NProperty<bool> regina::NNormalSurface::compact [mutable, protected]

Is this surface compact (i.e.

does it only contain finitely many discs)?

NProperty<bool> regina::NNormalSurface::canCrush [mutable, protected]

Can this surface be crushed without unintended topological side-effects?


The documentation for this class was generated from the following file:
Copyright © 1999-2006, 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).