Regina Calculation Engine
Classes | Macros | Typedefs | Enumerations | Enumerator | Functions | Variables | Friends
Normal Hypersurfaces

Classes

class  regina::HSVectorStandard
 A normal hypersurface vector using standard tetrahedron-prism coordinates. More...
 
class  regina::Matrix< T, ring >
 Represents a matrix of elements of the given type 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 regina::Flags< HyperListFlagsregina::HyperList
 A combination of flags for types of normal hypersurface lists. More...
 
typedef regina::Flags< HyperAlgFlagsregina::HyperAlg
 A combination of flags for types of normal surface lists. More...
 
typedef Matrix< Integer, true > regina::MatrixInt
 A matrix of arbitrary-precision integers. 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 override
 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 override
 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 override
 Returns the number of times this normal hypersurface crosses the given edge. More...
 
static NormalHypersurfaceVectorregina::HSVectorStandard::makeZeroVector (const Triangulation< 4 > *triangulation)
 
static MatrixIntregina::HSVectorStandard::makeMatchingEquations (const Triangulation< 4 > *triangulation)
 
static EnumConstraintsregina::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 Rayregina::NormalHypersurfaceVector::coords () const
 Gives read-only access to the underlying vector of coordinates. More...
 
virtual NormalHypersurfaceVectorregina::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 LargeIntegerregina::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 NormalHypersurfaceVectorregina::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 MatrixIntregina::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 EnumConstraintsregina::NormalHypersurfaceVector::makeEmbeddedConstraints (const Triangulation< 4 > *triangulation)
 Creates a new set of validity constraints representing the condition that normal hypersurfaces be embedded. More...
 
NormalHypersurfaceVectorregina::NormalHypersurfaceVector::operator= (const NormalHypersurfaceVector &)=delete
 
 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...
 
NormalHypersurfaceregina::NormalHypersurface::clone () const
 Creates a newly allocated clone of this normal hypersurface. More...
 
NormalHypersurfaceregina::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 AbelianGroupregina::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 Rayregina::NormalHypersurface::rawVector () const
 Gives read-only access to the raw vector that sits beneath this normal hypersurface. More...
 
 regina::NormalHypersurface::NormalHypersurface (const NormalHypersurface &)=delete
 
NormalHypersurfaceregina::NormalHypersurface::operator= (const NormalHypersurface &)=delete
 
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 NormalHypersurfacesregina::NormalHypersurfaces::enumerate (Triangulation< 4 > *owner, HyperCoords coords, HyperList which=HS_LIST_DEFAULT, HyperAlg algHints=HS_ALG_DEFAULT, ProgressTracker *tracker=nullptr)
 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 NormalHypersurfaceregina::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 override
 Writes a short text representation of this object to the given output stream. More...
 
virtual void regina::NormalHypersurfaces::writeTextLong (std::ostream &out) const override
 Writes a detailed text representation of this object to the given output stream. More...
 
static XMLPacketReaderregina::NormalHypersurfaces::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
virtual bool regina::NormalHypersurfaces::dependsOnParent () const override
 Determines if this packet depends upon its parent. More...
 
template<typename Comparison >
void regina::NormalHypersurfaces::sort (Comparison &&comp)
 Sorts the hypersurfaces in this list according to the given criterion. More...
 
MatrixIntregina::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)=default
 Creates a copy of the given iterator. More...
 
VectorIteratorregina::NormalHypersurfaces::VectorIterator::operator= (const VectorIterator &cloneMe)=default
 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 Rayregina::NormalHypersurfaces::VectorIterator::operator* () const
 Returns the raw vector for the normal hypersurface that this iterator is currently pointing to. More...
 
VectorIteratorregina::NormalHypersurfaces::VectorIterator::operator++ ()
 The preincrement operator. More...
 
VectorIterator regina::NormalHypersurfaces::VectorIterator::operator++ (int)
 The postincrement operator. More...
 
VectorIteratorregina::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 Packetregina::NormalHypersurfaces::internalClonePacket (Packet *parent) const override
 Makes a newly allocated copy of this packet. More...
 
virtual void regina::NormalHypersurfaces::writeXMLPacketData (std::ostream &out) const override
 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)=default
 Creates a new output iterator that is a clone of the given iterator. More...
 
HypersurfaceInserterregina::NormalHypersurfaces::HypersurfaceInserter::operator= (const HypersurfaceInserter &cloneMe)=default
 Sets this iterator to be a clone of the given output iterator. More...
 
HypersurfaceInserterregina::NormalHypersurfaces::HypersurfaceInserter::operator= (NormalHypersurface *hypersurface)
 Appends a normal hypersurface to the end of the appropriate surface list. More...
 
HypersurfaceInserterregina::NormalHypersurfaces::HypersurfaceInserter::operator= (NormalHypersurfaceVector *vector)
 Appends the normal hypersurface corresponding to the given vector to the end of the appropriate hypersurface list. More...
 
HypersurfaceInserterregina::NormalHypersurfaces::HypersurfaceInserter::operator* ()
 Returns a reference to this output iterator. More...
 
HypersurfaceInserterregina::NormalHypersurfaces::HypersurfaceInserter::operator++ ()
 Returns a reference to this output iterator. More...
 
HypersurfaceInserterregina::NormalHypersurfaces::HypersurfaceInserter::operator++ (int)
 Returns a reference to this output iterator. More...
 
 regina::NormalHypersurfaces::Enumerator::Enumerator (NormalHypersurfaces *list, Triangulation< 4 > *triang, MatrixInt *eqns, ProgressTracker *tracker)
 Creates a new functor with the given parameters. More...
 
 regina::NormalHypersurfaces::Enumerator::Enumerator (Enumerator &&)=default
 Default move constructor. 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...
 
 regina::NormalHypersurfaces::Enumerator::Enumerator (const Enumerator &)=delete
 
Enumerator & regina::NormalHypersurfaces::Enumerator::operator= (const Enumerator &)=delete
 
NormalHypersurfaceVectorregina::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...
 
MatrixIntregina::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...
 
EnumConstraintsregina::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...
 
NormalHypersurfaceregina::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) override
 Signifies that parsing of this XML element is beginning. More...
 
virtual void regina::XMLNormalHypersurfaceReader::initialChars (const std::string &chars) override
 Signifies that the initial text belonging to this XML element has been read. More...
 
virtual XMLElementReaderregina::XMLNormalHypersurfaceReader::startSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
 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 Packetregina::XMLNormalHypersurfacesReader::packet () override
 Returns the newly allocated packet that has been read by this element reader. More...
 
virtual XMLElementReaderregina::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...
 
NormalHypersurfaceVectorregina::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, StoreManagedPtrregina::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...
 
NormalHypersurfacesregina::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 override { \
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.
idthe corresponding NNormalCoords constant.
superclassthe 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

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

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 Matrix< Integer, true > 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.

Enumeration Type Documentation

◆ 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

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

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
inlineoverridevirtual

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
edgeIndexthe index in the triangulation of the edge in which we are interested; this should be between 0 and Triangulation<4>::countEdges()-1 inclusive.
Returns
the number of times this normal hypersurface crosses the given edge.

◆ edgeWeight() [2/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
edgeIndexthe index in the triangulation of the edge in which we are interested; this should be between 0 and Triangulation<4>::countEdges()-1 inclusive.
triangthe triangulation in which this normal hypersurface lives.
Returns
the number of times this normal hypersurface crosses the given edge.

Implemented in regina::HSVectorStandard.

◆ edgeWeight() [3/3]

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

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

See NormalHypersurface::edgeWeight() for further details.

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

Implements regina::NormalHypersurfaceVector.

◆ 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 
)
overridevirtual

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

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe 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 = nullptr 
)
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.

If an error occurs, then this routine will return null, no normal hypersurface list will be created, and the progress tracker (if passed) will be marked as finished. Errors can occur in the following scenarios:

  • Regina could not create the matching equations for the given triangulation in the given coordinate system. This is only possible in certain coordinate systems, and all such coordinate systems are marked as such in the HyperCoords enum documentation.
  • A progress tracker is passed but a new thread could not be started.
Parameters
ownerthe triangulation upon which this list of normal hypersurfaces will be based.
coordsthe coordinate system to be used.
whichindicates which normal hypersurfaces should be enumerated.
algHintspasses requests to Regina for which specific enumeration algorithm should be used.
trackera progress tracker through which progress will be reported, or null 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 an error occurs (as described above) then this routine will return null instead.

◆ Enumerator() [1/2]

regina::NormalHypersurfaces::Enumerator::Enumerator ( Enumerator &&  )
default

Default move constructor.

◆ Enumerator() [2/2]

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

Creates a new functor with the given parameters.

Parameters
listthe hypersurface list to be filled.
triangthe triangulation in which these hypersurfaces lie.
eqnsthe matching equations for the given triangulation in the coordinate system corresponding to list. This object will take ownership of eqns, and the bracket operator will delete it once the enumeration has finished. This pointer must be non-null, i.e., Regina must have been able to construct the matching equations.
trackerthe progress tracker to use for progress reporting and cancellation polling, or null 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
coordsthe given normal hypersurface coordinate system.
functhe function object whose bracket operator we will call with a HyperInfo<coords> object.
argsany 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
coordsthe given normal hypersurface coordinate system.
functhe function object whose bracket operator we will call with a HyperInfo<coords> object.
defaultReturnthe value to return if the given coordinate system is invalid.
argsany 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
cloneMethe 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
lengththe 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
indexthe 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)
default

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

Parameters
cloneMethe 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
listthe list into which hypersurfaces will be inserted.
ownerthe triangulation in which the hypersurfaces to be inserted are contained.

◆ initialChars()

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

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
charsthe initial text for this element.

Reimplemented from regina::XMLElementReader.

◆ internalClonePacket()

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

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
parentthe 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
triangthe 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
triangthe 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
triangthe 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
triangthe 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
otherthe other hypersurface to test for local compatibility with this hypersurface.
Returns
true if the two hypersurfaces are locally compatible, or false if they are not.

◆ 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
triangulationthe 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
triangulationthe triangulation upon which these validity constraints will be based.
coordsthe 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
triangulationthe 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.

For some coordinate systems, Regina may not be able to create matching equations for all triangulations (any such coordinate systems will be explicitly mentioned as such in the HyperCoords enum documentation). If Regina cannot create the matching equations as requested, this routine will return null instead.

Parameters
triangulationthe triangulation upon which these matching equations will be based.
coordsthe 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, or null if Regina is not able to construct them for the given combination of triangulation and coordinate system.

◆ 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
triangulationthe 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
triangulationthe triangulation upon which the underlying coordinate system is based.
coordsthe 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
triangthe triangulation in which this normal hypersurface resides.
coordSystemthe coordinate system used by this normal hypersurface.
allCoordsthe corresponding vector of normal coordinates, expressed as a Python list. The list elements will be converted internally to LargeInteger objects.

◆ NormalHypersurface() [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
triangulationthe triangulation in which this normal hypersurface resides.
vectora vector containing the coordinates of the normal hypersurface in whichever space is appropriate.

◆ NormalHypersurfaces()

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

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

Parameters
coordsthe coordinate system to be used for filling this list.
whichindicates which normal hypersurfaces these will represent within the underlying triangulation.
algorithmdetails 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
cloneMethe 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
lengththe 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
otherthe 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_.

The matching equation matrix eqns_ will be deleted during this routine.

Template Parameters
Coordsan 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)
inlinevirtual

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
otherthe 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]

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

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

Parameters
cloneMethe output iterator to clone.
Returns
this output iterator.

◆ operator=() [2/4]

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

Makes this a copy of the given iterator.

Parameters
cloneMethe 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
hypersurfacethe 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
vectorthe 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
otherthe 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 LargeInteger & regina::NormalHypersurfaceVector::operator[] ( size_t  index) const
inline

Returns the given coordinate from the underlying vector.

Parameters
indexthe 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
lhsthe first flag to combine.
rhsthe 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
lhsthe first flag to combine.
rhsthe second flag to combine.
Returns
the combination of both flags.

◆ packet()

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

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
pentIndexthe index in the triangulation of the pentachoron in which the requested prisms reside; this should be between 0 and Triangulation<4>::size()-1 inclusive.
prismTypespecifies the edge of the given pentachoron that this prism separates from the opposite triangle; this should be between 0 and 9 inclusive.
Returns
the number of prism pieces of the given type.

◆ prisms() [2/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
pentIndexthe 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.
prismTypespecifies the edge of the given pentachoron that this prism separates from the opposite triangle; this should be between 0 and 9 inclusive.
triangthe triangulation in which this normal hypersurface lives.
Returns
the number of prism pieces of the given type.

Implemented in regina::HSVectorStandard.

◆ prisms() [3/3]

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

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

See NormalHypersurface::prisms() for further details.

Parameters
pentIndexthe 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.
prismTypespecifies the edge of the given pentachoron that this prism separates from the opposite triangle; this should be between 0 and 9 inclusive.
triangthe triangulation in which this normal hypersurface lives.
Returns
the number of prism pieces of the given type.

Implements regina::NormalHypersurfaceVector.

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

Note that there are situations in which makeMatchingEquations() returns null (because the triangulation is not supported by the chosen coordinate system). However, this routine should never return null, because if makeMatchingEquations() had returned null then this normal hypersurface list would not have been created in the first place.

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

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

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
indexthe index of the coordinate to set; this must e between 0 and size()-1 inclusive.
valuethe 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
namethe 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.

◆ sort()

template<typename Comparison >
void regina::NormalHypersurfaces::sort ( Comparison &&  comp)
inline

Sorts the hypersurfaces in this list according to the given criterion.

This sort is stable, i.e., hypersurfaces that are equivalent under the given criterion will remain in the same relative order.

The implementation of this routine uses std::stable_sort.

Python:\n Not present.
Parameters
compa binary function (or function object) that accepts two const HyperSurface pointers, and returns true if and only if the first hypersurface should appear before the second in the sorted list.

◆ startContentSubElement()

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

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
subTagNamethe name of the subelement opening tag.
subTagPropsthe 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 
)
overridevirtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters
tagNamethe name of the opening tag for this element.
tagPropsthe properties associated with the opening tag.
parentReaderthe 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 
)
overridevirtual

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
subTagNamethe name of the subelement opening tag.
subTagPropsthe 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
pentIndexthe index in the triangulation of the pentachoron in which the requested pieces reside; this should be between 0 and Triangulation<4>::size()-1 inclusive.
vertexthe vertex of the given pentachoron around which the requested pieces lie; this should be between 0 and 4 inclusive.
Returns
the number of tetrahedron pieces of the given type.

◆ tetrahedra() [2/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
pentIndexthe 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.
vertexthe vertex of the given pentachoron around which the requested tetrahedron pieces lie; this should be between 0 and 4 inclusive.
triangthe triangulation in which this normal hypersurface lives.
Returns
the number of tetrahedron pieces of the given type.

Implemented in regina::HSVectorStandard.

◆ tetrahedra() [3/3]

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

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

See NormalHypersurface::tetrahedra() for further details.

Parameters
pentIndexthe 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.
vertexthe vertex of the given pentachoron around which the requested tetrahedron pieces lie; this should be between 0 and 4 inclusive.
triangthe triangulation in which this normal hypersurface lives.
Returns
the number of tetrahedron pieces of the given type.

Implements regina::NormalHypersurfaceVector.

◆ 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)
default

Creates a copy of the given iterator.

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

◆ writeTextLong()

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

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

Reimplemented from regina::Packet.

◆ writeTextShort() [1/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
outthe output stream to which to write.

◆ writeTextShort() [2/2]

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

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

This must be reimplemented by subclasses.

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

Implements regina::Packet.

◆ 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
outthe output stream to which the XML should be written.

◆ writeXMLPacketData()

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

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
outthe 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
trithe triangulation in which this normal hypersurface lives.
coordsthe 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
trithe triangulation in which these normal hypersurfaces live.
resolverthe 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 ( )
inlinevirtual

Destroys this list and all the hypersurfaces within.

◆ ~NormalHypersurfaceVector()

regina::NormalHypersurfaceVector::~NormalHypersurfaceVector ( )
inlinevirtual

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

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

◆ connected_

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

Is this hypersurface connected?

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

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

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

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

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:60

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