Normal Hypersurfaces

## Classes

class | regina::HSVectorStandard
| A normal hypersurface vector using standard tetrahedron-prism coordinates. More...
class | regina::MatrixIntDomain< T >
| Represents a matrix of elements from a given integral domain T. More...
struct | regina::HyperInfo< coordType >
| A template that stores information about a particular normal hypersurface coordinate system. More...
class | regina::NormalHypersurfaceVector
| Stores the vector of a single normal hypersurface in a 4-manifold triangulation. More...
class | regina::NormalHypersurface
| Represents a single normal hypersurface in a 4-manifold triangulation. More...
class | regina::NormalHypersurfaces::VectorIterator
| A bidirectional iterator that runs through the raw vectors for hypersurfaces in this list. More...
struct | regina::NormalHypersurfaces::HypersurfaceInserter
| An output iterator used to insert hypersurfaces into an NormalHypersurfaces. More...
class | regina::NormalHypersurfaces
| A packet representing a collection of normal hypersurfaces in a 4-manifold triangulation. More...
class | regina::XMLNormalHypersurfaceReader
| An XML element reader that reads a single normal hypersurface in a 4-manifold triangulation. More...
class | regina::XMLNormalHypersurfacesReader
| An XML packet reader that reads a single normal hypersurface list. More...

## Macros

#define | REGINA_NORMAL_HYPERSURFACE_FLAVOUR(class_, id, superclass)
| Defines various constants, types and virtual functions for a subclass of NormalHypersurfaceVector. More...

## Typedefs

typedef HSVectorStandard | regina::NNormalHypersurfaceVectorStandard
| Deprecated typedef for backward compatibility. More...
typedef regina::Flags< HyperListFlags > | regina::HyperList
| A combination of flags for types of normal hypersurface lists. More...
typedef regina::Flags< HyperAlgFlags > | regina::HyperAlg
| A combination of flags for types of normal surface lists. More...
typedef MatrixIntDomain< Integer > | regina::MatrixInt
| A matrix of arbitrary-precision integers. More...
typedef NormalHypersurfaceVector | regina::NNormalHypersurfaceVector
| Deprecated typedef for backward compatibility. More...
typedef NormalHypersurface | regina::NNormalHypersurface
| Deprecated typedef for backward compatibility. More...
typedef NormalHypersurfaces | regina::NNormalHypersurfaceList
| Deprecated typedef for backward compatibility. More...

## Enumerations

enum | regina::HyperCoords { regina::HS_STANDARD = 0, regina::HS_PRISM = 1, regina::HS_EDGE_WEIGHT = 200 }
| Represents different coordinate systems that can be used for enumerating and displaying normal hypersurface within 4-manifold triangulations. More...
enum | regina::HyperListFlags { regina::HS_LIST_DEFAULT = 0x0000, regina::HS_EMBEDDED_ONLY = 0x0001, regina::HS_IMMERSED_SINGULAR = 0x0002, regina::HS_VERTEX = 0x0004, regina::HS_FUNDAMENTAL = 0x0008, regina::HS_LEGACY = 0x4000, regina::HS_CUSTOM = 0x8000 }
| Represents different lists of normal hypersurfaces that might be constructed for a given 4-manifold triangulation. More...
enum | regina::HyperAlgFlags { regina::HS_ALG_DEFAULT = 0x0000, regina::HS_VERTEX_DD = 0x0020, regina::HS_HILBERT_PRIMAL = 0x0100, regina::HS_HILBERT_DUAL = 0x0200, regina::HS_ALG_LEGACY = 0x4000, regina::HS_ALG_CUSTOM = 0x8000 }
| Represents options and variants of algorithms for enumerating various types of normal hypersurfaces in 4-manifold triangulations. More...

## Functions

template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::ReturnType | regina::forCoords (HyperCoords coords, FunctionObject &&func, typename ReturnsTraits< FunctionObject >::ReturnType defaultReturn, Args &&... args)
| Allows the user to call a template function whose template parameter matches a given value of HyperCoords, which is not known until runtime. More...
template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::Void | regina::forCoords (HyperCoords coords, FunctionObject &&func, Args &&... args)
| Allows the user to call a template function whose template parameter matches a given value of HyperCoords, which is not known until runtime. More...
| regina::HSVectorStandard::HSVectorStandard (size_t length)
| Creates a new vector all of whose entries are initialised to zero. More...
| regina::HSVectorStandard::HSVectorStandard (const Vector< LargeInteger > &cloneMe)
| Creates a new vector that is a clone of the given vector. More...
virtual LargeInteger | regina::HSVectorStandard::tetrahedra (size_t pentIndex, int vertex, const Triangulation< 4 > *triang) const
| Returns the number of tetrahedron pieces of the given type in this normal hypersurface. More...
virtual LargeInteger | regina::HSVectorStandard::prisms (size_t pentIndex, int prismType, const Triangulation< 4 > *triang) const
| Returns the number of prism pieces of the given type in this normal hypersurface. More...
virtual LargeInteger | regina::HSVectorStandard::edgeWeight (size_t edgeIndex, const Triangulation< 4 > *triang) const
| Returns the number of times this normal hypersurface crosses the given edge. More...
static NormalHypersurfaceVector * | regina::HSVectorStandard::makeZeroVector (const Triangulation< 4 > *triangulation)
static MatrixInt * | regina::HSVectorStandard::makeMatchingEquations (const Triangulation< 4 > *triangulation)
static EnumConstraints * | regina::HSVectorStandard::makeEmbeddedConstraints (const Triangulation< 4 > *triangulation)
HyperList | regina::operator| (HyperListFlags lhs, HyperListFlags rhs)
| Returns the bitwise OR of the two given flags. More...
HyperAlg | regina::operator| (HyperAlgFlags lhs, HyperAlgFlags rhs)
| Returns the bitwise OR of the two given flags. More...
| regina::NormalHypersurfaceVector::NormalHypersurfaceVector (size_t length)
| Creates a new vector all of whose entries are initialised to zero. More...
| regina::NormalHypersurfaceVector::NormalHypersurfaceVector (const Vector< LargeInteger > &cloneMe)
| Creates a new vector that is a clone of the given vector. More...
virtual | regina::NormalHypersurfaceVector::~NormalHypersurfaceVector ()
| A virtual destructor. More...
const Ray & | regina::NormalHypersurfaceVector::coords () const
| Gives read-only access to the underlying vector of coordinates. More...
virtual NormalHypersurfaceVector * | regina::NormalHypersurfaceVector::clone () const =0
| Creates a newly allocated clone of this vector. More...
size_t | regina::NormalHypersurfaceVector::size () const
| Returns the number of coordinates in the underlying vector. More...
const NLargeInteger & | regina::NormalHypersurfaceVector::operator[] (size_t index) const
| Returns the given coordinate from the underlying vector. More...
virtual void | regina::NormalHypersurfaceVector::setElement (size_t index, const LargeInteger &value)
| Sets the given normal coordinate to the given value. More...
virtual void | regina::NormalHypersurfaceVector::operator+= (const NormalHypersurfaceVector &other)
| Adds the given vector to this vector. More...
virtual void | regina::NormalHypersurfaceVector::scaleDown ()
| Scales this vector down by the greatest common divisor of all its elements. More...
virtual bool | regina::NormalHypersurfaceVector::isCompact (const Triangulation< 4 > *triang) const
| Determines if the normal hypersurface represented is compact (has finitely many pieces). More...
virtual bool | regina::NormalHypersurfaceVector::isVertexLinking (const Triangulation< 4 > *triang) const
| Determines if the normal hypersurface represented is vertex linking. More...
virtual const Vertex< 4 > * | regina::NormalHypersurfaceVector::isVertexLink (const Triangulation< 4 > *triang) const
| Determines if a rational multiple of the normal hypersurface represented is the link of a single vertex. More...
virtual const Edge< 4 > * | regina::NormalHypersurfaceVector::isThinEdgeLink (const Triangulation< 4 > *triang) const
| Determines if a rational multiple of the normal hypersurface represented is the thin link of a single edge. More...
virtual LargeInteger | regina::NormalHypersurfaceVector::tetrahedra (size_t pentIndex, int vertex, const Triangulation< 4 > *triang) const =0
| Returns the number of tetrahedron pieces of the given type in this normal hypersurface. More...
virtual LargeInteger | regina::NormalHypersurfaceVector::prisms (size_t pentIndex, int prismType, const Triangulation< 4 > *triang) const =0
| Returns the number of prism pieces of the given type in this normal hypersurface. More...
virtual LargeInteger | regina::NormalHypersurfaceVector::edgeWeight (size_t edgeIndex, const Triangulation< 4 > *triang) const =0
| Returns the number of times this normal hypersurface crosses the given edge. More...
static NormalHypersurfaceVector * | regina::NormalHypersurfaceVector::makeZeroVector (const Triangulation< 4 > *triangulation)
| Returns a new normal hypersurface vector of the appropriate length for the given triangulation and for the coordinate system corresponding to this subclass of NormalHypersurfaceVector. More...
static MatrixInt * | regina::NormalHypersurfaceVector::makeMatchingEquations (const Triangulation< 4 > *triangulation)
| Creates a new set of normal hypersurface matching equations for the given triangulation using the coordinate system corresponding to this particular subclass of NormalHypersurfaceVector. More...
static EnumConstraints * | regina::NormalHypersurfaceVector::makeEmbeddedConstraints (const Triangulation< 4 > *triangulation)
| Creates a new set of validity constraints representing the condition that normal hypersurfaces be embedded. More...
| regina::NormalHypersurface::NormalHypersurface (const Triangulation< 4 > *triangulation, NormalHypersurfaceVector *vector)
| Creates a new normal hypersurface inside the given triangulation with the given coordinate vector. More...
| 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. More...
| regina::NormalHypersurface::~NormalHypersurface ()
| Destroys this normal hypersurface. More...
NormalHypersurface * | regina::NormalHypersurface::clone () const
| Creates a newly allocated clone of this normal hypersurface. More...
NormalHypersurface * | regina::NormalHypersurface::doubleHypersurface () const
| Creates a newly allocated hypersurface that is the double of this hypersurface. More...
LargeInteger | regina::NormalHypersurface::tetrahedra (size_t pentIndex, int vertex) const
| Returns the number of tetrahedron pieces of the given type in this normal hypersurface. More...
LargeInteger | regina::NormalHypersurface::prisms (size_t pentIndex, int prismType) const
| Returns the number of prism pieces of the given type in this normal hypersurface. More...
LargeInteger | regina::NormalHypersurface::edgeWeight (size_t edgeIndex) const
| Returns the number of times this normal hypersurface crosses the given edge. More...
size_t | regina::NormalHypersurface::countCoords () const
| Returns the number of coordinates in the specific underlying coordinate system being used. More...
const Triangulation< 4 > * | regina::NormalHypersurface::triangulation () const
| Returns the triangulation in which this normal hypersurface resides. More...
const std::string & | regina::NormalHypersurface::name () const
| Returns the name associated with this normal hypersurface. More...
void | regina::NormalHypersurface::setName (const std::string &name)
| Sets the name associated with this normal hypersurface. More...
void | regina::NormalHypersurface::writeTextShort (std::ostream &out) const
| Writes this hypersurface to the given output stream, using standard tetrahedron-prism coordinates. More...
void | regina::NormalHypersurface::writeRawVector (std::ostream &out) const
| Writes the underlying coordinate vector to the given output stream in text format. More...
void | regina::NormalHypersurface::writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this normal hypersurface and all of its properties. More...
bool | regina::NormalHypersurface::isEmpty () const
| Determines if this normal hypersurface is empty (has no pieces whatsoever). More...
bool | regina::NormalHypersurface::isCompact () const
| Determines if this normal hypersurface is compact (has finitely many pieces). More...
bool | regina::NormalHypersurface::isOrientable () const
| Returns whether or not this hypersurface is orientable. More...
bool | regina::NormalHypersurface::isTwoSided () const
| Returns whether or not this hypersurface is two-sided. More...
bool | regina::NormalHypersurface::isConnected () const
| Returns whether or not this hypersurface is connected. More...
bool | regina::NormalHypersurface::hasRealBoundary () const
| Determines if this hypersurface has any real boundary, that is, whether it meets any boundary tetrahedra of the triangulation. More...
bool | regina::NormalHypersurface::isVertexLinking () const
| Determines whether or not this hypersurface is vertex linking. More...
const Vertex< 4 > * | regina::NormalHypersurface::isVertexLink () const
| Determines whether or not a rational multiple of this hypersurface is the link of a single vertex. More...
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. More...
const AbelianGroup & | regina::NormalHypersurface::homology () const
| Returns the first homology group of this hypersurface. More...
Triangulation< 3 > * | regina::NormalHypersurface::triangulate () const
| Returns a 3-manifold triangulation describing this normal hypersurface. More...
bool | regina::NormalHypersurface::sameSurface (const NormalHypersurface &other) const
| Determines whether this and the given hypersurface in fact represent the same normal hypersurface. More...
bool | regina::NormalHypersurface::embedded () const
| Determines whether this hypersurface is embedded. More...
bool | regina::NormalHypersurface::locallyCompatible (const NormalHypersurface &other) const
| Determines whether this and the given hypersurface are locally compatible. More...
const Ray & | regina::NormalHypersurface::rawVector () const
| Gives read-only access to the raw vector that sits beneath this normal hypersurface. More...
void | regina::NormalHypersurface::calculateRealBoundary () const
| Calculates whether this hypersurface has any real boundary and stores the result as a property. More...
void | regina::NormalHypersurface::calculateFromTriangulation () const
| Calculate and store all properties that we derive from the 3-manifold triangulation of this hypersurface. More...
virtual | regina::NormalHypersurfaces::~NormalHypersurfaces ()
| Destroys this list and all the hypersurfaces within. More...
static NormalHypersurfaces * | regina::NormalHypersurfaces::enumerate (Triangulation< 4 > *owner, HyperCoords coords, HyperList which=HS_LIST_DEFAULT, HyperAlg algHints=HS_ALG_DEFAULT, ProgressTracker *tracker=0)
| A unified routine for enumerating various classes of normal hypersurfaces within a given triangulation. More...
HyperCoords | regina::NormalHypersurfaces::coords () const
| Returns the coordinate system being used by the hypersurfaces stored in this set. More...
HyperList | regina::NormalHypersurfaces::which () const
| Returns details of which normal hypersurfaces this list represents within the underlying triangulation. More...
HyperAlg | regina::NormalHypersurfaces::algorithm () const
| Returns details of the algorithm that was used to enumerate this list. More...
bool | regina::NormalHypersurfaces::isEmbeddedOnly () const
| Returns whether this set is known to contain only embedded normal hypersurfaces. More...
Triangulation< 4 > * | regina::NormalHypersurfaces::triangulation () const
| Returns the triangulation in which these normal hypersurfaces live. More...
size_t | regina::NormalHypersurfaces::size () const
| Returns the number of hypersurfaces stored in this list. More...
const NormalHypersurface * | regina::NormalHypersurfaces::hypersurface (size_t index) const
| Returns the hypersurface at the requested index in this list. More...
virtual void | regina::NormalHypersurfaces::writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
virtual void | regina::NormalHypersurfaces::writeTextLong (std::ostream &out) const
| Writes a detailed text representation of this object to the given output stream. More...
static XMLPacketReader * | regina::NormalHypersurfaces::xmlReader (Packet *parent, XMLTreeResolver &resolver)
virtual bool | regina::NormalHypersurfaces::dependsOnParent () const
| Determines if this packet depends upon its parent. More...
MatrixInt * | regina::NormalHypersurfaces::recreateMatchingEquations () const
| Returns a newly created matrix containing the matching equations that were used to create this normal hypersurface list. More...
VectorIterator | regina::NormalHypersurfaces::beginVectors () const
| An iterator that gives access to the raw vectors for hypersurfaces in this list, pointing to the beginning of this hypersurface list. More...
VectorIterator | regina::NormalHypersurfaces::endVectors () const
| An iterator that gives access to the raw vectors for hypersurfaces in this list, pointing past the end of this hypersurface list. More...
| regina::NormalHypersurfaces::VectorIterator::VectorIterator ()
| Creates a new uninitialised iterator. More...
| regina::NormalHypersurfaces::VectorIterator::VectorIterator (const VectorIterator &cloneMe)
| Creates a copy of the given iterator. More...
VectorIterator & | regina::NormalHypersurfaces::VectorIterator::operator= (const VectorIterator &cloneMe)
| Makes this a copy of the given iterator. More...
bool | regina::NormalHypersurfaces::VectorIterator::operator== (const VectorIterator &other) const
| Compares this with the given operator for equality. More...
bool | regina::NormalHypersurfaces::VectorIterator::operator!= (const VectorIterator &other) const
| Compares this with the given operator for inequality. More...
const Ray & | regina::NormalHypersurfaces::VectorIterator::operator* () const
| Returns the raw vector for the normal hypersurface that this iterator is currently pointing to. More...
VectorIterator & | regina::NormalHypersurfaces::VectorIterator::operator++ ()
| The preincrement operator. More...
VectorIterator | regina::NormalHypersurfaces::VectorIterator::operator++ (int)
| The postincrement operator. More...
VectorIterator & | regina::NormalHypersurfaces::VectorIterator::operator-- ()
| The predecrement operator. More...
VectorIterator | regina::NormalHypersurfaces::VectorIterator::operator-- (int)
| The postdecrement operator. More...
| regina::NormalHypersurfaces::NormalHypersurfaces (HyperCoords coords, HyperList which, HyperAlg algorithm)
| Creates an empty list of normal hypersurfaces with the given parameters. More...
virtual Packet * | regina::NormalHypersurfaces::internalClonePacket (Packet *parent) const
| Makes a newly allocated copy of this packet. More...
virtual void | regina::NormalHypersurfaces::writeXMLPacketData (std::ostream &out) const
| Writes a chunk of XML containing the data for this packet only. More...
| regina::NormalHypersurfaces::HypersurfaceInserter::HypersurfaceInserter (NormalHypersurfaces &list, Triangulation< 4 > *owner)
| Creates a new output iterator. More...
| regina::NormalHypersurfaces::HypersurfaceInserter::HypersurfaceInserter (const HypersurfaceInserter &cloneMe)
| Creates a new output iterator that is a clone of the given iterator. More...
HypersurfaceInserter & | regina::NormalHypersurfaces::HypersurfaceInserter::operator= (const HypersurfaceInserter &cloneMe)
| Sets this iterator to be a clone of the given output iterator. More...
HypersurfaceInserter & | regina::NormalHypersurfaces::HypersurfaceInserter::operator= (NormalHypersurface *hypersurface)
| Appends a normal hypersurface to the end of the appropriate surface list. More...
HypersurfaceInserter & | regina::NormalHypersurfaces::HypersurfaceInserter::operator= (NormalHypersurfaceVector *vector)
| Appends the normal hypersurface corresponding to the given vector to the end of the appropriate hypersurface list. More...
HypersurfaceInserter & | regina::NormalHypersurfaces::HypersurfaceInserter::operator* ()
| Returns a reference to this output iterator. More...
HypersurfaceInserter & | regina::NormalHypersurfaces::HypersurfaceInserter::operator++ ()
| Returns a reference to this output iterator. More...
HypersurfaceInserter & | regina::NormalHypersurfaces::HypersurfaceInserter::operator++ (int)
| Returns a reference to this output iterator. More...
| regina::NormalHypersurfaces::Enumerator::Enumerator (NormalHypersurfaces *list, Triangulation< 4 > *triang, ProgressTracker *tracker)
| Creates a new functor with the given parameters. More...
template<typename Coords >
void | regina::NormalHypersurfaces::Enumerator::operator() ()
| Performs the real enumeration work, in a setting where the underlying coordinate system is a compile-time constant. More...
NormalHypersurfaceVector * | regina::makeZeroVector (const Triangulation< 4 > *triangulation, HyperCoords coords)
| Returns a new normal hypersurface vector of the appropriate length for the given triangulation and the given coordinate system. More...
MatrixInt * | regina::makeMatchingEquations (const Triangulation< 4 > *triangulation, HyperCoords coords)
| Creates a new set of normal hypersurface matching equations for the given triangulation using the given coordinate system. More...
EnumConstraints * | regina::makeEmbeddedConstraints (const Triangulation< 4 > *triangulation, HyperCoords coords)
| Creates a new set of validity constraints representing the condition that normal hypersurfaces be embedded. More...
| regina::XMLNormalHypersurfaceReader::XMLNormalHypersurfaceReader (const Triangulation< 4 > *tri, HyperCoords coords)
| Creates a new normal hypersurface reader. More...
NormalHypersurface * | regina::XMLNormalHypersurfaceReader::hypersurface ()
| Returns the normal hypersurface that has been read. More...
virtual void | regina::XMLNormalHypersurfaceReader::startElement (const std::string &tagName, const regina::xml::XMLPropertyDict &tagProps, XMLElementReader *parentReader)
| Signifies that parsing of this XML element is beginning. More...
virtual void | regina::XMLNormalHypersurfaceReader::initialChars (const std::string &chars)
| Signifies that the initial text belonging to this XML element has been read. More...
virtual XMLElementReader * | regina::XMLNormalHypersurfaceReader::startSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps)
| Signifies that a subelement of this XML element is about to be parsed. More...
| regina::XMLNormalHypersurfacesReader::XMLNormalHypersurfacesReader (const Triangulation< 4 > *tri, XMLTreeResolver &resolver)
| Creates a new normal hypersurface list reader. More...
virtual Packet * | regina::XMLNormalHypersurfacesReader::packet () override
| Returns the newly allocated packet that has been read by this element reader. More...
virtual XMLElementReader * | regina::XMLNormalHypersurfacesReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
| Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
virtual void | regina::XMLNormalHypersurfacesReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader) override
| Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...

## Variables

Ray | regina::NormalHypersurfaceVector::coords_
| The raw vector of normal coordinates. More...
NormalHypersurfaceVector * | regina::NormalHypersurface::vector_
| Contains the coordinates of the normal hypersurface in whichever space is appropriate. More...
const Triangulation< 4 > * | regina::NormalHypersurface::triangulation_
| The triangulation in which this normal hypersurface resides. More...
std::string | regina::NormalHypersurface::name_
| An optional name associated with this hypersurface. More...
Property< bool > | regina::NormalHypersurface::orientable_
| Is this hypersurface orientable? More...
Property< bool > | regina::NormalHypersurface::twoSided_
| Is this hypersurface two-sided? More...
Property< bool > | regina::NormalHypersurface::connected_
| Is this hypersurface connected? More...
Property< bool > | regina::NormalHypersurface::realBoundary_
| Does this hypersurface have real boundary (i.e. More...
Property< bool > | regina::NormalHypersurface::compact_
| Is this hypersurface compact (i.e., does it only contain finitely many pieces)? More...
Property< AbelianGroup, StoreManagedPtr > | regina::NormalHypersurface::H1_
| First homology group of the hypersurface. More...
std::vector< NormalHypersurface * > | regina::NormalHypersurfaces::surfaces_
| Contains the normal hypersurfaces stored in this packet. More...
HyperCoords | regina::NormalHypersurfaces::coords_
| Stores which coordinate system is being used by the normal hypersurfaces in this packet. More...
HyperList | regina::NormalHypersurfaces::which_
| Indicates which normal hypersurfaces these represent within the underlying triangulation. More...
HyperAlg | regina::NormalHypersurfaces::algorithm_
| Stores the details of the enumeration algorithm that was used to generate this list. More...
NormalHypersurfaces * | regina::NormalHypersurfaces::HypersurfaceInserter::list_
| The list into which hypersurfaces will be inserted. More...
Triangulation< 4 > * | regina::NormalHypersurfaces::HypersurfaceInserter::owner_
| The triangulation in which the hypersurfaces to be inserted are contained. More...

## Friends

class | regina::NormalHypersurface::XMLNormalHypersurfaceReader
class | regina::NormalHypersurfaces::VectorIterator::NormalHypersurfaces
class | regina::NormalHypersurfaces::XMLNormalHypersurfacesReader

## Detailed Description

Normal hypersurfaces in 4-manifold triangulations.

## Macro Definition Documentation

## REGINA_NORMAL_HYPERSURFACE_FLAVOUR

#define REGINA_NORMAL_HYPERSURFACE_FLAVOUR | ( |  | class_,
|  |  | id,
|  |  | superclass
| ) |  |

Value:
public: \
typedef HyperInfo<id> Info; \
static constexpr const HyperCoords coordsID = id; \
inline class_(const class_& cloneMe) : \
superclass(cloneMe.coords()) {} \
inline virtual NormalHypersurfaceVector* clone() const { \
return new class_(*this); \
}

Defines various constants, types and virtual functions for a subclass of NormalHypersurfaceVector.

Every subclass of NormalHypersurfaceVector must include REGINA_NORMAL_HYPERSURFACE_FLAVOUR at the beginning of the class definition.

This macro provides the class with:

- a compile-time enum constant coordsID, which is equal to the corresponding HyperCoords constant;
- a typedef Info, which refers to the corresponding specialisation of the HyperInfo<> tempate;
- a copy constructor that takes a vector of the same subclass;
- declarations and implementations of the virtual function NormalHypersurfaceVector::clone().

Parameters

  class_ | the name of this subclass of NormalHypersurfaceVector.
  id | the corresponding NNormalCoords constant.
  superclass | the vector class from which class_ is derived. This is typically NormalHypersurfaceVector, though in some cases (e.g., prism coordinates) it may be different.

## Typedef Documentation

## HyperAlg

typedef regina::Flags<HyperAlgFlags> regina::HyperAlg

A combination of flags for types of normal surface lists.

Python:\n This is present, and all values in the HyperAlgFlags
  enumeration type are treated as members of this HyperAlg class.

## HyperList

typedef regina::Flags<HyperListFlags> regina::HyperList

A combination of flags for types of normal hypersurface lists.

Python:\n This is present, and all values in the HyperListFlags
  enumeration type are treated as members of this HyperList class.

## MatrixInt

typedef MatrixIntDomain< Integer > regina::MatrixInt

A matrix of arbitrary-precision integers.

This is the most common class used by Regina when running algebraic algorithms over integer matrices. Since the underlying type is Regina's Integer class, calculations will be exact regardless of how large the integers become.

Python:\n This represents the class MatrixIntDomain,
  which inherits from Matrix<Integer> and MatrixRing<Integer>. Most but not all inherited functions are implemented; see the individual members' documentation for exceptions where they arise.

## NNormalHypersurface

typedef NormalHypersurface regina::NNormalHypersurface

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurface has now been renamed to NormalHypersurface.

## NNormalHypersurfaceList

typedef NormalHypersurfaces regina::NNormalHypersurfaceList

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurfaceList has now been renamed to NormalHypersurfaces.

## NNormalHypersurfaceVector

typedef NormalHypersurfaceVector regina::NNormalHypersurfaceVector

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurfaceVector has now been renamed to NormalHypersurfaceVector.

## NNormalHypersurfaceVectorStandard

typedef HSVectorStandard regina::NNormalHypersurfaceVectorStandard

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NNormalHypersurfaceVectorStandard has now been renamed to HSVectorStandard.

## Enumeration Type Documentation

## HyperAlgFlags

enum regina::HyperAlgFlags

Represents options and variants of algorithms for enumerating various types of normal hypersurfaces in 4-manifold triangulations.

These options are typically combined in a bitwise fashion using the HyperAlg type, and then passed to enumeration routines such as NormalHypersurfaces::enumerate().

Python:\n The values in this enumeration type are present, but
  they are treated by Python as HyperList objects (and they can be combined and/or queried as such). The underlying enumeration type is not exposed to Python.

Enumerator
HS_ALG_DEFAULT | An empty flag, indicating to an enumeration routine that it should use its default behaviour. The numeric value of this flag is zero (i.e., it has no effect when combined with other flags using bitwise OR).

HS_VERTEX_DD

When enumerating vertex normal hypersurfaces, this flag indicates that a modified double description method should be used.

This algorithm can suffer from a combinatorial explosion with larger problems, leading to extremely large time and memory footprints. Users should only request this if they have some specialised need.

Having said that: this is the only algorithm that Regina currently supports for 4-dimensional vertex enumeration (unlike the 3-dimensional case, where several alternative algorithms are available). Therefore Regina will use the double description method regardless. Alternative algorithms will be implemented in future versions of Regina.

For details on the modified double description method, see B. A. Burton, "Optimizing the double description method for normal surface enumeration", Mathematics of Computation 79 (2010), pp. 453-484.

HS_HILBERT_PRIMAL

When enumerating fundamental normal hypersurfaces, this flag indicates that the primal method should be used for enumerating a Hilbert basis.

The primal method is recommended, and enumeration algorithms will use it if possible unless a different method is explicitly requested. This method uses code from Normaliz for parts of its processing.

For details and comparisons of the various options for enumerating fundamental normal surfaces, see B. A. Burton, "Enumerating fundamental normal surfaces: Algorithms, experiments and invariants", ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, SIAM, 2014, pp. 112-124.

This flag is incompatible with HS_HILBERT_DUAL.

HS_HILBERT_DUAL

When enumerating fundamental normal hypersurfaces, this flag indicates that the dual method should be used for enumerating a Hilbert basis.

The dual method is fast (like the primal method), but its performance is highly variable; for this reason the primal method is recommended instead. This method does not make use of Normaliz, and is the recommended method for situations in which Normaliz is not available for some reason.

For details and comparisons of the various options for enumerating fundamental normal surfaces, see B. A. Burton, "Enumerating fundamental normal surfaces: Algorithms, experiments and invariants", ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, SIAM, 2014, pp. 112-124.

This flag is incompatible with HS_HILBERT_PRIMAL.

HS_ALG_LEGACY | Indicates that a normal hypersurface list was enumerated using an older prerelease version of the 4-manifolds code (prior to Regina 5.0). These prerelease versions did not retain details of the algorithm used to build each list, and so in such cases no further algorithmic information is available. If this flag is passed to an enumeration algorithm, it will be ignored.
HS_ALG_CUSTOM | Indicates that a normal hypersurface list was built using a customised algorithm. In such cases, no further details on the algorithm are available. If this flag is passed to an enumeration algorithm, it will be ignored.

## HyperCoords

enum regina::HyperCoords

Represents different coordinate systems that can be used for enumerating and displaying normal hypersurface within 4-manifold triangulations.

IDs 0-9999 are reserved for future use by Regina. If you are extending Regina to include your own coordinate system, you should choose an ID >= 10000.

Enumerator
HS_STANDARD | Represents standard tetrahedron-prism coordinates for normal hypersurfaces.
HS_PRISM | Represents prism coordinates for normal hypersurfaces. For now, this coordinate system is for representation only; hypersurface vectors and lists cannot be created in this coordinate system. This will likely change in a future release of Regina, when prism coordinates will be supported for creation as well as viewing.
HS_EDGE_WEIGHT | Represents edge weight coordinates for normal hypersurfaces. This coordinate system is for representation only; hypersurface vectors and lists cannot be created in this coordinate system.

## HyperListFlags

enum regina::HyperListFlags

Represents different lists of normal hypersurfaces that might be constructed for a given 4-manifold triangulation.

The HyperList enumeration refers to the contents of the list, whereas the HyperAlgFlags enumeration refers to the algorithm used to build it.

Python:\n The values in this enumeration type are present, but
  they are treated by Python as HyperList objects (and they can be combined and/or queried as such). The underlying enumeration type is not exposed to Python.

Enumerator
HS_LIST_DEFAULT | An empty flag, indicating to an enumeration routine that it should use its default behaviour. The numeric value of this flag is zero (i.e., it has no effect when combined with other flags using bitwise OR).
HS_EMBEDDED_ONLY | Indicates that this list is restricted to properly embedded hypersurfaces only. This flag is incompatible with HS_IMMERSED_SINGULAR.

HS_IMMERSED_SINGULAR

Indicates that the scope of this list includes not just properly embedded hypersurfaces, but also immersed and/or branched hypersurfaces.

This is no guarantee that the list contains immersed and/or branched hypersurfaces; it merely states that such hypersurfaces have not been explicitly excluded (in particular, the prism constraints have not been enforced).

This flag is incompatible with HS_EMBEDDED_ONLY.

HS_VERTEX | Indicates a list of all vertex normal hypersurfaces, with respect to the particular normal coordinate system used by the list. This flag is incompatible with HS_FUNDAMENTAL.
HS_FUNDAMENTAL | Indicates a list of all fundamental normal hypersurfaces, with respect to the particular normal coordinate system used by the list. This flag is incompatible with HS_VERTEX.

HS_LEGACY

Indicates a list that was constructed using an older prerelease version of the 4-manifolds code (prior to Regina 5.0).

These prerelease versions did not retain details of how each list was constructed, beyond whether immersed and/or singular hypersurfaces were included. Therefore no information is available for such lists, other than the presence or absence of the HS_EMBEDDED_ONLY and/or HS_IMMERSED_SINGULAR flags.

If this flag is passed to an enumeration routine, it will be ignored.

HS_CUSTOM | Indicates some other type of list, typically hand-crafted by the user or built by some customised algorithm. If this flag is passed to an enumeration routine, it will be ignored.

## Function Documentation

## algorithm()

HyperAlg regina::NormalHypersurfaces::algorithm | ( |  | ) | const

inline

Returns details of the algorithm that was used to enumerate this list.

These may not be the same HyperAlg flags that were passed to enumerate(). In particular, default values will have been explicitly filled in, invalid and/or redundant values will have been removed, and unavailable and/or unsupported combinations of algorithm flags will be replaced with whatever algorithm was actually used.

Returns
  details of the algorithm used to enumerate this list.

## beginVectors()

NormalHypersurfaces::VectorIterator regina::NormalHypersurfaces::beginVectors | ( |  | ) | const

inline

An iterator that gives access to the raw vectors for hypersurfaces in this list, pointing to the beginning of this hypersurface list.

Python:\n Not present.

Returns
  an iterator at the beginning of this hypersurface list.

## 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() [1/2]

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.

## clone() [2/2]

virtual NormalHypersurfaceVector* regina::NormalHypersurfaceVector::clone | ( |  | ) | const

pure virtual

Creates a newly allocated clone of this vector.

The clone will be of the same subclass of NormalHypersurfaceVector as this vector.

## coords() [1/2]

HyperCoords regina::NormalHypersurfaces::coords | ( |  | ) | const

inline

Returns the coordinate system being used by the hypersurfaces stored in this set.

Returns
  the coordinate system used.

## coords() [2/2]

const Ray & regina::NormalHypersurfaceVector::coords | ( |  | ) | const

inline

Gives read-only access to the underlying vector of coordinates.

Returns
  the vector of coordinates.

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

## dependsOnParent()

bool regina::NormalHypersurfaces::dependsOnParent | ( |  | ) | const

inline virtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
  `true` if and only if this packet depends on its parent.

Implements regina::Packet.

## 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() [1/3]

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

inline

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

Parameters

  edgeIndex | the index in the triangulation of the edge in which we are interested; this should be between 0 and Triangulation<4>::countEdges()-1 inclusive.

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

## edgeWeight() [2/3]

virtual LargeInteger regina::HSVectorStandard::edgeWeight | ( | size_t | edgeIndex,
|  | const Triangulation< 4 > * | triang
| ) |  | const

virtual

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

See NormalHypersurface::edgeWeight() for further details.

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.
  triang | the triangulation in which this normal hypersurface lives.

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

Implements regina::NormalHypersurfaceVector.

## edgeWeight() [3/3]

virtual LargeInteger regina::NormalHypersurfaceVector::edgeWeight | ( | size_t | edgeIndex,
|  | const Triangulation< 4 > * | triang
| ) |  | const

pure virtual

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

See NormalHypersurface::edgeWeight() for further details.

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.
  triang | the triangulation in which this normal hypersurface lives.

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

Implemented in regina::HSVectorStandard.

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

## endContentSubElement()

virtual void regina::XMLNormalHypersurfacesReader::endContentSubElement | ( | const std::string & | subTagName,
|  | XMLElementReader * | subReader
| ) |  |

override virtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLPacketReader.

## endVectors()

NormalHypersurfaces::VectorIterator regina::NormalHypersurfaces::endVectors | ( |  | ) | const

inline

An iterator that gives access to the raw vectors for hypersurfaces in this list, pointing past the end of this hypersurface list.

This iterator is not dereferenceable.

Python:\n Not present.

Returns
  an iterator past the end of this hypersurface list.

## enumerate()

static NormalHypersurfaces* regina::NormalHypersurfaces::enumerate | ( | Triangulation< 4 > * | owner,
|  | HyperCoords | coords,
|  | HyperList | which = `HS_LIST_DEFAULT`,
|  | HyperAlg | algHints = `HS_ALG_DEFAULT`,
|  | ProgressTracker * | tracker = `0`
| ) |  |

static

A unified routine for enumerating various classes of normal hypersurfaces within a given triangulation.

The HyperCoords argument allows you to specify an underlying coordinate system.

The HyperList argument is a combination of flags that allows you to specify exactly which normal hypersurfaces you require. This includes (i) whether you want all vertex hypersurfaces or all fundamental hypersurfaces, which defaults to HS_VERTEX if you specify neither or both; and (ii) whether you want only properly embedded surfaces or you also wish to include immersed and/or singular surfaces, which defaults to HS_EMBEDDED_ONLY if you specify neither or both.

The HyperAlg argument is a combination of flags that allows you to control the underlying enumeration algorithm. These flags are treated as hints only: if your selection of algorithm is invalid, unavailable or unsupported then Regina will choose something more appropriate. Unless you have some specialised need, the default HS_ALG_DEFAULT (which makes no hints at all) will allow Regina to choose what it thinks will be the most efficient method.

The enumerated hypersurfaces will be stored in a new normal hypersurface list, and their representations will be scaled down to use the smallest possible integer coordinates. This normal hypersurface list will be inserted into the packet tree as the last child of the given triangulation. This triangulation must remain the parent of this normal hypersurface list, and must not change while this normal hypersurface list remains in existence.

If a progress tracker is passed, the normal hypersurface enumeration will take place in a new thread and this routine will return immediately. If the user cancels the operation from another thread, then the normal surface list will not be inserted into the packet tree (but the caller of this routine will still need to delete it). Regarding progress tracking, this routine will declare and work through a series of stages whose combined weights sum to 1; typically this means that the given tracker must not have been used before.

If no progress tracker is passed, the enumeration will run in the current thread and this routine will return only when the enumeration is complete. Note that this enumeration can be extremely slow for larger triangulations.

Parameters

  owner | the triangulation upon which this list of normal hypersurfaces will be based.
  coords | the coordinate system to be used.
  which | indicates which normal hypersurfaces should be enumerated.
  algHints | passes requests to Regina for which specific enumeration algorithm should be used.
  tracker | a progress tracker through which progress will be reported, or 0 if no progress reporting is required.

Returns
  the newly created normal hypersurface list. Note that if a progress tracker is passed then this list may not be completely filled when this routine returns. If a progress tracker is passed and a new thread could not be started, this routine returns 0 (and no normal hypersurface list is created).

## Enumerator()

regina::NormalHypersurfaces::Enumerator::Enumerator | ( | NormalHypersurfaces * | list,
|  | Triangulation< 4 > * | triang,
|  | ProgressTracker * | tracker
| ) |  |

inline

Creates a new functor with the given parameters.

Parameters

  list | the hypersurface list to be filled.
  triang | the triangulation in which these hypersurfaces lie.
  tracker | the progress tracker to use for progress reporting and cancellation polling, or 0 if these capabilities are not required.

## forCoords() [1/2]

template<typename FunctionObject , typename... Args>

ReturnsTraits<FunctionObject>::Void regina::forCoords | ( | HyperCoords | coords,
|  | FunctionObject && | func,
|  | Args &&... | args
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of HyperCoords, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible coordinate sytems.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new coordinate system is added then only a small amount of code needs to be extended to incorporate it.

This function can only work with coordinate systems in which you can create and store normal hypersurfaces. All other coordinate systems are considered invalid for our purposes here.

In detail: the function object func must define a templated bracket operator, so that `func.operator()<HyperInfo<c>>(...)` is defined for any valid HyperCoords enum value c. Then, when the user calls `forCoords(coords, func, ...)`, this routine will call `func.operator()<HyperInfo<coords>>(...)` in turn. If coords does not denote a valid coordinate system as described above, then forCoords() will do nothing.

There is also a variant of forCoords() that works with functions with return values, and which takes an extra defaultReturn argument.

Precondition
  There must not exist a type FunctionObject::ReturnType. (or, if FunctionObject is a reference to a class/struct F, there must likewise not exist a type F::ReturnType). The existence of a type FunctionObject::ReturnType will cause the non-void variant of forCoords() to be used instead.

Python:\n Not present.

Parameters

  coords | the given normal hypersurface coordinate system.
  func | the function object whose bracket operator we will call with a HyperInfo<coords> object.
  args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.

Returns
  nothing; the return type `ReturnsTraits<FunctionObject>::Void` simply evaluates to `void`.

## forCoords() [2/2]

template<typename FunctionObject , typename... Args>

ReturnsTraits<FunctionObject>::ReturnType regina::forCoords | ( | HyperCoords | coords,
|  | FunctionObject && | func,
|  | typename ReturnsTraits< FunctionObject >::ReturnType | defaultReturn,
|  | Args &&... | args
| ) |  |

Allows the user to call a template function whose template parameter matches a given value of HyperCoords, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible coordinate sytems.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new coordinate system is added then only a small amount of code needs to be extended to incorporate it.

This function can only work with coordinate systems in which you can create and store normal hypersurfaces. All other coordinate systems are considered invalid for our purposes here.

In detail: the function object func must define a templated bracket operator, so that `func.operator()<HyperInfo<c>>(...)` is defined for any valid HyperCoords enum value c. Then, when the user calls `forCoords(coords, func, defaultReturn, ...)`, this routine will call `func.operator()<HyperInfo<coords>>(...)` and pass back the corresponding return value. If coords does not denote a valid coordinate system as described above, then forCoords() will pass back defaultReturn instead.

There is also a variant of forCoords() that works with void functions, and so does not take the extra defaultReturn argument.

Precondition
  The function object must have a typedef ReturnType indicating the return type of the corresponding templated bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.

Python:\n Not present.

Parameters

  coords | the given normal hypersurface coordinate system.
  func | the function object whose bracket operator we will call with a HyperInfo<coords> object.
  defaultReturn | the value to return if the given coordinate system is invalid.
  args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.

Returns
  the return value from the corresponding bracket operator of func, or defaultReturn if the given coordinate system is invalid.

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

## HSVectorStandard() [1/2]

regina::HSVectorStandard::HSVectorStandard | ( | const Vector< LargeInteger > & | cloneMe | ) |

inline

Creates a new vector that is a clone of the given vector.

Parameters

  cloneMe | the vector to clone.

## HSVectorStandard() [2/2]

regina::HSVectorStandard::HSVectorStandard | ( | size_t | length | ) |

inline

Creates a new vector all of whose entries are initialised to zero.

Parameters

  length | the number of elements in the new vector.

## hypersurface() [1/2]

NormalHypersurface * regina::XMLNormalHypersurfaceReader::hypersurface | ( |  | ) |

inline

Returns the normal hypersurface that has been read.

Returns
  the newly allocated normal hypersurface, or 0 if an error occurred.

## hypersurface() [2/2]

const NormalHypersurface * regina::NormalHypersurfaces::hypersurface | ( | size_t | index | ) | const

inline

Returns the hypersurface at the requested index in this list.

Parameters

  index | the index of the requested hypersurface in this list; this must be between 0 and size()-1 inclusive.

Returns
  the normal hypersurface at the requested index in this list.

## HypersurfaceInserter() [1/2]

regina::NormalHypersurfaces::HypersurfaceInserter::HypersurfaceInserter | ( | const HypersurfaceInserter & | cloneMe | ) |

inline

Creates a new output iterator that is a clone of the given iterator.

Parameters

  cloneMe | the output iterator to clone.

## HypersurfaceInserter() [2/2]

regina::NormalHypersurfaces::HypersurfaceInserter::HypersurfaceInserter | ( | NormalHypersurfaces & | list,
|  | Triangulation< 4 > * | owner
| ) |  |

inline

Creates a new output iterator.

The member variables of this iterator will be initialised according to the parameters passed to this constructor.

Parameters

  list | the list into which hypersurfaces will be inserted.
  owner | the triangulation in which the hypersurfaces to be inserted are contained.

## initialChars()

virtual void regina::XMLNormalHypersurfaceReader::initialChars | ( | const std::string & | chars | ) |

virtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters

  chars | the initial text for this element.

Reimplemented from regina::XMLElementReader.

## internalClonePacket()

virtual Packet* regina::NormalHypersurfaces::internalClonePacket | ( | Packet * | parent | ) | const

protected virtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters

  parent | the parent beneath which the new packet will eventually be inserted.

Returns
  the newly allocated packet.

Implements regina::Packet.

## isCompact() [1/2]

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.

## isCompact() [2/2]

virtual bool regina::NormalHypersurfaceVector::isCompact | ( | const Triangulation< 4 > * | triang | ) | const

virtual

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

The default implementation for this routine simply runs through every piece type until a piece type with infinite piece count is found or all piece types have been examined. Subclasses of NormalHypersurfaceVector should override this if they can provide a faster implementation.

Parameters

  triang | the triangulation in which this normal hypersurface lives.

Returns
  `true` if and only if the normal hypersurface represented 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.

## isEmbeddedOnly()

bool regina::NormalHypersurfaces::isEmbeddedOnly | ( |  | ) | const

inline

Returns whether this set is known to contain only embedded normal hypersurfaces.

If this returns `false`, it does not guarantee that immersed and/or singular hypersurfaces are present; it merely indicates that they were not deliberately excluded (for instance, the prism constraints were not enforced).

Returns
  `true` if this list was constructed to contain only properly embedded hypersurfaces, or `false` otherwise.

## 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() [1/2]

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.

## isThinEdgeLink() [2/2]

virtual const Edge<4>* regina::NormalHypersurfaceVector::isThinEdgeLink | ( | const Triangulation< 4 > * | triang | ) | const

virtual

Determines if a rational multiple of the normal hypersurface represented is the thin link of a single edge.

The default implementation for this routine involves counting the number of pieces of every type. Subclasses of NormalHypersurfaceVector should override this if they can provide a faster implementation.

Parameters

  triang | the triangulation in which this normal hypersurface lives.

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() [1/2]

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.

## isVertexLink() [2/2]

virtual const Vertex<4>* regina::NormalHypersurfaceVector::isVertexLink | ( | const Triangulation< 4 > * | triang | ) | const

virtual

Determines if a rational multiple of the normal hypersurface represented is the link of a single vertex.

The default implementation for this routine involves counting the number of pieces of every type. Subclasses of NormalSurfaceVector should override this if they can provide a faster implementation.

Parameters

  triang | the triangulation in which this normal hypersurface lives.

Returns
  the vertex linked by this hypersurface, or 0 if this hypersurface is not the link of a single vertex.

## isVertexLinking() [1/2]

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.

## isVertexLinking() [2/2]

virtual bool regina::NormalHypersurfaceVector::isVertexLinking | ( | const Triangulation< 4 > * | triang | ) | const

virtual

Determines if the normal hypersurface represented is vertex linking.

A vertex linking hypersurface contains only tetrahedra.

The default implementation for this routine simply runs through every non-tetrahedron piece type ensuring that each has no corresponding pieces. Subclasses of NormalHypersurfaceVector should override this if they can provide a faster implementation.

Parameters

  triang | the triangulation in which this normal hypersurface lives.

Returns
  `true` if and only if the normal hypersurface represented 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.

## makeEmbeddedConstraints() [1/2]

static EnumConstraints* regina::NormalHypersurfaceVector::makeEmbeddedConstraints | ( | const Triangulation< 4 > * | triangulation | ) |

static

Creates a new set of validity constraints representing the condition that normal hypersurfaces be embedded.

The validity constraints will be expressed relative to the coordinate system corresponding to this particular subclass of NormalHypersurfaceVector.

Parameters

  triangulation | the triangulation upon which these validity constraints will be based.

Returns
  a newly allocated set of constraints.

## makeEmbeddedConstraints() [2/2]

EnumConstraints* regina::makeEmbeddedConstraints | ( | const Triangulation< 4 > * | triangulation,
|  | HyperCoords | coords
| ) |  |

Creates a new set of validity constraints representing the condition that normal hypersurfaces be embedded.

The validity constraints will be expressed relative to the given coordinate system.

Python:\n Not present.

Parameters

  triangulation | the triangulation upon which these validity constraints will be based.
  coords | the coordinate system to be used; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

Returns
  a newly allocated set of constraints.

## makeMatchingEquations() [1/2]

static MatrixInt* regina::NormalHypersurfaceVector::makeMatchingEquations | ( | const Triangulation< 4 > * | triangulation | ) |

static

Creates a new set of normal hypersurface matching equations for the given triangulation using the coordinate system corresponding to this particular subclass of NormalHypersurfaceVector.

See makeMatchingEquations() for further details.

Parameters

  triangulation | the triangulation upon which these matching equations will be based.

Returns
  a newly allocated set of matching equations.

## makeMatchingEquations() [2/2]

MatrixInt* regina::makeMatchingEquations | ( | const Triangulation< 4 > * | triangulation,
|  | HyperCoords | coords
| ) |  |

Creates a new set of normal hypersurface matching equations for the given triangulation using the given coordinate system.

The returned matrix will be newly allocated and its destruction will be the responsibility of the caller of this routine.

Each equation will be represented as a row of the matrix. Each column of the matrix represents a coordinate in the given coordinate system.

Parameters

  triangulation | the triangulation upon which these matching equations will be based.
  coords | the coordinate system to be used; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

Returns
  a newly allocated set of matching equations.

## makeZeroVector() [1/2]

static NormalHypersurfaceVector* regina::NormalHypersurfaceVector::makeZeroVector | ( | const Triangulation< 4 > * | triangulation | ) |

static

Returns a new normal hypersurface vector of the appropriate length for the given triangulation and for the coordinate system corresponding to this subclass of NormalHypersurfaceVector.

All elements of the new vector will be initialised to zero.

See makeZeroVector() for further details.

Parameters

  triangulation | the triangulation upon which the underlying coordinate system is based.

Returns
  a new zero vector of the correct class and length.

## makeZeroVector() [2/2]

NormalHypersurfaceVector* regina::makeZeroVector | ( | const Triangulation< 4 > * | triangulation,
|  | HyperCoords | coords
| ) |  |

Returns a new normal hypersurface vector of the appropriate length for the given triangulation and the given coordinate system.

All elements of this vector will be initialised to zero.

The new vector will be of the subclass of NormalHypersurfaceVector corresponding to the given coordinate system. The caller of this routine is responsible for destroying the new vector.

Python:\n Not present.

Parameters

  triangulation | the triangulation upon which the underlying coordinate system is based.
  coords | the coordinate system to be used; this must be one of the predefined coordinate system constants in NormalHypersurfaces.

Returns
  a new zero vector of the correct class and length.

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

## NormalHypersurface() [1/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++:\n Not available; this routine is for Python only.

Parameters

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

## NormalHypersurface() [2/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:\n Not present.

Parameters

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

## NormalHypersurfaces()

regina::NormalHypersurfaces::NormalHypersurfaces | ( | HyperCoords | coords,
|  | HyperList | which,
|  | HyperAlg | algorithm
| ) |  |

inline protected

Creates an empty list of normal hypersurfaces with the given parameters.

Parameters

  coords | the coordinate system to be used for filling this list.
  which | indicates which normal hypersurfaces these will represent within the underlying triangulation.
  algorithm | details of the enumeration algorithm that will be used to fill this list.

## NormalHypersurfaceVector() [1/2]

regina::NormalHypersurfaceVector::NormalHypersurfaceVector | ( | const Vector< LargeInteger > & | cloneMe | ) |

inline

Creates a new vector that is a clone of the given vector.

Parameters

  cloneMe | the vector to clone.

## NormalHypersurfaceVector() [2/2]

regina::NormalHypersurfaceVector::NormalHypersurfaceVector | ( | size_t | length | ) |

inline

Creates a new vector all of whose entries are initialised to zero.

Parameters

  length | the number of elements in the new vector.

## operator!=()

bool regina::NormalHypersurfaces::VectorIterator::operator!= | ( | const VectorIterator & | other | ) | const

inline

Compares this with the given operator for inequality.

Parameters

  other | the iterator to compare this with.

Returns
  `false` if the iterators point to the same element of the same normal surface list, or `true` if they do not.

## operator()()

template<typename Coords >

void regina::NormalHypersurfaces::Enumerator::operator() | ( |  | ) |

Performs the real enumeration work, in a setting where the underlying coordinate system is a compile-time constant.

We assume here that neither list_->which_ nor list_->algorithm_ have been sanity-checked.

This routine fills list_ with surfaces, and then once this is finished it inserts list_ into the packet tree as a child of triang_.

Template Parameters

  Coords | an instance of the HyperInfo<> template class.

## operator*() [1/2]

NormalHypersurfaces::HypersurfaceInserter & regina::NormalHypersurfaces::HypersurfaceInserter::operator* | ( |  | ) |

inline

Returns a reference to this output iterator.

Returns
  this output iterator.

## operator*() [2/2]

const Ray & regina::NormalHypersurfaces::VectorIterator::operator* | ( |  | ) | const

inline

Returns the raw vector for the normal hypersurface that this iterator is currently pointing to.

Precondition
  This iterator is dereferenceable (in particular, it is not past-the-end).

Returns
  the corresponding normal hypersurface vector.

## operator++() [1/4]

NormalHypersurfaces::VectorIterator & regina::NormalHypersurfaces::VectorIterator::operator++ | ( |  | ) |

inline

The preincrement operator.

Returns
  a reference to this iterator after the increment.

## operator++() [2/4]

NormalHypersurfaces::HypersurfaceInserter & regina::NormalHypersurfaces::HypersurfaceInserter::operator++ | ( |  | ) |

inline

Returns a reference to this output iterator.

Returns
  this output iterator.

## operator++() [3/4]

NormalHypersurfaces::VectorIterator regina::NormalHypersurfaces::VectorIterator::operator++ | ( | int |  | ) |

inline

The postincrement operator.

Returns
  a copy of this iterator before the increment took place.

## operator++() [4/4]

NormalHypersurfaces::HypersurfaceInserter & regina::NormalHypersurfaces::HypersurfaceInserter::operator++ | ( | int |  | ) |

inline

Returns a reference to this output iterator.

Returns
  this output iterator.

## operator+=()

void regina::NormalHypersurfaceVector::operator+= | ( | const NormalHypersurfaceVector & | other | ) |

inline virtual

Adds the given vector to this vector.

This behaves correctly in the case where other is `this`.

The default implementation simply adds the coordinates of the underlying vectors. Subclasses should reimplement this if they carry any additional information that also need adjusting.

Precondition
  This and the given vector represent normal hypersurfaces in the same triangulation, and use the same normal coordinate system.

Parameters

  other | the vector to add to this vector.

## operator--() [1/2]

NormalHypersurfaces::VectorIterator & regina::NormalHypersurfaces::VectorIterator::operator-- | ( |  | ) |

inline

The predecrement operator.

Returns
  a reference to this iterator after the decrement.

## operator--() [2/2]

NormalHypersurfaces::VectorIterator regina::NormalHypersurfaces::VectorIterator::operator-- | ( | int |  | ) |

inline

The postdecrement operator.

Returns
  a copy of this iterator before the decrement took place.

## operator=() [1/4]

NormalHypersurfaces::HypersurfaceInserter & regina::NormalHypersurfaces::HypersurfaceInserter::operator= | ( | const HypersurfaceInserter & | cloneMe | ) |

inline

Sets this iterator to be a clone of the given output iterator.

Parameters

  cloneMe | the output iterator to clone.

Returns
  this output iterator.

## operator=() [2/4]

NormalHypersurfaces::VectorIterator & regina::NormalHypersurfaces::VectorIterator::operator= | ( | const VectorIterator & | cloneMe | ) |

inline

Makes this a copy of the given iterator.

Parameters

  cloneMe | the iterator to clone.

Returns
  a reference to this iterator.

## operator=() [3/4]

NormalHypersurfaces::HypersurfaceInserter & regina::NormalHypersurfaces::HypersurfaceInserter::operator= | ( | NormalHypersurface * | hypersurface | ) |

inline

Appends a normal hypersurface to the end of the appropriate surface list.

The given hypersurface will be deallocated with the other hypersurfaces in this list when the list is eventually destroyed.

Parameters

  hypersurface | the normal hypersurface to insert.

Returns
  this output iterator.

## operator=() [4/4]

NormalHypersurfaces::HypersurfaceInserter & regina::NormalHypersurfaces::HypersurfaceInserter::operator= | ( | NormalHypersurfaceVector * | vector | ) |

inline

Appends the normal hypersurface corresponding to the given vector to the end of the appropriate hypersurface list.

The given vector will be owned by the newly created normal hypersurface and will be deallocated with the other hypersurfaces in this list when the list is eventually destroyed.

Parameters

  vector | the vector of the normal hypersurface to insert.

Returns
  this output iterator.

## operator==()

bool regina::NormalHypersurfaces::VectorIterator::operator== | ( | const VectorIterator & | other | ) | const

inline

Compares this with the given operator for equality.

Parameters

  other | the iterator to compare this with.

Returns
  `true` if the iterators point to the same element of the same normal surface list, or `false` if they do not.

## operator[]()

const NLargeInteger & regina::NormalHypersurfaceVector::operator[] | ( | size_t | index | ) | const

inline

Returns the given coordinate from the underlying vector.

Parameters

  index | the index of the coordinate to retrieve; this must be between 0 and size()-1 inclusive.

Returns
  the coordinate at the given index.

## operator|() [1/2]

HyperAlg regina::operator| | ( | HyperAlgFlags | lhs,
|  | HyperAlgFlags | rhs
| ) |  |

inline

Returns the bitwise OR of the two given flags.

Parameters

  lhs | the first flag to combine.
  rhs | the second flag to combine.

Returns
  the combination of both flags.

## operator|() [2/2]

HyperList regina::operator| | ( | HyperListFlags | lhs,
|  | HyperListFlags | rhs
| ) |  |

inline

Returns the bitwise OR of the two given flags.

Parameters

  lhs | the first flag to combine.
  rhs | the second flag to combine.

Returns
  the combination of both flags.

## packet()

Packet * regina::XMLNormalHypersurfacesReader::packet | ( |  | ) |

inline override virtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
  the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

## prisms() [1/3]

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

inline

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

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

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

Parameters

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

Returns
  the number of prism pieces of the given type.

## prisms() [2/3]

LargeInteger regina::HSVectorStandard::prisms | ( | size_t | pentIndex,
|  | int | prismType,
|  | const Triangulation< 4 > * | triang
| ) |  | const

inline virtual

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

See NormalHypersurface::prisms() for further details.

Parameters

  pentIndex | the index in the triangulation of the pentachoron in which the requested prism pieces 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.
  triang | the triangulation in which this normal hypersurface lives.

Returns
  the number of prism pieces of the given type.

Implements regina::NormalHypersurfaceVector.

## prisms() [3/3]

virtual LargeInteger regina::NormalHypersurfaceVector::prisms | ( | size_t | pentIndex,
|  | int | prismType,
|  | const Triangulation< 4 > * | triang
| ) |  | const

pure virtual

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

See NormalHypersurface::prisms() for further details.

Parameters

  pentIndex | the index in the triangulation of the pentachoron in which the requested prism pieces 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.
  triang | the triangulation in which this normal hypersurface lives.

Returns
  the number of prism pieces of the given type.

Implemented in regina::HSVectorStandard.

## 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:\n Not present.

Returns
  the underlying raw vector.

## recreateMatchingEquations()

MatrixInt * regina::NormalHypersurfaces::recreateMatchingEquations | ( |  | ) | const

inline

Returns a newly created matrix containing the matching equations that were used to create this normal hypersurface list.

The destruction of this matrix is the responsibility of the caller of this routine. Multiple calls to this routine will result in the construction of multiple matrices. This routine in fact merely calls makeMatchingEquations() with the appropriate parameters.

The format of the matrix is identical to that returned by makeMatchingEquations().

Returns
  the matching equations used to create this normal hypersurface list.

## sameSurface()

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

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

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

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

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

Parameters

  other | the hypersurface to be compared with this hypersurface.

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

## scaleDown()

void regina::NormalHypersurfaceVector::scaleDown | ( |  | ) |

inline virtual

Scales this vector down by the greatest common divisor of all its elements.

The resulting vector will be the smallest multiple of the original that maintains integral entries, and these entries will have the same signs as the originals.

This routine poses no problem for vectors containing infinite elements; such elements are simply ignored and left at infinity.

The default implementation simply scales down the underlying vector. Subclasses should reimplement this if they carry any additional information that also needs adjusting.

## setElement()

void regina::NormalHypersurfaceVector::setElement | ( | size_t | index,
|  | const LargeInteger & | value
| ) |  |

inline virtual

Sets the given normal coordinate to the given value.

The default implementation simply sets the coordinate in the underlying vector. Subclasses should reimplement this if they carry any additional information that also need adjusting.

Parameters

  index | the index of the coordinate to set; this must e between 0 and size()-1 inclusive.
  value | the new value to assign to the given coordinate.

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

## size() [1/2]

size_t regina::NormalHypersurfaceVector::size | ( |  | ) | const

inline

Returns the number of coordinates in the underlying vector.

Returns
  the number of coordinates.

## size() [2/2]

size_t regina::NormalHypersurfaces::size | ( |  | ) | const

inline

Returns the number of hypersurfaces stored in this list.

Returns
  the number of hypersurfaces.

## startContentSubElement()

virtual XMLElementReader* regina::XMLNormalHypersurfacesReader::startContentSubElement | ( | const std::string & | subTagName,
|  | const regina::xml::XMLPropertyDict & | subTagProps
| ) |  |

override virtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters

  subTagName | the name of the subelement opening tag.
  subTagProps | the properties associated with the subelement opening tag.

Returns
  a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLPacketReader.

## startElement()

virtual void regina::XMLNormalHypersurfaceReader::startElement | ( | const std::string & | tagName,
|  | const regina::xml::XMLPropertyDict & | tagProps,
|  | XMLElementReader * | parentReader
| ) |  |

virtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters

  tagName | the name of the opening tag for this element.
  tagProps | the properties associated with the opening tag.
  parentReader | the reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented from regina::XMLElementReader.

## startSubElement()

virtual XMLElementReader* regina::XMLNormalHypersurfaceReader::startSubElement | ( | const std::string & | subTagName,
|  | const regina::xml::XMLPropertyDict & | subTagProps
| ) |  |

virtual

Signifies that a subelement of this XML element is about to be parsed.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters

  subTagName | the name of the subelement opening tag.
  subTagProps | the properties associated with the subelement opening tag.

Returns
  a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLElementReader.

## tetrahedra() [1/3]

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

inline

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

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

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

Parameters

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

Returns
  the number of tetrahedron pieces of the given type.

## tetrahedra() [2/3]

LargeInteger regina::HSVectorStandard::tetrahedra | ( | size_t | pentIndex,
|  | int | vertex,
|  | const Triangulation< 4 > * | triang
| ) |  | const

inline virtual

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

See NormalHypersurface::tetrahedra() for further details.

Parameters

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

Returns
  the number of tetrahedron pieces of the given type.

Implements regina::NormalHypersurfaceVector.

## tetrahedra() [3/3]

virtual LargeInteger regina::NormalHypersurfaceVector::tetrahedra | ( | size_t | pentIndex,
|  | int | vertex,
|  | const Triangulation< 4 > * | triang
| ) |  | const

pure virtual

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

See NormalHypersurface::tetrahedra() for further details.

Parameters

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

Returns
  the number of tetrahedron pieces of the given type.

Implemented in regina::HSVectorStandard.

## 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() [1/2]

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

Returns the triangulation in which these normal hypersurfaces live.

Returns
  the triangulation in which these hypersurfaces live.

## triangulation() [2/2]

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

inline

Returns the triangulation in which this normal hypersurface resides.

Returns
  the underlying triangulation.

## VectorIterator() [1/2]

regina::NormalHypersurfaces::VectorIterator::VectorIterator | ( |  | ) |

inline

Creates a new uninitialised iterator.

## VectorIterator() [2/2]

regina::NormalHypersurfaces::VectorIterator::VectorIterator | ( | const VectorIterator & | cloneMe | ) |

inline

Creates a copy of the given iterator.

Parameters

  cloneMe | the iterator to clone.

## which()

HyperList regina::NormalHypersurfaces::which | ( |  | ) | const

inline

Returns details of which normal hypersurfaces this list represents within the underlying triangulation.

This may not be the same HyperList that was passed to enumerate(). In particular, default values will have been explicitly filled in (such as HS_VERTEX and/or HS_EMBEDDED_ONLY), and invalid and/or redundant values will have been removed.

Returns
  details of what this list represents.

## 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:\n The paramater out does not exist, and is
  taken to be standard output.

Parameters

  out | the output stream to which to write.

## writeTextLong()

virtual void regina::NormalHypersurfaces::writeTextLong | ( | std::ostream & | out | ) | const

virtual

Writes a detailed text representation of this object to the given output stream.

This may be reimplemented by subclasses, but the parent Packet class offers a reasonable default implementation.

Python:\n Not present.

Parameters

  out | the output stream to which to write.

Reimplemented from regina::Packet.

## writeTextShort() [1/2]

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

virtual

Writes a short text representation of this object to the given output stream.

This must be reimplemented by subclasses.

Python:\n Not present.

Parameters

  out | the output stream to which to write.

Implements regina::Packet.

## writeTextShort() [2/2]

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

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

Python:\n Not present.

Parameters

  out | the output stream to which to write.

## writeXMLData()

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

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

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

Python:\n Not present.

Parameters

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

## writeXMLPacketData()

virtual void regina::NormalHypersurfaces::writeXMLPacketData | ( | std::ostream & | out | ) | const

protected virtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters

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

Implements regina::Packet.

## XMLNormalHypersurfaceReader()

regina::XMLNormalHypersurfaceReader::XMLNormalHypersurfaceReader | ( | const Triangulation< 4 > * | tri,
|  | HyperCoords | coords
| ) |  |

inline

Creates a new normal hypersurface reader.

Parameters

  tri | the triangulation in which this normal hypersurface lives.
  coords | the coordinate system used by this normal hypersurface.

## XMLNormalHypersurfacesReader()

regina::XMLNormalHypersurfacesReader::XMLNormalHypersurfacesReader | ( | const Triangulation< 4 > * | tri,
|  | XMLTreeResolver & | resolver
| ) |  |

inline

Creates a new normal hypersurface list reader.

Parameters

  tri | the triangulation in which these normal hypersurfaces live.
  resolver | the master resolver that will be used to fix dangling packet references after the entire XML file has been read.

## ~NormalHypersurface()

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

inline

Destroys this normal hypersurface.

The underlying vector of coordinates will also be deallocated.

## ~NormalHypersurfaces()

regina::NormalHypersurfaces::~NormalHypersurfaces | ( |  | ) |

inline virtual

Destroys this list and all the hypersurfaces within.

## ~NormalHypersurfaceVector()

regina::NormalHypersurfaceVector::~NormalHypersurfaceVector | ( |  | ) |

inline virtual

A virtual destructor.

This is required because here we introduce virtual functions into the Ray hierarchy.

## Variable Documentation

## algorithm_

HyperAlg regina::NormalHypersurfaces::algorithm_

protected

Stores the details of the enumeration algorithm that was used to generate this list.

This might not be the same as the algorithmHints flag passed to the corresponding enumeration routine (e.g., if invalid or inappropriate flags were passed).

## compact_

Property<bool> regina::NormalHypersurface::compact_

mutable protected

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

## connected_

Property<bool> regina::NormalHypersurface::connected_

mutable protected

Is this hypersurface connected?

## coords_ [1/2]

HyperCoords regina::NormalHypersurfaces::coords_

protected

Stores which coordinate system is being used by the normal hypersurfaces in this packet.

## coords_ [2/2]

Ray regina::NormalHypersurfaceVector::coords_

protected

The raw vector of normal coordinates.

## H1_

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

mutable protected

First homology group of the hypersurface.

## list_

NormalHypersurfaces* regina::NormalHypersurfaces::HypersurfaceInserter::list_

The list into which hypersurfaces will be inserted.

## name_

std::string regina::NormalHypersurface::name_

protected

An optional name associated with this hypersurface.

## orientable_

Property<bool> regina::NormalHypersurface::orientable_

mutable protected

Is this hypersurface orientable?

## owner_

Triangulation<4>* regina::NormalHypersurfaces::HypersurfaceInserter::owner_

The triangulation in which the hypersurfaces to be inserted are contained.

## realBoundary_

Property<bool> regina::NormalHypersurface::realBoundary_

mutable protected

Does this hypersurface have real boundary (i.e.

does it meet any boundary facets)?

## surfaces_

std::vector<NormalHypersurface*> regina::NormalHypersurfaces::surfaces_

protected

Contains the normal hypersurfaces stored in this packet.

## triangulation_

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

protected

The triangulation in which this normal hypersurface resides.

## twoSided_

Property<bool> regina::NormalHypersurface::twoSided_

mutable protected

Is this hypersurface two-sided?

## vector_

NormalHypersurfaceVector* regina::NormalHypersurface::vector_

protected

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

## which_

HyperList regina::NormalHypersurfaces::which_

protected

Indicates which normal hypersurfaces these represent within the underlying triangulation.

regina::HyperCoords
HyperCoords
Represents different coordinate systems that can be used for enumerating and displaying normal hypers...
Definition: hypercoords.h:59

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