regina::NormalHypersurface Class Reference
Normal Hypersurfaces

Represents a single normal hypersurface in a 4-manifold triangulation. More...

`#include <hypersurface/normalhypersurface.h>`

Inheritance diagram for regina::NormalHypersurface:

## Public Member Functions

| NormalHypersurface (const Triangulation< 4 > *triangulation, NormalHypersurfaceVector *vector)
| Creates a new normal hypersurface inside the given triangulation with the given coordinate vector. More...
| NormalHypersurface (const Triangulation< 4 > *triang, HyperCoords coordSystem, List allCoords)
| A Python-only routine that creates a new normal hypersurface inside the given triangulation with the given coordinate vector. More...
| ~NormalHypersurface ()
| Destroys this normal hypersurface. More...
NormalHypersurface * | clone () const
| Creates a newly allocated clone of this normal hypersurface. More...
NormalHypersurface * | doubleHypersurface () const
| Creates a newly allocated hypersurface that is the double of this hypersurface. More...
LargeInteger | tetrahedra (size_t pentIndex, int vertex) const
| Returns the number of tetrahedron pieces of the given type in this normal hypersurface. More...
LargeInteger | prisms (size_t pentIndex, int prismType) const
| Returns the number of prism pieces of the given type in this normal hypersurface. More...
LargeInteger | edgeWeight (size_t edgeIndex) const
| Returns the number of times this normal hypersurface crosses the given edge. More...
size_t | countCoords () const
| Returns the number of coordinates in the specific underlying coordinate system being used. More...
const Triangulation< 4 > * | triangulation () const
| Returns the triangulation in which this normal hypersurface resides. More...
const std::string & | name () const
| Returns the name associated with this normal hypersurface. More...
void | setName (const std::string &name)
| Sets the name associated with this normal hypersurface. More...
void | writeTextShort (std::ostream &out) const
| Writes this hypersurface to the given output stream, using standard tetrahedron-prism 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 hypersurface and all of its properties. More...
bool | isEmpty () const
| Determines if this normal hypersurface is empty (has no pieces whatsoever). More...
bool | isCompact () const
| Determines if this normal hypersurface is compact (has finitely many pieces). More...
bool | isOrientable () const
| Returns whether or not this hypersurface is orientable. More...
bool | isTwoSided () const
| Returns whether or not this hypersurface is two-sided. More...
bool | isConnected () const
| Returns whether or not this hypersurface is connected. More...
bool | hasRealBoundary () const
| Determines if this hypersurface has any real boundary, that is, whether it meets any boundary tetrahedra of the triangulation. More...
bool | isVertexLinking () const
| Determines whether or not this hypersurface is vertex linking. More...
const Vertex< 4 > * | isVertexLink () const
| Determines whether or not a rational multiple of this hypersurface is the link of a single vertex. More...
const Edge< 4 > * | isThinEdgeLink () const
| Determines whether or not a rational multiple of this hypersurface is the thin link of a single edge. More...
const AbelianGroup & | homology () const
| Returns the first homology group of this hypersurface. More...
Triangulation< 3 > * | triangulate () const
| Returns a 3-manifold triangulation describing this normal hypersurface. More...
bool | sameSurface (const NormalHypersurface &other) const
| Determines whether this and the given hypersurface in fact represent the same normal hypersurface. More...
bool | embedded () const
| Determines whether this hypersurface is embedded. More...
bool | locallyCompatible (const NormalHypersurface &other) const
| Determines whether this and the given hypersurface are locally compatible. More...
const Ray & | rawVector () const
| Gives read-only access to the raw vector that sits beneath this normal hypersurface. 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 | calculateRealBoundary () const
| Calculates whether this hypersurface has any real boundary and stores the result as a property. More...
void | calculateFromTriangulation () const
| Calculate and store all properties that we derive from the 3-manifold triangulation of this hypersurface. More...

## Protected Attributes

NormalHypersurfaceVector * | vector_
| Contains the coordinates of the normal hypersurface in whichever space is appropriate. More...
const Triangulation< 4 > * | triangulation_
| The triangulation in which this normal hypersurface resides. More...
std::string | name_
| An optional name associated with this hypersurface. More...
Property< bool > | orientable_
| Is this hypersurface orientable? More...
Property< bool > | twoSided_
| Is this hypersurface two-sided? More...
Property< bool > | connected_
| Is this hypersurface connected? More...
Property< bool > | realBoundary_
| Does this hypersurface have real boundary (i.e. More...
Property< bool > | compact_
| Is this hypersurface compact (i.e., does it only contain finitely many pieces)? More...
Property< AbelianGroup, StoreManagedPtr > | H1_
| First homology group of the hypersurface. More...

## Friends

class | XMLNormalHypersurfaceReader

## Detailed Description

Represents a single normal hypersurface in a 4-manifold triangulation.

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

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

Note that non-compact surfaces (surfaces with infinitely many pieces, are allowed; in these cases, the corresponding coordinate lookup routines will return LargeInteger::infinity where appropriate.

## Constructor & Destructor Documentation

## NormalHypersurface() [1/2]

regina::NormalHypersurface::NormalHypersurface | ( | const Triangulation< 4 > * | triangulation,
|  | NormalHypersurfaceVector * | vector
| ) |  |

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

This normal hypersurface 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 hypersurface inside the given triangulation.
  The given coordinate vector cannot be the null pointer.

Python:
  Not present.

Parameters

  triangulation | the triangulation in which this normal hypersurface resides.
  vector | a vector containing the coordinates of the normal hypersurface in whichever space is appropriate.

## NormalHypersurface() [2/2]

regina::NormalHypersurface::NormalHypersurface | ( | const Triangulation< 4 > * | triang,
|  | HyperCoords | coordSystem,
|  | List | allCoords
| ) |  |

A Python-only routine that creates a new normal hypersurface 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 hypersurfaces (not a system like regina::HS_EDGE_WEIGHT, which is for viewing purposes only).
  The given coordinate vector represents a normal hypersurface 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 hypersurface resides.
  coordSystem | the coordinate system used by this normal hypersurface.
  allCoords | the corresponding vector of normal coordinates, expressed as a Python list. The list elements will be converted internally to LargeInteger objects.

## ~NormalHypersurface()

regina::NormalHypersurface::~NormalHypersurface | ( |  | ) |

inline

Destroys this normal hypersurface.

The underlying vector of coordinates will also be deallocated.

## Member Function Documentation

## calculateFromTriangulation()

void regina::NormalHypersurface::calculateFromTriangulation | ( |  | ) | const

protected

Calculate and store all properties that we derive from the 3-manifold triangulation of this hypersurface.

## calculateRealBoundary()

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

protected

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

## clone()

NormalHypersurface* regina::NormalHypersurface::clone | ( |  | ) | const

Creates a newly allocated clone of this normal hypersurface.

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

Returns
  a clone of this normal hypersurface.

## countCoords()

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

inline

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

Returns
  the number of coordinates.

## detail()

std::string regina::Output< NormalHypersurface , 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.

## doubleHypersurface()

NormalHypersurface* regina::NormalHypersurface::doubleHypersurface | ( |  | ) | const

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

Returns
  the double of this normal hypersurface.

## edgeWeight()

LargeInteger regina::NormalHypersurface::edgeWeight | ( | size_t | edgeIndex | ) | const

inline

Returns the number of times this normal hypersurface 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<4>::countEdges()-1 inclusive.

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

## embedded()

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

Determines whether this hypersurface is embedded.

This is true if and only if the surface contains no conflicting prism types.

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

## hasRealBoundary()

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

inline

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

## homology()

const AbelianGroup & regina::NormalHypersurface::homology | ( |  | ) | const

inline

Returns the first homology group of this hypersurface.

There is an important caveat regarding invalid 4-manifold triangulations. If the underlying triangulation has edge links that are not spheres, then it is possible that this normal hypersurface is not a compact 3-manifold. In such a case, this routine will compute homology in the same way as Triangulation<3>::homology() - that is, by effectively truncating ideal points of the hypersurface (which may arise where the hypersurface meets an invalid edge).

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 hypersurface is compact and embedded.

Warning
  This routine explicitly builds the normal pieces, and so may run out of memory if the normal coordinates are extremely large.

Returns
  the first homology group.

## isCompact()

bool regina::NormalHypersurface::isCompact | ( |  | ) | const

inline

Determines if this normal hypersurface is compact (has finitely many pieces).

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 hypersurface is compact.

## isConnected()

bool regina::NormalHypersurface::isConnected | ( |  | ) | const

inline

Returns whether or not this hypersurface 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 hypersurface is compact and embedded.

Warning
  This routine explicitly builds the normal pieces, and so may run out of memory if the normal coordinates are extremely large.

Returns
  `true` if this hypersurface is connected, or `false` if this hypersurface is disconnected.

## isEmpty()

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

Determines if this normal hypersurface is empty (has no pieces whatsoever).

## isOrientable()

bool regina::NormalHypersurface::isOrientable | ( |  | ) | const

inline

Returns whether or not this hypersurface 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 hypersurface is compact and embedded.

Warning
  This routine explicitly builds the normal pieces, and so may run out of memory if the normal coordinates are extremely large.

Returns
  `true` if this hypersurface is orientable, or `false` if this hypersurface is non-orientable.

## isThinEdgeLink()

const Edge< 4 > * regina::NormalHypersurface::isThinEdgeLink | ( |  | ) | const

inline

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

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 edge linked by this hypersurface, or 0 if this hypersurface is not a thin edge link.

## isTwoSided()

bool regina::NormalHypersurface::isTwoSided | ( |  | ) | const

inline

Returns whether or not this hypersurface 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 hypersurface is compact and embedded.

Warning
  This routine explicitly builds the normal pieces, and so may run out of memory if the normal coordinates are extremely large.

Returns
  `true` if this hypersurface is two-sided, or `false` if this hypersurface is one-sided.

## isVertexLink()

const Vertex< 4 > * regina::NormalHypersurface::isVertexLink | ( |  | ) | const

inline

Determines whether or not a rational multiple of this hypersurface 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 hypersurface, or 0 if this hypersurface is not the link of a single vertex.

## isVertexLinking()

bool regina::NormalHypersurface::isVertexLinking | ( |  | ) | const

inline

Determines whether or not this hypersurface is vertex linking.

A vertex linking hypersurface contains only tetrahedra.

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 hypersurface is vertex linking.

## locallyCompatible()

bool regina::NormalHypersurface::locallyCompatible | ( | const NormalHypersurface & | other | ) | const

Determines whether this and the given hypersurface are locally compatible.

Local compatibility means that, within each individual pentachoron of the triangulation, it is possible to arrange the normal discs of both hypersurfaces 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 pentachora simultaneously.

Local compatibility can be formulated in terms of normal piece types. Two normal hypersurfaces are locally compatible if and only if they together use at most two prism piece types per pentachoron; moreover, if there are two prism piece types within a single pentachoron then these prism types are non-intersecting.

If one of the two hypersurfaces breaks the local compatibility constraints on its own (for instance, it contains two conflicting prism types within the same pentachoron), then this routine will return `false` regardless of what the other hypersurface contains.

Precondition
  Both this and the given normal hypersurface live within the same 4-manifold triangulation.

Parameters

  other | the other hypersurface to test for local compatibility with this hypersurface.

Returns
  `true` if the two hypersurfaces are locally compatible, or `false` if they are not.

## name()

const std::string & regina::NormalHypersurface::name | ( |  | ) | const

inline

Returns the name associated with this normal hypersurface.

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

Returns
  the name of associated with this hypersurface.

## prisms()

LargeInteger regina::NormalHypersurface::prisms | ( | size_t | pentIndex,
|  | int | prismType
| ) |  | const

inline

Returns the number of prism pieces of the given type in this normal hypersurface.

A prism piece type is identified by specifying a pentachoron and an edge of that pentachoron; prisms of this type will then separate edge i of the pentachoron from triangle i of the pentachoron.

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

Parameters

  pentIndex | the index in the triangulation of the pentachoron in which the requested prisms reside; this should be between 0 and Triangulation<4>::size()-1 inclusive.
  prismType | specifies the edge of the given pentachoron that this prism separates from the opposite triangle; this should be between 0 and 9 inclusive.

Returns
  the number of prism pieces of the given type.

## rawVector()

const Ray & regina::NormalHypersurface::rawVector | ( |  | ) | const

inline

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

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 NormalHypersurface 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 hypersurface yourself), it is best to keep to the coordinate-system-agnostic access functions such as NormalHypersurfaceVector::tetrahedra() and NormalHypersurfaceVector::prisms().

Python:
  Not present.

Returns
  the underlying raw vector.

## sameSurface()

bool regina::NormalHypersurface::sameSurface | ( | const NormalHypersurface & | other | ) | const

Determines whether this and the given hypersurface in fact represent the same normal hypersurface.

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

It does not matter what coordinate systems the two hypersurfaces use. In particular, it does not matter if this and the given hypersurface use different coordinate systems.

Precondition
  Both this and the given normal hypersurface live within the same 4-manifold triangulation.

Parameters

  other | the hypersurface to be compared with this hypersurface.

Returns
  `true` if both hypersurfaces represent the same normal hypersurface, or `false` if not.

## setName()

void regina::NormalHypersurface::setName | ( | const std::string & | name | ) |

inline

Sets the name associated with this normal hypersurface.

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

Parameters

  name | the new name to associate with this hypersurface.

## str()

std::string regina::Output< NormalHypersurface , 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.

## tetrahedra()

LargeInteger regina::NormalHypersurface::tetrahedra | ( | size_t | pentIndex,
|  | int | vertex
| ) |  | const

inline

Returns the number of tetrahedron pieces of the given type in this normal hypersurface.

A tetrahedron piece type is identified by specifying a pentachoron and a vertex of that pentachoron that the tetrahedron surrounds.

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

Parameters

  pentIndex | the index in the triangulation of the pentachoron in which the requested pieces reside; this should be between 0 and Triangulation<4>::size()-1 inclusive.
  vertex | the vertex of the given pentachoron around which the requested pieces lie; this should be between 0 and 4 inclusive.

Returns
  the number of tetrahedron pieces of the given type.

## triangulate()

Triangulation<3>* regina::NormalHypersurface::triangulate | ( |  | ) | const

Returns a 3-manifold triangulation describing this normal hypersurface.

The triangulation will be simplified via Triangulation<3>::intelligentSimplify(), which means that the tetrahedra of the final triangulation are not likely to correspond to any particular tetrahedron/prism pieces of this normal hypersurface.

The 3-manifold triangulation will be newly allocated, and destroying it is the responsibility of the caller of this routine.

Todo:
  Bug: Check for absurdly large numbers of pieces and return 0 accordingly.

Precondition
  This normal hypersurface is compact and embedded.

Returns
  a triangulation of this normal hypersurface.

## triangulation()

const Triangulation< 4 > * regina::NormalHypersurface::triangulation | ( |  | ) | const

inline

Returns the triangulation in which this normal hypersurface resides.

Returns
  the underlying triangulation.

## utf8()

std::string regina::Output< NormalHypersurface , 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::NormalHypersurface::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< NormalHypersurface , 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::NormalHypersurface::writeTextShort | ( | std::ostream & | out | ) | const

Writes this hypersurface to the given output stream, using standard tetrahedron-prism coordinates.

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## writeXMLData()

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

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

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

Python:
  Not present.

Parameters

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

## Member Data Documentation

## compact_

Property<bool> regina::NormalHypersurface::compact_

mutable protected

Is this hypersurface compact (i.e., does it only contain finitely many pieces)?

## connected_

Property<bool> regina::NormalHypersurface::connected_

mutable protected

Is this hypersurface connected?

## H1_

Property<AbelianGroup, StoreManagedPtr> regina::NormalHypersurface::H1_

mutable protected

First homology group of the hypersurface.

## name_

std::string regina::NormalHypersurface::name_

protected

An optional name associated with this hypersurface.

## orientable_

Property<bool> regina::NormalHypersurface::orientable_

mutable protected

Is this hypersurface orientable?

## realBoundary_

Property<bool> regina::NormalHypersurface::realBoundary_

mutable protected

Does this hypersurface have real boundary (i.e.

does it meet any boundary facets)?

## triangulation_

const Triangulation<4>* regina::NormalHypersurface::triangulation_

protected

The triangulation in which this normal hypersurface resides.

## twoSided_

Property<bool> regina::NormalHypersurface::twoSided_

mutable protected

Is this hypersurface two-sided?

## vector_

NormalHypersurfaceVector* regina::NormalHypersurface::vector_

protected

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

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

- hypersurface/normalhypersurface.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).