Regina Calculation Engine
Classes | Macros | Typedefs | Enumerations | Functions | Variables
Normal Surfaces

Normal surfaces in 3-manifold triangulations. More...

Classes

struct  regina::NDiscSpec
 Specifies a single normal disc in a normal surface. More...
 
class  regina::NDiscSetTet
 Represents a set of normal discs inside a single tetrahedron. More...
 
class  regina::NDiscSetTetData< T >
 Stores data of type T for every normal disc inside a single tetrahedron. More...
 
class  regina::NDiscSetSurface
 Represents the set of all normal discs forming a normal surface. More...
 
class  regina::NDiscSetSurfaceData< T >
 Stores data of type T for every normal disc within a particular normal surface. More...
 
class  regina::NDiscSpecIterator
 An iterator used for running through all normal discs in a normal surface. More...
 
struct  regina::NDiscType
 Identifies a single normal or almost normal disc type within a triangulation. More...
 
struct  regina::NormalInfo< coordType >
 A template that stores information about a particular normal coordinate system. More...
 
class  regina::NNormalSurfaceVector
 Stores the vector of a single normal surface in a 3-manifold. More...
 
class  regina::NNormalSurface
 Represents a single normal surface in a 3-manifold. More...
 
struct  regina::PacketInfo< PACKET_NORMALSURFACELIST >
 Stores information about the normal surface list packet. More...
 
class  regina::NNormalSurfaceList
 A packet representing a collection of normal surfaces in a 3-manifold. More...
 
struct  regina::NPrismSpec
 Specifies a single triangular prism in a tetrahedron. More...
 
class  regina::NPrismSetSurface
 Represents the set of prisms defined by slicing along all the quads in a particular normal surface. More...
 
struct  regina::NormalInfo< NS_AN_STANDARD >
 Stores information about standard almost normal coordinates. More...
 
class  regina::NNormalSurfaceVectorANStandard
 An almost normal surface vector using standard triangle-quad-oct coordinates. More...
 
class  regina::NNormalSurfaceVectorMirrored
 A normal surface vector that is mirrored in another coordinate system to avoid frequent lengthy calculations. More...
 
struct  regina::NormalInfo< NS_ORIENTED >
 Stores information about transversely oriented standard normal coordinates. More...
 
class  regina::NNormalSurfaceVectorOriented
 A normal surface vector using transversely oriented standard (triangle-quad) coordinates. More...
 
struct  regina::NormalInfo< NS_ORIENTED_QUAD >
 Stores information about transversely oriented quad normal coordinates. More...
 
class  regina::NNormalSurfaceVectorOrientedQuad
 A normal surface vector using transversely oriented quadrilateral coordinates. More...
 
struct  regina::NormalInfo< NS_QUAD >
 Stores information about quad normal coordinates. More...
 
class  regina::NNormalSurfaceVectorQuad
 A normal surface vector using quad coordinates. More...
 
struct  regina::NormalInfo< NS_AN_QUAD_OCT >
 Stores information about quad-oct almost normal coordinates. More...
 
class  regina::NNormalSurfaceVectorQuadOct
 An almost normal surface vector using quad-oct coordinates. More...
 
struct  regina::NormalInfo< NS_STANDARD >
 Stores information about standard normal coordinates. More...
 
class  regina::NNormalSurfaceVectorStandard
 A normal surface vector using standard triangle-quad coordinates. More...
 
struct  regina::SurfaceFilterInfo< filterType >
 A template that stores information about a particular type of normal surface filter. More...
 
struct  regina::PacketInfo< PACKET_SURFACEFILTER >
 Stores information about the normal surface filter packet type. More...
 
struct  regina::SurfaceFilterInfo< NS_FILTER_DEFAULT >
 Stores information about the default accept-all surface filter. More...
 
class  regina::NSurfaceFilter
 A packet that accepts or rejects normal surfaces. More...
 
class  regina::NSurfaceSubset
 Represents a subset of a normal surface list. More...
 
class  regina::NXMLFilterReader
 An XML element reader that reads the specific details of a normal surface filter. More...
 
class  regina::NXMLFilterPacketReader
 An XML packet reader that reads a single surface filter. More...
 
class  regina::NXMLNormalSurfaceReader
 An XML element reader that reads a single normal surface. More...
 
class  regina::NXMLNormalSurfaceListReader
 An XML packet reader that reads a single normal surface list. More...
 
struct  regina::SurfaceFilterInfo< NS_FILTER_COMBINATION >
 Stores information about the combination surface filter. More...
 
class  regina::NSurfaceFilterCombination
 A normal surface filter that simply combines other filters. More...
 
struct  regina::SurfaceFilterInfo< NS_FILTER_PROPERTIES >
 Stores information about the property-based surface filter. More...
 
class  regina::NSurfaceFilterProperties
 A normal surface filter that filters by basic properties of the normal surface. More...
 

Macros

#define REGINA_NORMAL_SURFACE_FLAVOUR(class_, id)
 Defines various constants, types and virtual functions for a subclass of NNormalSurfaceVector. More...
 
#define REGINA_SURFACE_FILTER(class_, id)
 Defines various constants, types and virtual functions for a descendant class of NSurfaceFilter. More...
 

Typedefs

typedef NewFunction1
< NNormalSurfaceVector, size_t > 
regina::NewNormalSurfaceVector
 A legacy typedef provided for backward compatibility only. More...
 
typedef regina::Flags
< NormalListFlags > 
regina::NormalList
 A combination of flags for types of normal surface lists. More...
 
typedef regina::Flags
< NormalAlgFlags > 
regina::NormalAlg
 A combination of flags for types of normal surface lists. More...
 

Enumerations

enum  regina::NormalCoords {
  regina::NS_STANDARD = 0, regina::NS_QUAD = 1, regina::NS_AN_LEGACY = 100, regina::NS_AN_QUAD_OCT = 101,
  regina::NS_AN_STANDARD = 102, regina::NS_EDGE_WEIGHT = 200, regina::NS_TRIANGLE_ARCS = 201, regina::NS_FACE_ARCS = 201,
  regina::NS_ORIENTED = 300, regina::NS_ORIENTED_QUAD = 301
}
 Represents different coordinate systems that can be used for enumerating and displaying normal surfaces. More...
 
enum  regina::NormalListFlags {
  regina::NS_LIST_DEFAULT = 0x0000, regina::NS_EMBEDDED_ONLY = 0x0001, regina::NS_IMMERSED_SINGULAR = 0x0002, regina::NS_VERTEX = 0x0004,
  regina::NS_FUNDAMENTAL = 0x0008, regina::NS_LEGACY = 0x4000, regina::NS_CUSTOM = 0x8000
}
 Represents different lists of normal surfaces that might be constructed for a given triangulation. More...
 
enum  regina::NormalAlgFlags {
  regina::NS_ALG_DEFAULT = 0x0000, regina::NS_VERTEX_VIA_REDUCED = 0x0001, regina::NS_VERTEX_STD_DIRECT = 0x0002, regina::NS_VERTEX_TREE = 0x0010,
  regina::NS_VERTEX_DD = 0x0020, regina::NS_HILBERT_PRIMAL = 0x0100, regina::NS_HILBERT_DUAL = 0x0200, regina::NS_HILBERT_CD = 0x0400,
  regina::NS_HILBERT_FULLCONE = 0x0800, regina::NS_ALG_LEGACY = 0x4000, regina::NS_ALG_CUSTOM = 0x8000
}
 Represents options and variants of algorithms for enumerating various types of normal surfaces. More...
 
enum  regina::SurfaceFilterType { regina::NS_FILTER_DEFAULT = 0, regina::NS_FILTER_PROPERTIES = 1, regina::NS_FILTER_COMBINATION = 2 }
 Represents different types of filter classes that can be used to filter lists of normal surfaces in 3-manifold triangulations. More...
 

Functions

template<typename FunctionObject >
FunctionObject::ReturnType regina::forCoords (NormalCoords coords, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
 Allows the user to call a template function whose template parameter matches a given value of NormalCoords, which is not known until runtime. More...
 
template<typename VoidFunctionObject >
void regina::forCoords (NormalCoords coords, VoidFunctionObject func)
 Allows the user to call a template function whose template parameter matches a given value of NormalCoords, which is not known until runtime. More...
 
template<typename FunctionObject >
FunctionObject::ReturnType regina::forFlavour (NormalCoords coords, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
 A deprecated alias for the registry-based template function forCoords(). More...
 
template<typename VoidFunctionObject >
void regina::forFlavour (NormalCoords coords, VoidFunctionObject func)
 A deprecated alias for the registry-based template function forCoords(). More...
 
template<typename FunctionObject >
FunctionObject::ReturnType regina::forFilter (SurfaceFilterType filter, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
 Allows the user to call a template function whose template parameter matches a given value of SurfaceFilterType, which is not known until runtime. More...
 
template<typename VoidFunctionObject >
void regina::forFilter (SurfaceFilterType filter, VoidFunctionObject func)
 Allows the user to call a template function whose template parameter matches a given value of SurfaceFilterType, which is not known until runtime. More...
 
REGINA_API std::ostream & regina::operator<< (std::ostream &out, const NDiscSpec &spec)
 Writes the given disc specifier to the given output stream. More...
 
REGINA_API bool regina::numberDiscsAwayFromVertex (int discType, int vertex)
 Determines whether or not normal discs of the given type are numbered away from the given vertex. More...
 
REGINA_API bool regina::discOrientationFollowsEdge (int discType, int vertex, int edgeStart, int edgeEnd)
 Determines whether or not the natural boundary orientation of a normal disc of the given type follows the given directed normal arc. More...
 
REGINA_API std::ostream & regina::operator<< (std::ostream &out, const NDiscType &type)
 Writes the given disc type to the given output stream. More...
 
REGINA_API NNormalSurfaceVector * regina::makeZeroVector (const NTriangulation *triangulation, NormalCoords coords)
 Returns a new normal surface vector of the appropriate length for the given triangulation and the given coordinate system. More...
 
REGINA_API NMatrixInt * regina::makeMatchingEquations (NTriangulation *triangulation, NormalCoords coords)
 Creates a new set of normal surface matching equations for the given triangulation using the given coordinate system. More...
 
REGINA_API NEnumConstraintList * regina::makeEmbeddedConstraints (NTriangulation *triangulation, NormalCoords coords)
 Creates a new set of validity constraints representing the condition that normal surfaces be embedded. More...
 
NormalList regina::operator| (NormalListFlags lhs, NormalListFlags rhs)
 Returns the bitwise OR of the two given flags. More...
 
NormalAlg regina::operator| (NormalAlgFlags lhs, NormalAlgFlags rhs)
 Returns the bitwise OR of the two given flags. More...
 
REGINA_API std::ostream & regina::operator<< (std::ostream &out, const NPrismSpec &spec)
 Writes the given prism specifier to the given output stream. More...
 

Variables

REGINA_API const int regina::vertexSplit [4][4]
 Lists which vertex splits separate which pairs of vertices. More...
 
REGINA_API const int regina::vertexSplitMeeting [4][4][2]
 Lists which vertex splits meet which edges. More...
 
REGINA_API const int regina::vertexSplitDefn [3][4]
 Lists the vertices which each vertex split splits. More...
 
REGINA_API const int regina::vertexSplitPartner [3][4]
 Lists the second vertex with which each vertex is paired under each vertex split. More...
 
REGINA_API const char regina::vertexSplitString [3][6]
 Contains strings describing which vertices each vertex split splits. More...
 
REGINA_API const NPerm4 regina::triDiscArcs [4][3]
 Lists in consecutive order the directed normal arcs that form the boundary of each type of triangular normal disc. More...
 
REGINA_API const NPerm4 regina::quadDiscArcs [3][4]
 Lists in consecutive order the directed normal arcs that form the boundary of each type of quadrilateral normal disc. More...
 
REGINA_API const NPerm4 regina::octDiscArcs [3][8]
 Lists in consecutive order the directed normal arcs that form the boundary of each type of octagonal normal disc. More...
 

Detailed Description

Normal surfaces in 3-manifold triangulations.

Macro Definition Documentation

#define REGINA_NORMAL_SURFACE_FLAVOUR (   class_,
  id 
)
Value:
public: \
typedef NormalInfo<id> Info; \
enum { coordType = id }; \
inline virtual NNormalSurfaceVector* clone() const { \
return new class_(*this); \
} \
inline virtual bool allowsAlmostNormal() const { \
return Info::almostNormal; \
} \
inline virtual bool allowsSpun() const { \
return Info::spun; \
} \
inline virtual bool allowsOriented() const { \
return Info::oriented; \
}

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

Every subclass of NNormalSurfaceVector must include REGINA_NORMAL_SURFACE_FLAVOUR at the beginning of the class definition.

This macro provides the class with:

  • a compile-time enum constant coordType, which is equal to the corresponding NormalCoords constant;
  • a typedef Info, which refers to the corresponding specialisation of the NormalInfo<> template;
  • declarations and implementations of the virtual functions NNormalSurfaceVector::clone(), NNormalSurfaceVector::allowsAlmostNormal(), NNormalSurfaceVector::allowsSpun(), and NNormalSurfaceVector::allowsOriented().
Parameters
class_the name of this subclass of NNormalSurfaceVector.
idthe corresponding NNormalCoords constant.
#define REGINA_SURFACE_FILTER (   class_,
  id 
)
Value:
public: \
enum { filterType = id, filterID = id }; \
inline virtual SurfaceFilterType getFilterType() const { \
return id; \
} \
inline virtual SurfaceFilterType getFilterID() const { \
return id; \
} \
inline virtual std::string getFilterTypeName() const { \
return SurfaceFilterInfo<id>::name(); \
} \
inline virtual std::string getFilterName() const { \
return SurfaceFilterInfo<id>::name(); \
}

Defines various constants, types and virtual functions for a descendant class of NSurfaceFilter.

Every descendant class of NSurfaceFilter must include REGINA_SURFACE_FILTER at the beginning of the class definition.

This macro provides the class with:

  • a compile-time enum constant filterType, which is equal to the corresponding SurfaceFilterType constant;
  • a deprecated compile-time enum constant filterID, which is identical to filterType;
  • declarations and implementations of the virtual functions NSurfaceFilter::getFilterType() and NSurfaceFilter::getFilterTypeName();
  • declarations and implementations of the deprecated virtual functions NSurfaceFilter::getFilterID() and NSurfaceFilter::getFilterName().
Parameters
class_the name of this descendant class of NSurfaceFilter.
idthe corresponding SurfaceFilterType constant.

Typedef Documentation

typedef NewFunction1<NNormalSurfaceVector, size_t> regina::NewNormalSurfaceVector

A legacy typedef provided for backward compatibility only.

Deprecated:
The old NewNormalSurfaceVector class has been redesigned as the more general template class NewFunction1, and moved into the header registryutils.h. This typedef is provided for backward compatibility, and will be removed in some future version of Regina.
typedef regina::Flags<NormalAlgFlags> regina::NormalAlg

A combination of flags for types of normal surface lists.

Python:
This is present, and all values in the NormalAlgFlags enumeration type are treated as members of this NormalAlg class.
typedef regina::Flags<NormalListFlags> regina::NormalList

A combination of flags for types of normal surface lists.

Python:
This is present, and all values in the NormalListFlags enumeration type are treated as members of this NormalList class.

Enumeration Type Documentation

Represents options and variants of algorithms for enumerating various types of normal surfaces.

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

Python:
The values in this enumeration type are present, but they are treated by Python as NormalList objects (and they can be combined and/or queried as such). The underlying enumeration type is not exposed to Python.
Enumerator
NS_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).

NS_VERTEX_VIA_REDUCED 

When enumerating in standard normal or almost normal coordinates, this flag indicates that the algorithm should first enumerate in quadrilateral or quadrilateral-octagon coordinates, and then expand this "reduced" solution set to the (typically larger) "standard" solution set.

This is typically much faster than a direct enumeration in standard normal or almost normal coordinates, and enumeration routines will use this option where possible unless explicitly requested not to (via the flag NS_VERTEX_STD_DIRECT).

For an explanation of this procedure, see B. A. Burton, "Converting between quadrilateral and standard solution sets in normal surface theory", Algebr. Geom. Topol. 9 (2009), 2121-2174.

This flag is incompatible with NS_VERTEX_STD_DIRECT.

NS_VERTEX_STD_DIRECT 

When enumerating in standard normal or almost normal coordinates, this flag indicates that the algorithm should work directly in that coordinate system, and should not go via the "reduced" (quadrilateral or quadrilateral-octagon) coordinate system.

This is typically much slower than going via the reduced system, and users should only request this if they have a specialised need. See NS_VERTEX_VIA_REDUCED for further information.

This flag is incompatible with NS_VERTEX_VIA_REDUCED.

NS_VERTEX_TREE 

When enumerating vertex normal surfaces, this flag indicates that the tree traversal algorithm should be used.

This algorithm is based on linear and integer programming techniques, and has many desirable properties including a relatively low overhead. Enumeration algorithms will use it if possible unless a different method is explicitly requested.

For details on the tree traversal algorithm, see B. A. Burton and M. Ozlen, "A tree traversal algorithm for decision problems in knot theory and 3-manifold topology", Algorithmica 65 (2013), pp. 772-801.

This flag is incompatible with NS_VERTEX_DD.

NS_VERTEX_DD 

When enumerating vertex normal surfaces, 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.

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.

This flag is incompatible with NS_VERTEX_TREE.

NS_HILBERT_PRIMAL 

When enumerating fundamental normal surfaces, 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", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_DUAL, NS_HILBERT_CD and NS_HILBERT_FULLCONE.

NS_HILBERT_DUAL 

When enumerating fundamental normal surfaces, 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", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_PRIMAL, NS_HILBERT_CD and NS_HILBERT_FULLCONE.

NS_HILBERT_CD 

When enumerating fundamental normal surfaces, this flag indicates that a modified Contejean-Devie procedure should be used for enumerating a Hilbert basis.

The Contejean-Devie procedure is typically much slower than either the primal or dual method, and users should only request it if they have some specialised need.

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", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_PRIMAL, NS_HILBERT_DUAL and NS_HILBERT_FULLCONE.

NS_HILBERT_FULLCONE 

When enumerating fundamental normal surfaces, this flag indicates that a Hilbert basis for the full solution cone should be constructed, and additional combinatorial constraints (such as the quadrilateral constraints) should only be enforced as the final step.

If you are only enumerating properly embedded surfaces then this procedure extremely slow, and users should only request it if they have some specialised need.

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", to appear in ALENEX 2014: Proceedings of the Meeting on Algorithm Engineering & Experiments, arXiv:1111.7055.

This flag is incompatible with NS_HILBERT_PRIMAL, NS_HILBERT_DUAL and NS_HILBERT_CD.

NS_ALG_LEGACY 

Indicates that a normal surface list was enumerated using an older version of Regina (4.93 or earlier).

These older 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.

NS_ALG_CUSTOM 

Indicates that a normal surface 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.

Represents different coordinate systems that can be used for enumerating and displaying normal surfaces.

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
NS_STANDARD 

Represents standard triangle-quadrilateral coordinates for normal surfaces.

NS_QUAD 

Represents quadrilateral coordinates for normal surfaces.

For details, see "Normal surface Q-theory", Jeffrey L. Tollefson, Pacific J. Math. 183 (1998), no. 2, 359–374.

NS_AN_LEGACY 

Indicates that a list of almost normal surfaces was created using Regina 4.5.1 or earlier, where surfaces with more than one octagon of the same type were stripped out of the final solution set.

As of Regina 4.6 such surfaces are now included in the solution set, since we need them if we wish to enumerate all almost normal surfaces (not just the vertex almost normal surfaces).

This coordinate system is only used with legacy data files; new vectors and lists cannot be created in this coordinate system. The underlying coordinates are identical to those of NS_AN_STANDARD.

NS_AN_QUAD_OCT 

Represents quadrilateral-octagon coordinates for octagonal almost normal surfaces.

For details, see "Quadrilateral-octagon coordinates for almost normal surfaces", Benjamin A. Burton, Experiment. Math. 19 (2010), 285-315.

NS_AN_STANDARD 

Represents standard triangle-quadrilateral-octagon coordinates for octagonal almost normal surfaces.

NS_EDGE_WEIGHT 

Represents edge weight coordinates for normal surfaces.

This coordinate system is for display only; surface vectors and lists cannot be created in this coordinate system.

NS_TRIANGLE_ARCS 

Represents triangle arc coordinates for normal surfaces.

This coordinate system is for display only; surface vectors and lists cannot be created in this coordinate system.

NS_FACE_ARCS 

A deprecated alias for NS_TRIANGLE_ARCS.

This represents triangle arc coordinates for normal surfaces. See NS_TRIANGLE_ARCS for further details.

Deprecated:
This constant will be removed in a future version of Regina. Please use NS_TRIANGLE_ARCS instead.
NS_ORIENTED 

Represents standard triangle-quadrilateral coordinates for transversely oriented normal surfaces.

NS_ORIENTED_QUAD 

Represents quadrilateral coordinates for transversely oriented normal surfaces.

Represents different lists of normal surfaces that might be constructed for a given triangulation.

The NormalList enumeration refers to the contents of the list, whereas the NormalAlgFlags enumeration refers to the algorithm used to build it.

Python:
The values in this enumeration type are present, but they are treated by Python as NormalList objects (and they can be combined and/or queried as such). The underlying enumeration type is not exposed to Python.
Enumerator
NS_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).

NS_EMBEDDED_ONLY 

Indicates that this list is restricted to properly embedded surfaces only.

This flag is incompatible with NS_IMMERSED_SINGULAR.

NS_IMMERSED_SINGULAR 

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

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

This flag is incompatible with NS_EMBEDDED_ONLY.

NS_VERTEX 

Indicates a list of all vertex normal surfaces, with respect to the particular normal coordinate system used by the list.

This flag is incompatible with NS_FUNDAMENTAL.

NS_FUNDAMENTAL 

Indicates a list of all fundamental normal surfaces, with respect to the particular normal coordinate system used by the list.

This flag is incompatible with NS_VERTEX.

NS_LEGACY 

Indicates a list that was constructed using an old version of Regina (4.93 or earlier).

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

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

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

Represents different types of filter classes that can be used to filter lists of normal surfaces in 3-manifold triangulations.

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

Enumerator
NS_FILTER_DEFAULT 

Represents the NSurfaceFilter class: a do-nothing filter that accepts any normal surface.

NS_FILTER_PROPERTIES 

Represents the NSurfaceFilterProperties subclass: a filter that examines simple properties of a normal surface.

NS_FILTER_COMBINATION 

Represents the NSurfaceFilterCombination subclass: a filter that combines other filters using boolean AND or OR.

Function Documentation

REGINA_API bool regina::discOrientationFollowsEdge ( int  discType,
int  vertex,
int  edgeStart,
int  edgeEnd 
)

Determines whether or not the natural boundary orientation of a normal disc of the given type follows the given directed normal arc.

Natural boundary orientation is defined by arrays triDiscArcs, quadDiscArcs and octDiscArcs.

Precondition
The given normal arc lies on a normal disc of the given type.
Parameters
discTypethe normal disc type under consideration; this should be between 0 and 9 inclusive, as described by the NDiscSpec class notes.
vertexthe vertex about which the normal arc runs.
edgeStartthe start vertex of the edge to which the normal arc is parallel.
edgeEndthe end vertex of the edge to which the normal arc is parallel.
template<typename FunctionObject >
FunctionObject::ReturnType regina::forCoords ( NormalCoords  coords,
FunctionObject  func,
typename FunctionObject::ReturnType  defaultReturn 
)

Allows the user to call a template function whose template parameter matches a given value of NormalCoords, 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 surfaces. All other coordinate systems are considered invalid for our purposes here.

In detail: the function object func must define a templated unary bracket operator, so that func(NormalInfo<c>) is defined for any valid NormalCoords enum value c. Then, when the user calls forCoords(coords, func, defaultReturn), this routine will call func(NormalInfo<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 two-argument variant of forCoords() that works with void functions.

Precondition
The function object must have a typedef ReturnType indicating the return type of the corresponding templated unary bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.
Python:
Not present.
Parameters
coordsthe given normal coordinate system.
functhe function object whose unary bracket operator we will call with a NormalInfo<coords> object.
defaultReturnthe value to return if the given coordinate system is invalid.
Returns
the return value from the corresponding unary bracket operator of func, or defaultReturn if the given coordinate system is invalid.
template<typename VoidFunctionObject >
void regina::forCoords ( NormalCoords  coords,
VoidFunctionObject  func 
)

Allows the user to call a template function whose template parameter matches a given value of NormalCoords, 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 surfaces. All other coordinate systems are considered invalid for our purposes here.

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

There is also a three-argument variant of forCoords() that works with functions with return values.

Python:
Not present.
Parameters
coordsthe given normal coordinate system.
functhe function object whose unary bracket operator we will call with a NormalInfo<coords> object.
template<typename FunctionObject >
FunctionObject::ReturnType regina::forFilter ( SurfaceFilterType  filter,
FunctionObject  func,
typename FunctionObject::ReturnType  defaultReturn 
)

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

In essence, this routine contains a switch/case statement that runs through all possible normal surface filter types.

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 filter type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated unary bracket operator, so that func(SurfaceFilterInfo<t>) is defined for any valid SurfaceFilterType enum value t. Then, when the user calls forFilter(filter, func, defaultReturn), this routine will call func(SurfaceFilterInfo<filter>) and pass back the corresponding return value. If filter does not denote a valid filter type, then forFilter() will pass back defaultReturn instead.

There is also a two-argument variant of forFilter() that works with void functions.

Precondition
The function object must have a typedef ReturnType indicating the return type of the corresponding templated unary bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.
Python:
Not present.
Parameters
filterthe given type of normal surface filter.
functhe function object whose unary bracket operator we will call with a SurfaceFilterInfo<filter> object.
defaultReturnthe value to return if the given filter type is not valid.
Returns
the return value from the corresponding unary bracket operator of func, or defaultReturn if the given filter type is not valid.
template<typename VoidFunctionObject >
void regina::forFilter ( SurfaceFilterType  filter,
VoidFunctionObject  func 
)

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

In essence, this routine contains a switch/case statement that runs through all possible normal surface filter types.

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 filter type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated unary bracket operator, so that func(SurfaceFilterInfo<t>) is defined for any valid SurfaceFilterType enum value t. Then, when the user calls forFilter(filter, func), this routine will call func(SurfaceFilterInfo<filter>) in turn. If filter does not denote a valid filter type, then forFilter() will do nothing.

There is also a three-argument variant of forFilter() that works with functions with return values.

Python:
Not present.
Parameters
filterthe given type of normal surface filter.
functhe function object whose unary bracket operator we will call with a SurfaceFilterInfo<filter> object.
template<typename FunctionObject >
FunctionObject::ReturnType regina::forFlavour ( NormalCoords  coords,
FunctionObject  func,
typename FunctionObject::ReturnType  defaultReturn 
)
inline

A deprecated alias for the registry-based template function forCoords().

See forCoords() for further details.

template<typename VoidFunctionObject >
void regina::forFlavour ( NormalCoords  coords,
VoidFunctionObject  func 
)
inline

A deprecated alias for the registry-based template function forCoords().

See forCoords() for further details.

REGINA_API NEnumConstraintList* regina::makeEmbeddedConstraints ( NTriangulation *  triangulation,
NormalCoords  coords 
)

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

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

Python:
Not present.
Parameters
triangulationthe triangulation upon which these validity constraints will be based.
coordsthe coordinate system to be used.
Returns
a newly allocated set of constraints.
REGINA_API NMatrixInt* regina::makeMatchingEquations ( NTriangulation *  triangulation,
NormalCoords  coords 
)

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

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

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

Parameters
triangulationthe triangulation upon which these matching equations will be based.
coordsthe coordinate system to be used.
Returns
a newly allocated set of matching equations.
REGINA_API NNormalSurfaceVector* regina::makeZeroVector ( const NTriangulation *  triangulation,
NormalCoords  coords 
)

Returns a new normal surface 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 NNormalSurfaceVector corresponding to the given coordinate system. The caller of this routine is responsible for destroying the new vector.

Python:
Not present.
Parameters
triangulationthe triangulation upon which the underlying coordinate system is based.
coordsthe coordinate system to be used.
Returns
a new zero vector of the correct class and length.
REGINA_API bool regina::numberDiscsAwayFromVertex ( int  discType,
int  vertex 
)

Determines whether or not normal discs of the given type are numbered away from the given vertex.

Parameters
discTypethe normal disc type under consideration; this should be between 0 and 9 inclusive, as described by the NDiscSpec class notes.
vertexthe vertex under consideration; this should be between 0 and 3 inclusive.
Returns
true if normal discs of the given type are numbered away from the given vertex, or false if they are numbered towards the given vertex.
REGINA_API std::ostream& regina::operator<< ( std::ostream &  out,
const NPrismSpec &  spec 
)

Writes the given prism specifier to the given output stream.

The prism specifier will be written as a pair (tetIndex, edge).

Parameters
outthe output stream to which to write.
specthe prism specifier to write.
Returns
a reference to out.
REGINA_API std::ostream& regina::operator<< ( std::ostream &  out,
const NDiscSpec &  spec 
)

Writes the given disc specifier to the given output stream.

The disc specifier will be written as a triple (tetIndex, type, number).

Parameters
outthe output stream to which to write.
specthe disc specifier to write.
Returns
a reference to out.
std::ostream & regina::operator<< ( std::ostream &  out,
const NDiscType &  type 
)
inline

Writes the given disc type to the given output stream.

The disc type will be written as a pair (tetIndex, type).

Parameters
outthe output stream to which to write.
typethe disc type to write.
Returns
a reference to the given output stream.
NormalList regina::operator| ( NormalListFlags  lhs,
NormalListFlags  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.
NormalAlg regina::operator| ( NormalAlgFlags  lhs,
NormalAlgFlags  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.

Variable Documentation

REGINA_API const NPerm4 regina::octDiscArcs[3][8]

Lists in consecutive order the directed normal arcs that form the boundary of each type of octagonal normal disc.

Each permutation p represents an arc about vertex p[0] parallel to the directed edge from p[1] to p[2].

Array octDiscArcs[i] lists the boundary arcs of the octagonal disc of type i. See NNormalSurface::getOctCoord() for further details.

Note that permutation octDiscArcs[i][j] will be even precisely when j is 0, 1, 4 or 5.

C++:
This array is replaced by a macro octDiscArcs(discType, arcIndex) that essentially looks up the corresponding array. This is necessary because of a bug in gcc 2.95.
REGINA_API const NPerm4 regina::quadDiscArcs[3][4]

Lists in consecutive order the directed normal arcs that form the boundary of each type of quadrilateral normal disc.

Each permutation p represents an arc about vertex p[0] parallel to the directed edge from p[1] to p[2].

Array quadDiscArcs[i] lists the boundary arcs of the quadrilateral disc of type i. See NNormalSurface::getQuadCoord() for further details.

Note that permutation quadDiscArcs[i][j] will be even precisely when j is even.

C++:
This array is replaced by a macro quadDiscArcs(discType, arcIndex) that essentially looks up the corresponding array. This is necessary because of a bug in gcc 2.95.
REGINA_API const NPerm4 regina::triDiscArcs[4][3]

Lists in consecutive order the directed normal arcs that form the boundary of each type of triangular normal disc.

Each permutation p represents an arc about vertex p[0] parallel to the directed edge from p[1] to p[2].

Array triDiscArcs[i] lists the boundary arcs of the triangular disc of type i. See NNormalSurface::getTriangleCoord() for further details.

Note that every permutation in this array is even.

C++:
This array is replaced by a macro triDiscArcs(discType, arcIndex) that essentially looks up the corresponding array. This is necessary because of a bug in gcc 2.95.
REGINA_API const int regina::vertexSplit[4][4]

Lists which vertex splits separate which pairs of vertices.

There are three vertex splits, numbered 0,1,2. Each vertex split separates the four tetrahedron vertices 0,1,2,3 into two pairs. vertexSplit[i][j] is the number of the vertex split that keeps vertices i and j together.

It is guaranteed that vertex split i will keep the vertices of edge i together (and will therefore also keep the vertices of edge 5-i together).

REGINA_API const int regina::vertexSplitDefn[3][4]

Lists the vertices which each vertex split splits.

See vertexSplit for details on what a vertex split is. Vertex split number i splits the vertex pairs vertexSplitDefn[i][0,1] and vertexSplitDefn[i][2,3].

It is guaranteed that:

  • vertexSplitDefn[i][0] < vertexSplitDefn[i][1];
  • vertexSplitDefn[i][2] < vertexSplitDefn[i][3];
  • vertexSplitDefn[i][0] < vertexSplitDefn[i][2].
REGINA_API const int regina::vertexSplitMeeting[4][4][2]

Lists which vertex splits meet which edges.

See vertexSplit for details on what a vertex split is. vertexSplitMeeting[i][j][0,1] are the numbers of the two vertex splits that meet the edge joining tetrahedron vertices i and j.

REGINA_API const int regina::vertexSplitPartner[3][4]

Lists the second vertex with which each vertex is paired under each vertex split.

See vertexSplit for details on what a vertex split is. Vertex split number i pairs vertex v with vertex vertexSplitPartner[i][v].

REGINA_API const char regina::vertexSplitString[3][6]

Contains strings describing which vertices each vertex split splits.

See vertexSplit for details on what a vertex split is. The string describing vertex split number i is vertexSplitString[i] and is of the form 02/13, which in this case is the vertex split that splits vertices 0,2 from vertices 1,3.


Copyright © 1999-2013, 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@debian.org).