Regina Calculation Engine
Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
regina::NNormalHypersurface Class Reference

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

#include <hypersurface/nnormalhypersurface.h>

Inheritance diagram for regina::NNormalHypersurface:
regina::ShortOutput< NNormalHypersurface > regina::Output< NNormalHypersurface, false >

Public Member Functions

 NNormalHypersurface (const Dim4Triangulation *triangulation, NNormalHypersurfaceVector *vector)
 Creates a new normal hypersurface inside the given triangulation with the given coordinate vector. More...
 
 NNormalHypersurface (const Dim4Triangulation *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...
 
 ~NNormalHypersurface ()
 Destroys this normal hypersurface. More...
 
NNormalHypersurfaceclone () const
 Creates a newly allocated clone of this normal hypersurface. More...
 
NNormalHypersurfacedoubleHypersurface () const
 Creates a newly allocated hypersurface that is the double of this hypersurface. More...
 
NLargeInteger tetrahedra (size_t pentIndex, int vertex) const
 Returns the number of tetrahedron pieces of the given type in this normal hypersurface. More...
 
NLargeInteger prisms (size_t pentIndex, int prismType) const
 Returns the number of prism pieces of the given type in this normal hypersurface. More...
 
NLargeInteger 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 Dim4Triangulationtriangulation () 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 Dim4VertexisVertexLink () const
 Determines whether or not a rational multiple of this hypersurface is the link of a single vertex. More...
 
const Dim4EdgeisThinEdgeLink () const
 Determines whether or not a rational multiple of this hypersurface is the thin link of a single edge. More...
 
const NAbelianGrouphomology () const
 Returns the first homology group of this hypersurface. More...
 
NTriangulationtriangulate () const
 Returns a 3-manifold triangulation describing this normal hypersurface. More...
 
bool sameSurface (const NNormalHypersurface &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 NNormalHypersurface &other) const
 Determines whether this and the given hypersurface are locally compatible. More...
 
const NNormalHypersurfaceVectorrawVector () 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...
 
REGINA_DEPRECATED std::string toString () const
 A deprecated alias for str(). More...
 
REGINA_DEPRECATED std::string toStringLong () const
 A deprecated alias for detail(). 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

NNormalHypersurfaceVectorvector_
 Contains the coordinates of the normal hypersurface in whichever space is appropriate. More...
 
const Dim4Triangulationtriangulation_
 The triangulation in which this normal hypersurface resides. More...
 
std::string name_
 An optional name associated with this hypersurface. More...
 
NProperty< bool > orientable_
 Is this hypersurface orientable? More...
 
NProperty< bool > twoSided_
 Is this hypersurface two-sided? More...
 
NProperty< bool > connected_
 Is this hypersurface connected? More...
 
NProperty< bool > realBoundary_
 Does this hypersurface have real boundary (i.e. More...
 
NProperty< bool > compact_
 Is this hypersurface compact (i.e., does it only contain finitely many pieces)? More...
 
NProperty< NAbelianGroup, StoreManagedPtrH1_
 First homology group of the hypersurface. More...
 

Friends

class regina::NXMLNormalHypersurfaceReader
 

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 NNormalHypersurfaceVector 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 NLargeInteger::infinity where appropriate.

Constructor & Destructor Documentation

§ NNormalHypersurface() [1/2]

regina::NNormalHypersurface::NNormalHypersurface ( const Dim4Triangulation triangulation,
NNormalHypersurfaceVector 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
triangulationthe triangulation in which this normal hypersurface resides.
vectora vector containing the coordinates of the normal hypersurface in whichever space is appropriate.

§ NNormalHypersurface() [2/2]

regina::NNormalHypersurface::NNormalHypersurface ( const Dim4Triangulation 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
triangthe triangulation in which this normal hypersurface resides.
coordSystemthe coordinate system used by this normal hypersurface.
allCoordsthe corresponding vector of normal coordinates, expressed as a Python list. The list elements will be converted internally to NLargeInteger objects.

§ ~NNormalHypersurface()

regina::NNormalHypersurface::~NNormalHypersurface ( )
inline

Destroys this normal hypersurface.

The underlying vector of coordinates will also be deallocated.

Member Function Documentation

§ calculateFromTriangulation()

void regina::NNormalHypersurface::calculateFromTriangulation ( ) const
protected

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

§ calculateRealBoundary()

void regina::NNormalHypersurface::calculateRealBoundary ( ) const
protected

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

§ clone()

NNormalHypersurface* regina::NNormalHypersurface::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::NNormalHypersurface::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< NNormalHypersurface , 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()

NNormalHypersurface* regina::NNormalHypersurface::doubleHypersurface ( ) const

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

Returns
the double of this normal hypersurface.

§ edgeWeight()

NLargeInteger regina::NNormalHypersurface::edgeWeight ( size_t  edgeIndex) const
inline

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

Parameters
edgeIndexthe index in the triangulation of the edge in which we are interested; this should be between 0 and Dim4Triangulation::countEdges()-1 inclusive.
Returns
the number of times this normal hypersurface crosses the given edge.

§ embedded()

bool regina::NNormalHypersurface::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::NNormalHypersurface::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 NAbelianGroup & regina::NNormalHypersurface::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 NTriangulation::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::NNormalHypersurface::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::NNormalHypersurface::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::NNormalHypersurface::isEmpty ( ) const

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

§ isOrientable()

bool regina::NNormalHypersurface::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 Dim4Edge * regina::NNormalHypersurface::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::NNormalHypersurface::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 Dim4Vertex * regina::NNormalHypersurface::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::NNormalHypersurface::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::NNormalHypersurface::locallyCompatible ( const NNormalHypersurface 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
otherthe 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::NNormalHypersurface::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()

NLargeInteger regina::NNormalHypersurface::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
pentIndexthe index in the triangulation of the pentachoron in which the requested prisms reside; this should be between 0 and Dim4Triangulation::size()-1 inclusive.
prismTypespecifies 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 NNormalHypersurfaceVector * regina::NNormalHypersurface::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 NNormalHypersurface 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 NNormalHypersurfaceVector::tetrahedra() and NNormalHypersurfaceVector::prisms().
Python:
Not present.
Returns
the underlying raw vector.

§ sameSurface()

bool regina::NNormalHypersurface::sameSurface ( const NNormalHypersurface 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
otherthe hypersurface to be compared with this hypersurface.
Returns
true if both hypersurfaces represent the same normal hypersurface, or false if not.

§ setName()

void regina::NNormalHypersurface::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
namethe new name to associate with this hypersurface.

§ str()

std::string regina::Output< NNormalHypersurface , 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()

NLargeInteger regina::NNormalHypersurface::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
pentIndexthe index in the triangulation of the pentachoron in which the requested pieces reside; this should be between 0 and Dim4Triangulation::size()-1 inclusive.
vertexthe 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.

§ toString()

REGINA_DEPRECATED std::string regina::Output< NNormalHypersurface , supportsUtf8 >::toString ( ) const
inherited

A deprecated alias for str().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type str() instead.
Returns
a short text representation of this object.

§ toStringLong()

REGINA_DEPRECATED std::string regina::Output< NNormalHypersurface , supportsUtf8 >::toStringLong ( ) const
inherited

A deprecated alias for detail().

Deprecated:
This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.
Returns
a long text representation of this object.

§ triangulate()

NTriangulation* regina::NNormalHypersurface::triangulate ( ) const

Returns a 3-manifold triangulation describing this normal hypersurface.

The triangulation will be simplified via NTriangulation::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 Dim4Triangulation * regina::NNormalHypersurface::triangulation ( ) const
inline

Returns the triangulation in which this normal hypersurface resides.

Returns
the underlying triangulation.

§ utf8()

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

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

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

Python:
The paramater out does not exist, and is taken to be standard output.
Parameters
outthe output stream to which to write.

§ writeTextLong()

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

A default implementation for detailed output.

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

Python:
Not present.
Parameters
outthe output stream to which to write.

§ writeTextShort()

void regina::NNormalHypersurface::writeTextShort ( std::ostream &  out) const

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

Python:
Not present.
Parameters
outthe output stream to which to write.

§ writeXMLData()

void regina::NNormalHypersurface::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 NNormalHypersurfaceList::writeXMLPacketData().

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

Member Data Documentation

§ compact_

NProperty<bool> regina::NNormalHypersurface::compact_
mutableprotected

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

§ connected_

NProperty<bool> regina::NNormalHypersurface::connected_
mutableprotected

Is this hypersurface connected?

§ H1_

NProperty<NAbelianGroup, StoreManagedPtr> regina::NNormalHypersurface::H1_
mutableprotected

First homology group of the hypersurface.

§ name_

std::string regina::NNormalHypersurface::name_
protected

An optional name associated with this hypersurface.

§ orientable_

NProperty<bool> regina::NNormalHypersurface::orientable_
mutableprotected

Is this hypersurface orientable?

§ realBoundary_

NProperty<bool> regina::NNormalHypersurface::realBoundary_
mutableprotected

Does this hypersurface have real boundary (i.e.

does it meet any boundary facets)?

§ triangulation_

const Dim4Triangulation* regina::NNormalHypersurface::triangulation_
protected

The triangulation in which this normal hypersurface resides.

§ twoSided_

NProperty<bool> regina::NNormalHypersurface::twoSided_
mutableprotected

Is this hypersurface two-sided?

§ vector_

NNormalHypersurfaceVector* regina::NNormalHypersurface::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:

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