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

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

#include <hypersurface/normalhypersurface.h>

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

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...
 
NormalHypersurfaceclone () const
 Creates a newly allocated clone of this normal hypersurface. More...
 
NormalHypersurfacedoubleHypersurface () 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 AbelianGrouphomology () 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 RayrawVector () const
 
Gives read-only access to the raw vector that sits beneath this normal hypersurface. More...
 
 NormalHypersurface (const NormalHypersurface &)=delete
 
NormalHypersurfaceoperator= (const NormalHypersurface &)=delete
 
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

NormalHypersurfaceVectorvector_
 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, StoreManagedPtrH1_
 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
triangulationthe triangulation in which this normal hypersurface resides.
vectora 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
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 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
edgeIndexthe 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
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::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
pentIndexthe index in the triangulation of the pentachoron in which the requested prisms reside; this should be between 0 and Triangulation<4>::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 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.
      @return 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
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::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
namethe 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
pentIndexthe index in the triangulation of the pentachoron in which the requested pieces reside; this should be between 0 and Triangulation<4>::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.

◆ 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
outthe output stream to which to write.

◆ writeTextLong()

void regina::ShortOutput< NormalHypersurface , 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::NormalHypersurface::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::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
outthe output stream to which the XML should be written.

Member Data Documentation

◆ compact_

Property<bool> regina::NormalHypersurface::compact_
mutableprotected

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

◆ connected_

Property<bool> regina::NormalHypersurface::connected_
mutableprotected

Is this hypersurface connected?

◆ H1_

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

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_
mutableprotected

Is this hypersurface orientable?

◆ realBoundary_

Property<bool> regina::NormalHypersurface::realBoundary_
mutableprotected

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_
mutableprotected

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:

Copyright © 1999-2021, 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).