regina::NormalSurface Class Reference
Normal Surfaces

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

`#include <surfaces/normalsurface.h>`

Inheritance diagram for regina::NormalSurface:

## Public Member Functions

| NormalSurface (const Triangulation< 3 > *triang, NormalSurfaceVector *newVector)
| Creates a new normal surface inside the given triangulation with the given coordinate vector. More...
| NormalSurface (const Triangulation< 3 > *triang, NormalCoords coordSystem, List allCoords)
| A Python-only routine that creates a new normal surface inside the given triangulation with the given coordinate vector. More...
| ~NormalSurface ()
| Destroys this normal surface. More...
NormalSurface * | clone () const
| Creates a newly allocated clone of this normal surface. More...
NormalSurface * | doubleSurface () const
| Creates a newly allocated surface that is the double of this surface. More...
LargeInteger | triangles (size_t tetIndex, int vertex) const
| Returns the number of triangular discs of the given type in this normal surface. More...
LargeInteger | orientedTriangles (size_t tetIndex, int vertex, bool orientation) const
| Returns the number of oriented triangular discs of the given type in this normal surface. More...
LargeInteger | quads (size_t tetIndex, int quadType) const
| Returns the number of quadrilateral discs of the given type in this normal surface. More...
LargeInteger | orientedQuads (size_t tetIndex, int quadType, bool orientation) const
| Returns the number of oriented quadrilateral discs of the given type in this normal surface. More...
LargeInteger | octs (size_t tetIndex, int octType) const
| Returns the number of octagonal discs of the given type in this normal surface. More...
LargeInteger | edgeWeight (size_t edgeIndex) const
| Returns the number of times this normal surface crosses the given edge. More...
LargeInteger | arcs (size_t triIndex, int triVertex) const
| Returns the number of arcs in which this normal surface intersects the given triangle in the given direction. More...
DiscType | octPosition () const
| Determines the first coordinate position at which this surface has a non-zero octagonal coordinate. More...
size_t | countCoords () const
| Returns the number of coordinates in the specific underlying coordinate system being used. More...
const Triangulation< 3 > * | triangulation () const
| Returns the triangulation in which this normal surface resides. More...
const std::string & | name () const
| Returns the name associated with this normal surface. More...
void | setName (const std::string &newName)
| Sets the name associated with this normal surface. More...
void | writeTextShort (std::ostream &out) const
| Writes this surface to the given output stream, using standard triangle-quad-oct coordinates. More...
void | writeRawVector (std::ostream &out) const
| Writes the underlying coordinate vector to the given output stream in text format. More...
void | writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this normal surface and all of its properties. More...
bool | isEmpty () const
| Determines if this normal surface is empty (has no discs whatsoever). More...
bool | isCompact () const
| Determines if this normal surface is compact (has finitely many discs). More...
LargeInteger | eulerChar () const
| Returns the Euler characteristic of this surface. More...
bool | isOrientable () const
| Returns whether or not this surface is orientable. More...
bool | isTwoSided () const
| Returns whether or not this surface is two-sided. More...
bool | isConnected () const
| Returns whether or not this surface is connected. More...
bool | hasRealBoundary () const
| Determines if this surface has any real boundary, that is, whether it meets any boundary triangles of the triangulation. More...
bool | isVertexLinking () const
| Determines whether or not this surface is vertex linking. More...
const Vertex< 3 > * | isVertexLink () const
| Determines whether or not a rational multiple of this surface is the link of a single vertex. More...
std::pair< const Edge< 3 > *, const Edge< 3 > * > | isThinEdgeLink () const
| Determines whether or not a rational multiple of this surface is the thin link of a single edge. More...
bool | isSplitting () const
| Determines whether or not this surface is a splitting surface. More...
LargeInteger | isCentral () const
| Determines whether or not this surface is a central surface. More...
bool | isCompressingDisc (bool knownConnected=false) const
| Determines whether this surface represents a compressing disc in the underlying 3-manifold. More...
bool | isIncompressible () const
| Determines whether this is an incompressible surface within the surrounding 3-manifold. More...
Triangulation< 3 > * | cutAlong () const
| Cuts the associated triangulation along this surface and returns a newly created resulting triangulation. More...
Triangulation< 3 > * | crush () const
| Crushes this surface to a point in the associated triangulation and returns a newly created resulting triangulation. More...
bool | sameSurface (const NormalSurface &other) const
| Determines whether this and the given surface in fact represent the same normal (or almost normal) surface. More...
bool | normal () const
| Determines whether this surface contains only triangle and/or quadrilateral discs. More...
bool | embedded () const
| Determines whether this surface is embedded. More...
bool | locallyCompatible (const NormalSurface &other) const
| Determines whether this and the given surface are locally compatible. More...
bool | disjoint (const NormalSurface &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. More...
MatrixInt * | boundaryIntersections () const
| Computes the information about the boundary slopes of this surface at each cusp of the triangulation. More...
const Ray & | rawVector () const
| Gives read-only access to the raw vector that sits beneath this normal surface. More...
bool | systemAllowsAlmostNormal () const
| Determines if the underlying coordinate system being used allows for almost normal surfaces, that is, allows for octagonal discs. More...
bool | systemAllowsSpun () const
| Determines if the underlying coordinate system being used allows for spun normal surfaces. More...
bool | systemAllowsOriented () const
| Determines if the underlying coordinate system being used allows for transversely oriented normal surfaces. More...
void | writeTextLong (std::ostream &out) const
| A default implementation for detailed output. More...
std::string | str () const
| Returns a short text representation of this object. More...
std::string | utf8 () const
| Returns a short text representation of this object using unicode characters. More...
std::string | detail () const
| Returns a detailed text representation of this object. More...

## Protected Member Functions

void | calculateOctPosition () const
| Calculates the position of the first non-zero octagon coordinate and stores it as a property. More...
void | calculateEulerChar () const
| Calculates the Euler characteristic of this surface and stores it as a property. More...
void | calculateOrientable () const
| Calculates whether this surface is orientable and/or two-sided and stores the results as properties. More...
void | calculateRealBoundary () const
| Calculates whether this surface has any real boundary and stores the result as a property. More...

## Protected Attributes

NormalSurfaceVector * | vector
| Contains the coordinates of the normal surface in whichever space is appropriate. More...
const Triangulation< 3 > * | triangulation_
| The triangulation in which this normal surface resides. More...
std::string | name_
| An optional name associated with this surface. More...
Property< DiscType > | octPosition_
| The position of the first non-zero octagonal coordinate, or DiscType::NONE if there is no non-zero octagonal coordinate. More...
Property< LargeInteger > | eulerChar_
| The Euler characteristic of this surface. More...
Property< bool > | orientable
| Is this surface orientable? More...
Property< bool > | twoSided
| Is this surface two-sided? More...
Property< bool > | connected
| Is this surface connected? More...
Property< bool > | realBoundary
| Does this surface have real boundary (i.e. More...
Property< bool > | compact
| Is this surface compact (i.e. More...

## Friends

class | XMLNormalSurfaceReader

## 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 NormalSurfaceVector class notes for details of what to do when introducing a new 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 LargeInteger::infinity where appropriate.

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

## NormalSurface() [1/2]

regina::NormalSurface::NormalSurface | ( | const Triangulation< 3 > * | triang,
|  | NormalSurfaceVector * | newVector
| ) |  |

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

This normal surface will claim ownership of the given vector (i.e., you should not change or delete the vector yourself afterwards).

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.

## NormalSurface() [2/2]

regina::NormalSurface::NormalSurface | ( | const Triangulation< 3 > * | triang,
|  | NormalCoords | coordSystem,
|  | List | allCoords
| ) |  |

A Python-only routine that creates a new normal surface inside the given triangulation with the given coordinate vector.

Precondition
  The given coordinate system is one in which Regina is able to enumerate and store normal surfaces (not a system like regina::NS_EDGE_WEIGHT, which is for viewing purposes only).
  The given coordinate vector represents a normal surface inside the given triangulation (in particular, it satisfies the relevant system of matching equations). This will not be checked, and things will go wrong if you break it.

C++:
  Not available; this routine is for Python only.

Parameters

  triang | the triangulation in which this normal surface resides.
  coordSystem | the coordinate system used by this normal surface.
  allCoords | the corresponding vector of normal coordinates, expressed as a Python list. The list elements will be converted internally to LargeInteger objects.

## ~NormalSurface()

regina::NormalSurface::~NormalSurface | ( |  | ) |

inline

Destroys this normal surface.

The underlying vector of coordinates will also be deallocated.

## Member Function Documentation

## arcs()

LargeInteger regina::NormalSurface::arcs | ( | size_t | triIndex,
|  | int | triVertex
| ) |  | const

inline

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

Parameters

  triIndex | the index in the triangulation of the triangle in which we are interested; this should be between 0 and Triangulation<3>::countTriangles()-1 inclusive.
  triVertex | the vertex of the triangle (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 triangle with the given arc type.

## boundaryIntersections()

MatrixInt* regina::NormalSurface::boundaryIntersections | ( |  | ) | const

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

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

This routine is only available for use with SnapPea triangulations, since it needs to know the specific meridian and longitude on each cusp. This information is only available through the SnapPea kernel, since Regina does not use or store peripheral curves for its own Triangulation<3> class. Therefore, if the underlying triangulation (as returned by triangulation()) is not of the subclass SnapPeaTriangulation, this routine will simply return 0.

All cusps are treated as complete. That is, any Dehn fillings stored in the SnapPea triangulation will be ignored.

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.

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 the triangulation contains more than one vertex, the rows in the resulting matrix are ordered by cusp index (as stored by SnapPea). You can call SnapPeaTriangulation::cuspVertex() to map these to Regina's vertex indices if needed.

At present, Regina can only compute boundary slopes if the triangulation is oriented, 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 (e.g., if the underlying triangulation is not of type SnapPeaTriangulation, or if it fails to meet the preconditions outlined above).

## calculateEulerChar()

void regina::NormalSurface::calculateEulerChar | ( |  | ) | 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).

## calculateOctPosition()

void regina::NormalSurface::calculateOctPosition | ( |  | ) | const

protected

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

## calculateOrientable()

void regina::NormalSurface::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).

## calculateRealBoundary()

void regina::NormalSurface::calculateRealBoundary | ( |  | ) | const

protected

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

## clone()

NormalSurface* regina::NormalSurface::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.

## countCoords()

size_t regina::NormalSurface::countCoords | ( |  | ) | const

inline

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

Returns
  the number of coordinates.

## crush()

Triangulation<3>* regina::NormalSurface::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 triangles 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.

## cutAlong()

Triangulation<3>* regina::NormalSurface::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.

## detail()

std::string regina::Output< NormalSurface , supportsUtf8 >::detail | ( |  | ) | const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns
  a detailed text representation of this object.

## disjoint()

bool regina::NormalSurface::disjoint | ( | const NormalSurface & | 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 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 coordinate system (i.e., the same subclass of NormalSurfaceVector).
  Both this and the given surface are compact (have finitely many discs), embedded, non-empty and connected.

Parameters

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

## doubleSurface()

NormalSurface* regina::NormalSurface::doubleSurface | ( |  | ) | const

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

Returns
  the double of this normal surface.

## edgeWeight()

LargeInteger regina::NormalSurface::edgeWeight | ( | size_t | 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 Triangulation<3>::countEdges()-1 inclusive.

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

## embedded()

bool regina::NormalSurface::embedded | ( |  | ) | const

Determines whether this surface is embedded.

This is true if and only if the surface contains no conflicting quadrilateral and/or octagon types.

Returns
  `true` if and only if this surface is embedded.

## eulerChar()

LargeInteger regina::NormalSurface::eulerChar | ( |  | ) | 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.

## hasRealBoundary()

bool regina::NormalSurface::hasRealBoundary | ( |  | ) | const

inline

Determines if this surface has any real boundary, that is, whether it meets any boundary triangles 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.

## isCentral()

LargeInteger regina::NormalSurface::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.

## isCompact()

bool regina::NormalSurface::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.

## isCompressingDisc()

bool regina::NormalSurface::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

  knownConnected | `true` 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.

## isConnected()

bool regina::NormalSurface::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.

## isEmpty()

bool regina::NormalSurface::isEmpty | ( |  | ) | const

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

## isIncompressible()

bool regina::NormalSurface::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 and irreducible 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 may in some circumstances be extremely slow. This is because the underlying algorithm cuts along this surface, retriangulates (possibly using a very large number of tetrahedra), and then searches for a normal compressing disc in each component of the cut-open triangulation.

Precondition
  The underlying triangulation is valid and closed, and represents an irreducible 3-manifold.
  This normal surface is compact, embedded and connected, and 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).

## isOrientable()

bool regina::NormalSurface::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.

## isSplitting()

bool regina::NormalSurface::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.

## isThinEdgeLink()

std::pair< const Edge< 3 > *, const Edge< 3 > * > regina::NormalSurface::isThinEdgeLink | ( |  | ) | const

inline

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.

## isTwoSided()

bool regina::NormalSurface::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.

## isVertexLink()

const Vertex< 3 > * regina::NormalSurface::isVertexLink | ( |  | ) | const

inline

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.

## isVertexLinking()

bool regina::NormalSurface::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.

## locallyCompatible()

bool regina::NormalSurface::locallyCompatible | ( | const NormalSurface & | 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

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

## name()

const std::string & regina::NormalSurface::name | ( |  | ) | 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.

## normal()

bool regina::NormalSurface::normal | ( |  | ) | const

inline

Determines whether this surface contains only triangle and/or quadrilateral discs.

This is to distinguish normal surfaces from more general surfaces such as almost normal surfaces (which also contain octagonal pieces).

Even if the underlying coordinate system supports other disc types (such as octagons), this routine will still return `true` if this particular surface does not use them. This is in contrast to the routine NormalSurfaces::allowsAlmostNormal(), which only examines the underlying coordinate system.

Returns
  `true` if and only if this surface contains only triangles and/or quadrilaterals.

## octPosition()

DiscType regina::NormalSurface::octPosition | ( |  | ) | 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 octs(t.tetIndex, t.type) is non-zero. Here DiscType::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 DiscType::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 DiscType::NONE immediately).

Returns
  the position of the first non-zero octagonal coordinate, or DiscType::NONE if there is no such coordinate.

## octs()

LargeInteger regina::NormalSurface::octs | ( | size_t | tetIndex,
|  | int | octType
| ) |  | const

inline

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

In each tetrahedron, there are three types of octagons, defined by how they separate the four tetrahedron vertices into two pairs. Octagon type i (for i = 0, 1 or 2) is defined to intersect edges i and (5-i) of the tetrahedron twice each, and to intersect the remaining edges once each. This means:

- type 0 separates vertices 0,1 of the tetrahedron from vertices 2,3;
- type 1 separates vertices 0,2 of the tetrahedron from vertices 1,3;
- type 2 separates vertices 0,3 of the tetrahedron from vertices 1,2.

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

  tetIndex | the index in the triangulation of the tetrahedron in which the requested octagons reside; this should be between 0 and Triangulation<3>::size()-1 inclusive.
  octType | the type of this octagon in the given tetrahedron; this should be 0, 1 or 2, as described above.

Returns
  the number of octagonal discs of the given type.

## orientedQuads()

LargeInteger regina::NormalSurface::orientedQuads | ( | size_t | 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 quadrilateral disc type is identified by specifying a tetrahedron, a quadrilateral type (0, 1 or 2) as described in quads(), 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

  tetIndex | the index in the triangulation of the tetrahedron in which the requested quadrilaterals reside; this should be between 0 and Triangulation<3>::size()-1 inclusive.
  quadType | the type of this quadrilateral in the given tetrahedron; this should be 0, 1 or 2, as described above.
  orientation | the orientation of the quadrilateral disc

Returns
  the number of quadrilateral discs of the given type.

## orientedTriangles()

LargeInteger regina::NormalSurface::orientedTriangles | ( | size_t | 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

  tetIndex | the index in the triangulation of the tetrahedron in which the requested triangles reside; this should be between 0 and Triangulation<3>::size()-1 inclusive.
  vertex | the vertex of the given tetrahedron around which the requested triangles lie; this should be between 0 and 3 inclusive.
  orientation | the orientation of the triangle

Returns
  the number of triangular discs of the given type.

## quads()

LargeInteger regina::NormalSurface::quads | ( | size_t | tetIndex,
|  | int | quadType
| ) |  | const

inline

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

In each tetrahedron, there are three types of quadrilaterals, defined by how they separate the four tetrahedron vertices into two pairs. Quadrilateral type i (for i = 0, 1 or 2) is defined to separate edge i of the tetrahedron from edge (5-i). That is:

- type 0 separates vertices 0,1 of the tetrahedron from vertices 2,3;
- type 1 separates vertices 0,2 of the tetrahedron from vertices 1,3;
- type 2 separates vertices 0,3 of the tetrahedron from vertices 1,2.

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

  tetIndex | the index in the triangulation of the tetrahedron in which the requested quadrilaterals reside; this should be between 0 and Triangulation<3>::size()-1 inclusive.
  quadType | the type of this quadrilateral in the given tetrahedron; this should be 0, 1 or 2, as described above.

Returns
  the number of quadrilateral discs of the given type.

## rawVector()

const Ray & regina::NormalSurface::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
  A NormalSurface 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 NormalSurfaceVector::triangles() and NormalSurfaceVector::quads().

Python:
  Not present.

Returns
  the underlying raw vector.

## sameSurface()

bool regina::NormalSurface::sameSurface | ( | const NormalSurface & | 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

  other | the surface to be compared with this surface.

Returns
  `true` if both surfaces represent the same normal or almost normal surface, or `false` if not.

## setName()

void regina::NormalSurface::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.

## str()

std::string regina::Output< NormalSurface , supportsUtf8 >::str | ( |  | ) | const

inherited

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
  In addition to str(), this is also used as the Python "stringification" function `__str__()`.

Returns
  a short text representation of this object.

## systemAllowsAlmostNormal()

bool regina::NormalSurface::systemAllowsAlmostNormal | ( |  | ) | const

inline

Determines if the underlying coordinate system being used allows for almost normal surfaces, that is, allows for octagonal discs.

This is a property of the coordinate system in which this surface is natively stored, not a property of the surface itself. For example, if this surface has no octagons but is stored using standard almost normal coordinates, then this routine will return `true`.

Returns
  `true` if and only if almost normal surfaces are allowed in the underlying coordinate system.

## systemAllowsOriented()

bool regina::NormalSurface::systemAllowsOriented | ( |  | ) | const

inline

Determines if the underlying coordinate system being used allows for transversely oriented normal surfaces.

Returns
  `true` if and only if transverse orientations are supported in the underlying coordinate system.

## systemAllowsSpun()

bool regina::NormalSurface::systemAllowsSpun | ( |  | ) | const

inline

Determines if the underlying coordinate system being used allows for spun normal surfaces.

This is a property of the coordinate system in which this surface is natively stored, not a property of the surface itself. For example, if this surface is compact but is stored using quad coordinates, then this routine will return `true`.

Returns
  `true` if and only if spun normal surface are supported in the underlying coordinate system.

## triangles()

LargeInteger regina::NormalSurface::triangles | ( | size_t | 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

  tetIndex | the index in the triangulation of the tetrahedron in which the requested triangles reside; this should be between 0 and Triangulation<3>::size()-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.

## triangulation()

const Triangulation< 3 > * regina::NormalSurface::triangulation | ( |  | ) | const

inline

Returns the triangulation in which this normal surface resides.

Returns
  the underlying triangulation.

## utf8()

std::string regina::Output< NormalSurface , supportsUtf8 >::utf8 | ( |  | ) | const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
  a short text representation of this object.

## writeRawVector()

void regina::NormalSurface::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.

## writeTextLong()

void regina::ShortOutput< NormalSurface , false >::writeTextLong | ( | std::ostream & | out | ) | const

inline inherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort()

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

Writes this surface to the given output stream, using standard triangle-quad-oct coordinates.

Octagonal coordinates will only be written if the surface is stored using a coordinate system that supports almost normal surfaces.

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## writeXMLData()

void regina::NormalSurface::writeXMLData | ( | std::ostream & | out | ) | const

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

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

Python:
  Not present.

Parameters

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

## Member Data Documentation

## compact

Property<bool> regina::NormalSurface::compact

mutable protected

Is this surface compact (i.e.

does it only contain finitely many discs)?

## connected

Property<bool> regina::NormalSurface::connected

mutable protected

Is this surface connected?

## eulerChar_

Property<LargeInteger> regina::NormalSurface::eulerChar_

mutable protected

The Euler characteristic of this surface.

## name_

std::string regina::NormalSurface::name_

protected

An optional name associated with this surface.

## octPosition_

Property<DiscType> regina::NormalSurface::octPosition_

mutable protected

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

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

## orientable

Property<bool> regina::NormalSurface::orientable

mutable protected

Is this surface orientable?

## realBoundary

Property<bool> regina::NormalSurface::realBoundary

mutable protected

Does this surface have real boundary (i.e.

does it meet any boundary triangles)?

## triangulation_

const Triangulation<3>* regina::NormalSurface::triangulation_

protected

The triangulation in which this normal surface resides.

## twoSided

Property<bool> regina::NormalSurface::twoSided

mutable protected

Is this surface two-sided?

## vector

NormalSurfaceVector* regina::NormalSurface::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:

- surfaces/normalsurface.h

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