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 NormalHypersurface &)=default
	Creates a new copy of the given normal hypersurface. More...

	NormalHypersurface (const NormalHypersurface &src, const Triangulation< 4 > &triangulation)
	Creates a new copy of the given normal hypersurface, but relocated to the given triangulation. More...

	NormalHypersurface (const NormalHypersurface &src, const SnapshotRef< Triangulation< 4 > > &triangulation)
	Creates a new copy of the given normal hypersurface, but relocated to the given triangulation. More...

	NormalHypersurface (NormalHypersurface &&) noexcept=default
	Moves the given hypersurface into this new normal hypersurface. More...

	NormalHypersurface (const Triangulation< 4 > &triang, HyperEncoding enc, const Vector< LargeInteger > &vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given vector encoding. More...

	NormalHypersurface (const Triangulation< 4 > &triang, HyperEncoding enc, Vector< LargeInteger > &&vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given vector encoding. More...

	NormalHypersurface (const SnapshotRef< Triangulation< 4 > > &triang, HyperEncoding enc, const Vector< LargeInteger > &vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given vector encoding. More...

	NormalHypersurface (const SnapshotRef< Triangulation< 4 > > &triang, HyperEncoding enc, Vector< LargeInteger > &&vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given vector encoding. More...

	NormalHypersurface (const Triangulation< 4 > &triang, HyperCoords coords, const Vector< LargeInteger > &vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given coordinate system. More...

	NormalHypersurface (const Triangulation< 4 > &triang, HyperCoords coords, Vector< LargeInteger > &&vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given coordinate system. More...

	NormalHypersurface (const SnapshotRef< Triangulation< 4 > > &triang, HyperCoords coords, const Vector< LargeInteger > &vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given coordinate system. More...

	NormalHypersurface (const SnapshotRef< Triangulation< 4 > > &triang, HyperCoords coords, Vector< LargeInteger > &&vector)
	Creates a new normal hypersurface inside the given triangulation with the given coordinate vector, using the given coordinate system. More...

NormalHypersurface *	clone () const
	Deprecated routine that creates a newly allocated clone of this normal hypersurface. More...

NormalHypersurface &	operator= (const NormalHypersurface &)=default
	Sets this to be a copy of the given normal hypersurface. More...

NormalHypersurface &	operator= (NormalHypersurface &&) noexcept=default
	Moves the contents of the given normal hypersurface to this hypersurface. More...

void	swap (NormalHypersurface &other) noexcept
	Swaps the contents of this and the given normal hypersurface. More...

NormalHypersurface	doubleHypersurface () const
	Returns the double of this hypersurface. More...

NormalHypersurface	operator+ (const NormalHypersurface &rhs) const
	Returns the sum of this and the given 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...

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
	Deprecated routine that writes the underlying coordinate vector to the given output stream in text format. More...

void	writeXMLData (std::ostream &out, FileFormat format, const NormalHypersurfaces *list) 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	operator== (const NormalHypersurface &other) const
	Determines whether this and the given hypersurface in fact represent the same normal hypersurface. More...

bool	operator!= (const NormalHypersurface &other) const
	Determines whether this and the given hypersurface represent different normal hypersurfaces. More...

bool	operator< (const NormalHypersurface &other) const
	Imposes a total order on all normal hypersurfaces. More...

bool	sameSurface (const NormalHypersurface &other) const
	Deprecated routine that 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 Vector< LargeInteger > &	vector () const
	Gives read-only access to the integer vector that Regina uses internally to represent this hypersurface. More...

const Vector< LargeInteger > &	rawVector () const
	A deprecated alias for vector(). More...

HyperEncoding	encoding () const
	Returns the specific integer vector encoding that this hypersurface uses internally. 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...

Static Public Member Functions
static HyperEncoding	reconstructTetrahedra (const Triangulation< 4 > &tri, Vector< LargeInteger > &vector, HyperEncoding enc)
	Reconstructs the tetrahedron coordinates in the given integer vector. More...

Protected Attributes
HyperEncoding	enc_
	The specific encoding of a normal hypersurface used by the coordinate vector. More...

Vector< LargeInteger >	vector_
	Contains the coordinates of the normal hypersurface. More...

SnapshotRef< Triangulation< 4 > >	triangulation_
	The triangulation in which this normal hypersurface resides. More...

std::string	name_
	An optional name associated with this hypersurface. More...

std::optional< bool >	orientable_
	Is this hypersurface orientable? This is std::nullopt if it has not yet been computed. More...

std::optional< bool >	twoSided_
	Is this hypersurface two-sided? This is std::nullopt if it has not yet been computed. More...

std::optional< bool >	connected_
	Is this hypersurface connected? This is std::nullopt if it has not yet been computed. More...

std::optional< bool >	realBoundary_
	Does this hypersurface have real boundary (i.e. More...

std::optional< bool >	compact_
	Is this hypersurface compact (i.e., does it only contain finitely many pieces)? This is std::nullopt if it has not yet been computed. More...

std::optional< AbelianGroup >	H1_
	First homology group of the hypersurface. More...

Friends
class	XMLNormalHypersurfaceReader

Detailed Description

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

The normal hypersurface is described internally by an integer vector (discussed in more detail below). Since different hypersurfaces may use different vector encodings, you should not rely on the raw vector entries unless absolutely necessary. Instead, the query routines such as tetrahedra(), prisms(), edgeWeight() and so on are independent of the underlying vector encoding being used.

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

Since Regina 7.0, you can modify or even destroy the original triangulation that was used to create this normal hypersurface. If you do, then this normal hypersurface will automatically make a private copy of the original triangulation as an ongoing reference. Different normal hypersurfaces can all share the same private copy, so this is not an expensive process.

Internally, a normal hypersurface is represented by a Vector<LargeInteger> (possibly using a different coordinate system from the one in which the hypersurfaces were originally enumerated). This contains a block of coordinates for each pentachoron, in order from the first pentachoron to the last. Each block begins with five tetrahedron coordinates (always), followed by ten prisms coordinates (always) - unlike the 3-dimensional world, there are currently no optional coordinates that might or might not be stored (though this could change in future versions of Regina). Therefore the vector that is stored will always have length 15n, where n is the number of pentachora in the underlying triangulation.

When adding support for a new coordinate system:

The file hypercoords.h must be updated. This includes a new enum value for HyperCoords, a new case for the HyperEncoding constructor, and new cases for the functions in HyperInfo. Do not forget to update the python bindings for HyperCoords also.
The global routines makeEmbeddedConstraints() and makeMatchingEquations() should be updated to incorporate the new coordinate system.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Constructor & Destructor Documentation

◆ NormalHypersurface() [1/12]

regina::NormalHypersurface::NormalHypersurface ( const NormalHypersurface & )

default

Creates a new copy of the given normal hypersurface.

◆ NormalHypersurface() [2/12]

regina::NormalHypersurface::NormalHypersurface	(	const NormalHypersurface &	src,
		const Triangulation< 4 > &	triangulation
	)

inline

Creates a new copy of the given normal hypersurface, but relocated to the given triangulation.

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this normal hypersurface will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given triangulation is either the same as, or is combinatorially identical to, the triangulation in which src resides.

Parameters

src	the normal hypersurface to copy.
triangulation	the triangulation in which this new hypersurface will reside.

◆ NormalHypersurface() [3/12]

regina::NormalHypersurface::NormalHypersurface	(	const NormalHypersurface &	src,
		const SnapshotRef< Triangulation< 4 > > &	triangulation
	)

inline

Creates a new copy of the given normal hypersurface, but relocated to the given triangulation.

Precondition: The given triangulation is either the same as, or is combinatorially identical to, the triangulation in which src resides.

Python: Not present, but you can use the version that takes a "pure" triangulation.

Parameters

src	the normal hypersurface to copy.
triangulation	a snapshot, frozen in time, of the triangulation in which this new hypersurface will reside.

◆ NormalHypersurface() [4/12]

regina::NormalHypersurface::NormalHypersurface ( NormalHypersurface && )

defaultnoexcept

Moves the given hypersurface into this new normal hypersurface.

This is a fast (constant time) operation.

The hypersurface that is passed will no longer be usable.

◆ NormalHypersurface() [5/12]

regina::NormalHypersurface::NormalHypersurface	(	const Triangulation< 4 > &	triang,
		HyperEncoding	enc,
		const Vector< LargeInteger > &	vector
	)

inline

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

There is no guarantee that this hypersurface will keep the given encoding: NormalHypersurface will sometimes convert the vector to use a different encoding for its own internal storage.

Despite what is said in the class notes, it is okay if the given vector encoding does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this normal hypersurface will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the given encoding. This will not be checked!

Python: Instead of a Vector<LargeInteger>, you may (if you prefer) pass a Python list of integers.

Parameters

triang	the triangulation in which this normal hypersurface resides.
enc	indicates precisely how the given vector encodes a normal hypersurface.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [6/12]

regina::NormalHypersurface::NormalHypersurface	(	const Triangulation< 4 > &	triang,
		HyperEncoding	enc,
		Vector< LargeInteger > &&	vector
	)

inline

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

There is no guarantee that this hypersurface will keep the given encoding: NormalHypersurface will sometimes convert the vector to use a different encoding for its own internal storage.

Despite what is said in the class notes, it is okay if the given vector encoding does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this normal hypersurface will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the given encoding. This will not be checked!

Python: Not present, but you can use the version that copies vector.

Parameters

triang	the triangulation in which this normal hypersurface resides.
enc	indicates precisely how the given vector encodes a normal hypersurface.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [7/12]

regina::NormalHypersurface::NormalHypersurface	(	const SnapshotRef< Triangulation< 4 > > &	triang,
		HyperEncoding	enc,
		const Vector< LargeInteger > &	vector
	)

inline

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

There is no guarantee that this hypersurface will keep the given encoding: NormalHypersurface will sometimes convert the vector to use a different encoding for its own internal storage.

Despite what is said in the class notes, it is okay if the given vector encoding does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the given encoding. This will not be checked!

Python: Not present, but you can use the version that takes a "pure" triangulation.

Parameters

triang	a snapshot, frozen in time, of the triangulation in which this normal hypersurface resides.
enc	indicates precisely how the given vector encodes a normal hypersurface.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [8/12]

regina::NormalHypersurface::NormalHypersurface	(	const SnapshotRef< Triangulation< 4 > > &	triang,
		HyperEncoding	enc,
		Vector< LargeInteger > &&	vector
	)

inline

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

There is no guarantee that this hypersurface will keep the given encoding: NormalHypersurface will sometimes convert the vector to use a different encoding for its own internal storage.

Despite what is said in the class notes, it is okay if the given vector encoding does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the given encoding. This will not be checked!

Python: Not present, but you can use the version that takes a "pure" triangulation and copies vector.

Parameters

triang	a snapshot, frozen in time, of the triangulation in which this normal hypersurface resides.
enc	indicates precisely how the given vector encodes a normal hypersurface.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [9/12]

regina::NormalHypersurface::NormalHypersurface	(	const Triangulation< 4 > &	triang,
		HyperCoords	coords,
		const Vector< LargeInteger > &	vector
	)

inline

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

It is assumed that this hypersurface uses the vector encoding described by HyperEncoding(coords). Be careful with this if you are extracting the vector from some other normal hypersurface, since Regina may internally convert to use a different encoding from whatever was used during enumeration and/or read from file. In the same spirit, there is no guarantee that this hypersurface will use HyperEncoding(coords) as its internal encoding method.

Despite what is said in the class notes, it is okay if the given coordinate system does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this normal hypersurface will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the encoding HyperEncoding(coords). This will not be checked!

Python: Instead of a Vector<LargeInteger>, you may (if you prefer) pass a Python list of integers.

Parameters

triang	the triangulation in which this normal hypersurface resides.
coords	the coordinate system from which the vector encoding will be deduced.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [10/12]

regina::NormalHypersurface::NormalHypersurface	(	const Triangulation< 4 > &	triang,
		HyperCoords	coords,
		Vector< LargeInteger > &&	vector
	)

inline

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

It is assumed that this hypersurface uses the vector encoding described by HyperEncoding(coords). Be careful with this if you are extracting the vector from some other normal hypersurface, since Regina may internally convert to use a different encoding from whatever was used during enumeration and/or read from file. In the same spirit, there is no guarantee that this hypersurface will use HyperEncoding(coords) as its internal encoding method.

Despite what is said in the class notes, it is okay if the given coordinate system does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

A snapshot will be taken of the given triangulation as it appears right now. You may change or even delete the triangulation later on; if so, then this normal hypersurface will still refer to the frozen snapshot that was taken at the time of construction.

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the encoding HyperEncoding(coords). This will not be checked!

Python: Not present, but you can use the version that copies vector.

Parameters

triang	the triangulation in which this normal hypersurface resides.
coords	the coordinate system from which the vector encoding will be deduced.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [11/12]

regina::NormalHypersurface::NormalHypersurface	(	const SnapshotRef< Triangulation< 4 > > &	triang,
		HyperCoords	coords,
		const Vector< LargeInteger > &	vector
	)

inline

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

It is assumed that this hypersurface uses the vector encoding described by HyperEncoding(coords). Be careful with this if you are extracting the vector from some other normal hypersurface, since Regina may internally convert to use a different encoding from whatever was used during enumeration and/or read from file. In the same spirit, there is no guarantee that this hypersurface will use HyperEncoding(coords) as its internal encoding method.

Despite what is said in the class notes, it is okay if the given coordinate system does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the encoding HyperEncoding(coords). This will not be checked!

Python: Not present, but you can use the version that takes a "pure" triangulation.

Parameters

triang	a snapshot, frozen in time, of the triangulation in which this normal hypersurface resides.
coords	the coordinate system from which the vector encoding will be deduced.
vector	a vector containing the coordinates of the normal hypersurface.

◆ NormalHypersurface() [12/12]

regina::NormalHypersurface::NormalHypersurface	(	const SnapshotRef< Triangulation< 4 > > &	triang,
		HyperCoords	coords,
		Vector< LargeInteger > &&	vector
	)

inline

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

It is assumed that this hypersurface uses the vector encoding described by HyperEncoding(coords). Be careful with this if you are extracting the vector from some other normal hypersurface, since Regina may internally convert to use a different encoding from whatever was used during enumeration and/or read from file. In the same spirit, there is no guarantee that this hypersurface will use HyperEncoding(coords) as its internal encoding method.

Despite what is said in the class notes, it is okay if the given coordinate system does not include tetrahedron coordinates. (If this is the case, the vector will be converted automatically.)

Precondition: The given coordinate vector does indeed represent a normal hypersurface inside the given triangulation, using the encoding HyperEncoding(coords). This will not be checked!

Python: Not present, but you can use the version that takes a "pure" triangulation and copies vector.

Parameters

triang	a snapshot, frozen in time, of the triangulation in which this normal hypersurface resides.
coords	the coordinate system from which the vector encoding will be deduced.
vector	a vector containing the coordinates of the normal hypersurface.

Member Function Documentation

◆ clone()

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

inline

Deprecated routine that 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.

Deprecated:: Simply use the copy constructor instead.

Returns: a clone of this normal hypersurface.

◆ detail()

template<class T , bool supportsUtf8 = false>

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

Returns the double of this hypersurface.

Returns: the double of this normal hypersurface.

◆ edgeWeight()

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

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.

◆ encoding()

HyperEncoding regina::NormalHypersurface::encoding ( ) const

inline

Returns the specific integer vector encoding that this hypersurface uses internally.

This is the encoding that should be used to interpret vector().

Note that this might differ from the encoding originally passed to the class constructor.

Returns: the internal vector encoding.

◆ 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

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

inline

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

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 null 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

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 null if this hypersurface is not the link of a single vertex.

◆ isVertexLinking()

bool regina::NormalHypersurface::isVertexLinking ( ) const

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.

◆ operator!=()

bool regina::NormalHypersurface::operator!= ( const NormalHypersurface & other ) const

inline

Determines whether this and the given hypersurface represent different normal hypersurfaces.

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

It does not matter what vector encodings the two hypersurfaces use. In particular, it does not matter if this and the given hypersurface use different encodings, or if one but not the other supports non-compact hypersurfaces.

This routine is safe to call even if this and the given hypersurface do not belong to the same triangulation:

If the two triangulations have the same size, then this routine will test whether this hypersurface, if transplanted into the other triangulation using the same pentachoron numbering and the same normal piece types, would be different from other.
If the two triangulations have different sizes, then this routine will return true.

Parameters

other the hypersurface to be compared with this hypersurface.

Returns: true if both hypersurfaces represent different normal hypersurface, or false if not.

◆ operator+()

NormalHypersurface regina::NormalHypersurface::operator+ ( const NormalHypersurface & rhs ) const

inline

Returns the sum of this and the given hypersurface.

This will combine all tetrahedra and/or prisms from both surfaces.

The two hypersurfaces do not need to use the same coordinate system and/or internal vector encodings. Moreover, the resulting hypersurface might well use an encoding different from both of these, or even a hybrid encoding that does not come from one of Regina's ready-made coordinate systems.

Precondition: Both this and the given normal hypersurface use the same underlying triangulation.

Parameters

rhs	the hypersurface to sum with this.

Returns: the sum of both normal hypersurfaces.

◆ operator<()

bool regina::NormalHypersurface::operator< ( const NormalHypersurface & other ) const

Imposes a total order on all normal hypersurfaces.

This order is not mathematically meaningful; it is merely provided for scenarios where you need to be able to sort hypersurfaces (e.g., when using them as keys in a map).

The order is well-defined, and will be preserved across copy/move operations, different program executions, and different platforms (since it is defined purely in terms of the normal coordinates, and does not use transient properties such as locations in memory).

This operation is consistent with the equality test. In particular, it does not matter whether the two hypersurfaces belong to different triangulations, or use different encodings, or if one but not the other supports non-compact hypersurfaces. See the equality test operator==() for further details.

Parameters

other the hypersurface to be compared with this hypersurface.

Returns: true if and only if this appears before the given hypersurface in the total order.

◆ operator=() [1/2]

NormalHypersurface & regina::NormalHypersurface::operator= ( const NormalHypersurface & )

default

Sets this to be a copy of the given normal hypersurface.

This and the given normal hypersurface do not need to live in the same underlying triangulation, and they do not need to have the same length vectors or use the same normal coordinate system - if any of these properties differs then this hypersurface will be adjusted accordingly.

This operator induces a deep copy of the given normal hypersurface.

Returns: a reference to this normal hypersurface.

◆ operator=() [2/2]

NormalHypersurface & regina::NormalHypersurface::operator= ( NormalHypersurface && )

defaultnoexcept

Moves the contents of the given normal hypersurface to this hypersurface.

This is a fast (constant time) operation.

This and the given normal hypersurface do not need to live in the same underlying triangulation, and they do not need to have the same length vectors or use the same normal coordinate system - if any of these properties differs then this hypersurface will be adjusted accordingly.

The hypersurface that was passed will no longer be usable.

Returns: a reference to this normal hypersurface.

◆ operator==()

bool regina::NormalHypersurface::operator== ( 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 vector encodings the two hypersurfaces use. In particular, it does not matter if this and the given hypersurface use different encodings, or if one but not the other supports non-compact hypersurfaces.

This routine is safe to call even if this and the given hypersurface do not belong to the same triangulation:

If the two triangulations have the same size, then this routine will test whether this hypersurface, if transplanted into the other triangulation using the same pentachoron numbering and the same normal piece types, would be the same as other.
If the two triangulations have different sizes, then this routine will return false.

Parameters

other the hypersurface to be compared with this hypersurface.

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

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

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 Vector< LargeInteger > & regina::NormalHypersurface::rawVector ( ) const

inline

A deprecated alias for vector().

Deprecated:: This routine has been renamed to vector().

Returns: the underlying integer vector.

◆ reconstructTetrahedra()

static HyperEncoding regina::NormalHypersurface::reconstructTetrahedra	(	const Triangulation< 4 > &	tri,
		Vector< LargeInteger > &	vector,
		HyperEncoding	enc
	)

static

Reconstructs the tetrahedron coordinates in the given integer vector.

The given vector must represent a normal hypersurface within the given triangulation, using the given vector encoding.

If the given encoding does not already store tetrahedron coordinates, then the vector will be modified directly to use a new encoding that does, and this new encoding will be returned.
If the given encoding does already store tetrahedra, then this routine will do nothing and immediately return enc.

Parameters

tri	the triangulation in which the normal hypersurface lives.
vector	an integer vector that encodes a normal hypersurface within tri; this will be modified directly.
enc	the encoding used by the given integer vector.

Returns: the new encoding used by the modified vector.

◆ sameSurface()

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

inline

Deprecated routine that determines whether this and the given hypersurface in fact represent the same normal hypersurface.

Deprecated:: This routine has been renamed to the comparison operator (==).

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

template<class T , bool supportsUtf8 = false>

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

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python str() and repr() functions.

Python: The Python "stringification" function str() will use precisely this function, and for most classes the Python repr() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ swap()

void regina::NormalHypersurface::swap ( NormalHypersurface & other )

inlinenoexcept

Swaps the contents of this and the given normal hypersurface.

This is a fast (constant time) operation.

This and the given normal hypersurface do not need to live in the same underlying triangulation, and they do not need to have the same length vectors or use the same normal coordinate system - if any of these properties differs then the two hypersurfaces will be adjusted accordingly.

Parameters

other the normal hypersurface whose contents should be swapped with this.

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

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.

Todo:: Bug: Check for absurdly large numbers of pieces and return null 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.

This will be a snapshot frozen in time of the triangulation that was originally passed to the NormalHypersurface constructor.

This will return a correct result even if the original triangulation has since been modified or destroyed. However, in order to ensure this behaviour, it is possible that at different points in time this function may return references to different C++ objects.

The rules for using the triangulation() reference are:

Do not keep the resulting reference as a long-term reference or pointer of your own, since in time you may find yourself referring to the wrong object (see above). Just call this function again.
You must respect the read-only nature of the result (i.e., you must not cast the constness away). The snapshotting process detects modifications, and modifying the frozen snapshot may result in an exception being thrown.

Returns: a reference to the underlying triangulation.

◆ utf8()

template<class T , bool supportsUtf8 = false>

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

inherited

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

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ vector()

const Vector< LargeInteger > & regina::NormalHypersurface::vector ( ) const

inline

Gives read-only access to the integer vector that Regina uses internally to represent this hypersurface.

Note that this vector might not use the same coordinate system in which the hypersurfaces were originally enumerated. (For example, this vector will always include tetrahedron coordinates, even if the surfaces were originally enumerated in prism coordinates.) You can call encoding() to find out precisley how the coordinates of this vector should be interpreted.

See the NormalHypersurface class notes for information on how this vector is structured.

Note: If you wish to access the numbers of tetrahedra, prisms and so on, you should use the functions tetrahedra(), prisms(), etc., which do not require any knowledge of the internal vector encoding that this hypersurface uses.

Returns: the underlying integer vector.

◆ writeRawVector()

void regina::NormalHypersurface::writeRawVector ( std::ostream & out ) const

inline

Deprecated routine that 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.

Deprecated:: Just write vector() directly to the output stream.

Python: Not present; instead just write vector() to the appropriate output stream.

Parameters

out	the 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; instead you can call detail() from the subclass T, which returns this output as a string.

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; use str() instead.

Parameters

out	the output stream to which to write.

◆ writeXMLData()

void regina::NormalHypersurface::writeXMLData	(	std::ostream &	out,
		FileFormat	format,
		const NormalHypersurfaces *	list
	)		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: The argument out should be an open Python file object.

Parameters

out	the output stream to which the XML should be written.
format	indicates which of Regina's XML file formats to write.
list	the enclosing normal hypersurface list. Currently this is only relevant when writing to the older REGINA_XML_GEN_2 format; it will be ignored (and may be `null`) for newer file formats.

Member Data Documentation

◆ compact_

std::optional<bool> regina::NormalHypersurface::compact_

mutableprotected

Is this hypersurface compact (i.e., does it only contain finitely many pieces)? This is std::nullopt if it has not yet been computed.

◆ connected_

std::optional<bool> regina::NormalHypersurface::connected_

mutableprotected

Is this hypersurface connected? This is std::nullopt if it has not yet been computed.

◆ enc_

HyperEncoding regina::NormalHypersurface::enc_

protected

The specific encoding of a normal hypersurface used by the coordinate vector.

◆ H1_

std::optional<AbelianGroup> regina::NormalHypersurface::H1_

mutableprotected

First homology group of the hypersurface.

This is std::nullopt if it has not yet been computed.

◆ name_

std::string regina::NormalHypersurface::name_

protected

An optional name associated with this hypersurface.

◆ orientable_

std::optional<bool> regina::NormalHypersurface::orientable_

mutableprotected

Is this hypersurface orientable? This is std::nullopt if it has not yet been computed.

◆ realBoundary_

std::optional<bool> regina::NormalHypersurface::realBoundary_

mutableprotected

Does this hypersurface have real boundary (i.e.

does it meet any boundary facets)? This is std::nullopt if it has not yet been computed.

◆ triangulation_

SnapshotRef<Triangulation<4> > regina::NormalHypersurface::triangulation_

protected

The triangulation in which this normal hypersurface resides.

◆ twoSided_

std::optional<bool> regina::NormalHypersurface::twoSided_

mutableprotected

Is this hypersurface two-sided? This is std::nullopt if it has not yet been computed.

◆ vector_

Vector<LargeInteger> regina::NormalHypersurface::vector_

protected

Contains the coordinates of the normal hypersurface.

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

hypersurface/normalhypersurface.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ NormalHypersurface() [1/12]

◆ NormalHypersurface() [2/12]

◆ NormalHypersurface() [3/12]

◆ NormalHypersurface() [4/12]

◆ NormalHypersurface() [5/12]

◆ NormalHypersurface() [6/12]

◆ NormalHypersurface() [7/12]

◆ NormalHypersurface() [8/12]

◆ NormalHypersurface() [9/12]

◆ NormalHypersurface() [10/12]

◆ NormalHypersurface() [11/12]

◆ NormalHypersurface() [12/12]

Member Function Documentation

◆ clone()

◆ detail()

◆ doubleHypersurface()

◆ edgeWeight()

◆ embedded()

◆ encoding()

◆ hasRealBoundary()

◆ homology()

◆ isCompact()

◆ isConnected()

◆ isEmpty()

◆ isOrientable()

◆ isThinEdgeLink()

◆ isTwoSided()

◆ isVertexLink()

◆ isVertexLinking()

◆ locallyCompatible()

◆ name()

◆ operator!=()

◆ operator+()

◆ operator<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ prisms()

◆ rawVector()

◆ reconstructTetrahedra()

◆ sameSurface()

◆ setName()

◆ str()

◆ swap()

◆ tetrahedra()

◆ triangulate()

◆ triangulation()

◆ utf8()

◆ vector()

◆ writeRawVector()

◆ writeTextLong()

◆ writeTextShort()

◆ writeXMLData()

Member Data Documentation

◆ compact_

◆ connected_

◆ enc_

◆ H1_

◆ name_

◆ orientable_

◆ realBoundary_

◆ triangulation_

◆ twoSided_

◆ vector_